docs: fold verification-run feedback into verify skill
Stale-compose-stack check + host-process path for branch code, worktree .env/bun-install setup, concrete config.toml injection recipe, live-LLM model-var requirement, and telemetry log-noise hint. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
parent
be3de9234e
commit
8e633ec1c3
|
|
@ -14,23 +14,39 @@ run directly on the host (see Launch below); you'll need Postgres with pgvector
|
|||
and Redis reachable, plus a `.env` with connection strings and an LLM provider
|
||||
key for any flow that hits a model (deriver, dialectic, dreamer).
|
||||
|
||||
Working in a worktree? It carries neither `.env` nor `node_modules`. Copy
|
||||
`.env` from the main checkout (that's where the provider keys live), and run
|
||||
`bun install` in `sdks/typescript` if you'll run the full test suite —
|
||||
otherwise the pre-push gate fails on a phantom `Cannot find package 'zod'`.
|
||||
|
||||
## Launch
|
||||
|
||||
First check whether the stack is already running via Docker Compose — that's
|
||||
the preferred setup, and reusing it beats starting a second one:
|
||||
First check whether the stack is already running via Docker Compose:
|
||||
|
||||
```bash
|
||||
docker compose ps # look for api / deriver / database / redis
|
||||
docker compose up -d # start it if not
|
||||
```
|
||||
|
||||
Without Docker, run the two processes directly (shared Postgres + Redis):
|
||||
A running stack is not the same as *your branch's code* running — check the
|
||||
CREATED column; the images may be weeks old. For verifying a diff, the cheap
|
||||
path is to reuse the stack's Postgres/Redis containers but run the branch's
|
||||
API as a host process on a spare port:
|
||||
|
||||
```bash
|
||||
uv run fastapi dev src/main.py # API server (default :8000)
|
||||
uv run python -m src.deriver # deriver worker (queue consumer)
|
||||
uv run uvicorn src.main:app --port 8901 # branch code, stack's DB/Redis
|
||||
uv run python -m src.deriver # if the diff touches the worker
|
||||
```
|
||||
|
||||
This avoids both an image rebuild and the port/project-name conflicts a second
|
||||
compose stack in a worktree would cause. Without Docker at all, run the two
|
||||
processes the same way against host Postgres + Redis (API default port 8000
|
||||
via `uv run fastapi dev src/main.py`).
|
||||
|
||||
When reading server logs, note that with the main `.env` the telemetry emitter
|
||||
spams connection warnings at an unreachable endpoint — `grep -v
|
||||
telemetry.emitter` before looking for the real error.
|
||||
|
||||
## Drive it
|
||||
|
||||
Prefer driving through the `honcho-cli` skill; fall back to the SDKs
|
||||
|
|
@ -41,6 +57,10 @@ skill covers how to use the SDKs.
|
|||
When a change updates endpoints or makes schema changes, verify across all
|
||||
three surfaces — CLI, SDKs, and REST — since they can drift independently.
|
||||
|
||||
For LLM-path changes, the fastest synchronous surface is dialectic at the
|
||||
`minimal` reasoning level: send a couple of messages, then hit
|
||||
`/v3/.../peers/{peer_id}/chat` and observe the response.
|
||||
|
||||
## Configuration
|
||||
|
||||
Configuration is central to both driving the app and running tests: it's how
|
||||
|
|
@ -52,6 +72,12 @@ process, and observe the behavioral difference at the surface — the same
|
|||
mechanism lets you point provider base URLs, model choices, and timeouts at
|
||||
credentials and proxies you actually have.
|
||||
|
||||
Two concrete levers: deep-nested settings (e.g.
|
||||
`[dialectic.levels.minimal.model_config.overrides.provider_params]`) are
|
||||
miserable as env vars — drop a partial `config.toml` in the repo root instead.
|
||||
And for load-time config behavior, `uv run python -c "import src.config; ..."`
|
||||
is faster than booting the server.
|
||||
|
||||
## Test suites
|
||||
|
||||
Three test types matter here. All run in CI, but they're also runnable locally
|
||||
|
|
@ -69,7 +95,9 @@ uv run python -m tests.unified.run
|
|||
uv run python -m tests.unified.run --test-dir tests/unified/test_cases
|
||||
|
||||
# Live LLM tests — real provider calls, for testing specific backends.
|
||||
# Needs LLM_ANTHROPIC_API_KEY / LLM_OPENAI_API_KEY / LLM_GEMINI_API_KEY and
|
||||
# LIVE_LLM_*_MODELS env vars; see tests/live_llm/README.md.
|
||||
# Needs provider API keys AND model vars — without LIVE_LLM_*_MODELS the
|
||||
# tests silently deselect that provider. See tests/live_llm/README.md.
|
||||
export LLM_ANTHROPIC_API_KEY=...
|
||||
export LIVE_LLM_ANTHROPIC_45_PLUS_MODELS=claude-sonnet-4-5
|
||||
uv run pytest tests/live_llm -n 0 --live-llm --no-header -q
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue