| Filename | Latest commit message | Latest commit date |
|---|---|---|
ea679e364c
Sealed receipts already record what a cascade walk did: which tier
closed the query, at what microjoule cost, at what counter honesty.
That is an observed execution outcome — the same class of supervision
a code model gets from "passes on head, fails on base", except it
arrives signed and energy-metered rather than reconstructed after the
fact. Until now receipts were terminal: written, verified, summed into
cost reports, never read again.
This projects them into the labelled (embedding, stage, success,
cost_microjoules) rows an EOC router trainer consumes, so the ledger
compounds instead of merely accumulating.
Derivation is honest about its limits:
- cost_microjoules is verbatim joules_uj — not modelled, not rescaled.
- stage prefers the runtime's own eoc_stage label, else maps from
CascadeTier only where unambiguous. L1Lawful has no EOC analogue and
nothing maps to Graph, so those receipts are skipped and counted in
CorpusStats rather than guessed into a bucket.
- success means "this tier closed the walk". The receipt carries no
failure discriminator; that is documented, not papered over.
- Monotone negatives (the cheaper rungs a strict cascade must have
escalated past) are opt-in, because they rest on an assumption a
rung-skipping router would break. Graph is never synthesised as a
negative.
Two traps absorbed. The receipt's eoc_stage is lower-case ("neural")
while the trainer's Stage deserialises capitalised ("Neural") and
rejects anything else — passing the field through fails at ingest, so
from_eoc_label converts and a test pins the emitted spelling. And the
bundled StructuralEmbedder deliberately excludes tier and joules: they
are the label side of every row, and a router that could read the
closing tier out of its own features would score perfectly while
learning nothing.
Receipts carry no vector, so the embedder is a trait. The bundled one
is deterministic and offline over receipt structure — it does not
encode query semantics, and says so.
Coupling is the wire format by design: EOC takes no dependency on
JouleClaw and JouleClaw none on EOC.
Verified end to end: emit_corpus → JSONL → the trainer's own loader →
train_logreg and train_mf both produce routers. 14 tests.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
|
||
| .. | ||
| conformance/v1 | ||
| jouleclaw-rs | ||
| vocab | ||
| LICENSE | ||
| README.md | ||
| ROADMAP.md | ||
| SPEC.md | ||
JouleClaw — Energy-Optimized AI Runtime
The substrate for AI that costs Joules, not tokens.
Capability per Joule, not capability per parameter.
What JouleClaw is
JouleClaw is a pure-Rust, omni-modal AI runtime + harness + agentic layer governed by Transaction Science as an open standard (5th in the open-standards quartet, alongside OpenPay, Smart Byte, EOC, and WAI).
Every operation JouleClaw performs walks an explicit energy-tiered cascade, top to bottom, stopping at the first stage that closes the query:
| Tier | Name | Cost class | What runs here |
|---|---|---|---|
| L0 | Cache | picojoules | Content-addressed cache hits |
| L1 | Lawful | nanojoules | Deterministic, pre-compiled primitive (text/code only) |
| L2 | Embed | sub-millijoules | Matryoshka embeddings + nearest-neighbor + hybrid search |
| L3 | Model | joules | Local SSM / ternary / multimodal / diffusion / etc. |
| L4 | Wire | tens of joules | Remote frontier RPC (escape hatch only) |
L1 (Lawful) is only meaningful for text and code modalities. For image, audio, video and 3D generation, the cascade collapses to L0 / L2 / L3 / L4 — the energy savings come from caching plus dispatch to the cheapest model that meets the quality bar.
Why JouleClaw exists
The mainstream "agentic AI" ecosystem treats inference as the entry point. Every state shift, every tool call, every routing decision runs through a 70-billion-parameter stochastic engine, burning kilojoules to do work that deterministic compute or a hot cache could resolve for microjoules.
JouleClaw inverts the default. Inference is the last resort, not the first. Frozen model weights are less trustworthy than current world state; fresh, provenance-stamped retrieval beats synthesis from training cuts. Every operation is metered in microjoules where the hardware permits it, and in millijoules where it doesn't — the spec is honest about the floor on every platform.
The thermodynamic circuit breaker is the safety mechanism. Set an energy budget; when measured consumption exceeds the budget, the breaker trips and the operation halts. Hallucination loops cannot survive an honest joule ledger.
What's here
| Path | Contents |
|---|---|
SPEC.md |
JouleClaw v1 spec — cascade tiers, energy contract, receipt |
CHARTER.md |
Stewardship pattern (shared across open-standards) |
jouleclaw-rs/ |
Apache-2.0 Rust reference implementation |
spec/ |
Tier specifications, energy provenance, receipt format |
conformance/v1/ |
Signed wire vectors for cross-implementation verification |
Reference implementation
jouleclaw-rs/ is the Apache-2.0 reference implementation in Rust. It
runs on Apple Silicon (M3/M4/M5 with UMA + Metal 4 Tensor APIs), AMD Strix
Halo / Ryzen AI Max, Intel Lunar Lake, NVIDIA Jetson, and discrete
NVIDIA / AMD GPUs.
It is omni-modal: text, code, vision, audio, video, image diffusion, 3D Gaussian splatting, and cross-modal fusion all dispatch through the same energy-tiered cascade.
The MCP tool surface is a JCP consumer: jouleclaw-jcp wraps any
jouleclaw-mcp metered tool so every dispatch is decided by the JCP runtime
against a signed, metered Grant before a byte reaches the tool — the tool's
identity is the content-addressed resource, the call's energy estimate is
debited from the grant's joule budget, and every decision (allow and deny
alike) seals as a JCR-1 receipt. An injected instruction can name an ungranted
tool; it cannot make the gate dispatch it.
Status
v0.1.0 reference implementation in active development. The spec is draft status. Cross-implementation conformance vectors will land with v1.0.0.
License
- Code: Apache-2.0 (see
LICENSE) - Spec text: CC-BY-4.0 (see
spec/LICENSE)