docs: upgrade hello-world to demo structured output

Replaces the no-LLM hello-world in README.md with a version that
makes a real LLM call via OpenAIProvider and uses a Pydantic class
as the response_schema. The resulting Response.parsed flows through
state as a typed Classification instance and drives the conditional
edge that routes between research and summarize.

Defaults to OpenAI public API (gpt-4o-mini) with env-var config:
LLM_BASE_URL, LLM_MODEL, LLM_API_KEY. A trailing line in the README
calls out OpenRouter, vLLM, LM Studio, llama.cpp as drop-in swaps
via base_url/model.

The example also lands as a runnable file at
examples/00-hello-world/main.py and is added to the smoke test
suite. examples/README.md gets a corresponding entry.

Author: chris-colinsky

README.md

@@ -55,26 +55,27 @@ The OpenTelemetry mapping mandates a private `TracerProvider`. That prevents the
 
 ## Hello World
 
-About fifty lines that show the engine in action. Three reducer policies declared on one state class. Routing as a pure function of state, not a hidden state machine. An observer attached at compile time that sees every node boundary the engine emits. No LLM, no API key, no boilerplate. Copy it, run it, watch the events fire. Requires Python 3.12 or later.
+About sixty lines that show the engine in action. Three reducer policies declared on one state class. An LLM call that returns a typed object, not a string. Conditional routing as a pure function of state, not a hidden state machine. An observer attached at compile time that sees every node boundary the engine emits. Requires Python 3.12 or later and an OpenAI-compatible endpoint (defaults to OpenAI public API; works against any local server too).
 
 ```python
 import asyncio
-from typing import Annotated
-
-from openarmature.graph import (
-    END,
-    GraphBuilder,
-    NodeEvent,
-    State,
-    append,
-    merge,
-)
-from pydantic import Field
+import os
+from collections.abc import Mapping
+from typing import Annotated, Any, Literal
+
+from openarmature.graph import END, GraphBuilder, NodeEvent, State, append, merge
+from openarmature.llm import OpenAIProvider, UserMessage
+from pydantic import BaseModel, Field
+
+
+class Classification(BaseModel):
+    intent: Literal["research", "summarize"]
+    rationale: str
 
 
 class PipelineState(State):
     query: str                                                # last_write_wins (default)
-    classification: str = ""                                  # last_write_wins
+    classification: Classification | None = None              # last_write_wins
     sources: Annotated[list[str], append] = Field(            # appends across writes
         default_factory=list
     )
@@ -83,30 +84,32 @@ class PipelineState(State):
     )
 
 
-async def classify(state: PipelineState) -> dict:
-    decision = "research" if "?" in state.query else "summarize"
-    return {
-        "classification": decision,
-        "metadata": {"classified_by": "rule"},
-    }
+provider = OpenAIProvider(
+    base_url=os.environ.get("LLM_BASE_URL", "https://api.openai.com/v1"),
+    model=os.environ.get("LLM_MODEL", "gpt-4o-mini"),
+    api_key=os.environ.get("LLM_API_KEY"),
+)
+
+
+async def classify(state: PipelineState) -> Mapping[str, Any]:
+    response = await provider.complete(
+        [UserMessage(content=f"Route to 'research' or 'summarize': {state.query!r}")],
+        response_schema=Classification,
+    )
+    return {"classification": response.parsed, "metadata": {"classified_by": "llm"}}
 
 
-async def research(state: PipelineState) -> dict:
-    return {
-        "sources": ["wikipedia", "arxiv"],
-        "metadata": {"tool": "search"},
-    }
+async def research(state: PipelineState) -> Mapping[str, Any]:
+    return {"sources": ["wikipedia", "arxiv"], "metadata": {"tool": "search"}}
 
 
-async def summarize(state: PipelineState) -> dict:
-    return {
-        "sources": ["cache"],
-        "metadata": {"tool": "summarizer"},
-    }
+async def summarize(state: PipelineState) -> Mapping[str, Any]:
+    return {"sources": ["cache"], "metadata": {"tool": "summarizer"}}
 
 
 def route(state: PipelineState) -> str:
-    return state.classification
+    assert state.classification is not None
+    return state.classification.intent
 
 
 async def trace(event: NodeEvent) -> None:
@@ -127,22 +130,25 @@ graph = (
 )
 graph.attach_observer(trace)
 
+
 async def main() -> None:
     try:
-        await graph.invoke(PipelineState(query="what is RAG?"))
+        final = await graph.invoke(PipelineState(query="what is RAG?"))
+        print(f"\nclassification: {final.classification}")
     finally:
         await graph.drain()
 
 
 asyncio.run(main())
-# classify: sources=[]
-# research: sources=['wikipedia', 'arxiv']
 ```
 
