Skip to content

docs: rewrite safety/errors/playbooks/skills/observability/server/rag/checkpointers#31

Merged
fede-kamel merged 3 commits into
mainfrom
docs/concept-rewrites-batch3
May 2, 2026
Merged

docs: rewrite safety/errors/playbooks/skills/observability/server/rag/checkpointers#31
fede-kamel merged 3 commits into
mainfrom
docs/concept-rewrites-batch3

Conversation

@fede-kamel
Copy link
Copy Markdown
Contributor

Summary

Third concept-page batch. Same template as PRs #29 and #30: pitch /
when to pick / getting started / capabilities (each runnable) /
gotchas / source / see also.

Notable: several pages were aligned with the real API after I
read the source. The previous copy described surfaces that don't
exist:

  • safety.md (81→165) — `GuardrailsHook(config=GuardrailConfig(...))` with the actual fields (block_dangerous_tools / pii_patterns / blocked_content_patterns / max_prompt_length / default_action). Previous version invented a `TopicPolicy(deny=...)` API.
  • errors.md (60→127) — full `LocusError` hierarchy with stable `kind` strings; idiomatic one-handler / kind-keyed metrics / differentiated retry / chained-cause patterns.
  • playbooks.md (72→178) — real `PlaybookStep` schema (`id / description / expected_tools / hints / required / max_tool_calls / validation`) + `PlaybookEnforcerHook`. Previous version used a fictional `action / args / expect / requires` schema.
  • skills.md (70→163) — real `Skill` class + AgentSkills.io progressive-disclosure story (catalog → instructions → resources), `allowed_tools` scoping, Skill vs Playbook vs Tool disambiguation.
  • observability.md (72→166) — actual metric names (`locus.invocations`, `locus.iterations`, `locus.tool_calls`, `locus.tool_errors`); PII guidance for `record_arguments` / `record_results`.
  • server.md (67→178) — real `AgentServer` auth model (bearer `api_key`, loopback fallback, per-principal thread scoping that prevents cross-client thread guessing).
  • rag.md (83→229) — `create_rag_tool(retriever)` factory (previous version called `retriever.as_tool()` which doesn't exist), embedder/store matrices, hybrid retrieval guidance.
  • checkpointers.md (96→181) — clarifies the two checkpointer shapes: native `BaseCheckpointer` vs storage backends needing the `*_checkpointer()` factory adapter.

Test plan

  • `hatch -e docs run mkdocs build --strict` — clean (0 warnings, 0 broken anchors)
  • `pre-commit run --files docs/concepts/{safety,errors,playbooks,skills,observability,server,rag,checkpointers}.md` — codespell + markdownlint pass
  • DCO sign-off on the commit

…/checkpointers concept pages

Same template as the prior concept-page batches: pitch / when to pick /
getting started / capabilities (each runnable) / gotchas / source /
see also.

- safety.md: align with the real GuardrailsHook(config=GuardrailConfig(...))
  + TopicPolicy / ContentPolicy + SteeringHook surface (the previous
  copy described an API that doesn't exist).
- errors.md: enumerate the full LocusError hierarchy with stable kind
  strings and idiomatic patterns (one-handler, kind-keyed metrics,
  differentiated retry, chained causes).
- playbooks.md: align with the real PlaybookStep schema
  (id / description / expected_tools / hints / required / max_tool_calls
  / validation), strict_sequence vs allow_extra_tools, PlaybookEnforcerHook.
- skills.md: real Skill class + AgentSkills.io progressive-disclosure
  story (catalog -> instructions -> resources), allowed_tools scoping,
  Skill vs Playbook vs Tool disambiguation table.
- observability.md: StructuredLoggingHook + TelemetryHook with the actual
  metric names (locus.invocations / iterations / tool_calls / tool_errors
  + invocation/tool_call duration histograms), PII guidance for
  record_arguments / record_results.
- server.md: real AgentServer auth model (bearer api_key, loopback
  fallback, per-principal thread scoping), endpoint table, deployment
  paths.
- rag.md: real create_rag_tool factory (the previous copy used a
  retriever.as_tool() that doesn't exist), embedder/store matrices,
  hybrid retrieval guidance.
- checkpointers.md: clarify the two checkpointer shapes (native
  BaseCheckpointer vs storage backends needing the *_checkpointer()
  factory), capability flags, OCI-day-1 recommendation.

Pages sized 81->165, 60->127, 72->178, 70->163, 72->166, 67->178,
83->229, 96->181.

Signed-off-by: Federico Kamelhar <federico.kamelhar@oracle.com>
@oracle-contributor-agreement oracle-contributor-agreement Bot added the OCA Verified All contributors have signed the Oracle Contributor Agreement. label May 2, 2026
fede-kamel added 2 commits May 2, 2026 10:25
…fix)

Signed-off-by: Federico Kamelhar <federico.kamelhar@oracle.com>
Signed-off-by: Federico Kamelhar <federico.kamelhar@oracle.com>
@fede-kamel fede-kamel merged commit ea6d47d into main May 2, 2026
9 checks passed
@fede-kamel fede-kamel deleted the docs/concept-rewrites-batch3 branch May 2, 2026 14:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

OCA Verified All contributors have signed the Oracle Contributor Agreement.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant