agentforge-py 0.2.1__py3-none-any.whl

agentforge/templates/_shared/docs/runbooks/10-add-evaluators.md

@@ -0,0 +1,76 @@
+# 10 — Add evaluators
+
+> **Goal:** score each agent run on quality so regressions are
+> caught before they ship.
+> **Time:** ~20 minutes.
+> **Prereqs:** runbook 06.
+
+## TL;DR
+
+```yaml
+# agentforge.yaml
+modules:
+  evaluators:
+    - name: faithfulness        # LLM-judge
+    - name: coverage            # deterministic
+      config:
+        required_facts: ["population", "year"]
+    - name: regression-vs-baseline
+      config:
+        baseline_path: ./tests/baselines/answers.jsonl
+```
+
+```bash
+agentforge eval --fixtures ./tests/golden.jsonl --threshold 0.8
+```
+
+## Step by step
+
+1. **Mix deterministic + LLM-judge.** Deterministic graders
+   (coverage, format-compliance, regression-vs-baseline,
+   consistency) are cheap; ship them everywhere. Use LLM-judge
+   graders (faithfulness, groundedness, hallucination,
+   relevance, helpfulness, correctness) when no rule captures
+   the property — they cost LLM calls per evaluation.
+2. **Declare under `modules.evaluators`.** Each entry has a
+   `name` (resolver key) and optional `config`. The framework
+   instantiates and runs them post-run, attaching scores to
+   `RunResult.eval_scores`.
+3. **Wire into CI.** `agentforge eval --fixtures golden.jsonl
+   --threshold 0.8 --output-format junit > eval.xml` exits 5
+   when the mean score is below the threshold.
+4. **Threshold per evaluator** (when one matters more than the
+   others) goes in the evaluator's own `config` block.
+5. **Custom evaluators** subclass `Evaluator` and register with
+   `@register("evaluators", "my-name")`. Run
+   `run_evaluator_conformance(my_eval)` to verify the contract.
+
+## Variations
+
+- **Cost gating** — each LLM-judge declares
+  `cost_estimate_usd`. `BudgetPolicy` skips them when the run's
+  remaining budget would be exceeded.
+- **GEval rubrics** — `agentforge-eval-geval` lets you define
+  arbitrary judge rubrics in YAML.
+- **Snapshot diff** — for outputs that should stay byte-stable,
+  pair an evaluator with `agentforge_testing.assert_snapshot`.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `No module registered for evaluators:faithfulness` | LLM-judge pkg missing | `agentforge add module eval-geval` |
+| Evaluators didn't run | budget exhausted before eval pass | bump `agent.budget.usd` or drop expensive judges |
+| Threshold pass but quality regressed | mean masked outliers | switch CI to per-fixture threshold or run with `--threshold-per-evaluator` |
+| Judge gives same score every time | judge prompt too vague | tighten the rubric; add 2-3 worked examples |
+
+## Related
+
+- Runbook 06 — Test your agent
+- Runbook 12 — Add observability (eval scores feed dashboards)
+- Feature spec: `docs/features/feat-006-evaluators-and-benchmarks.md`
+
+<!-- agentforge:end-managed -->
+
+<!-- agentforge:custom -->
+<!-- agentforge:end-custom -->

agentforge/templates/_shared/docs/runbooks/11-add-safety-guardrails.md

