Skip to content

Glossary

This glossary collects the named concepts defined across OpenArmature's capability specifications — each with a one-line gloss and a link to the section where it is normatively defined. Terms are grouped by capability; the index links to every term for alphabetical lookup. The gloss orients — the linked spec section is authoritative.

Index

Graph engine

  • Compiled graph — The immutable, executable result of compiling a graph definition; compilation fails on no declared entry, unreachable nodes, dangling edges, multiple outgoing edges, or conflicting reducers. graph-engine §2
  • Drain — The engine's flush of all queued observer events before an invocation returns, so delivery completes within the invocation boundary. graph-engine §6
  • Edge — A directed connection between nodes: a static edge (fixed destination) or a conditional edge (destination computed from state, or the END sentinel). Each node has exactly one outgoing edge. graph-engine §2
  • END — The engine-provided sentinel routing target that halts execution; a distinct constant, not a reserved node name. graph-engine §2
  • Error category — A canonical identifier classifying a failure (e.g. node_exception, no_declared_entry, dangling_edge, fan_out_empty), surfaced per the language's idiom for cross-impl consistency. graph-engine §4
  • Framework-emitted augmentation event — A typed event the engine emits beyond raw node events — typed LLM completion / failure, embedding, rerank, and tool-call events — carrying provider- or tool-specific structured detail to observers. graph-engine §6
  • Invocation — A single execution of a compiled graph via the entry surface (invoke()), returning one of three outcomes. (In conformance fixtures, one invoke() call within an invocations: list — conformance-adapter §2.) graph-engine §3
  • Invocation outcome — The result shape of an invocation: completed (reached END), errored (a node raised), or suspended (a node paused; see Suspension). graph-engine §3
  • Node — A named, asynchronous unit of work that receives the current state and returns a partial update; it must not mutate the state it received. graph-engine §2
  • Node event — The started/completed event pair the engine dispatches per node execution (and per retry attempt) to observers. graph-engine §6
  • Observer — An async callable receiving node lifecycle events from a strictly-serial delivery queue; the read-only telemetry surface over an invocation. graph-engine §6
  • Reducer — A function merging a node's partial update into prior state for one field; each field has exactly one. Eight canonical reducers ship — last_write_wins (default), append, merge, concat_flatten, merge_all, bounded_append, dedupe_append, merge_by_key — and custom reducers may be registered per field. graph-engine §2
  • State — The typed schema (a record of named, typed fields) describing data flowing through a graph; validated at graph boundaries. graph-engine §2
  • Subgraph — A compiled graph used as a node inside another graph; runs against its own state schema and projects results back into the parent via inputs/outputs mappings or field-name matching. graph-engine §2

