docs: complete reference, add middleware page#57
Merged
Conversation
The mkdocstrings reference was silently omitting public members that had no docstring. Add docstrings to 35 affected members across graph, prompts, and checkpoint so every name in __all__ renders in the reference. Add a new Middleware concept page covering the protocol shape, the four registration sites, composition order, subgraph boundary, error semantics, and the built-in RetryMiddleware and TimingMiddleware. Place it between Composition and Fan-out in the nav since both reference middleware concepts. Export NextCall and default_classifier from openarmature.graph so custom middleware can type its `next_` parameter and extend the retry classifier without reaching into the submodule. Change FanOutNode.run and ParallelBranchesNode.run to raise NotImplementedError instead of RuntimeError. Both methods exist only to satisfy the Node protocol; the engine dispatches these node types through run_with_context. NotImplementedError is the right signal and stays backwards-compatible since it subclasses RuntimeError. Sweep em dashes from public docstrings (155 occurrences across 34 files). Docstrings render in mkdocstrings; comments don't, and are left untouched.
![github-code-quality[bot]](https://avatars.githubusercontent.com/u/9919?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull request overview
This PR improves the completeness and usability of the project documentation by ensuring all public API members render in mkdocstrings, adding a new “Middleware” concept page, and making a couple of small API-surface adjustments to support middleware authors.
Changes:
- Added/updated docstrings across
graph,prompts,checkpoint,llm, andobservabilityso mkdocstrings includes all public__all__members. - Added a new Middleware concept page and linked it into the MkDocs nav and concepts index.
- Re-exported
NextCallanddefault_classifierfromopenarmature.graph, and adjusted fan-out / parallel-branchesrun()stubs to raiseNotImplementedError.
Reviewed changes
Copilot reviewed 43 out of 43 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| src/openarmature/init.py | Docstring punctuation tweak. |
| src/openarmature/prompts/init.py | Docstring punctuation tweak. |
| src/openarmature/prompts/backend.py | Added PromptBackend.fetch docstring for reference rendering. |
| src/openarmature/prompts/group.py | Docstring punctuation tweak. |
| src/openarmature/prompts/manager.py | Docstring formatting tweaks for rendered reference. |
| src/openarmature/prompts/backends/filesystem.py | Added fetch docstring; docstring punctuation tweaks. |
| src/openarmature/observability/init.py | Docstring punctuation/format tweaks. |
| src/openarmature/observability/correlation.py | Docstring punctuation/format tweaks. |
| src/openarmature/observability/otel/init.py | Docstring punctuation/format tweaks. |
| src/openarmature/observability/otel/logs.py | Docstring punctuation/format tweaks. |
| src/openarmature/observability/otel/observer.py | Docstring punctuation/format tweaks. |
| src/openarmature/llm/init.py | Docstring punctuation tweak. |
| src/openarmature/llm/errors.py | Error-class docstring punctuation tweaks. |
| src/openarmature/llm/messages.py | Docstring punctuation tweaks (list-level invariants section). |
| src/openarmature/llm/provider.py | Docstring punctuation/format tweaks. |
| src/openarmature/llm/response.py | Docstring punctuation tweak. |
| src/openarmature/llm/providers/init.py | Docstring punctuation tweak. |
| src/openarmature/llm/providers/openai.py | Docstring punctuation tweaks. |
| src/openarmature/graph/init.py | Re-export NextCall/default_classifier via package API surface. |
| src/openarmature/graph/builder.py | Added docstrings for key builder methods to appear in reference docs. |
| src/openarmature/graph/compiled.py | Docstring punctuation tweaks. |
| src/openarmature/graph/edges.py | Docstring punctuation tweak. |
| src/openarmature/graph/errors.py | Added docstrings for error types to render in reference docs. |
| src/openarmature/graph/events.py | Docstring punctuation/format tweaks. |
| src/openarmature/graph/fan_out.py | FanOutNode.run now raises NotImplementedError + added docstring. |
| src/openarmature/graph/nodes.py | Added FunctionNode.run docstring. |
| src/openarmature/graph/observer.py | Added/adjusted docstrings for observer protocols/handles. |
| src/openarmature/graph/parallel_branches.py | ParallelBranchesNode.run now raises NotImplementedError + added docstring. |
| src/openarmature/graph/projection.py | Added docstrings for projection strategy methods to render in reference docs. |
| src/openarmature/graph/subgraph.py | Docstring punctuation tweaks (subgraph typing explanation). |
| src/openarmature/graph/middleware/init.py | Docstring punctuation tweak; re-export list includes NextCall and classifier helpers. |
| src/openarmature/graph/middleware/_core.py | Docstring punctuation tweaks describing chain composition and protocol semantics. |
| src/openarmature/graph/middleware/retry.py | Docstring punctuation tweaks for retry semantics/classifier/backoff. |
| src/openarmature/graph/middleware/timing.py | Docstring punctuation tweak. |
| src/openarmature/checkpoint/init.py | Docstring punctuation tweak. |
| src/openarmature/checkpoint/errors.py | Docstring punctuation tweaks for checkpoint error types. |
| src/openarmature/checkpoint/migration.py | Added registry method docstring; punctuation tweaks. |
| src/openarmature/checkpoint/protocol.py | Docstring punctuation/format tweaks for protocol records. |
| src/openarmature/checkpoint/backends/memory.py | Added backend method docstrings for reference rendering. |
| src/openarmature/checkpoint/backends/sqlite.py | Added backend method docstrings for reference rendering; punctuation tweaks. |
| mkdocs.yml | Added Middleware page to nav. |
| docs/concepts/index.md | Linked to new Middleware concept page. |
| docs/concepts/middleware.md | New middleware concept documentation page. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The em-dash sweep replaced double em-dashes used as parenthetical
brackets ("X -- inner -- Y") with two semicolons ("X; inner; Y"),
producing grammatically broken sentences in five public docstrings.
Switch the affected sites to parentheses or a colon/period
restructuring as appropriate.
Affected docstrings:
- llm/messages.py (Message module: list-level invariants)
- graph/subgraph.py (module: outer graph sees run(state: ParentT))
- graph/compiled.py (CompiledGraph: observer plumbing)
- checkpoint/protocol.py (CheckpointRecord: frozen)
- observability/otel/logs.py (install_log_bridge: filters note)
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
__all__acrossgraph,prompts, andcheckpoint. Before this,add_node,add_edge,set_entry,compile, and the in-memory / SQLite checkpointer methods (among others) were invisible to anyone reading the docs.RetryMiddleware/TimingMiddleware. Nav placement: between Composition and Fan-out, since both reference middleware concepts.NextCallanddefault_classifierfromopenarmature.graphso custom middleware can type itsnext_parameter and extend the retry classifier without reaching into the submodule.FanOutNode.runandParallelBranchesNode.runnow raiseNotImplementedErrorinstead ofRuntimeError. Both methods exist only to satisfy theNodeprotocol; the engine dispatches these node types throughrun_with_context.NotImplementedErroris the right signal and stays backwards-compatible since it subclassesRuntimeError.#comments don't and are left untouched.Test plan
uv run pytest tests/(697 pass, 64 skip)uv run pyright src/(0 errors)uv run ruff check src/(clean)uv run mkdocs buildsucceedsuv run mkdocs serveand visit/concepts/middleware/,/reference/graph/,/reference/prompts/,/reference/checkpoint/— confirm new docstrings render and Middleware page looks rightfrom openarmature.graph import NextCall, default_classifierworks