@@ -0,0 +1,83 @@
+# 11 — Add safety guardrails
+
+> **Goal:** layer input validation, output redaction, and tool-
+> call gating onto your agent.
+> **Time:** ~15 minutes.
+> **Prereqs:** runbook 02.
+
+## TL;DR
+
+```yaml
+# agentforge.yaml
+modules:
+  guardrails:
+    defaults: true               # framework basics auto-installed
+    input:
+      - prompt_injection_basic
+    output:
+      - pii_redact_basic
+    tool_gates:
+      - capability_check
+      - allowlist:
+          allowed: ["web_search", "calculator"]
+guardrail_policy:
+  on_input_violation: block
+  on_output_violation: redact
+  on_tool_violation: block
+  fail_open: false
+```
+
+## Step by step
+
+1. **Start with the basics.** `prompt_injection_basic` +
+   `pii_redact_basic` + `capability_check` cover the obvious
+   cases out of the box; they ship with the framework.
+2. **Add an allowlist** if your tools include anything
+   `destructive`. `capability_check` already denies destructive
+   tools by default; `allowlist` is a tighter second layer.
+3. **Pick a policy.** `block` is the safe default for input and
+   tool violations; `redact` for outputs lets the run complete
+   with PII stripped. `fail_open: false` (the default) treats
+   validator exceptions as failures.
+4. **Add vendor modules** when basics aren't enough. `presidio`
+   for richer PII, `llmguard` for richer prompt-injection,
+   `nemo` for programmable Colang rails, `llamaguard` for the
+   Llama Guard 3 classifier. Each is a separate pip install.
+5. **Audit decisions.** Every validator call emits an
+   `agentforge.audit` log record and appends to
+   `RunResult.guardrail_events`. Configure your log pipeline to
+   stream the audit logger to a security store.
+
+## Variations
+
+- **Custom validator.** Subclass `InputValidator` /
+  `OutputValidator` / `ToolCallGate` from
+  `agentforge_core.contracts.guardrails`, register with
+  `@register("guardrails.input", "my-name")`.
+- **Score-only mode** — Presidio + LLM Guard support a
+  `score-only` action that reports without modifying content.
+  Useful for triage dashboards.
+- **Conformance test custom validators** with
+  `run_input_validator_conformance` / `run_output_validator_
+  conformance` / `run_tool_gate_conformance` from
+  `agentforge.testing`.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `GuardrailViolation` at startup | input flagged | inspect `RunResult.guardrail_events`; relax to `warn` if false-positive |
+| PII still in output | regex basic doesn't catch your case | install `agentforge-guard-presidio` for richer detection |
+| Destructive tool still ran | `capability_check` was disabled in config | re-enable; ensure `Tool.capabilities` includes `"destructive"` |
+| Tests fail with `GuardrailViolation` | tests use prompts that look like injection | mock the validator in tests, or rephrase the test prompt |
+
+## Related
+
+- Runbook 12 — Add observability (audit stream)
+- Runbook 14 — Deploy your agent (policy hardening)
+- Feature spec: `docs/features/feat-018-safety-and-security-guardrails.md`
+
+<!-- agentforge:end-managed -->
+
+<!-- agentforge:custom -->
+<!-- agentforge:end-custom -->

agentforge/templates/_shared/docs/runbooks/12-add-observability.md

@@ -0,0 +1,77 @@
+# 12 — Add observability
+
+> **Goal:** stream structured logs + distributed traces from
+> every agent run to your APM stack.
+> **Time:** ~15 minutes.
+> **Prereqs:** runbook 01.
+
+## TL;DR
+
+```yaml
+# agentforge.yaml
+logging:
+  format: json
+  run_id_filter: true
+modules:
+  observability:
+    - name: otel
+      config:
+        endpoint: "${OTEL_EXPORTER_OTLP_ENDPOINT}"
+        service_name: "{{ project_slug }}"
+```
+
+```bash
+agentforge add module otel
+```
+
+## Step by step
+
+1. **Turn on JSON logging.** `logging.format: json` swaps the
+   default text formatter for `JSONFormatter`; every log line
+   becomes one JSON object suitable for piping into a log
+   aggregator.
+2. **Enable run_id propagation.** `run_id_filter: true`
+   installs a logging filter that attaches the active run's
+   `run_id` to every record under that run's context. Cross-
+   reference runs across components.
+3. **Install OTel.** `agentforge add module otel` adds
+   `agentforge-otel`; the framework's root span (`agent.run`)
+   then becomes the parent of every strategy / LLM / tool span.
+4. **Point at your collector.** OTLP/gRPC by default; set
+   `OTEL_EXPORTER_OTLP_ENDPOINT` (or hard-code in the YAML).
+   Service name = project slug by default.
+5. **Custom hooks.** Implement `on_step(step)` / `on_finish(
+   result)` callables and pass them to `Agent(on_step=...,
+   on_finish=...)` for bespoke metrics; multiple hooks fan out
+   in parallel.
+
+## Variations
+
+- **Custom log channels.** Audit decisions go to
+  `agentforge.audit`; route them to a security store separately
+  from app logs.
+- **Vendor backends** — Langfuse / Phoenix / Evidently / StatsD
+  modules each wrap their own SDK behind the same hook
+  contract. Add via `agentforge add module <name>`.
+- **Cost dashboards.** `RunResult.cost_usd` + `eval_scores` are
+  cheap series for daily cost-vs-quality charts.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| No spans in OTel UI | exporter endpoint wrong | check `agentforge config show --resolved` then curl the OTLP endpoint |
+| Run id missing from logs | run_id_filter disabled | re-enable in YAML; restart the process |
+| Hook breaks the run | exceptions in hooks default to log-and-continue | check the hook's error log; framework isolates failures |
+| Spans missing inside strategies | older `agentforge-otel`; iteration spans land in 0.2+ | upgrade the module |
+
+## Related
+
+- Runbook 11 — Add safety guardrails (audit stream)
+- Runbook 14 — Deploy your agent
+- Feature spec: `docs/features/feat-009-observability.md`
+
+<!-- agentforge:end-managed -->
+
+<!-- agentforge:custom -->
+<!-- agentforge:end-custom -->

