From 089d4c5fd09afb8047ce9292d21d935edafd99ca Mon Sep 17 00:00:00 2001 From: chris-colinsky Date: Thu, 28 May 2026 17:18:42 -0700 Subject: [PATCH 1/3] De-hyphenate pattern titles in docs nav The Patterns section showed kebab-case titles inherited from the filenames (Tool-dispatch-as-node, Session-as-checkpoint-resume, Bypass-if-output-exists), inconsistent with "Parameterized entry point". Convert the nav labels, page H1s, and index catalog links to spaced titles. Filenames stay kebab-case: they are the canonical pattern slugs behind patterns.get() / patterns.list(), so the link targets and the public API surface are unchanged. --- docs/patterns/bypass-if-output-exists.md | 2 +- docs/patterns/index.md | 6 +++--- docs/patterns/session-as-checkpoint-resume.md | 2 +- docs/patterns/tool-dispatch-as-node.md | 2 +- mkdocs.yml | 6 +++--- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/patterns/bypass-if-output-exists.md b/docs/patterns/bypass-if-output-exists.md index e9e1d22d..a4ad7015 100644 --- a/docs/patterns/bypass-if-output-exists.md +++ b/docs/patterns/bypass-if-output-exists.md @@ -1,4 +1,4 @@ -# Bypass-if-output-exists +# Bypass if output exists **Problem.** How do I skip a node whose external output already exists? diff --git a/docs/patterns/index.md b/docs/patterns/index.md index bbc4dae8..00e57414 100644 --- a/docs/patterns/index.md +++ b/docs/patterns/index.md @@ -25,11 +25,11 @@ docs composing existing primitives. - [Parameterized entry point](parameterized-entry-point.md) — start the graph at an arbitrary node via state-driven routing. -- [Tool-dispatch-as-node](tool-dispatch-as-node.md) — model an +- [Tool dispatch as node](tool-dispatch-as-node.md) — model an agent tool-call loop as a graph cycle. -- [Session-as-checkpoint-resume](session-as-checkpoint-resume.md) — +- [Session as checkpoint resume](session-as-checkpoint-resume.md) — carry multi-turn agent state across turns using the existing checkpointer. -- [Bypass-if-output-exists](bypass-if-output-exists.md) — +- [Bypass if output exists](bypass-if-output-exists.md) — short-circuit a node whose external output already exists, via middleware. diff --git a/docs/patterns/session-as-checkpoint-resume.md b/docs/patterns/session-as-checkpoint-resume.md index 56aed63b..5e5c6344 100644 --- a/docs/patterns/session-as-checkpoint-resume.md +++ b/docs/patterns/session-as-checkpoint-resume.md @@ -1,4 +1,4 @@ -# Session-as-checkpoint-resume +# Session as checkpoint resume **Problem.** How do I keep multi-turn agent state across turns? diff --git a/docs/patterns/tool-dispatch-as-node.md b/docs/patterns/tool-dispatch-as-node.md index 794897e8..3a385ba4 100644 --- a/docs/patterns/tool-dispatch-as-node.md +++ b/docs/patterns/tool-dispatch-as-node.md @@ -1,4 +1,4 @@ -# Tool-dispatch-as-node +# Tool dispatch as node **Problem.** How do I run an agent tool-call loop? diff --git a/mkdocs.yml b/mkdocs.yml index 8b9d1dbc..0af35df4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -118,9 +118,9 @@ nav: - Patterns: - patterns/index.md - Parameterized entry point: patterns/parameterized-entry-point.md - - Tool-dispatch-as-node: patterns/tool-dispatch-as-node.md - - Session-as-checkpoint-resume: patterns/session-as-checkpoint-resume.md - - Bypass-if-output-exists: patterns/bypass-if-output-exists.md + - Tool dispatch as node: patterns/tool-dispatch-as-node.md + - Session as checkpoint resume: patterns/session-as-checkpoint-resume.md + - Bypass if output exists: patterns/bypass-if-output-exists.md - Examples: - examples/index.md - Hello, world: examples/00-hello-world.md From 9ad83b338ae1c12ccf29650cd2773243d7d09312 Mon Sep 17 00:00:00 2001 From: chris-colinsky Date: Thu, 28 May 2026 17:18:56 -0700 Subject: [PATCH 2/3] Default full local toolchain in uv sync A plain `uv run mkdocs serve` failed because mkdocs lives in the docs dependency group, which uv does not sync by default. The docs and examples groups and the otel/langfuse extras were absent from the default environment. Add a [tool.uv] default-groups covering dev, docs, examples, and a new observability group. uv can default groups but not extras, so the observability group self-references the public otel/langfuse extras to pull them into the default-synced env. Regenerate uv.lock to record the new group. --- pyproject.toml | 12 ++++++++++++ uv.lock | 4 ++++ 2 files changed, 16 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index fe8b32af..a84ac1a9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -85,6 +85,18 @@ docs = [ examples = [ "openai>=1.40", ] +# Self-references the project's public otel + langfuse extras so the +# observability backends can be defaulted into the local env: uv can +# default dependency groups but not extras. +observability = ["openarmature[otel,langfuse]"] + +[tool.uv] +# Default-synced env for local work so a plain `uv run` (mkdocs +# serve, the examples, pytest) needs no per-command flags. Naming +# default-groups overrides uv's built-in ["dev"] default, hence "dev" +# is re-listed. The "observability" group carries the otel/langfuse +# extras, which uv otherwise can't default. +default-groups = ["dev", "docs", "examples", "observability"] [tool.hatch.build.targets.wheel] packages = ["src/openarmature"] diff --git a/uv.lock b/uv.lock index 0d560a87..ffc93c69 100644 --- a/uv.lock +++ b/uv.lock @@ -966,6 +966,9 @@ docs = [ examples = [ { name = "openai" }, ] +observability = [ + { name = "openarmature", extra = ["langfuse", "otel"] }, +] [package.metadata] requires-dist = [ @@ -1000,6 +1003,7 @@ docs = [ { name = "pymdown-extensions", specifier = ">=10.0,<11" }, ] examples = [{ name = "openai", specifier = ">=1.40" }] +observability = [{ name = "openarmature", extras = ["otel", "langfuse"] }] [[package]] name = "opentelemetry-api" From 31f3e659893946c85535c4412e54c046ae444d2f Mon Sep 17 00:00:00 2001 From: chris-colinsky Date: Thu, 28 May 2026 17:38:02 -0700 Subject: [PATCH 3/3] Regenerate bundled agent docs for pattern titles The de-hyphenate commit changed docs/patterns/ H1s but not the artifacts generated from them: src/openarmature/AGENTS.md and the src/openarmature/_patterns/ copies the patterns API serves. The drift test caught the mismatch in CI. Regenerate both via scripts/build_agents_md.py so the bundled recipe titles match the docs. Pattern slugs (filenames / API keys) are unchanged. --- src/openarmature/AGENTS.md | 6 +++--- src/openarmature/_patterns/bypass-if-output-exists.md | 2 +- src/openarmature/_patterns/session-as-checkpoint-resume.md | 2 +- src/openarmature/_patterns/tool-dispatch-as-node.md | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/openarmature/AGENTS.md b/src/openarmature/AGENTS.md index d000d97a..67e614b3 100644 --- a/src/openarmature/AGENTS.md +++ b/src/openarmature/AGENTS.md @@ -402,7 +402,7 @@ treats fetch and render as separable. _Recipes that compose the primitives. Not framework contracts — these are how to do common things idiomatically._ -### Bypass-if-output-exists +### Bypass if output exists **Problem.** How do I skip a node whose external output already exists? @@ -614,7 +614,7 @@ fields the chosen branch needs) and the graph routes accordingly. - [Checkpointing](https://openarmature.ai/concepts/checkpointing/) - Spec: [graph-engine](https://openarmature.org/capabilities/graph-engine/) -### Session-as-checkpoint-resume +### Session as checkpoint resume **Problem.** How do I keep multi-turn agent state across turns? @@ -729,7 +729,7 @@ state and the session table holds the join keys. single-resume baseline. - Spec: [pipeline-utilities](https://openarmature.org/capabilities/pipeline-utilities/) -### Tool-dispatch-as-node +### Tool dispatch as node **Problem.** How do I run an agent tool-call loop? diff --git a/src/openarmature/_patterns/bypass-if-output-exists.md b/src/openarmature/_patterns/bypass-if-output-exists.md index ff7b4532..6b0f215f 100644 --- a/src/openarmature/_patterns/bypass-if-output-exists.md +++ b/src/openarmature/_patterns/bypass-if-output-exists.md @@ -1,4 +1,4 @@ -# Bypass-if-output-exists +# Bypass if output exists **Problem.** How do I skip a node whose external output already exists? diff --git a/src/openarmature/_patterns/session-as-checkpoint-resume.md b/src/openarmature/_patterns/session-as-checkpoint-resume.md index 28c00c5d..84390bd6 100644 --- a/src/openarmature/_patterns/session-as-checkpoint-resume.md +++ b/src/openarmature/_patterns/session-as-checkpoint-resume.md @@ -1,4 +1,4 @@ -# Session-as-checkpoint-resume +# Session as checkpoint resume **Problem.** How do I keep multi-turn agent state across turns? diff --git a/src/openarmature/_patterns/tool-dispatch-as-node.md b/src/openarmature/_patterns/tool-dispatch-as-node.md index 3d201692..6ed6bc59 100644 --- a/src/openarmature/_patterns/tool-dispatch-as-node.md +++ b/src/openarmature/_patterns/tool-dispatch-as-node.md @@ -1,4 +1,4 @@ -# Tool-dispatch-as-node +# Tool dispatch as node **Problem.** How do I run an agent tool-call loop?