From 18021b7661e66751d27e1240c2902b221013e2a7 Mon Sep 17 00:00:00 2001 From: Federico Kamelhar Date: Tue, 28 Apr 2026 10:38:41 -0400 Subject: [PATCH] docs: surface tutorial 31 (plugins) and fix stale source links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add the Plugins tutorial link to the production track on the homepage. Pre-fix, examples/tutorial_31_plugins.py was orphaned with zero references in the docs site. - Add a 'See also' block to docs/concepts/hooks.md linking tutorials 5, 27, and 31, plus the user-facing concept pages (Retry, Safety, Observability) for the built-in hooks. - Fix the stale 'src/locus/integrations/mcp/' references in docs/index.md and docs/concepts/mcp.md — the package was flattened to src/locus/integrations/fastmcp.py. - Fix the stale 'agent_state.py' reference in docs/concepts/agent-loop.md — the file was consolidated into loop/runner.py. Audit: every github.com/oracle-samples/locus source / examples link across the docs tree now points at a path that exists in the repo. mkdocs build --strict passes with zero warnings. --- docs/concepts/agent-loop.md | 4 ++-- docs/concepts/hooks.md | 12 ++++++++++++ docs/concepts/mcp.md | 2 +- docs/index.md | 3 ++- 4 files changed, 17 insertions(+), 4 deletions(-) diff --git a/docs/concepts/agent-loop.md b/docs/concepts/agent-loop.md index 82a5670..7cac221 100644 --- a/docs/concepts/agent-loop.md +++ b/docs/concepts/agent-loop.md @@ -12,8 +12,8 @@ and is composed of four files: [`react.py`](https://github.com/oracle-samples/locus/blob/main/src/locus/loop/react.py) (the runner), [`nodes.py`](https://github.com/oracle-samples/locus/blob/main/src/locus/loop/nodes.py) (Think / Execute / Reflect / Terminate), [`router.py`](https://github.com/oracle-samples/locus/blob/main/src/locus/loop/router.py) (transitions), -and [`agent_state.py`](https://github.com/oracle-samples/locus/blob/main/src/locus/loop/agent_state.py) -(the state value object). +and [`runner.py`](https://github.com/oracle-samples/locus/blob/main/src/locus/loop/runner.py) +(the loop driver that wires the nodes together). ## Origin: ReAct, then refinement diff --git a/docs/concepts/hooks.md b/docs/concepts/hooks.md index da33838..881ba25 100644 --- a/docs/concepts/hooks.md +++ b/docs/concepts/hooks.md @@ -67,3 +67,15 @@ from locus.hooks.builtin import LoggingHook, GuardrailsHook agent = Agent(..., hooks=[LoggingHook(), GuardrailsHook()]) ``` + +## See also + +- [Tutorial 05 — agent hooks](https://github.com/oracle-samples/locus/blob/main/examples/tutorial_05_agent_hooks.py) + — the basics, end to end. +- [Tutorial 27 — hooks advanced](https://github.com/oracle-samples/locus/blob/main/examples/tutorial_27_hooks_advanced.py) + — write-protected events, retry, cancel. +- [Tutorial 31 — plugins](https://github.com/oracle-samples/locus/blob/main/examples/tutorial_31_plugins.py) + — bundle hooks + tools + lifecycle into a reusable `Plugin`. +- [Retry Strategies](retry.md), [Safety & Guardrails](safety.md), + [Observability](observability.md) — the user-facing concept pages + for the built-in hooks. diff --git a/docs/concepts/mcp.md b/docs/concepts/mcp.md index 2c44e84..3a69c9a 100644 --- a/docs/concepts/mcp.md +++ b/docs/concepts/mcp.md @@ -48,4 +48,4 @@ different transports. ## Source -`src/locus/integrations/mcp/` — built on FastMCP. +`src/locus/integrations/fastmcp.py` — built on FastMCP. diff --git a/docs/index.md b/docs/index.md index 3792b5d..8b2ab3b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -331,7 +331,7 @@ path. No magic, no hidden registries, no import-time side-effects. | Skills · AgentSkills.io | [`src/locus/skills/`](https://github.com/oracle-samples/locus/tree/main/src/locus/skills) | | Playbooks · enforcer | [`src/locus/playbooks/`](https://github.com/oracle-samples/locus/tree/main/src/locus/playbooks) | | Evaluation harness | [`src/locus/evaluation/`](https://github.com/oracle-samples/locus/tree/main/src/locus/evaluation) | -| MCP client + server | [`src/locus/integrations/mcp/`](https://github.com/oracle-samples/locus/tree/main/src/locus/integrations/mcp) | +| MCP client + server | [`src/locus/integrations/fastmcp.py`](https://github.com/oracle-samples/locus/tree/main/src/locus/integrations/fastmcp.py) | | A2A protocol | [`src/locus/a2a/`](https://github.com/oracle-samples/locus/tree/main/src/locus/a2a) | Read the [concepts](concepts/agent.md) for the *why*; read the @@ -395,6 +395,7 @@ The six in-process patterns plus A2A: [Agent Server](https://github.com/oracle-samples/locus/blob/main/examples/tutorial_28_agent_server.py) · [Model providers](https://github.com/oracle-samples/locus/blob/main/examples/tutorial_29_model_providers.py) · [Guardrails advanced](https://github.com/oracle-samples/locus/blob/main/examples/tutorial_30_guardrails_advanced.py) · +[Plugins](https://github.com/oracle-samples/locus/blob/main/examples/tutorial_31_plugins.py) · [Steering](https://github.com/oracle-samples/locus/blob/main/examples/tutorial_33_steering.py) · [Graph advanced](https://github.com/oracle-samples/locus/blob/main/examples/tutorial_35_graph_advanced.py) · [Termination](https://github.com/oracle-samples/locus/blob/main/examples/tutorial_37_termination.py).