Pipeline utilities

  • Branch middleware — Middleware wrapping a single parallel branch's invocation, analogous to fan-out instance middleware. pipeline-utilities §11.7
  • Branch spec — The per-branch definition inside a parallel-branches node: the branch's subgraph plus its inputs/outputs projections. pipeline-utilities §11.1.1
  • Cause chain — The structured caught_exception on a failure-isolation event: an ordered list of {category, message, carrier} links (outermost→innermost) plus a derived top-level category and message. pipeline-utilities §6.3
  • Checkpointer — The save / load / list / delete protocol backends implement to persist checkpoint records, keyed by invocation_id. pipeline-utilities §10.1
  • Checkpointing — Opt-in durable persistence of invocation progress so an interrupted run can resume; provided by a registered Checkpointer. pipeline-utilities §10
  • CheckpointRecord — The in-memory typed object the engine hands to save: serialized state plus the completed-node positions needed to resume. pipeline-utilities §10.2
  • Degraded instance — A fan-out instance that returns a configured degraded_update instead of raising; it counts as a §9.3 success whose contribution is the degraded value. pipeline-utilities §9.8
  • error_policy — A fan-out / parallel-branches failure mode: fail_fast (default — the first failure aborts) or collect (gather per-instance / per-branch errors and continue). pipeline-utilities §9.5
  • Failure isolation — The canonical middleware that catches exceptions escaping the inner chain and returns a configured degraded partial update, emitting a named failure-isolation event. pipeline-utilities §6.3
  • Fan-in / collect — The merge of each fan-out instance's collect_field value back into the parent's target_field via that field's reducer. pipeline-utilities §9.3
  • Fan-out node — A node that runs a subgraph (or async callable) once per item in a parent field — or count times — with bounded concurrency, collecting per-instance results into a parent field. The one place subgraph executions overlap in time. pipeline-utilities §9
  • Idempotency contract — The requirement that resumed nodes tolerate re-execution, since resume may re-run a node whose effects partially applied before the interruption. pipeline-utilities §10.5
  • Instance middleware — Middleware wrapping each fan-out instance's invocation as a unit, sitting between the fan-out node's outer middleware and the instance subgraph's own middleware. pipeline-utilities §9.7
  • Middleware — An async callable wrapping a node with the shape (state, next) -> partial_update; it may inspect or transform input, short-circuit, catch exceptions, or retry by calling next again. pipeline-utilities §2
  • Middleware chain — An ordered sequence of middleware around one node, composing outer-to-inner; each layer's return flows back through the previous layer's next call. pipeline-utilities §2
  • Parallel branches — A node holding a static map of named, heterogeneous subgraphs that run concurrently within one invocation; topology-driven, complementing data-driven fan-out. pipeline-utilities §11
  • Per-instance projection — How each fan-out instance receives its slice of parent state: the per-item value via item_field, plus any inputs-mapped parent fields. pipeline-utilities §9.1
  • Pre-/post-node phase — The two halves of a middleware split by await next(...): the pre-phase runs on the way in (outer-to-inner), the post-phase on the way out (inner-to-outer). pipeline-utilities §2
  • Resume — Continuation of a checkpointed (or suspended) invocation via invoke(resume_invocation=...), replaying from the last completed position. (Suspension's resume: suspension §7.) pipeline-utilities §10.4
  • Retry — The canonical middleware that re-invokes the wrapped chain on classifier-matched exceptions, up to max_attempts, with configurable backoff (default exponential with full jitter). pipeline-utilities §6.1
  • State migration — Versioned transformation of a persisted checkpoint's state shape (schema_version chain resolution) so older records load into a newer schema. pipeline-utilities §10.12
  • Timing — The canonical middleware that measures wrapped-node wall-clock duration on a monotonic clock and reports it via callback. pipeline-utilities §6.2

LLM provider

  • Call-level retry — The provider's own retry lane for transient API failures, distinct from (and nested inside) graph-engine retry middleware. llm-provider §7.1
  • Content block — A typed segment of message content: text, image, thinking, or redacted_thinking; imported unchanged by harness-chat. llm-provider §3.1
  • Extras pass-through — The convention by which vendor-specific request parameters not in the typed config are forwarded to the provider via an extras bag, with null-skip semantics. llm-provider §6
  • Message — A typed conversation entry of kind system, user, assistant, or tool, each carrying kind-specific content. llm-provider §2
  • Provider — An object bound to a model identifier that, given messages and optional tools, returns one assistant message wrapped in a Response. llm-provider §2
  • Provider interface — The ready() / complete(...) contract every provider satisfies. llm-provider §5
  • Reasoning-continuity signature — An opaque token attached to a thinking block that lets a provider verify reasoning continuity across turns. llm-provider §3.1.7
  • Response — A provider call's result: the assistant message, a finish reason, and usage information. llm-provider §2
  • RuntimeConfig — The caller-supplied per-request parameter record (temperature, max tokens, etc.) plus an extras pass-through bag for vendor-specific knobs. llm-provider §6
  • Structured output — Provider support for constraining a completion to a caller-supplied response schema, with a documented fallback for models lacking native support. llm-provider §8
  • Tool — A function the model may request the caller execute, defined by name, description, and a JSON-Schema parameters shape. llm-provider §2
  • Tool call — An assistant message's request to invoke a named tool with structured arguments; answered by a tool message bearing the matching tool_call_id. llm-provider §2
  • Tool definition — The record (name, description, parameters) describing a tool to the provider. llm-provider §4
  • Wire-format mapping — The normative translation between the spec's message / tool / config shapes and a vendor API's wire bytes; defined for OpenAI-compatible, Anthropic Messages, and Google Gemini. llm-provider §8

Retrieval provider

  • Embedding runtime config — A RuntimeConfig-shaped record for embedding requests; minimally an optional dimensions plus an extras pass-through bag. retrieval-provider §2
  • EmbeddingProvider — An object bound to an embedding model that turns input strings into vectors wrapped in an EmbeddingResponse. retrieval-provider §2
  • EmbeddingResponse — An embed() result: the vectors, model identifier, usage, and optional request id / parsed raw response. retrieval-provider §2
  • EmbeddingUsage — An embedding usage record carrying input_tokens only (vectors have no output tokens). retrieval-provider §2
  • RerankProvider — The retrieval protocol for relevance reranking — re-scores candidate documents against a query, returning relevance-sorted ScoredDocument entries — named as part of the RetrievalProvider umbrella. retrieval-provider §5
  • RetrievalProvider — The umbrella capability covering EmbeddingProvider and RerankProvider; a capability-level descriptor for cross-protocol concerns, not a concrete protocol itself. retrieval-provider §2

Observability

  • Attribute namespace — The openarmature.* dotted-key namespace for OA span attributes; upstream GenAI semconv names are adopted only once they reach upstream Stable. observability §5
  • Correlation ID — A per-invocation, application-supplied identifier that flows across every observability backend as a join key; distinct from the backend-local invocation_id. observability §2
  • Detached trace mode — An opt-in mode where a specific subgraph or fan-out gets its own trace, with the parent's dispatch span carrying an OTel Link to it. observability §4.4
  • Driving span — The currently-open span an implementation drives as work executes; its lifecycle (open / attribute / close) is specified for deterministic emission. observability §6
  • GenAI semconv — The OpenTelemetry Generative-AI semantic-convention attribute subset OA emits on LLM spans (the Stable subset). observability §5.5.3
  • invocation_id — The per-invocation identifier (caller-supplied or framework-generated) that correlates spans within a single backend; the checkpoint / resume key, distinct from the cross-backend correlation_id. observability §3.2
  • Langfuse mapping — The normative projection of OA spans onto Langfuse's trace / observation / generation data model and attributes. observability §8
  • Log correlation — The contract that log records emitted during an invocation carry the correlating ids (correlation_id, invocation_id) so logs join to traces. observability §7
  • Queryable observer — The pattern where a concrete observer exposes extra read methods that pipeline nodes consume at runtime, without expanding the abstract Observer protocol. observability §9
  • Span — An OTel unit of work — a named interval with timestamps, status, attributes, and parent/child links; each meaningful unit of a graph invocation maps to one. observability §2
  • Span attributes — Scalar (or scalar-array) key/value pairs on a span, namespaced under openarmature.. observability §2
  • Span hierarchy — The span tree of an invocation: invocation span (root) → node / subgraph / fan-out spans, with one node span per retry attempt. observability §4
  • Span status — A span's OK / ERROR / UNSET status; engine error categories map to ERROR with a category-bearing description. observability §2
  • Trace — An OTel tree of spans under one trace id; by default one outermost invocation is one trace, with subgraphs / fan-outs nested (unless detached). observability §2
  • Turn-level wrapper span — An optional harness-emitted span wrapping a whole turn, parenting the invocation span(s) within it. observability §4.6

Prompt management

  • ChatSegment — A unit of a chat-prompt template (role + content) in the chat-prompt variant of Prompt. prompt-management §3.1
  • ContentBlockTemplate — A templated content block within a ChatSegment, mirroring llm-provider content blocks at the template layer. prompt-management §3.1
  • Fetch vs. render — The deliberate split between retrieving a template (the I/O-bound step) and applying variables to it (local), enabling separate caching and inspection. prompt-management §2
  • Prompt — An unrendered template plus identity metadata; what a backend returns from a fetch, renderable and content-addressable without another round-trip. prompt-management §2
  • PromptBackend — The fetch-by-name-and-label protocol backends implement; backends fetch, they do not render. prompt-management §2
  • PromptGroup — A tracing convention grouping related PromptResults (e.g. classifier + follow-up) under one logical span grouping; not a fetch or render primitive. prompt-management §10
  • PromptManager — The user-facing API composing one or more PromptBackends and exposing fetch + render. prompt-management §2
  • PromptResult — The rendered output of applying variables to a Prompt: the rendered Message sequence, identity metadata, and a rendered_hash. prompt-management §2

Sessions

  • Session — The typed state record persisted under a session_id, carrying cross-invocation state plus identity metadata; distinct from per-invoke state. sessions §2
  • session_id — The caller-supplied, application-stable identifier scoping a session across many invocations; never engine-generated. sessions §2
  • SessionRecord — The stored representation of a session: session_id, serialized state, schema_version, and opaque backend metadata. sessions §2
  • SessionState — The optional typed projection of cross-invoke state — a narrower view than full invoke State, excluding per-invoke scratch fields. sessions §2
  • SessionStore — The load / save / delete / list protocol for session persistence; mirrors Checkpointer but session-keyed. sessions §2

Suspension

  • Paused-invocation record — The persisted state of a suspended invocation (state, signal descriptor, ids, completed positions), stored via the same machinery as checkpoints. suspension §2
  • Signal descriptor — The typed record attached at suspension: a caller-supplied signal_id correlation token plus optional application metadata. suspension §2
  • Signal payload — The application-defined data delivered at resume time and merged into invocation state before execution continues. suspension §2
  • signal_id — The caller-supplied correlation token on a signal descriptor, used to route an inbound signal back to its paused invocation. suspension §2
  • Suspended outcome — The invoke() return shape when a graph suspends — carrying invocation / correlation ids, the signal descriptor, the state at the pause, and the suspending node. suspension §2
  • Suspension — The intentional pause of an in-progress invocation at a node via suspend(); the engine persists state and returns a suspended outcome, resumed later with a signal payload. suspension §2

Harness

  • Harness — The integration layer wrapping the engine for a deployment runtime; owns inbound dispatch, the outbound surface, session lookup, and signal coordination. harness §2
  • Harness mode — Whether a harness is sessioned (every transmission tied to a session_id, state loaded / saved per turn) or stateless (independent turns, no session); fixed at construction. harness §2
  • Inbound dispatch path — One of the classification paths the harness routes inbound traffic into (stateless, new-session, existing-session, signal-resume). harness §2
  • Outbound surface — The mechanisms a harness uses to expose in-invocation effects: sync returns, async dispatches from node bodies, and signal subscriptions. harness §2
  • Session resolver — The (sessioned-mode) mechanism mapping inbound traffic to a session_id; the contract specifies that resolution happens, not how. harness §2
  • Signal coordinator — The mechanism routing inbound signal callbacks to the correct paused invocation. harness §2
  • Turn — One bounded engine execution serving an inbound request or event — exactly one invoke() (or resume) call, beginning at invoke entry and ending at its outcome. harness §2

Harness — chat

  • ChatMessage — The canonical typed message at the chat-harness boundary, mirroring llm-provider's message shape. harness-chat §2
  • ChatTurnOutcome — The discriminated return of the chat harness's send(): completed reply, errored turn, or suspended turn. harness-chat §2
  • ConversationHistory — The per-session field holding the ordered chat message list. harness-chat §2
  • Pending message — A synthetic assistant message a node may append before suspend() to tell the user the turn is awaiting a signal. harness-chat §2
  • send() callable — The convenience surface above raw invoke(): takes a session id and an inbound user message, returns a ChatTurnOutcome. harness-chat §2
  • Subscribed listener — The default mechanism by which a chat harness surfaces the post-resume assistant reply after a suspend → signal → resume cycle. harness-chat §2

Conformance adapter

  • Adapter — A language-specific runtime that discovers fixtures, parses their YAML into native graph calls, executes them, and asserts against the expected: block. Implementation-private; the fixtures are spec-public. conformance-adapter §2
  • Assertion shape — A field under expected: specifying what to verify — exact-equality (final_state, execution_order) or invariant (invariants, observer_event_invariants). conformance-adapter §2
  • Case — One scenario within a fixture; a fixture may hold a single top-level case or multiple under cases:. conformance-adapter §2
  • Directive — A named YAML field declaring something the adapter translates into a runtime construct or assertion (e.g. update, fan_out, observers[], final_state). conformance-adapter §2
  • Directive vocabulary — The full catalog of fixture directives the adapter supports, organized by kind (node-behavior, state / schema, edge, composition, observer, persistence, invocation-shape, expected-outcome, invariant). conformance-adapter §5
  • Fixture — A declarative test case: a YAML file (graph, initial state, expected outcome) plus a sibling Markdown describing intent and spec coverage. conformance-adapter §2
  • Harness primitive — A runtime construct the adapter must provide to satisfy directives needing infrastructure beyond the bare engine — in-memory observers, persistence backends, OTel capture, etc. conformance-adapter §2
  • Invariant — A name-keyed boolean predicate checked when ordering is observable but not uniquely determined (fan-out scheduling, parallel branches, observer dispatch). conformance-adapter §2