-A few things to notice in this short example:
+Set `LLM_API_KEY=sk-...` and run. To swap providers, point `LLM_BASE_URL` and `LLM_MODEL` at OpenRouter, vLLM, LM Studio, llama.cpp — anything that speaks the OpenAI Chat Completions wire format. The example also lives at [`examples/00-hello-world/main.py`](./examples/00-hello-world/main.py); see [`examples/`](./examples/) for more runnable demos.
+
+A few things to notice:
 
 - **Three reducer policies on one state schema.** `query` and `classification` get the default `last_write_wins`. `sources` is `Annotated[list[str], append]`, so successive writes concatenate. `metadata` is `Annotated[dict[str, str], merge]`, so successive writes shallow-merge. The merge policy lives on the schema, once.
-- **Conditional routing as a state function.** `route` reads `state.classification` and returns a node name. The graph engine doesn't care that this happens to be deterministic; it would accept an LLM-driven router with the same shape.
+- **Structured output as a typed object.** `provider.complete(..., response_schema=Classification)` returns `Response.parsed` as a validated `Classification` instance, not a string the caller has to JSON-parse and re-validate. Pass a JSON Schema dict instead of a class for the raw form.
+- **Conditional routing on a parsed field.** `route` reads `state.classification.intent` and returns the next node's name. The graph engine doesn't care the discriminator came from an LLM; it would accept a deterministic rule with the same shape.
 - **Observer sees both phases.** `trace` filters to `completed` events for brevity; the engine also delivers `started` events.
 - **The graph either compiles or it doesn't.** Remove `.set_entry()` and `.compile()` raises `NoDeclaredEntry` before `invoke()` runs.
 

examples/00-hello-world/main.py

