OpenArmature¶
A workflow framework for LLM pipelines and tool-calling agents — defined as a language-agnostic specification. Implementations conform to the same behavior via canonical fixtures, so the same workload runs the same way regardless of language or runtime.
Read the charter View on GitHub
Pipelines and agents — one substrate¶
Most frameworks pick a side: deterministic LLM pipelines or autonomous tool-calling agents. OpenArmature treats both as applications of the same primitives — typed graphs, conditional edges, middleware, checkpointing. A multi-stage content-extraction pipeline and a tool-loop agent are both just compiled graphs.
-
Deterministic LLM pipelines
Topology pinned at compile time. Each node does one thing — LLM call, parse, validate, persist. Per-node retries with explicit budgets; observability captures every step.
Use cases: content extraction, classification cascades, multi-stage analysis, document refinery.
-
Tool-calling agents
Same primitives, different shape: LLM node + tool-dispatch node + conditional edge back to the LLM. Tool-call envelope is normalized; multi-turn agents resume mid-conversation via checkpoint/resume.
Use cases: research agents, code-generation loops, data-extraction bots, multi-turn assistants.
What sets it apart¶
-
Transparency over abstraction
Provider responses surface verbatim alongside normalized fields. Internal events are observable via hook points at every node boundary. The framework adds structure; it never hides what the underlying tools returned.
-
Compile-time safety
Bad graph shapes fail at compile, not at run. Reducer conflicts, dangling edges, multiple outgoing edges from a non-conditional node — all caught before the first LLM call.
-
Composable, not prescriptive
Middleware is a primitive. Retry and timing ship canonical; everything else composes from the same protocol. No magic decorators, no global state — just explicit composition.
-
Observability built in
OpenTelemetry mapping is normative, not bolt-on. Span hierarchy mirrors graph structure; cross-backend correlation IDs flow with every invocation; detached trace mode keeps high-volume fan-outs readable.
Reference implementation¶
openarmature-python — currently in active development
The canonical reference implementation, building out the full capability set defined in this repo — graph engine, LLM and retrieval providers, pipeline utilities, prompt management, sessions, suspension, and observability — all driven by the conformance fixtures.
A TypeScript implementation is on the roadmap. Both will pin behavior to this spec.
Why a spec, not a library?¶
LLM workflow frameworks usually ship as opinionated libraries. Pick the wrong one and you're rewriting your pipeline; ship in two languages and you're maintaining two divergent codebases that drift over time. OpenArmature flips the model: the contract lives here as a spec with conformance fixtures, and reference implementations in each language port to the same behavior. Same workload, multiple runtimes, no behavioral drift.
-
Behavior pinned by fixtures
Over 400 conformance fixtures across ten capabilities. Implementations run them; if they pass, behavior matches every other conforming runtime. No "implementation-defined" footguns.
-
One contract, many runtimes
Reference implementations in Python (active) and TypeScript (planned). The same pipeline definition, the same observable trace shape, the same retry semantics — across languages.
-
Open evolution
New behavior lands through numbered RFC-style proposals reviewed in the open. Once accepted, a proposal's text is immutable; superseding proposals link the chain forward. No silent drift between releases.
How it evolves¶
OpenArmature is governed by a numbered proposal system: every behavioral change starts as a Draft RFC, is reviewed in the open, lands with a SemVer bump, and is frozen in proposal text once accepted. The capability specs are the source of truth; proposals are the change history.