From 91b97eccef05bd265b7f84a4c42defebbc54165b Mon Sep 17 00:00:00 2001 From: chris-colinsky Date: Tue, 2 Jun 2026 09:43:23 -0700 Subject: [PATCH] Scrub proposal/spec refs from example walk-throughs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Extends feedback_examples_no_spec_refs.md (which targets example source files) to the docs/examples/ walk-throughs. Drops every ``proposal NNNN``, ``spec §N.N.N``, and ``spec v0.NN.0`` reference from four files; concept-link targets stay intact, only the parenthetical citation labels and explanatory phrases pointing at spec sections come out. Replacement link text uses descriptive user-facing language ("no double-export between them", "deriving domain dicts from State", "caller metadata and reserved keys", "the caller-metadata API"). Affected files: - docs/examples/chat-with-multimodal.md - docs/examples/fan-out-with-retry.md - docs/examples/langfuse-observability.md - docs/examples/production-observability.md Same spirit as the rename PR's "drop the NN- prefix from link text" pass: spec-process artifacts don't belong in user-facing docs; the underlying concept pages do. Future example walk- throughs should follow the same rule from the start. --- docs/examples/chat-with-multimodal.md | 6 +++--- docs/examples/fan-out-with-retry.md | 7 +++---- docs/examples/langfuse-observability.md | 2 +- docs/examples/production-observability.md | 14 +++++++------- 4 files changed, 14 insertions(+), 15 deletions(-) diff --git a/docs/examples/chat-with-multimodal.md b/docs/examples/chat-with-multimodal.md index 489dbf40..1089ecd5 100644 --- a/docs/examples/chat-with-multimodal.md +++ b/docs/examples/chat-with-multimodal.md @@ -34,9 +34,9 @@ turn's `render()` injects the grown history into the placeholder. - [`ChatPrompt`](../concepts/prompts.md) with [`ContentSegment`](../concepts/prompts.md) and - [`PlaceholderSegment`](../concepts/prompts.md) (proposal 0046, - spec v0.38.0). The placeholder is how multi-turn chat history - shapes get injected at render time. + [`PlaceholderSegment`](../concepts/prompts.md). The placeholder + is how multi-turn chat history shapes get injected at render + time. - The same chat template can carry an [`ImageURLBlockTemplate`](../concepts/prompts.md) when the current user turn includes an image. The `content` field on the diff --git a/docs/examples/fan-out-with-retry.md b/docs/examples/fan-out-with-retry.md index d4b91fd9..0597c21f 100644 --- a/docs/examples/fan-out-with-retry.md +++ b/docs/examples/fan-out-with-retry.md @@ -59,10 +59,9 @@ normally. The `append` reducer's no-double-merge guarantee holds across resume because `completed` is a one-shot accumulator state. Composition with `instance_middleware` (retry): on resume, an -instance's `attempt_index` resets to 0 (a fresh retry budget) per -spec graph-engine §6's resume semantics. So a retry-exhausted -instance whose `in_flight` state was saved gets a fresh budget on -the resumed run. +instance's `attempt_index` resets to 0 (a fresh retry budget). So +a retry-exhausted instance whose `in_flight` state was saved gets +a fresh budget on the resumed run. See [Resume semantics in fan-out](../concepts/fan-out.md#resume-semantics) and the [Checkpointing concept page](../concepts/checkpointing.md) diff --git a/docs/examples/langfuse-observability.md b/docs/examples/langfuse-observability.md index 1a5c4ccb..d0aee2ef 100644 --- a/docs/examples/langfuse-observability.md +++ b/docs/examples/langfuse-observability.md @@ -98,7 +98,7 @@ Trace id=01234567-89ab-... - **Trace name = entry node name** by default. The caller-supplied invocation-label path (a per-`invoke()` argument that overrides the - default) ships with proposal 0034's caller-metadata work. + default) is part of the caller-metadata API. - **Span observation per node.** `answer_briefing` is the only node here; a multi-node graph would produce a tree of nested Span observations under the Trace. diff --git a/docs/examples/production-observability.md b/docs/examples/production-observability.md index cc504f33..681c7ec6 100644 --- a/docs/examples/production-observability.md +++ b/docs/examples/production-observability.md @@ -22,10 +22,10 @@ answer. The interesting part is the observability wiring: - Both observers consume the same `NodeEvent` stream independently; node code never knows there are two backends. - `LangfuseObserver` carries `trace_input_from_state` and - `trace_output_from_state` caller hooks (proposal 0043 §8.4.1) - that derive domain dicts like `{"question": ...}` / - `{"answer": ..., "model": ...}` from State, instead of letting - the observer dump the raw State object. + `trace_output_from_state` caller hooks that derive domain dicts + like `{"question": ...}` / `{"answer": ..., "model": ...}` from + State, instead of letting the observer dump the raw State + object. - `TimingMiddleware` (canonical, from `openarmature.graph.middleware`) wraps the respond node. An `on_complete` async callback receives a `TimingRecord` and @@ -42,14 +42,14 @@ sees the same logical events represented two ways. ## What it teaches - **Two observers on one graph** - ([proposal 0031 + the no-double-export claim](../concepts/observability.md)). + ([no double-export between them](../concepts/observability.md)). Each consumes the `NodeEvent` stream independently; the engine fans events out to all attached observers. Production deployments often run both: OTel for infrastructure-side correlation (logs, distributed tracing across services), Langfuse for LLM-aware generation rendering. - **Caller hooks for `trace.input` / `trace.output`** - ([proposal 0043, observability §8.4.1](../concepts/observability.md)). + ([deriving domain dicts from State](../concepts/observability.md)). Without the hooks the Langfuse observer either omits the field (`disable_state_payload=True` default) or dumps the raw State (when `disable_state_payload=False`). The hooks let you return a @@ -63,7 +63,7 @@ sees the same logical events represented two ways. callback fires inline before the chain's result reaches the engine; keep it fast (queue work, defer I/O). - **`invoke(metadata={...})` propagation across observers** - ([proposal 0034 + 0041 reserved keys](../concepts/observability.md)). + ([caller metadata and reserved keys](../concepts/observability.md)). One call site, both backends pick it up: OTel attaches each entry as `openarmature.user.` cross-cutting span attribute, Langfuse merges as top-level `trace.metadata` keys plus