agentforge/templates/_shared/docs/runbooks/13-configure-multi-provider.md

@@ -0,0 +1,91 @@
+# 13 — Configure multi-provider
+
+> **Goal:** run different model classes for reasoning, judging,
+> and embedding without rewriting your agent.
+> **Time:** ~10 minutes.
+> **Prereqs:** runbook 01.
+
+## TL;DR
+
+```yaml
+# agentforge.yaml
+providers:
+  default:
+    type: anthropic                                    # native Anthropic API
+    model: claude-sonnet-4-7
+  judge:
+    type: anthropic
+    model: claude-haiku-4-5                            # cheaper judge
+  embed:
+    type: voyage
+    model: voyage-3-large
+agent:
+  model: anthropic:claude-sonnet-4-7
+modules:
+  evaluators:
+    - name: faithfulness
+      config:
+        judge_provider: judge
+```
+
+**Available provider drivers (v0.2):**
+
+| `type:` | Package | Capabilities |
+|---|---|---|
+| `bedrock` | `agentforge-bedrock` | tools, json_mode, caching, thinking, streaming |
+| `anthropic` | `agentforge-anthropic` | tools, json_mode, caching, thinking, streaming |
+| `openai` | `agentforge-openai` | tools, json_mode, streaming, vision (gpt-4o*) |
+| `ollama` | `agentforge-ollama` | tools, streaming (local; zero cost) |
+| `litellm` | `agentforge-litellm` | tools (router → 100+ backends) |
+| `voyage` | `agentforge-voyage` | embedding-only; matryoshka |
+
+## Step by step
+
+1. **Name your providers** under the top-level `providers:` map.
+   `default` is the one `agent.model` falls back to; named
+   entries (`judge`, `embed`, `summariser`) can be addressed by
+   downstream modules.
+2. **Pick the reasoning model.** `agent.model` is the agent's
+   primary LLM. Use the strongest model you can afford.
+3. **Use a cheaper judge** for LLM-judge evaluators. Per
+   feat-006, judge graders take a `judge_provider` config that
+   resolves the named provider. Cheap haiku-class models bring
+   judge cost down 10x with marginal quality loss for boolean
+   evaluations.
+4. **Separate embedding from reasoning.** Vector indexing
+   typically benefits from a dedicated embedder
+   (`voyage-3`, `text-embedding-3-large`). Wire it into
+   `modules.retriever.embedding_provider`.
+5. **Per-module overrides.** Any module that takes an LLM (
+   guardrails / evaluators / etc.) can name a provider.
+
+## Variations
+
+- **Fallback chain.** Use `agentforge_core.production.FallbackChain`
+  to wrap two providers; primary first, secondary on
+  `RateLimitError` / `ServiceError`.
+- **Different providers per environment.** `agentforge.dev.yaml`
+  overlay points at a cheap dev model; `agentforge.prod.yaml`
+  swaps to the production tier. `AGENTFORGE_ENV=prod` selects.
+- **Mock provider for tests.** Register `MockLLMClient` as a
+  named provider so config-driven tests reuse it.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `No LLM provider registered for X` | provider package not installed | `agentforge add module <X>` |
+| Judge cost > reasoning cost | judge running on the same big model | name a cheaper judge provider |
+| Embedder shape mismatch | mixed-dimension stores | pin embedding model + dimension in the vector store config |
+| Run intermittently 5xx | provider outage | wrap with FallbackChain |
+
+## Related
+
+- Runbook 10 — Add evaluators (judge_provider)
+- Runbook 14 — Deploy your agent (environment overlays)
+- Feature spec: `docs/features/feat-003-llm-provider-abstraction.md`
+
+<!-- agentforge:end-managed -->
+
+<!-- agentforge:custom -->
+<!-- agentforge:end-custom -->