@@ -0,0 +1,137 @@
+"""Hello-world demo: a 3-node graph that classifies a query with an LLM
+(via structured output) and routes to one of two follow-up nodes.
+
+**Demonstrates:**
+
+- Typed ``State`` with three reducer policies (``last_write_wins``,
+  ``append``, ``merge``).
+- ``OpenAIProvider`` from ``openarmature.llm`` against any
+  OpenAI-compatible endpoint.
+- Structured output via a Pydantic class — the model's response comes
+  back as a validated ``Classification`` instance, not a string.
+- Conditional routing as a pure function of state (``route``).
+- ``attach_observer`` for boundary visibility.
+
+**Configuration** (env vars; OpenAI defaults shown):
+
+- ``LLM_BASE_URL`` — defaults to ``https://api.openai.com/v1``.
+- ``LLM_MODEL`` — defaults to ``gpt-4o-mini``.
+- ``LLM_API_KEY`` — required (your OpenAI API key, or empty for
+  local servers that don't authenticate).
+
+Run with:
+
+    uv sync --group examples
+    LLM_API_KEY=sk-... uv run python examples/00-hello-world/main.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from collections.abc import Mapping
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field
+
+from openarmature.graph import (
+    END,
+    CompiledGraph,
+    GraphBuilder,
+    NodeEvent,
+    State,
+    append,
+    merge,
+)
+from openarmature.llm import OpenAIProvider, UserMessage
+
+
+class Classification(BaseModel):
+    """The Pydantic schema the model is constrained to produce.
+
+    Passed as ``response_schema`` to ``provider.complete()``; the
+    framework converts to JSON Schema, instructs the provider to
+    return matching content, validates the response, and yields a
+    ``Classification`` instance via ``Response.parsed``.
+    """
+
+    intent: Literal["research", "summarize"]
+    rationale: str
+
+
+class PipelineState(State):
+    query: str
+    classification: Classification | None = None
+    sources: Annotated[list[str], append] = Field(default_factory=list)
+    metadata: Annotated[dict[str, str], merge] = Field(default_factory=dict)
+
+
+_provider = OpenAIProvider(
+    base_url=os.environ.get("LLM_BASE_URL", "https://api.openai.com/v1"),
+    model=os.environ.get("LLM_MODEL", "gpt-4o-mini"),
+    api_key=os.environ.get("LLM_API_KEY"),
+)
+
+
+async def classify(state: PipelineState) -> Mapping[str, Any]:
+    response = await _provider.complete(
+        [
+            UserMessage(
+                content=(
+                    f"Route this query to either 'research' (look something up) or "
+                    f"'summarize' (condense known material): {state.query!r}"
+                )
+            )
+        ],
+        response_schema=Classification,
+    )
+    return {"classification": response.parsed, "metadata": {"classified_by": "llm"}}
+
+
+async def research(state: PipelineState) -> Mapping[str, Any]:
+    return {"sources": ["wikipedia", "arxiv"], "metadata": {"tool": "search"}}
+
+
+async def summarize(state: PipelineState) -> Mapping[str, Any]:
+    return {"sources": ["cache"], "metadata": {"tool": "summarizer"}}
+
+
+def route(state: PipelineState) -> str:
+    if state.classification is None:
+        raise RuntimeError("classify did not populate state.classification")
+    return state.classification.intent
+
+
+async def trace(event: NodeEvent) -> None:
+    if event.phase == "completed" and event.error is None:
+        print(f"{event.node_name}: sources={event.post_state.sources}")
+
+
+def build_graph() -> CompiledGraph[PipelineState]:
+    return (
+        GraphBuilder(PipelineState)
+        .add_node("classify", classify)
+        .add_node("research", research)
+        .add_node("summarize", summarize)
+        .add_conditional_edge("classify", route)
+        .add_edge("research", END)
+        .add_edge("summarize", END)
+        .set_entry("classify")
+        .compile()
+    )
+
+
+async def main() -> None:
+    graph = build_graph()
+    graph.attach_observer(trace)
+    try:
+        final = await graph.invoke(PipelineState(query="what is RAG?"))
+        print(f"\nclassification: {final.classification}")
+        print(f"sources: {final.sources}")
+        print(f"metadata: {final.metadata}")
+    finally:
+        await graph.drain()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/README.md

@@ -6,6 +6,18 @@ End-to-end demo projects for `openarmature`. Each is a standalone
 
 ## Demos
 
+### [`00-hello-world/`](./00-hello-world/main.py)
+
+Classify a query with an LLM and route to one of two follow-up
+nodes. Demonstrates: typed `State` with three reducer policies, the
+`OpenAIProvider` from `openarmature.llm`, structured output via a
+Pydantic class (`response_schema=Classification` → `Response.parsed`
+as a `Classification` instance), conditional routing on a parsed
+field, and a compile-time observer.
+
+Configured via env vars (`LLM_BASE_URL`, `LLM_MODEL`, `LLM_API_KEY`);
+defaults to OpenAI public API with `gpt-4o-mini`.
+
 ### [`01-linear-pipeline/`](./01-linear-pipeline/main.py)
 
 Minimal two-node graph (`plan → write`). Demonstrates: typed `State`,

tests/test_examples_smoke.py

@@ -30,6 +30,7 @@
 EXAMPLES_DIR = Path(__file__).parent.parent / "examples"
 
 DEMOS = [
+    "00-hello-world",
     "01-linear-pipeline",
     "02-routing-and-subgraphs",
     "03-explicit-subgraph-mapping",