You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Six changes after the first pass:
- Title capitalized: "openarmature" → "OpenArmature".
- PyPI badge explicit blue color.
- Python versions badge swapped from pypi/pyversions (which read
empty because pyproject.toml has no Python classifiers, so it
rendered "missing") to python/required-version-toml, which
reads requires-python directly. Renders "python: >=3.12".
A separate followup will add the classifiers list to
pyproject.toml so the PyPI listing itself shows Python compat.
- Hero tagline pulled into a centered h3 above the paragraph so
it reads as the headline of the page.
- "Why" bullets reformatted: bold header on its own line via
<br>, body underneath, instead of inline header-then-body.
- Hello World preamble rewritten with more energy: leads with
"Forty lines that show the engine in action" and ends with
"Copy it, run it, watch the events fire."
- All em dashes scrubbed from the copy (eleven total) and
replaced with commas, colons, or sentence splits. Next steps
switched to "Label: body. [link]" format with colon + period.
OpenArmature is a workflow framework for LLM pipelines and tool-calling
12
-
agents — typed state, compile-time topology checks, and observability
13
-
and crash-safe checkpoints baked into the engine. The graph layer
14
-
itself has no concept of LLMs or tools, so the same primitives drive
15
-
deterministic ETL pipelines and tool-calling agents alike.
11
+
<divalign="center">
12
+
<h3>OpenArmature is a workflow framework for LLM pipelines and tool-calling agents.</h3>
13
+
</div>
16
14
17
-
This Python package is the reference implementation; the behavioral
18
-
contract is specified in [openarmature-spec](https://github.com/LunarCommand/openarmature-spec)
19
-
and verified by conformance fixtures.
15
+
Typed state, compile-time topology checks, and observability and crash-safe checkpoints are baked into the engine. The graph layer itself has no concept of LLMs or tools, so the same primitives drive deterministic ETL pipelines and tool-calling agents alike.
16
+
17
+
This Python package is the reference implementation. The behavioral contract is specified in [openarmature-spec](https://github.com/LunarCommand/openarmature-spec)and verified by conformance fixtures.
alongside the framework's. Your spans flow exactly where you point
89
-
them; no surprise fan-out to vendor backends you didn't configure.
31
+
**State you can't accidentally mutate.**<br>
32
+
State schemas are frozen Pydantic models. Nodes return partial updates; the engine merges. The snapshot a node holds can't change mid-execution, and assignment into state raises rather than silently writing.
33
+
34
+
**Schema validation at every merge.**<br>
35
+
Fields outside the declared schema fail at the merge boundary instead of silently dropping. A node returning `{"plann": "..."}` (typo) raises `StateValidationError` immediately, not three nodes downstream when the field is read and doesn't exist.
36
+
37
+
**Merge policy on the schema, not the call site.**<br>
38
+
Each state field declares its reducer (`last_write_wins`, `append`, `merge`, or a user-defined callable) as part of the schema. Two nodes writing the same field compose via the field's policy: once, declaratively, instead of duplicated across call sites.
39
+
40
+
**Subgraphs compose with explicit data seams.**<br>
41
+
Subgraphs run against their own state schema with `inputs` (additive, opt in to share parent fields) and `outputs` (replacement, name exactly what comes back) mappings. Parent fields don't leak in by accident; subgraph fields don't slip out unless declared.
42
+
43
+
**Bad graphs don't compile.**<br>
44
+
Dangling edges, unreachable nodes, conflicting reducers, no declared entry, mappings to undeclared fields, multiple outgoing edges from one node. Six categories of structural error all fail at `.compile()`, not at runtime mid-execution. The graph either constructs cleanly or it doesn't reach `invoke()`.
45
+
46
+
**The graph engine has no concept of LLMs or tools.**<br>
47
+
Validation, retry, recovery, structured output: those are node-internal or middleware concerns. The same engine runs deterministic ETL pipelines and tool-calling agents; the topology layer doesn't pick a side.
48
+
49
+
**Determinism is a contract.**<br>
50
+
Same input, same node implementations, same edge functions, same final state, and same observed node-execution order. The spec mandates it; conformance fixtures verify it across every implementation. Replay an audit run and get byte-identical state.
51
+
52
+
**Checkpoint saves are synchronous-by-contract.**<br>
53
+
The engine awaits each save before advancing. A crash immediately after a `completed` event cannot have lost the corresponding write. Resume mints a fresh `invocation_id` (audit trail) while preserving `correlation_id` (cross-system join key), so a recovered run is traceable as a new attempt without losing the thread to the original request.
54
+
55
+
**Observability that doesn't double-export.**<br>
56
+
The OpenTelemetry mapping mandates a private `TracerProvider`. That prevents the trap where global-provider auto-instrumentation libraries (OpenInference, Langfuse v3, etc.) emit duplicate spans alongside the framework's. Your spans flow exactly where you point them; no surprise fan-out to vendor backends you didn't configure.
90
57
91
58
## Hello World
92
59
93
-
A three-node classification pipeline. Three different reducer
94
-
policies on one state class, conditional routing as a pure function
95
-
of state, and an observer that sees every node boundary — without
96
-
any LLM setup. Requires Python ≥ 3.12.
60
+
Forty lines that show the engine in action. Three reducer policies declared on one state class. Routing as a pure function of state, not a hidden state machine. An observer attached at compile time that sees every node boundary the engine emits. No LLM, no API key, no boilerplate. Copy it, run it, watch the events fire. Requires Python 3.12 or later.
97
61
98
62
```python
99
63
import asyncio
@@ -170,35 +134,18 @@ final = asyncio.run(graph.invoke(PipelineState(query="what is RAG?")))
170
134
# research: sources=['wikipedia', 'arxiv']
171
135
```
172
136
173
-
A few things to notice in ~40 lines:
174
-
175
-
-**Three reducer policies on one state schema.**`query` and
176
-
`classification` get the default `last_write_wins`. `sources` is
`metadata` is `Annotated[dict[str, str], merge]` — successive
179
-
writes shallow-merge. The merge policy lives on the schema, once.
180
-
-**Conditional routing as a state function.**`route` reads
181
-
`state.classification` and returns a node name. The graph engine
182
-
doesn't care that this happens to be deterministic; it would
183
-
accept an LLM-driven router with the same shape.
184
-
-**Observer sees both phases.**`trace` filters to `completed` events
185
-
for brevity; the engine also delivers `started` events.
186
-
-**The graph either compiles or it doesn't.** Remove `.set_entry()`
187
-
and `.compile()` raises `NoDeclaredEntry` before `invoke()` runs.
137
+
A few things to notice in those forty lines:
138
+
139
+
-**Three reducer policies on one state schema.**`query` and `classification` get the default `last_write_wins`. `sources` is `Annotated[list[str], append]`, so successive writes concatenate. `metadata` is `Annotated[dict[str, str], merge]`, so successive writes shallow-merge. The merge policy lives on the schema, once.
140
+
-**Conditional routing as a state function.**`route` reads `state.classification` and returns a node name. The graph engine doesn't care that this happens to be deterministic; it would accept an LLM-driven router with the same shape.
141
+
-**Observer sees both phases.**`trace` filters to `completed` events for brevity; the engine also delivers `started` events.
142
+
-**The graph either compiles or it doesn't.** Remove `.set_entry()` and `.compile()` raises `NoDeclaredEntry` before `invoke()` runs.
188
143
189
144
## Next steps
190
145
191
-
-**Quickstart** — build your first graph end-to-end:
-**Model Providers**: implement the Provider Protocol for a custom LLM backend. [openarmature.ai/model-providers/authoring](https://openarmature.ai/model-providers/authoring/)
149
+
-**API reference**: auto-generated from docstrings. [openarmature.ai/reference](https://openarmature.ai/reference/)
0 commit comments