agentforge/templates/_shared/docs/runbooks/14-deploy-your-agent.md

@@ -0,0 +1,70 @@
+# 14 — Deploy your agent
+
+> **Goal:** get the agent running somewhere durable (container,
+> serverless, batch job) with proper secrets and observability.
+> **Time:** ~30 minutes.
+> **Prereqs:** runbooks 01, 08, 12.
+
+## TL;DR
+
+```dockerfile
+FROM python:3.13-slim
+WORKDIR /app
+RUN pip install --no-cache-dir uv
+COPY pyproject.toml uv.lock ./
+COPY src/ ./src/
+COPY agentforge.yaml ./
+RUN uv sync --frozen
+ENV AGENTFORGE_ENV=prod
+CMD ["uv", "run", "agentforge", "run", "--task-file", "/in/task.txt", "--output-format", "json"]
+```
+
+## Step by step
+
+1. **Pin every dependency.** `uv.lock` must ship with the
+   image. `uv sync --frozen` enforces that.
+2. **Use environment overlays.** Ship `agentforge.yaml` +
+   `agentforge.prod.yaml`; set `AGENTFORGE_ENV=prod` in the
+   container. The framework merges the overlay automatically.
+3. **Mount secrets via env.** `${AWS_ACCESS_KEY_ID}` etc. in
+   the YAML resolve from the container's env. Never bake
+   secrets into the image.
+4. **Provision the memory store.** If using Postgres, run
+   `agentforge db migrate` as a pre-deploy step (helm hook,
+   k8s Job, deployment script).
+5. **Configure observability** — export `OTEL_EXPORTER_OTLP_
+   ENDPOINT`, `OTEL_RESOURCE_ATTRIBUTES=service.name=...`.
+6. **Health probe.** `agentforge health --output-format json`
+   exits 0 when config + modules + backends are all OK; perfect
+   for k8s readiness probes.
+
+## Variations
+
+- **Serverless.** Same image, different entrypoint. Lambda /
+  Cloud Run trigger calls `agentforge run` with the task from
+  the event.
+- **Batch worker.** Loop over a queue; reuse the Agent across
+  tasks. `Agent` is thread-safe; each `run` creates fresh
+  per-run state.
+- **Multi-tenant.** One Agent per tenant; route requests by
+  `project` / `agent` claim namespace.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Container exits 2 on start | config invalid in the prod overlay | check `agentforge config validate --env prod` locally |
+| `connection refused` on DB | network policy blocking | mount the secret AND open egress |
+| OTel spans not appearing | service.name not set | export `OTEL_RESOURCE_ATTRIBUTES=service.name=<your-agent>` |
+| Probe fails intermittently | cold-start LLM auth | bump probe initial delay; cache provider client across requests |
+
+## Related
+
+- Runbook 08 — Add memory (DSN secrets, migration)
+- Runbook 12 — Add observability
+- Runbook 15 — Upgrade your agent (release process)
+
+<!-- agentforge:end-managed -->
+
+<!-- agentforge:custom -->
+<!-- agentforge:end-custom -->

agentforge/templates/_shared/docs/runbooks/15-upgrade-your-agent.md

