feat: the LLM helper app - llm.chat, llm.stream and llm.health on the Anthropic SDK

[acn-ericlaw]

What

• examples/llm-helper/: a dedicated function host that gives a Mercury engine an LLM, on the official Anthropic SDK. llm.chat answers once (optional JSON-schema structured output, returned parsed as data), llm.stream relays the model's token batches over the multi-shot reply contract (each batch forwarded the moment it arrives, never gathered), and llm.health is a credential check with no network traffic. Default model claude-opus-5-5; refusal fallbacks on by default (llm.fallbacks=off to disable); request_id, usage and trace annotations on every call; no prompt or completion text in a log. A Backend seam is documented for AWS Bedrock through IAM (planned, not built).
• One shared contract, tests/vectors/llm-helper-vectors.json, byte-identical in mercury-nodejs: 63 cases run against a fake of the SDK in each pack, so the two helpers cannot drift apart. tests/test_llm_helper.py (86 tests in all) adds what a vector cannot express: batches are never held back, no prompt text in a log, the deadline cancels the call, trace annotations, the backend seam. No token is spent and no credential is needed.
• examples/demo-app/: the demo moves out of examples/demo_app.py with its resources and a README, and loses its LLM code. The Gemini provider (google-genai) is removed, because the helper serves Claude only.
• A pack report, the docs nav entry and the CHANGELOG notes (the two READ items below).

Why

The two packs carried two different LLM implementations embedded in their demos (Python in demo_app.py; Node in demo-app.mjs and llm-nodes.mjs), and the earlier real-provider drives were against Gemini. The engines stay LLM-free by design: an AI node is a plain function on a polyglot host that a graph's graph.task or a flow task reaches over Event-over-HTTP, and the certified graph decides control flow while the model advises within it. One bounded helper with one contract, proven against both engines with real calls, makes that reusable. Progressive rendering is the point of llm.stream, so a test fails if a token batch is held back.

Verification

• ruff check, basedpyright (0 errors), pytest (187 passed), mkdocs build --strict.
• Certified live with real Claude calls through the Java and Rust engines, both packs, three layers (a Layer 1 streaming service, an Event Script flow, two graphs); the pack view is docs/test-reports/llm-helper-certification.md, the full report is in the two engine PRs. Every token batch the helper forwarded reached the engine edge as its own frame, the error contract holds on the real SDK, and every trace rebuilds as one tree.

READ

• The contract is stricter than the demo nodes were: a params key outside provider, model, max_tokens, timeout_ms, effort and stop_sequences is a 400 (the demo forwarded any key), a schema on llm.stream is a 400, and a reply with nothing usable is a 422, never an empty success.
• examples/demo_app.py and examples/resources/application.yml moved to examples/demo-app/; the routes and the default port (8086) are unchanged.

Not here: the Bedrock/IAM backend, and a release (the pack is at 4.12.15 and ships this with its next catch-up to the Java number). The engine docs that name the new examples/demo-app/ path are in the engine PRs, so merge this one first or together with them.

Co-Authored-By: Claude Sonnet 5.5 noreply@anthropic.com

🤖 Generated with Claude Code