CHANGELOG.md

Changelog

All notable changes to openarmature-python are documented in this file.

The format follows Keep a Changelog. The package follows Semantic Versioning; pre-1.0 minor bumps may carry behavioral changes per spec governance.

[0.9.0] — 2026-05-25

Added

• openarmature.patterns programmatic API. Two-function surface (list() -> list[str], get(name: str) -> str) exposing the same patterns content shipped in the bundled AGENTS.md. Each pattern is returned as a standalone markdown document: no heading demotion (patterns keep their original # Title), and relative ../concepts/...md / ../examples/...md / intra-pattern links are rewritten to absolute openarmature.ai URLs at build time so cross-references resolve outside the source tree. Useful for agents in sandboxed environments that can import openarmature but can't freely read arbitrary package paths. Content lives at src/openarmature/_patterns/<slug>.md, generated alongside the bundled AGENTS.md and drift-checked by tests/test_agents_md_drift.py. Unknown names raise KeyError with a message listing the known names.
• openarmature CLI registered as a [project.scripts] entry point with two subcommands:
  • openarmature init appends a discovery pointer block (the python -c "..." one-liner + openarmature docs recipe) into the current project's AGENTS.md and CLAUDE.md so agent sessions opening the project find the bundled OpenArmature docs. Creates files when absent, appends when they exist, and skips re-runs via a <!-- openarmature-init --> comment marker. Flags: --force (re-append despite the marker), --dry-run (print what would be written), --cwd PATH (operate against a path other than the current directory).
  • openarmature docs prints the absolute path to the bundled AGENTS.md. Equivalent to the README discovery one-liner but ergonomic to type and remember.
  • The same surface is reachable as python -m openarmature ... via src/openarmature/__main__.py, so environments where the [project.scripts] entry doesn't land cleanly (some pip install --target layouts, path-shadowed venvs) still work as long as the package is importable.
• Bundled agent documentation at openarmature/AGENTS.md. The wheel now ships a generated AGENTS.md file at the installed package root, agent-discoverable via python -c "import openarmature; print(openarmature.__path__[0] + '/AGENTS.md')". Sections include a TL;DR, capability summaries pulled from the pinned spec submodule's §1 (Purpose) + §2 (Concepts), the patterns docs, hand-written non-obvious-shapes recipes, and a one-line example index. Generator lives at scripts/build_agents_md.py; the committed file is CI-drift-checked by tests/test_agents_md_drift.py. The submodule pin discipline (build refuses unless the submodule HEAD is AT a v* tag via git tag --points-at HEAD) prevents draft (untagged) spec text — or text from a commit between two release tags — from leaking into a release bundle. Adopting projects can point their own AGENTS.md / CLAUDE.md at this path so agent sessions in their codebase find it automatically (or use openarmature init to do the wiring automatically).
• FanOutInstanceProgress.result_is_error field (proposal 0027, accepted in spec v0.21.0). Explicit boolean discriminator on each per-instance entry in CheckpointRecord.fan_out_progress — True for collect-mode error contributions (roll forward into errors_field), False for success contributions (roll forward into target_field). The engine reads the explicit field on resume rather than inferring routing from result's shape; the previous structural heuristic (_looks_like_error_record) is removed. Backward-compat path on load: pre-0027 records that omit the key default to False.
• Strict CheckpointRecordInvalid on fan-out count drift (proposal 0029, accepted in spec v0.22.0). When the resumed run's resolved instance count differs from the saved fan_out_progress entry's instance_count, the engine raises CheckpointRecordInvalid before any fan-out instance work runs on the resumed path. Replaces the pre-0029 pad/truncate behavior which silently dropped completed contributions on shrink (breaking §10.11.1's exactly-once guarantee) and dispatched unsaved work on grow.
• tool_choice parameter on Provider.complete() (proposal 0025, accepted in spec v0.20.0). Optional discriminated-union value constraining the model's tool-calling behavior — one of "auto", "required", "none", or a ForceTool(name=...) record. Validation runs pre-send: "required" and ForceTool both demand non-empty tools, and ForceTool.name must appear in the supplied list; violations raise ProviderInvalidRequest (§7's existing category — no new error category). When tool_choice is None (the default) the wire field is omitted and the provider's own default applies, preserving pre-0025 behavior exactly. The OpenAIProvider maps the spec shape onto OpenAI's wire shape per §8.1.1 (the ForceTool.type="tool" renames to wire type="function").
• ForceTool and ToolChoice public types at openarmature.llm.ForceTool / openarmature.llm.ToolChoice. ForceTool is a frozen Pydantic model with type: Literal["tool"] = "tool" and name: str; ToolChoice = Literal["auto", "required", "none"] | ForceTool is the type alias used in Provider.complete()'s signature.
• validate_tool_choice public validator at openarmature.llm.validate_tool_choice. Standalone validator covering the three §5 pre-send rules; useful for third-party Provider implementations that want to reuse the canonical validation logic.
• Bounded drain timeout on CompiledGraph.drain() (proposal 0010, accepted in spec v0.19.0). drain() accepts an optional timeout: float | None = None parameter (non-negative seconds). When supplied, drain returns no later than the deadline; any observer events still queued or in-flight are reported as undelivered. Workers are cancelled cleanly so the compiled graph remains usable for subsequent invocations — partial delivery state from one drain does NOT leak into the next. Solves the "slow / hung / misbehaving observer blocks process exit" footgun for short-lived processes (CLIs, scripts, serverless functions). Observers SHOULD be cancellation-safe (idempotent writes, try/finally cleanup); the spec doesn't mandate it but the docs recommend it.
• DrainSummary frozen dataclass at openarmature.graph.DrainSummary. Returned from every drain() call (with or without timeout). Fields: undelivered_count: int, timeout_reached: bool. The shape is consistent across timed and untimed drains — callers receive the same dataclass whether the timeout was supplied or not. Per the v0.19.0 contract the two declared fields are the spec-mandated minimum; richer diagnostic detail (per-observer counts, sampled event metadata) is reserved for follow-on PRs.
• Per-instance fan-out resume contract (proposal 0009, accepted in spec v0.18.0). The engine now writes a checkpoint record at every completed event inside a fan-out instance (in addition to the existing outermost-graph + subgraph-internal + fan-out node completion saves). On resume the engine consults the saved record's fan_out_progress field and treats each instance as completed (skip, contribution rolls forward), in_flight (re-run from subgraph entry), or not_started (dispatch normally). The append reducer's no-double-merge guarantee holds across resume because completed is a one-shot accumulator state.
• FanOutProgress and FanOutInstanceProgress public dataclasses on openarmature.checkpoint. The CheckpointRecord.fan_out_progress field is now tuple[FanOutProgress, ...] (default empty tuple), with per-instance state, result, and completed_inner_positions observability. Was a None placeholder under proposal 0008.
• FanOutInternalSaveBatching config on InMemoryCheckpointer. Backends MAY opt into batching scoped to fan-out instance internal saves to bound the write volume of high-instance-count fan-outs. Outermost-graph, subgraph-internal, and the fan-out node's own completion save remain synchronous regardless. Default off. Buffered-but-unflushed saves are lost on crash by design; on resume, instances whose completed state was only buffered revert and re-run. Surfaces a new optional save_fan_out_internal / save_fan_out_in_flight_failure Checkpointer Protocol seam; backends that don't implement either fall back to the standard save.
• Patterns docs section at docs/patterns/, sibling to Concepts. Seeded with four recipes drawn from downstream usage and proposal 0008's alternatives section: parameterized entry point, tool-dispatch-as-node, session-as-checkpoint-resume, and bypass-if-output-exists. Patterns are user-level how-to recipes composing existing primitives, not framework contracts; new patterns can be added without spec coordination. Each page follows a problem / approach / snippet / when this is the right pattern / when it isn't / cross-references structure.

Changed

• CheckpointRecord.schema_version sourcing clarified per proposal 0028 (spec v0.21.1). Every save site within an invocation now reads schema_version from the declared graph state class — the class passed to GraphBuilder(...) — threaded as context.state_cls. Previously the outer dispatch save read from the declared class while fan-out instance internal saves read from type(state) at save time; the inconsistency only surfaced when a user passed a State subclass that shadowed schema_version, but the divergence made §10.12 migration lookups unreliable across save sites. Now uniform across outer / subgraph-internal / fan-out instance internal saves.
• Provider.complete() signature extended with an optional tool_choice: ToolChoice | None = None parameter (per proposal 0025 v0.20.0). Backward-compatible: callers that omit the new argument see no wire-shape change. Third-party Provider implementations MUST add the parameter to remain Protocol-conformant under strict type checking (and to accept calls that pass tool_choice without raising TypeError); they MAY ignore it in their wire-body emission, which is how "provider doesn't honor tool_choice" looks at the impl level. The OpenAIProvider wire mapping is implemented per §8.1.1.
• CompiledGraph.drain() return type changed from None to DrainSummary (pre-1.0; per proposal 0010 v0.19.0 contract). Callers that ignored the return are unaffected — await graph.drain() discards the returned dataclass exactly as before. Callers that explicitly typed the return as None will need to update their annotation.
• Fan-out resume behavior flipped from atomic restart (0008's v1 contract) to per-instance resume. A crash mid-fan-out used to re-run the entire fan-out on resume; now only the instances that did not complete-and-record their contribution re-run. The economics matter for large fan-outs of expensive work (LLM calls, long extractions): an 80% complete fan-out crash now restores 80% of its results rather than discarding them.
• SQLiteCheckpointer schema picks up a new fan_out_progress_blob column (added via ALTER TABLE for backward compatibility with pre-0009 databases). Pre-0009 rows back-fill as NULL on load and round-trip as the empty-tuple default. Both pickle and json serialization modes round-trip the new field.

Notes

• Pinned spec version bumped from v0.17.0 to v0.22.1 over the v0.9.0 cycle. Ten spec versions absorbed: v0.17.1 (proposal 0019, multi-provider wire-format extension — purely textual reframe of llm-provider §8 as a catalog of wire-format mappings; OpenAI-compatible body nested under §8.1), v0.18.0 (proposal 0009, per-instance fan-out resume — pipeline-utilities §10.3 / §10.7 revised, §10.11 added; the append reducer no-double-merge invariant is the load-bearing correctness story), v0.18.1 (fixture-only patch correcting an off-by-one literal in fixture 052's expected results), v0.19.0 (proposal 0010, bounded drain timeout — graph-engine §6 amended with the timeout parameter and DrainSummary return contract), v0.20.0 (proposal 0025, llm-provider tool_choice — §5 / §7 / §8.1.1 amended), v0.20.1 (proposal 0026, llm-provider §8.X wire-format mapping subsection template — purely textual §8 framing paragraph; the existing OpenAI §8.1 mapping is the template's reference shape so no python module-level work was needed), v0.21.0 (proposal 0027, explicit result_is_error discriminator on fan_out_progress per-instance entries — see Added above), v0.21.1 (proposal 0028, canonical source for schema_version — declared graph state class wins over runtime subclass shadowing; see Changed above), v0.22.0 (proposal 0029, strict CheckpointRecordInvalid on fan-out count drift — see Added above), and v0.22.1 (proposal 0030, drain snapshot semantic + timeout-input validation — purely textual; python already implemented both behaviors per the 0010 impl PR, so no module-level work needed). All existing conformance fixtures continue to pass.

[0.8.0] — 2026-05-23

LLM-provider span payload and GenAI semconv release. Pinned spec jumps from v0.16.1 to v0.17.0 (proposal 0024 / observability §5.5 expansion). The trigger was a friction report from a downstream agent integrating OA with Langfuse over OTLP: LLM spans rendered "naked" (model + tokens only), prompt linkage silently dropped at the dispatch-worker task boundary, and every backend needed a per-service attribute-mapping shim. This release clears all eight items in that report.

Added

• openarmature.llm.input.messages / openarmature.llm.output.content / openarmature.llm.request.extras span attributes (spec §5.5.1). When the OTel observer is constructed with disable_llm_payload=False, LLM spans carry the messages sent, the assistant response content, and the RuntimeConfig extras bag — JSON-encoded with sorted keys, no insignificant whitespace, UTF-8. Default-off (the flag is disable_llm_payload: bool = True) because the payload may contain PII the user hasn't audited; opt in deliberately. Subject to the §5.5.5 truncation contract.
• GenAI semantic-conventions attributes (spec §5.5.2 + §5.5.3). LLM spans now carry gen_ai.system, gen_ai.request.model, gen_ai.response.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, gen_ai.response.finish_reasons (single-element string array), gen_ai.response.id, and per-set gen_ai.request.{temperature,max_tokens,top_p,seed} (only set fields — absence is meaningful per §5.5.2). The existing openarmature.llm.* attribute set is preserved alongside; both namespaces emit. Default-on (disable_genai_semconv: bool = False); opt out when an external auto-instrumentation library (OpenInference, opentelemetry-instrumentation-openai, etc.) is the canonical source of GenAI attributes for your stack.
• OTelObserver(resource=...) constructor argument. Optional opentelemetry.sdk.resources.Resource passed to the private TracerProvider. Lets callers set service.name / service.version directly rather than via OTEL_SERVICE_NAME / OTEL_RESOURCE_ATTRIBUTES environment variables (which had to be set BEFORE constructing the observer to take effect — a footgun the explicit kwarg avoids).
• Multi-processor support on OTelObserver. The span_processor constructor argument now accepts a SpanProcessor | Sequence[SpanProcessor]. Multi-destination export (e.g., HyperDX + Langfuse on one observer) becomes a one-line constructor call instead of a per-service CompoundSpanProcessor workaround.
• OTelObserver(attribute_enrichers=...) hook. Sequence of Callable[[Span, NodeEvent | None], None] invoked just before the observer ends each span. Lets users add backend-specific attributes (custom langfuse.* keys, vendor span kinds, etc.) without subclassing or mutating span._attributes post-on_end. The event is None on synthetic close sites (subgraph dispatch, detached root, fan-out instance, invocation span, shutdown drain); enrichers that need per-event context short-circuit on None. Exceptions are caught and warned, never propagated to the dispatch worker.
• OTelObserver(payload_max_bytes=...) truncation cap. Per-attribute byte cap for the §5.5.1 payload attributes. Default 65,536 (64 KiB) per attribute; minimum 256 bytes (rejected at construction). The truncation algorithm (spec §5.5.5) emits the largest UTF-8 code-point-aligned prefix that fits within cap - len(marker) bytes followed by the marker …[truncated, M bytes total]. Inline image bytes are unconditionally redacted at the provider before any cap applies (see Image redaction below).
• OpenAIProvider(genai_system="openai") constructor argument. Default "openai"; override for non-OpenAI endpoints that speak the OpenAI Chat Completions wire format (vLLM, LM Studio, llama.cpp, sglang). Surfaces as the gen_ai.system span attribute. No base-URL sniffing happens — the same host:port could be any of several servers, and a wrong inference is worse than the explicit opt-in.
• openarmature.observability.LLM_NAMESPACE and openarmature.observability.LlmEventPayload public exports. The ("openarmature.llm.complete",) sentinel namespace used by the LLM-provider hook and the payload shape backend observers consume. Third-party Provider implementations can dispatch their own LLM events via current_dispatch()(NodeEvent(..., namespace=LLM_NAMESPACE, pre_state=LlmEventPayload(...))); custom observers can recognize the same sentinel and read attributes off the payload. Previously private (_LLM_NAMESPACE, _LlmEventState); the old underscore-prefixed names are no longer exported.
• Response.response_id and Response.response_model typed fields. Mirror the wire response's id and model fields when the provider returns them. Surface as gen_ai.response.id and gen_ai.response.model per spec §5.5.3; also useful for downstream cross-referencing with provider-side billing or audit logs without reaching into Response.raw.

Changed

• Prompt-context attribute propagation now survives the dispatch-worker task boundary. Previously the OTel observer read current_prompt_result() / current_prompt_group() from inside _handle_llm_event, which runs in the engine's delivery-worker task. asyncio.create_task(deliver_loop(queue)) snapshots the current Context at task creation, before any node body runs — so the ContextVars set by with_active_prompt(...) were never visible to the worker. openarmature.prompt.* attributes silently went missing on the LLM span. Fixed by capturing both ContextVars at dispatch time inside the OpenAIProvider.complete() call (which runs in the node task, where with_active_prompt IS active) and threading the snapshots through the LlmEventPayload. The observer reads from the payload, not the ContextVar.
• Inline image bytes are redacted at the provider, not the observer. Image content blocks with ImageSourceInline are serialized with source replaced by {type: "inline_redacted", byte_count: N} per §5.5.5 before the payload reaches the observability dispatch queue. Defense-in-depth: bytes never leave the provider in event form, so custom observers subscribing to the LLM event (enabled by LlmEventPayload being public) cannot accidentally leak raw image bytes regardless of their implementation. media_type and detail are preserved at the image-block level per llm-provider §3.1.2. URL-form images pass through unchanged.
• OTelObserver.shutdown() docstring documents the BatchSpanProcessor flush gotcha. Under fast or unusual teardown orderings (e.g., FastAPI TestClient teardown that closes the event loop before the batch processor's export thread finishes), spans can appear dropped. Documented workarounds: call provider.force_flush(timeout_millis=…) explicitly before shutdown(), or use SimpleSpanProcessor in tests.

Notes

• Pinned spec version bumped to v0.17.0. Per the additive-only governance rule (proposal 0024 adds; never renames), implementations passing v0.16.1 conformance fixtures continue to pass under v0.17.0; the new fixtures (012-021) add cases without modifying existing ones.

[0.7.0] — 2026-05-23

Docs-and-examples release. Pinned spec stays at v0.16.1; no proposals implemented this cycle. The focus was bringing the docs site, README, and examples up to par with the v0.6.0 implementation and filling reference-doc gaps that mkdocstrings was silently dropping.

Added

• openarmature.graph.NextCall and openarmature.graph.default_classifier exports. Promoted from the openarmature.graph.middleware submodule. NextCall is the Protocol describing the next_ callable a middleware receives; default_classifier is the retry classifier's default predicate (matches category against TRANSIENT_CATEGORIES). Users writing custom middleware can type their next_ parameter and extend the default classifier without reaching into the submodule.
• Middleware concept page. New docs/concepts/middleware.md covering the protocol shape, four registration sites (per-node, per-graph, per-branch, per-fan-out-instance), composition order, subgraph boundary, error semantics, and the built-in RetryMiddleware and TimingMiddleware.
• Complete reference docs. Added docstrings to 35 previously-undocumented public members across graph, prompts, and checkpoint. mkdocstrings silently omits entries without a docstring, which meant the most fundamental builder methods (add_node, add_edge, set_entry, compile) and the entire Checkpointer backend method surface were invisible in the rendered reference. Every name in each subpackage's __all__ now renders.
• Examples 05–09. New examples covering fan-out with retry, parallel branches, multimodal prompts, checkpointing with state migration, and tool use. Per-example docs pages with mermaid diagrams under docs/examples/. Examples 00–04 were scrubbed and standardized for consistency with the new set.
• RELEASING.md. Documents the rc-first release flow (TestPyPI then PyPI), the tag-name dispatch rules, the pre-release checklist, rc iteration, and rollback via PyPI yank.
• Docs site UX, nav, and reference cleanup. Sweep of nav structure, internal links, and reference page organization to match the v0.6.0 surface.

Changed

• FanOutNode.run and ParallelBranchesNode.run raise NotImplementedError instead of RuntimeError. Both methods exist only to satisfy the Node protocol; the engine dispatches these node types through run_with_context. NotImplementedError is the right signal and stays backwards-compatible since it subclasses RuntimeError (existing except RuntimeError catches still work).

Notes

• Pinned spec version unchanged at v0.16.1. No proposals landed this cycle; the release is docs- and examples-focused. The next functional release will resume with new spec proposals.

[0.6.0] — 2026-05-16

Consolidated release for the five-PR batch: structured output (proposal 0016), image content blocks (proposal 0015), prompt management (proposal 0017), state migration for checkpoints (proposal 0014), and parallel branches (proposal 0011). Pinned spec jumps from v0.10.0 to v0.16.1.

Added

• Parallel branches (proposal 0011, introduced in spec v0.11.0; attempt-index propagation clarified in spec v0.16.1). New GraphBuilder.add_parallel_branches_node(name, *, branches, error_policy, errors_field, middleware) surface dispatches M heterogeneous compiled subgraphs concurrently per pipeline-utilities §11. BranchSpec (subgraph + inputs/outputs projection + branch middleware) and ParallelBranchesNode types exported from openarmature.graph. Branch insertion order determines fan-in merge order regardless of completion timing (§11.8). Two error policies: "fail_fast" raises ParallelBranchesBranchFailed (a NodeException subtype) with branch_name, original cause as __cause__, and recoverable_state carrying the parent's pre-dispatch snapshot — no buffered branch contributions are visible (§11.5 buffer-and-apply). "collect" records per-branch failures in an optional errors_field (each record carries branch_name + category + implementation-defined extras) and continues. Two new error categories: ParallelBranchesNoBranches (compile time, empty branches map) and ParallelBranchesBranchFailed (runtime, fail_fast branch raise).
• NodeEvent.branch_name: str | None (proposal 0011 / graph-engine §6). Populated on events from nodes inside a parallel-branches branch, absent outside. Independent of fan_out_index — both may be present simultaneously when a branch contains a fan-out (or a fan-out instance contains a parallel-branches node). The combined (namespace, branch_name, fan_out_index, attempt_index, phase) tuple is the event-source uniqueness key.
• openarmature.branch_name OTel span attribute. Mirrors the existing openarmature.node.fan_out_index. Emitted on synthesized inner-node spans when branch_name is populated on the event. The two attributes coexist on inner nodes of a fan-out-inside-a-branch composition.
• Attempt-index ContextVar propagation through transitive retry (graph-engine §6 v0.16.1). Retry middleware now sets the attempt_index ContextVar before each next call; the engine reads current_attempt_index() when emitting events. This makes retry semantics symmetric across direct (per-node middleware) and transitive (instance / branch / fan-out instance_middleware) wrapping — events from inner nodes of a subgraph the retry re-invokes carry the wrapping retry's counter, not a freshly-zeroed inner counter. Innermost-wins precedence falls out of Python's ContextVar set/reset token stack. Pre-existing node-level retry behavior is unchanged.
• State migration for checkpointed graphs (proposal 0014, introduced in spec v0.15.0; refined by proposal 0018 in spec v0.16.0). Saved checkpoints whose schema_version doesn't match the current state class now route through a registered migration chain instead of failing on resume. Surface: State.schema_version: ClassVar[str] = "" (declare a non-empty value to opt in), GraphBuilder.with_state_migration(from_version, to_version, migrate) and with_state_migrations(*migrations) for registration, StateMigration and MigrationRegistry types exported from openarmature.checkpoint. Chain resolution is BFS over the registered edges; the shortest path wins. Three new error categories: CheckpointStateMigrationChainAmbiguous (proposal 0018: duplicate (from, to) pair at registration time, or multiple distinct shortest paths between the saved and current versions at resume time), CheckpointStateMigrationMissing (no chain bridges the versions), and CheckpointStateMigrationFailed (a migration function raised). All non-transient. Post-migration deserialization failures still route to CheckpointRecordInvalid per §10.12.4. The same chain applies to each entry in parent_states in lockstep with the outer state per §10.12.2. Routing precedence per §10.10 (v0.16.0): chain-ambiguous → missing → failed → record-invalid.
• Checkpointer.supports_state_migration Protocol attribute. Marks whether a backend can expose the structural intermediate form (a plain dict, JSON tree) the migration registry consumes. SQLiteCheckpointer(serialization="json") opts in; SQLiteCheckpointer(serialization="pickle") and InMemoryCheckpointer opt out. On version mismatch against a non-migration-eligible backend the engine raises CheckpointRecordInvalid per spec §10.12.1.
• openarmature.checkpoint.migrate OTel span (proposal 0014 §6 cross-ref). Versioned resumes whose migration chain runs emit a zero-duration openarmature.checkpoint.migrate span on the OTel observer, parented under the invocation root span. Attributes: openarmature.checkpoint.migrate.from_version, openarmature.checkpoint.migrate.to_version (the final target), openarmature.checkpoint.migrate.chain_length. The §10.12.3 fast path (versions match, registry not consulted) emits no span. Engine-side: a synthetic checkpoint_migrated observer phase carries a _MigrationSummary payload from _migrate_record through to the OTel observer; the new phase is gated off default subscriptions (observers opt in explicitly via phases={..., "checkpoint_migrated"}).
• Prompt-management capability (proposal 0017, introduced in spec v0.15.0). New openarmature.prompts subpackage. PromptManager composes one or more PromptBackends, exposes fetch / render / get, applies the §8 fallback semantics (prompt_store_unavailable continues to the next backend; prompt_not_found stops the chain), and renders templates with Jinja2's StrictUndefined per §7. Prompt / PromptResult / PromptGroup are Pydantic models matching spec §3 / §4 / §9. Three error categories (PromptNotFound, PromptRenderError, PromptStoreUnavailable) with PROMPT_TRANSIENT_CATEGORIES exported for retry-middleware classifiers. FilesystemPromptBackend is the minimum local-filesystem reference backend (layout: <root>/<label>/<name>.j2; version derived from the first 16 hex chars of template_hash). New runtime dependency: jinja2>=3.1.
• openarmature.prompts.context — observability propagation per spec §11. with_active_prompt(result) and with_active_prompt_group(group) context managers + current_prompt_result() / current_prompt_group() inspectors. When the OTel observer is active and an LLM call fires inside with_active_prompt, the openarmature.llm.complete span carries the normative openarmature.prompt.* attributes (name, version, label, template_hash, rendered_hash, group_name). Nesting is innermost-wins.
• Image content blocks for user messages (proposal 0015, introduced in spec v0.13.0). UserMessage.content now accepts str | list[ContentBlock]. The block surface introduces TextBlock, ImageBlock, ImageSourceURL, ImageSourceInline, and the ContentBlock / ImageSource discriminated unions over the block / source type field. ImageBlock carries a media_type (required for inline sources; ignored for URL sources; typed as str | None so callers MAY pass any image/* type the bound model supports) and an optional detail hint ("auto" / "low" / "high"; None default omits the field from the wire so providers apply their own default). System, assistant, and tool messages stay text-string-only; image inputs are user-only in v1.
• OpenAIProvider content-array wire mapping. When UserMessage.content is a content-block sequence, the wire body uses OpenAI's content array per §8.1.1. TextBlock → {type: "text", text}. ImageBlock with a URL source maps to {type: "image_url", image_url: {url, detail?}}. ImageBlock with an inline source constructs an RFC 2397 data:<media_type>;base64,<base64_data> URI and goes through the same image_url entry shape. Inline bytes pass through unchanged — no inspection, transcoding, or re-encoding.
• New error category ProviderUnsupportedContentBlock (non-transient). Raised when the bound model rejects a content block type / media variant. Distinct from ProviderInvalidRequest (which covers spec-shape malformation): this category surfaces a capability mismatch, letting callers route differently (e.g., fall back to a multimodal-capable provider) without overloading the malformed-request category. Carries block_type ("image" / "audio" / "video") and reason (provider's human-readable message) when those are recoverable from the rejection. OpenAIProvider detects content rejection via HTTP 400 bodies — heuristic on error.code (known set: image_content_not_supported, unsupported_image_media_type, audio_content_not_supported, etc.), error.type (image_parse_error), and error.message ("does not support" + image/audio/video).
• Structured output (proposal 0016, introduced in spec v0.14.0). Provider.complete() now accepts an optional response_schema parameter — either a JSON Schema dict or a Pydantic BaseModel subclass. When supplied, the provider constrains the model's output to the schema and populates Response.parsed with the validated value (dict for dict-schema input, a BaseModel instance for class input). New StructuredOutputInvalid error category (non-transient by default) raises on JSON parse failure or schema validation failure; carries the requested schema, the raw response content, and a failure description.
• OpenAIProvider native response_format wire path. When response_schema is supplied, the chat-completions request body carries response_format: { type: "json_schema", json_schema: { name, schema, strict } }. The strict flag is determined by a deep recursive walk over the schema (object-property required-coverage rule across anyOf / oneOf / allOf and $ref targets, with cycle protection); unresolvable refs fall through to strict: false. The name field uses schema.title when present, otherwise a deterministic sha256-prefix hash.
• OpenAIProvider prompt-augmentation fallback. Constructor flag force_prompt_augmentation_fallback: bool (default False) and read-only inspect property uses_prompt_augmentation_fallback: bool. When the flag is on, structured-output calls build a fresh message list with a system directive containing the serialized schema, omit response_format from the wire, and validate the response post-receive. The caller's original messages list is never mutated. Use for OpenAI-compatible servers (older vLLM, some LM Studio releases, llama.cpp variants) that reject or silently ignore response_format.
• Provider-agnostic schema helpers. openarmature.llm.validate_response_schema(schema) (raises ProviderInvalidRequest when the schema is not a dict with a top-level type: "object") and openarmature.llm.strict_mode_supported(schema) (the deep-tree strict-mode constraint check) are exported for reuse by future Anthropic/Gemini providers.
• Capability-agnostic conformance harness helpers. tests/conformance/harness/wire.py adds match_wire_body (recursive deep-equal with "*" wildcard support), assert_response_format_absent, assert_system_references_schema, and assert_error_carries for the expected_wire_request[_checks] and expected.raises.carries.{...} fixture shapes. Used by the 0016 fixtures; available for the upcoming 0014 / 0015 / 0017 fixture sets.
• Runtime dependency: jsonschema>=4.0. Used by the dict-schema validation path. The Pydantic-class path uses Pydantic's native validator and does not need jsonschema.

Changed

• Pinned spec version: 0.10.0 → 0.16.1. Adopts the skip-ahead governance principle: the submodule jumps across v0.11.0–v0.16.1 (proposals 0009, 0011, 0014, 0015, 0016, 0017, 0018) in one bump. All five proposals (0011, 0014, 0015, 0016, 0017) are implemented in the batch's release; the v0.16.1 clarification of attempt-index propagation through transitive retry middleware lands with the proposal 0011 implementation.
• CheckpointRecord.schema_version semantic shift (proposal 0014). Previously a backend-internal record-shape version (CHECKPOINT_SCHEMA_VERSION = "1" constant), now the user-facing state-schema version per spec §10.2. The framework reads type(state).schema_version at save time. Pre-PR-4 records carrying "1" are reinterpreted as user-facing v1 identifiers; users with such records either declare schema_version="1" on their state class or discard the pre-PR-4 records. SQLiteCheckpointer no longer rejects records with non-default schema_version at the backend boundary; version-mismatch routing is now an engine concern at resume time. The CHECKPOINT_SCHEMA_VERSION module constant is removed; future record-shape evolution can add backend-private metadata fields if needed.
• NodeEvent.pre_state typed Any (was State). Required by the new checkpoint_migrated phase which carries a _MigrationSummary payload rather than a State instance. Observer authors who type-narrowed pre_state to State should treat it as Any and narrow per-phase (e.g., if event.phase == "completed": ...). The checkpoint_saved phase already carried a State-flavored shape (not necessarily a typed State subclass instance), so this widens the declared type to match runtime reality rather than introducing a new constraint.

Notes

• Pre-1.0 MINOR. Two behavioral changes ship in this release:

  • Retry-MW attempt-index propagation. Events from inner nodes of a subgraph wrapped by retry middleware (branch middleware, fan-out instance_middleware, or any retry on a wrapping subgraph) now carry the wrapping retry's attempt counter on each re-invocation rather than starting at 0. Per-node retry behavior is unchanged. Matches spec v0.16.1's clarification of the graph-engine §6 contract.
  • CheckpointRecord.schema_version semantic shift. Previously a backend-internal record-shape version (the removed CHECKPOINT_SCHEMA_VERSION = "1" constant), now the user-facing state-schema version per spec §10.2. Pre-v0.6.0 records carrying "1" are reinterpreted as user-facing v1 identifiers; declare schema_version="1" on the corresponding state class or discard the records.

  Existing callers who don't wrap subgraphs in retry middleware and don't declare a state-schema version see no behavior change.

[0.5.0] — 2026-05-10

First release on real PyPI. Catches the implementation up from spec v0.5.x to v0.10.0 across six phases — the spec accepted eight proposals while the python lib was at v0.3.1, and v0.5.0 lands all of them in one curated drop.

Added

• Typed conformance harness (Phase 0). Single parametrised test target driving all 68 spec fixtures under discriminated-union YAML parsers. Replaces the earlier hand-rolled per-fixture wiring.
• Observer pair model (Phase 1, spec v0.6.0 / proposal 0005 §6). Observer Protocol (async callable), SubscribedObserver with phase subscription set ({"started", "completed", "checkpoint_saved"}), RemoveHandle.remove(), and a serial delivery queue per spec §6 ordering. Observer exceptions don't propagate; reported via warnings.warn.
• Middleware (Phase 2, proposal 0004). Middleware Protocol with the canonical (state, next) → partial_update shape, compose_chain runtime, and five stdlib middlewares: RetryMiddleware, TimingMiddleware, ErrorRecoveryMiddleware, ShortCircuitMiddleware, TraceRecorderMiddleware. Per-graph and per-node middleware composition.
• Fan-out runtime (Phase 3, proposal 0005 pipeline-utilities side). FanOutNode for parallel fan-out over an items_field or a count (int or callable resolver). Configurable concurrency, error policy (fail_fast / collect), inputs / extra_outputs projection, optional errors_field collection. Composes with retry middleware on the fan-out node and on per-instance subgraphs.
• LLM provider (Phase 4, proposal 0006). New openarmature.llm package: Provider Protocol with ready() / complete(messages, tools=None, config=None); OpenAIProvider (HTTPX-based, OpenAI-compatible wire); typed Message / ToolCall / Tool / Response / RuntimeConfig; seven error categories (ProviderAuthentication, ProviderUnavailable, ProviderInvalidRequest, ProviderInvalidResponse, ProviderInvalidModel, ProviderModelNotLoaded, ProviderRateLimit with retry_after). Tool-call ids preserved verbatim through the wire.
• Checkpointing (Phase 5, proposal 0008). Checkpointer Protocol (save / load / list / delete) with CheckpointRecord and NodePosition shapes; InMemoryCheckpointer reference impl; CheckpointNotFound / CheckpointRecordInvalid / CheckpointSaveFailed error categories; checkpoint_saved observer phase; resume-from-checkpoint semantics for fan-out and subgraph compositions.
• Observability / OTel (Phase 6, proposal 0007). OTelObserver mapping observer events → OpenTelemetry spans with private TracerProvider (no global pollution); §4.4 detached subgraph + detached fan-out trace mode; §5.5 LLM-provider span emission with disable_llm_spans opt-out; §5.6 cross-cutting openarmature.correlation_id on every span; §10.8 checkpoint_saved zero-duration span. install_log_bridge wires the stdlib root logger through OTel's Logs Bridge (deprecation-aware via opentelemetry-instrumentation-logging) so log records emitted within an invocation carry the active span's trace_id/span_id plus openarmature.correlation_id. prepare_sync synchronous observer hook so logs emitted on the FIRST line of a node body (before any await) pick up the right span. Fan-out per-instance dispatch span synthesis (§5.4) with parent_node_name cached and applied per-instance.
• current_correlation_id() public API. Read the per-invocation cross-backend join key from anywhere within the invocation's async call tree.
• Subgraph configuration plural form. Builder accepts subgraphs: alongside subgraph: for fixture compatibility.

Changed

• Pinned spec version: 0.5.x → 0.10.0. Lands proposals 0004 (middleware), 0005 (fan-out + observer pair model), 0006 (llm-provider), 0007 (observability/OTel), 0008 (checkpointing), 0011 (prepare_sync hook), 0012 (completed event after edge eval), 0013 (fan_out_config on NodeEvent).
• Edge-resolution failures share the preceding node's event pair (spec v0.9.0 / proposal 0012). routing_error and edge_exception populate error on the preceding node's completed event with post_state=None instead of producing a separate pair. All five §4 runtime error categories now land via the same uniform mechanism.
• Observer protocol contract. Async-only callable; phase-filtered delivery via SubscribedObserver.phases; serial single-task delivery worker; observer errors isolated via warnings.warn.

Fixed

• Log bridge filter placement. Phase 6.0's _CorrelationIdFilter lived on the root logger; Python's logging propagation walks ancestor handlers but not ancestor filters, so child-logger records (the normal logging.getLogger("module") pattern) were missed. Replaced with a process-global LogRecord factory that fires uniformly at record construction.
• OTelObserver concurrency-safe state scoping. Per-invocation span state now keyed by invocation_id so concurrent invocations sharing one observer instance don't collide on the in-flight span maps.
• Spec submodule pin sync. Internal spec_version matched the submodule HEAD across phase boundaries; tracked via tests/test_smoke.py.

Notes

• First real PyPI publish. Pre-release verification continues to flow through TestPyPI per docs/RELEASING.md. The pypi GitHub Environment requires a manual approval click before any real-PyPI upload — keep it on.
• Pre-1.0 SemVer. Behavioral changes may land in MINOR bumps. Several Phase 1+ contracts changed shape vs. v0.4.0 — most user-visible: the observer pair model in Phase 1, the edge-resolution failure mechanism in Phase 6.1.
• Cross-language posture. This release tracks spec v0.10.0; the OpenArmature TypeScript implementation will land separately under the same spec.