@@ -0,0 +1,67 @@
+# 15 — Upgrade your agent
+
+> **Goal:** pull the latest framework changes into this project
+> without losing your customisations.
+> **Time:** ~15 minutes.
+> **Prereqs:** runbook 01.
+
+## TL;DR
+
+```bash
+agentforge upgrade --dry-run     # preview
+agentforge upgrade               # apply
+agentforge status                # any drift?
+pytest -q
+```
+
+## Step by step
+
+1. **Read the framework's CHANGELOG.** Open
+   `docs/features/README.md` from the framework repo (or the
+   release notes) and skim what shipped between your version
+   and current.
+2. **Stage clean.** Commit any uncommitted work first.
+   `agentforge upgrade` is a three-way merge — easier to
+   resolve from a clean tree.
+3. **Dry-run.** `agentforge upgrade --dry-run` prints the diff
+   without writing. Use to scope the review.
+4. **Apply.** `agentforge upgrade` runs Copier's `run_update`,
+   merging managed files against the recorded template
+   version. Custom sections of three-section docs are
+   preserved automatically; non-managed code is left alone.
+5. **Resolve conflicts.** Copier surfaces conflicts in `.rej`
+   files. Edit by hand or `agentforge fork <path>` to claim
+   the file outright (future upgrades skip it).
+6. **Verify.** `agentforge status` should show no `DRIFTED`
+   files; `pytest -q` should pass.
+
+## Variations
+
+- **Fork a file.** `agentforge fork src/myagent/agent_runtime.py`
+  strips the marker and flips the lock entry to `forked: true`.
+  Future upgrades skip it.
+- **Unfork.** `agentforge unfork <path>` re-prepends the marker;
+  next upgrade re-pulls framework content (lossy).
+- **Pin a target ref.** `agentforge upgrade --to <ref>` points
+  at a specific template ref instead of the latest. Useful for
+  staged rollouts.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `No .agentforge-state/answers.yml` | this directory wasn't scaffolded by `agentforge new` | upgrade only works on scaffolded projects |
+| `.rej` conflict file | three-way merge couldn't auto-resolve | edit by hand; the `.rej` carries the framework's preferred shape |
+| Custom section in runbook overwritten | edit went above the `<!-- agentforge:end-managed -->` marker | move custom content below the marker, restore from git |
+| DB schema out of date | driver bumped its schema | `agentforge db backup` → `agentforge db migrate` → `agentforge db restore` |
+
+## Related
+
+- Runbook 08 — Add memory (db migrate during upgrade)
+- Runbook 14 — Deploy your agent (release process)
+- Feature spec: `docs/features/feat-011-scaffolding-and-upgrade.md`
+
+<!-- agentforge:end-managed -->
+
+<!-- agentforge:custom -->
+<!-- agentforge:end-custom -->

agentforge/templates/_shared/docs/runbooks/16-configuration-reference.md

@@ -0,0 +1,81 @@
+# 16 — Configuration reference
+
+> **Goal:** find the canonical shape of every `agentforge.yaml`
+> field without re-reading source.
+> **Time:** ~5 minutes (lookup).
+> **Prereqs:** none.
+
+## TL;DR
+
+```bash
+agentforge config schema | less     # print the full JSON schema
+agentforge config show --resolved   # see what your YAML actually parsed to
+agentforge config validate          # fast-fail on bad keys
+```
+
+## Step by step
+
+1. **Schema is the truth.** `agentforge config schema` prints
+   the Pydantic-derived JSON schema for `AgentForgeConfig`. No
+   guessing.
+2. **Resolved view.** `agentforge config show --resolved` prints
+   the parsed config with `${ENV_VAR}` interpolation expanded,
+   env overlay merged, and CLI overrides applied. Source-of-
+   truth for "what will the agent actually run with?"
+3. **Validate** before commit. `agentforge config validate` is
+   the same parse the runtime does; exit code 2 means the YAML
+   has unknown keys, bad types, or invalid env references.
+
+## Top-level sections
+
+| Section | Purpose |
+|---|---|
+| `agent` | name, model, strategy, system prompt, tools, budget, max_iterations, llm_options |
+| `modules` | memory / graph / retriever / evaluators / observability / tools / protocols / guardrails |
+| `providers` | named LLM clients (default + judge + embed + custom) |
+| `logging` | level, run_id_filter, format (text\|json) |
+| `output` | finding variant defaults, renderer choice, thresholds |
+| `guardrail_policy` | on_input / on_output / on_tool violation actions, audit_channel, fail_open |
+
+## Environment + override order
+
+CLI flags > `--override` flags > `agentforge.<env>.yaml` overlay >
+`agentforge.yaml` > defaults.
+
+```bash
+agentforge run \
+  --env prod \
+  --override agent.budget.usd=20 \
+  --override providers.default.model=claude-haiku-4-5 \
+  "your task"
+```
+
+## Variations
+
+- **Schema export** — `agentforge config schema > schema.json`
+  feeds IDE YAML LSPs (vs-code-yaml etc.) for autocomplete.
+- **Per-module schemas** — installed modules contribute schemas
+  to `modules.<section>.config`. `agentforge config validate
+  --strict` enforces.
+- **`AGENTFORGE_CONFIG`** + `AGENTFORGE_ENV` + `AGENTFORGE_LOG_
+  LEVEL` env vars are the three shortcuts that don't require
+  flags.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `unknown field` on a key you expected to be valid | typo or post-major rename | check the schema; spec changes are listed in CHANGELOG |
+| `${VAR}` not resolving | env var unset | `agentforge config show --resolved` reports the missing one |
+| Override not taking effect | wrong dotted path | overrides are dotted: `agent.budget.usd=10`, not `budget.usd` |
+| `fail_open: true` slipped into prod | dev overlay leaked | rotate env-overlay names; only prod overlay shipped to prod |
+
+## Related
+
+- Every other runbook (they all link back here)
+- Feature spec: `docs/features/feat-012-configuration-system.md`
+
+<!-- agentforge:end-managed -->
+
+<!-- agentforge:custom -->
+<!-- agentforge:end-custom -->

