Docs: vLLM cookbook, non-obvious shapes, caller-metadata concept#87
Merged
Conversation
Adds five new "non-obvious shape" entries to docs/agent/non-obvious-shapes.md (regenerated into AGENTS.md): - Reconcile started → completed pairs via a per-invocation dict keyed on (namespace, attempt_index, fan_out_index). Closes downstream feedback item 4 (StepMetadataObserver reconciliation pattern). - Filter openarmature.*-namespaced events when the observer only cares about user nodes. Closes downstream feedback item 5 (sentinel-event noise in custom observers). - A with_state_migration recipe — register migrations alongside the state class, run on resume. Closes downstream feedback item 6. - Fan-out subgraphs that emit list[X] per instance produce list[list[X]] at target_field. Documents the gotcha plus a custom-reducer workaround; forward-references the spec v0.27.0 built-ins (concat_flatten, merge_all) not yet absorbed into the python impl. - invoke(metadata=...) for caller-supplied trace identifiers. Pairs with proposal 0034's new public surface. Adds a self-hosted vLLM cookbook page at docs/model-providers/vllm.md covering base_url shape (rejected /v1 suffix), authentication, genai_system="vllm" override, force_prompt_augmentation_fallback for older vLLM, readiness-probe limitations, and tool-calling. Linked from model-providers/index.md and mkdocs.yml nav. Adds a caller-supplied invocation metadata section to docs/concepts/observability.md (right after the correlation_id section), covering boundary validation, mid-invocation augmentation via set_invocation_metadata, and per-async-context COW isolation for fan-out instances. Fixes a stale comment in examples/00-hello-world/main.py that enumerated only three of RuntimeConfig's seven post-proposal-0032 declared fields. All 12 python snippets in docs/model-providers/vllm.md execute under the doc-examples test (916 passed, 129 skipped).
There was a problem hiding this comment.
Pull request overview
Documentation-focused PR that expands the “non-obvious shapes” cookbook, adds a vLLM provider cookbook page, and documents the new caller-supplied invocation metadata concept for observability.
Changes:
- Added 5 new “non-obvious shapes” recipes (and regenerated the bundled
src/openarmature/AGENTS.md). - Added a new “Self-hosted vLLM” cookbook page and linked it into the MkDocs nav.
- Expanded observability concepts docs with a new “Caller-supplied invocation metadata” section; refreshed a stale RuntimeConfig comment in example 00.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| src/openarmature/AGENTS.md | Regenerated bundled agent-facing docs with new “non-obvious shapes” content. |
| docs/agent/non-obvious-shapes.md | Added 5 new “non-obvious shapes” recipes (source for AGENTS regen). |
| docs/model-providers/vllm.md | New vLLM cookbook page with runnable snippets and deployment notes. |
| docs/model-providers/index.md | Linked new vLLM cookbook page from provider docs. |
| docs/concepts/observability.md | Documented caller-supplied invocation metadata (invoke-time + mid-invocation augmentation). |
| mkdocs.yml | Added vLLM page to MkDocs navigation. |
| examples/00-hello-world/main.py | Updated RuntimeConfig comment to list all current fields. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Reconciliation shape entry: add branch_name to the event-pair key. Per the NodeEvent docstring the unique tuple is (namespace, branch_name, fan_out_index, attempt_index, phase); omitting branch_name let two parallel-branches running the same subgraph collide. Fixed the heading, the prose, and the code example. - Filter-events shape entry: drop the incorrect claim that OA-internal events lack an invocation_id. invocation_id is set at invoke() entry before the deliver_loop task is created, so the observer reads it as non-None for both user-node and OA-internal events. The namespace-prefix check is the only correct filter. - vLLM 30-second example: construct the messages + config locals so the imports are referenced naturally, and run asyncio.run( main()) so the doc-examples test exercises provider construction + aclose() (network calls stay commented). - vLLM readiness section: document that ready() also consults the optional per-entry status field and raises ProviderModelNotLoaded on loading/not_loaded, then frame the warm-up workaround as the vLLM-specific fallback (vLLM's /v1/models omits status). AGENTS.md regenerated.
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
Five new "non-obvious shape" recipes + a self-hosted vLLM cookbook page + a caller-supplied metadata concept-page section + a stale-comment fix on example 00. All downstream-feedback-driven; no code touches the engine, observers, or providers.
Changes
docs/agent/non-obvious-shapes.md(regenerated into AGENTS.md)Five new entries:
started→completedpairs via a per-invocation dict keyed on(namespace, attempt_index, fan_out_index)— closes downstream feedback item 4.openarmature.*-namespaced events when the observer only cares about user nodes — closes downstream feedback item 5.with_state_migrationrecipe — register migrations alongside the state class, run on resume. Closes downstream feedback item 6.list[X]per instance producelist[list[X]]attarget_field— documents the gotcha + a custom-reducer workaround; forward-references the spec v0.27.0 built-ins (concat_flatten/merge_all) not yet absorbed into the python impl.invoke(metadata=...)for caller-supplied trace identifiers — pairs with proposal 0034's new public surface.docs/model-providers/vllm.md(new)Self-hosted vLLM cookbook covering:
base_urlshape (host root only, no/v1per the PR 3.8 validation)genai_system="vllm"for the observability layerforce_prompt_augmentation_fallback=Truefor older vLLM releasesRetry-After, streaming)Linked from
docs/model-providers/index.mdandmkdocs.ymlnav. All 12 python snippets execute under the doc-examples test.docs/concepts/observability.mdNew "Caller-supplied invocation metadata" section right after the existing correlation_id section, covering boundary validation, mid-invocation augmentation via
set_invocation_metadata, per-async-context COW scoping (fan-out instances).examples/00-hello-world/main.py:97Stale comment enumerated only three of RuntimeConfig's seven post-proposal-0032 declared fields; updated to enumerate all six (besides
temperaturewhich is set in the snippet).Test plan
ruff check/ruff format --checkcleanpyrightcleanmkdocs serve(worth eyeballing the vLLM page in the live nav)