Skip to content

CHANGELOG.md

Latest commit

 

History

History
73 lines (54 loc) · 19.5 KB

CHANGELOG.md

File metadata and controls

73 lines (54 loc) · 19.5 KB
Raw

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.

[Unreleased]

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

  • Release gate cleared with PR-5 (proposal 0011). All five proposals in the batch ({0011, 0014, 0015, 0016, 0017}) are now implemented. Tag the consolidated release once this PR merges.
  • Pre-1.0 MINOR. Existing free-form callers (no response_schema) see no behavior change — the new field defaults to None, the wire body omits response_format, and Response.parsed remains absent.

[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.