From 93adb1494bec2020d85f7571b1e920407a1a7f40 Mon Sep 17 00:00:00 2001 From: chris-colinsky Date: Tue, 2 Jun 2026 10:18:45 -0700 Subject: [PATCH] Add source callout to example walk-through docs Inserts a Material ``!!! info "Source"`` admonition between the H1 and the lead paragraph on every example walk-through doc. The admonition links the page's main.py on the LunarCommand GitHub repo (``/blob/main/examples//main.py``), opening in a new tab via ``{target="_blank" rel="noopener"}``. Applied to all 13 walk-throughs (one callout each): chat-with-multimodal, checkpointing-and-migration, explicit-subgraph-mapping, fan-out-with-retry, hello-world, langfuse-observability, multimodal-prompt, nested-subgraphs, observer-hooks, parallel-branches, production-observability, routing-and-subgraphs, tool-use. Styling: overrides the default Material info-admonition accent to the project lavender (rgb(228, 193, 249)); inside the admonition, slate-theme link color shifts to the body-text gray (rgba(226, 228, 233, 0.82)) so the URL reads as content rather than as a highlighted action against the lavender backdrop. URLs use the LunarCommand org for now; will need a one-line perl substitution after the OpenArmature org move per the project_org_move_to_openarmature memory. --- docs/examples/chat-with-multimodal.md | 3 ++ docs/examples/checkpointing-and-migration.md | 3 ++ docs/examples/explicit-subgraph-mapping.md | 3 ++ docs/examples/fan-out-with-retry.md | 3 ++ docs/examples/hello-world.md | 3 ++ docs/examples/langfuse-observability.md | 3 ++ docs/examples/multimodal-prompt.md | 3 ++ docs/examples/nested-subgraphs.md | 3 ++ docs/examples/observer-hooks.md | 3 ++ docs/examples/parallel-branches.md | 3 ++ docs/examples/production-observability.md | 3 ++ docs/examples/routing-and-subgraphs.md | 3 ++ docs/examples/tool-use.md | 3 ++ docs/stylesheets/extra.css | 37 ++++++++++++++++++++ 14 files changed, 76 insertions(+) diff --git a/docs/examples/chat-with-multimodal.md b/docs/examples/chat-with-multimodal.md index 1089ecd5..feda8f99 100644 --- a/docs/examples/chat-with-multimodal.md +++ b/docs/examples/chat-with-multimodal.md @@ -1,5 +1,8 @@ # Chat with multi-turn memory and a multimodal turn +!!! info "Source" + [https://github.com/LunarCommand/openarmature-python/blob/main/examples/chat-with-multimodal/main.py](https://github.com/LunarCommand/openarmature-python/blob/main/examples/chat-with-multimodal/main.py){target="_blank" rel="noopener"} + A lunar-mission Q&A assistant that maintains conversation context across four turns. One mid-conversation turn includes an attached photograph (Apollo 16 Lunar Module "Orion" on the lunar surface): diff --git a/docs/examples/checkpointing-and-migration.md b/docs/examples/checkpointing-and-migration.md index f477f953..6d090613 100644 --- a/docs/examples/checkpointing-and-migration.md +++ b/docs/examples/checkpointing-and-migration.md @@ -1,5 +1,8 @@ # Checkpointing and migration +!!! info "Source" + [https://github.com/LunarCommand/openarmature-python/blob/main/examples/checkpointing-and-migration/main.py](https://github.com/LunarCommand/openarmature-python/blob/main/examples/checkpointing-and-migration/main.py){target="_blank" rel="noopener"} + A lunar-mission planning pipeline that writes a SQLite checkpoint after every step, survives a simulated mid-pipeline crash, and then resumes the saved invocation under an upgraded state schema with a diff --git a/docs/examples/explicit-subgraph-mapping.md b/docs/examples/explicit-subgraph-mapping.md index aad6f717..1064234d 100644 --- a/docs/examples/explicit-subgraph-mapping.md +++ b/docs/examples/explicit-subgraph-mapping.md @@ -1,5 +1,8 @@ # Explicit subgraph mapping +!!! info "Source" + [https://github.com/LunarCommand/openarmature-python/blob/main/examples/explicit-subgraph-mapping/main.py](https://github.com/LunarCommand/openarmature-python/blob/main/examples/explicit-subgraph-mapping/main.py){target="_blank" rel="noopener"} + Compare two topics by running the *same* compiled analysis subgraph on each, with each call site writing into disjoint parent fields. This is the canonical use of `ExplicitMapping`. diff --git a/docs/examples/fan-out-with-retry.md b/docs/examples/fan-out-with-retry.md index 0597c21f..a9455092 100644 --- a/docs/examples/fan-out-with-retry.md +++ b/docs/examples/fan-out-with-retry.md @@ -1,5 +1,8 @@ # Fan-out with retry +!!! info "Source" + [https://github.com/LunarCommand/openarmature-python/blob/main/examples/fan-out-with-retry/main.py](https://github.com/LunarCommand/openarmature-python/blob/main/examples/fan-out-with-retry/main.py){target="_blank" rel="noopener"} + Summarize a batch of lunar-mission headlines in parallel, with per-headline retry and timing middleware wrapping each instance's subgraph run. diff --git a/docs/examples/hello-world.md b/docs/examples/hello-world.md index e17dbd60..b1b8c7ff 100644 --- a/docs/examples/hello-world.md +++ b/docs/examples/hello-world.md @@ -1,5 +1,8 @@ # Hello, world +!!! info "Source" + [https://github.com/LunarCommand/openarmature-python/blob/main/examples/hello-world/main.py](https://github.com/LunarCommand/openarmature-python/blob/main/examples/hello-world/main.py){target="_blank" rel="noopener"} + The smallest possible LLM-routed pipeline: classify a query, then either plan research on it or summarize it in one sentence. Sets the shape every other example builds on. diff --git a/docs/examples/langfuse-observability.md b/docs/examples/langfuse-observability.md index d0aee2ef..6e74d9c9 100644 --- a/docs/examples/langfuse-observability.md +++ b/docs/examples/langfuse-observability.md @@ -1,5 +1,8 @@ # Langfuse observability +!!! info "Source" + [https://github.com/LunarCommand/openarmature-python/blob/main/examples/langfuse-observability/main.py](https://github.com/LunarCommand/openarmature-python/blob/main/examples/langfuse-observability/main.py){target="_blank" rel="noopener"} + Send LLM call observability to Langfuse natively: Trace at the top, Span observations for graph nodes, Generation observations with input, output, token usage, model parameters, and a native link back to the diff --git a/docs/examples/multimodal-prompt.md b/docs/examples/multimodal-prompt.md index fb9cd661..786f4c81 100644 --- a/docs/examples/multimodal-prompt.md +++ b/docs/examples/multimodal-prompt.md @@ -1,5 +1,8 @@ # Multimodal prompt +!!! info "Source" + [https://github.com/LunarCommand/openarmature-python/blob/main/examples/multimodal-prompt/main.py](https://github.com/LunarCommand/openarmature-python/blob/main/examples/multimodal-prompt/main.py){target="_blank" rel="noopener"} + Two independent analyses of a lunar-mission photograph using versioned prompt templates, a fallback prompt backend, and a multimodal user message that carries both text and image. diff --git a/docs/examples/nested-subgraphs.md b/docs/examples/nested-subgraphs.md index 8f6641cc..8e8601a4 100644 --- a/docs/examples/nested-subgraphs.md +++ b/docs/examples/nested-subgraphs.md @@ -1,5 +1,8 @@ # Nested subgraphs +!!! info "Source" + [https://github.com/LunarCommand/openarmature-python/blob/main/examples/nested-subgraphs/main.py](https://github.com/LunarCommand/openarmature-python/blob/main/examples/nested-subgraphs/main.py){target="_blank" rel="noopener"} + Question answering against a tiny baked-in document corpus, with two levels of subgraph nesting: outer coordinator, middle doc-QA, inner section-extract. diff --git a/docs/examples/observer-hooks.md b/docs/examples/observer-hooks.md index e9707bd5..8be02319 100644 --- a/docs/examples/observer-hooks.md +++ b/docs/examples/observer-hooks.md @@ -1,5 +1,8 @@ # Observer hooks +!!! info "Source" + [https://github.com/LunarCommand/openarmature-python/blob/main/examples/observer-hooks/main.py](https://github.com/LunarCommand/openarmature-python/blob/main/examples/observer-hooks/main.py){target="_blank" rel="noopener"} + Add observability to a `draft → review → finalize` pipeline without touching any node code. Three observer flavors run side-by-side: a console tracer, a per-invocation metrics collector, and the diff --git a/docs/examples/parallel-branches.md b/docs/examples/parallel-branches.md index 618dd5ca..e73ee837 100644 --- a/docs/examples/parallel-branches.md +++ b/docs/examples/parallel-branches.md @@ -1,5 +1,8 @@ # Parallel branches +!!! info "Source" + [https://github.com/LunarCommand/openarmature-python/blob/main/examples/parallel-branches/main.py](https://github.com/LunarCommand/openarmature-python/blob/main/examples/parallel-branches/main.py){target="_blank" rel="noopener"} + Enrich a lunar-mission news article with three independent analyses (one-sentence summary, sentiment label, topic tags) running concurrently as separate subgraphs. diff --git a/docs/examples/production-observability.md b/docs/examples/production-observability.md index 681c7ec6..2dedec6d 100644 --- a/docs/examples/production-observability.md +++ b/docs/examples/production-observability.md @@ -1,5 +1,8 @@ # Production observability with dual observers and timing middleware +!!! info "Source" + [https://github.com/LunarCommand/openarmature-python/blob/main/examples/production-observability/main.py](https://github.com/LunarCommand/openarmature-python/blob/main/examples/production-observability/main.py){target="_blank" rel="noopener"} + A single-turn lunar-mission Q&A endpoint instrumented the way you'd ship it: BOTH OTel and Langfuse observers attached to the same graph, caller hooks deriving domain-shaped `trace.input` / diff --git a/docs/examples/routing-and-subgraphs.md b/docs/examples/routing-and-subgraphs.md index 2721b3e8..c69c8b9d 100644 --- a/docs/examples/routing-and-subgraphs.md +++ b/docs/examples/routing-and-subgraphs.md @@ -1,5 +1,8 @@ # Routing and subgraphs +!!! info "Source" + [https://github.com/LunarCommand/openarmature-python/blob/main/examples/routing-and-subgraphs/main.py](https://github.com/LunarCommand/openarmature-python/blob/main/examples/routing-and-subgraphs/main.py){target="_blank" rel="noopener"} + A question-answering assistant. Classify the question, then either give a one-shot quick answer or run a multi-step research sub-pipeline, then lightly copy-edit the result. diff --git a/docs/examples/tool-use.md b/docs/examples/tool-use.md index c507f516..efcb8430 100644 --- a/docs/examples/tool-use.md +++ b/docs/examples/tool-use.md @@ -1,5 +1,8 @@ # Tool use +!!! info "Source" + [https://github.com/LunarCommand/openarmature-python/blob/main/examples/tool-use/main.py](https://github.com/LunarCommand/openarmature-python/blob/main/examples/tool-use/main.py){target="_blank" rel="noopener"} + A lunar-mission assistant that calls local Python tools to answer questions mixing fact recall and physics arithmetic about Apollo and Artemis missions. diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index be908956..d5b5d9c1 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -285,6 +285,43 @@ padding-left: 0.75rem; } +/* Source-box callout color (the ``!!! info "Source"`` admonition + * inserted between the H1 and lead paragraph on every example + * walk-through doc). Material's default ``info`` admonition uses + * a blue accent; this override paints it in the project lavender + * to match the ``#9d4edd`` brand purple and inline-code color + * (``#e4c1f9`` ≈ rgb(228, 193, 249)) used elsewhere in the slate + * theme. Scoped to ``.admonition.info``; currently the only + * ``!!! info`` usage in the docs is the Source callout, so this + * effectively styles "the Source box". If a future doc adds a + * non-Source info admonition that should stay blue, switch the + * walk-through callouts to a custom ``!!! source`` type and + * re-scope this rule to ``.admonition.source``. */ +.md-typeset .admonition.info, +.md-typeset details.info { + border-color: rgb(228, 193, 249); +} + +.md-typeset .admonition.info > .admonition-title, +.md-typeset details.info > summary { + background-color: rgba(228, 193, 249, 0.1); +} + +.md-typeset .admonition.info > .admonition-title::before, +.md-typeset details.info > summary::before { + background-color: rgb(228, 193, 249); +} + +/* Source-box link color (slate theme). The default slate link + * color (``#9d4edd`` purple) clashes with the lavender source-box + * accent; switch the link inside the source admonition to the + * dark-theme body-text tone so the URL reads as content rather + * than as a highlighted action. Selector specificity beats the + * general ``[data-md-color-scheme="slate"] .md-typeset a`` rule. */ +[data-md-color-scheme="slate"] .md-typeset .admonition.info a { + color: rgba(226, 228, 233, 0.82); +} + /* The vertical guide line, rendered as a ::before pseudo-element * (so it can stop 5px short of the nav's bottom edge via * ``top: 0; bottom: 5px``). Scoped to any sub-section whose nested