Add Patterns docs section with 4 seed patterns#67
Merged
Conversation
Add docs/patterns/, sibling to Concepts, seeded with four recipes from downstream usage: parameterized entry point, tool-dispatch- as-node, session-as-checkpoint-resume, and bypass-if-output-exists. Each page follows a problem / approach / snippet / when-right-and- when-not / cross-references structure. Patterns are user-level how-to recipes composing existing primitives, not framework contracts; new patterns can be added without spec coordination. Updates mkdocs.yml nav (Patterns between Concepts and Examples) and the llmstxt plugin sections. CHANGELOG notes the addition under Unreleased.
There was a problem hiding this comment.
Pull request overview
Adds a new “Patterns” section to the MkDocs documentation site, intended to provide user-level recipes that compose existing OpenArmature primitives (rather than introducing new framework contracts).
Changes:
- Adds
docs/patterns/with an index page and 4 seeded pattern pages. - Updates
mkdocs.ymlnav andllmstxtplugin sections so Patterns appear in site navigation and/llms-full.txt. - Adds an “[Unreleased]” changelog entry for the new docs section.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| mkdocs.yml | Adds Patterns to nav and to llmstxt sections so they render and export. |
| docs/patterns/index.md | Introduces the Patterns section and catalog links. |
| docs/patterns/parameterized-entry-point.md | Documents a state-driven “router” entry pattern (snippet currently has runnable-code issues). |
| docs/patterns/tool-dispatch-as-node.md | Documents an agent tool loop pattern (snippet currently has type/validity issues). |
| docs/patterns/session-as-checkpoint-resume.md | Documents multi-turn state via resume (snippet currently has API mismatch issues). |
| docs/patterns/bypass-if-output-exists.md | Documents output-bypass middleware pattern. |
| CHANGELOG.md | Notes the addition of the Patterns docs section. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Pattern 1: clarify the router lambda's inline comment so a reader who lands mid-snippet without the surrounding prose still sees the intent. Pattern 3: switch state messages to list[Message] for consistency with pattern 2, add the Message import, and use attribute access (.content) rather than dict subscript at the read site. Per spec review on PR #67.
Pattern 1 (parameterized-entry-point): convert plan, execute,
report to async def to match GraphBuilder.add_node's signature
(Callable[[StateT], Awaitable[...]]); replace the inline router
lambda with a named async router function since lambdas cannot
be async.
Pattern 2 (tool-dispatch-as-node): replace the set-literal
parameters={...} with a minimal JSON Schema dict; add import json
and serialize non-string tool outputs before constructing
ToolMessage, since ToolMessage.content is typed str.
Pattern 3 (session-as-checkpoint-resume): SQLiteCheckpointer's
constructor parameter is path, not db_path.
CHANGELOG: align the structure phrasing with the actual page
headings (when this is the right pattern / when it isn't).
SQLiteCheckpointer's constructor parameter is path, not db_path. Same typo as the patterns snippet flagged in PR review; surfaced while grepping for other occurrences. The tests and examples reference a local variable named db_path but pass it positionally (or via path=db_path), which is correct. This concept page is the only remaining spot using db_path= as a kwarg.
Match the convention in docs/concepts/state-and-reducers.md.
Pattern 2 and pattern 3 State models had list/dict fields with
mutable defaults (=[], ={}); convert to Field(default_factory=...)
and import Field from pydantic.
Patterns 1 and 4 have no mutable defaults so they're unchanged.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/patterns/, sibling to Concepts in the site navmkdocs.ymlnav (Patterns between Concepts and Examples) and themkdocs-llmstxtplugin sections so patterns also surface in/llms-full.txt[Unreleased]Patterns are user-level how-to recipes composing existing primitives, not framework contracts. New patterns can be added without spec coordination.
Test plan
uv run mkdocs build --strictsucceedshttp://127.0.0.1:8765/patterns/viauv run mkdocs servehttps://openarmature.ai/patterns/resolves and/llms-full.txtincludes the patterns content