Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
115 lines (87 loc) · 4.23 KB

CONTRIBUTING.md

File metadata and controls

115 lines (87 loc) · 4.23 KB
Raw

Contributing to yapi

Thanks for considering a contribution. yapi is small and intentionally opinionated; this guide explains the workflow so changes can land smoothly.

Local development

git clone https://github.com/TokenRollAI/yapi.git
cd yapi
uv sync --extra dev        # creates .venv with runtime + dev deps
uv run pytest              # offline test matrix; live tests are skipped by default

Python 3.12+ is required. The lockfile (uv.lock) is committed and should be kept in sync; if you change pyproject.toml dependencies, run uv sync and commit the updated lockfile.

Trying changes against a real or mock model

# Offline smoke (no API key, no network):
YAPI_MODEL=test uv run uvicorn examples.wish_api:app --reload

# Against a real provider — see README.md "Configuration":
uv run uvicorn examples.wish_api:app --reload --env-file .env

The model must support OpenAI Function Calling's tool_choice — see the warning in README.md under YAPI_MODEL.

Live tests (real LLM)

tests/live/ runs end-to-end against the configured provider — useful when changing prompt composition, <context> wrapping, or PydanticAI integration. Skipped by default; requires both a CLI flag and a real YAPI_MODEL:

set -a; source .env; set +a            # or otherwise export YAPI_MODEL etc.
uv run pytest tests/live --run-live -v

CI does not run them (provider creds + nondeterministic LLM output). See llmdoc/reference/run-and-test.md §8 for the gating logic and assertion style.

Code style

  • No automated formatter / linter is wired up yet (intentional, see docs/superpowers/specs/2026-05-24-yapi-v2.2-design.md §10). Match the surrounding style: PEP 8, type annotations on public surface, no trailing whitespace.
  • Public symbols live in yapi/__init__.py __all__. If you add one, re-export it explicitly and update llmdoc/must/api-surface.md.
  • Errors that the user can hit raise YapiDeclarationError at decoration time (preferred) or RuntimeExecutionError at request time. Don't add a new error type without updating llmdoc/reference/error-catalog.md.

Commit messages

Conventional-commit style is used throughout the history:

feat: short summary
fix: short summary
docs: short summary
chore: short summary
chore(deps): short summary       # dependabot
chore(actions): short summary    # dependabot for github-actions

Keep the subject under ~70 chars. A body is optional but encouraged for non-trivial changes — explain the why, not the what.

Pull request checklist

Before opening a PR:

  1. uv run pytest passes locally.
  2. New behavior has at least one test in tests/. The breakdown of test files is documented in llmdoc/reference/run-and-test.md.
  3. If the change touches the public contract (router, runner, errors), update the relevant llmdoc/ file(s). See llmdoc/index.md for the doc map.
  4. Examples in examples/ still import without errors: 
    uv run python -c "import examples.wish_api, examples.mixed_router, examples.with_depends, examples.state_via_depends, examples.custom_runner"

CI (GitHub Actions) runs the test matrix on Python 3.12 + 3.13. No secrets are required.

Releasing (maintainers)

Bump [project].version in pyproject.toml, commit, tag vX.Y.Z, push the tag. The release pipeline (.github/workflows/release.yml) verifies the tag matches the pyproject version, builds sdist + wheel, publishes to PyPI via Trusted Publishing, and creates a GitHub Release with autogenerated notes. See llmdoc/guides/release.md for the full flow.

Scope: what this project does not aim to do

yapi is not a chat platform, agent framework, or prompt-management tool. See llmdoc/overview/project-overview.md "明确不做的事" and docs/superpowers/specs/2026-05-24-yapi-v2.2-design.md §10 for the full list of out-of-scope items before proposing large features. In particular, yapi does not integrate state stores (Redis / Mongo / SQL) — use FastAPI Depends(...) and pass results to PromptContext; see examples/state_via_depends.py.

Questions

Open a GitHub issue at https://github.com/TokenRollAI/yapi/issues with a minimal reproduction or a concrete proposal. For security issues, see SECURITY.md instead.