agentforge/templates/_shared/docs/runbooks/17-add-reranker.md

@@ -0,0 +1,78 @@
+# 17 — Add a reranker
+
+> **Goal:** improve retrieval precision by re-scoring the top-k
+> candidates a vector store returned, then keeping the best.
+> **Time:** ~10 minutes.
+> **Prereqs:** runbook 08 (retrieval already wired).
+
+## TL;DR
+
+```yaml
+# agentforge.yaml
+retrieval:
+  embedder:
+    driver: voyage
+    config: {model: voyage-3-large}
+  vector_store:
+    driver: postgres
+    config: {dsn: $POSTGRES_DSN, table: docs}
+  reranker:
+    name: cohere               # or: sentence_transformers / voyage / mixedbread
+    config:
+      api_key: $COHERE_API_KEY
+      model: rerank-english-v3.0
+      top_k: 4                  # keep the top 4 after re-scoring
+```
+
+## Step by step
+
+1. **Pick a reranker driver.** Built-in choices:
+   - `sentence_transformers` — local cross-encoder; no API key, slower.
+   - `cohere` — managed; fast; needs `COHERE_API_KEY`.
+   - `voyage` — managed; high quality; needs `VOYAGE_API_KEY`.
+   - `mixedbread` — managed; needs `MIXEDBREAD_API_KEY`.
+2. **Install the matching package.**
+   `agentforge add module reranker-cohere` (or `-voyage`,
+   `-mixedbread`, `-sentence-transformers`).
+3. **Drop the `reranker:` block** into `retrieval:`. The
+   `Retriever` looks up the driver via the `agentforge.rerankers`
+   entry-point category and slots it after the vector / hybrid
+   search stage.
+4. **Set `top_k`.** The reranker runs over the vector store's
+   `top_k_pre` candidates and returns `top_k`. Common settings:
+   `top_k_pre=20, top_k=4` for cost-aware, `top_k_pre=50,
+   top_k=8` for quality-aware.
+5. **Test it.** `await retriever.retrieve("query")` returns
+   `VectorMatch` rows already in reranked order — the
+   `score` field reflects the reranker's score, not the
+   original vector similarity.
+
+## Variations
+
+- **Two-stage** — keep an embedding-based fast path with a
+  reranker only on cold queries. Set
+  `retrieval.reranker.always: false`.
+- **Custom reranker** — implement the `Reranker` ABC in
+  `agentforge_core.contracts.reranker` and register it via the
+  `agentforge.rerankers` entry-point in your module's
+  `pyproject.toml`.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `No reranker registered for X` | package not installed | `agentforge add module reranker-X` |
+| Latency 2-3x higher | local cross-encoder on CPU | switch to managed (Cohere / Voyage) |
+| Top result is wrong | reranker model mismatch with corpus language | pick the matching `rerank-multilingual-v3.0` or similar |
+| Cost spike | reranker called per request, hot path | cache by query hash or move reranker to async batch path |
+
+## Related
+
+- Runbook 08 — Add memory + retrieval
+- Runbook 18 — Add hybrid search
+- Feature spec: `docs/features/feat-021-reranker.md`
+
+<!-- agentforge:end-managed -->
+
+<!-- agentforge:custom -->
+<!-- agentforge:end-custom -->