open-standards/eoc/eoc-rs/README.md

eoc-rs — EOC reference implementation in Rust

Apache-2.0 reference implementation of the Energy-Optimized Compute specification (CC-BY-4.0 spec lives in ../spec/).

EOC is a four-stage memoizing cascade. Every query is tried at each stage in turn and the first that can answer wins. The four stages, cheapest to most expensive, are:

1. Cache (eoc-cache) — content-addressed LRU. Cache hits are nearly free.
2. Key-value (eoc-kv) — exact key match plus cosine-similarity embedding match.
3. Graph (eoc-graph) — triple-store retrieval. Reference impl is a small in-memory matcher; production deployments swap in a real graph backend driven by DCY (EOC-4).
4. Neural (eoc-neural) — last-resort inference. Reference impl ships an EchoBackend; production deployments wire in llama.cpp / Ollama / Anthropic API / etc.

Joule cost is the unit of accounting. The eoc-meter crate reads cumulative micro-joules from whatever hardware counter is available (Linux RAPL, macOS powermetrics, NVIDIA NVML behind the cuda feature) and falls back to a StubCounter everywhere else — including WASM.

Workspace layout

Crate	Purpose
eoc-core	Types: Query, Response, Stage, JouleCost, Receipt.
eoc-cache	Stage 1 — LRU cache + the Stage trait.
eoc-kv	Stage 2 — KV + embedding-similarity lookup.
eoc-graph	Stage 3 — in-memory triple store.
eoc-neural	Stage 4 — neural inference trait + EchoBackend.
eoc-meter	Hardware energy counters with stub fallback.
eoc-cascade	Glue: walks the four stages, attributes joule cost.
eoc	Reference CLI.
eoc-wasm	wasm-bindgen wrapper — browser-runnable cascade.

Running

cargo test --workspace
cargo clippy --workspace --all-targets
cargo run --bin eoc -- query "what is 2+2"
cargo run --bin eoc -- meter

Example output:

$ cargo run --bin eoc -- query "what is 2+2"
stage  : kv
payload: 4
cost   : 50 µJ (estimated)
receipt: <64-char hex>

CUDA / NVML

NVIDIA NVML support is feature-gated and off by default so the workspace builds without libnvidia-ml. To enable:

cargo build -p eoc-meter --features cuda

WASM

The cascade compiles to wasm32-unknown-unknown. The meter does not — RAPL, NVML, and powermetrics are all absent in the browser, so WASM builds use StubCounter and report estimated joule cost.

rustup target add wasm32-unknown-unknown
cargo build -p eoc-wasm --target wasm32-unknown-unknown --release
wasm-bindgen target/wasm32-unknown-unknown/release/eoc_wasm.wasm \
    --out-dir ./pkg --target web

Then from JavaScript:

import init, { WasmCascade } from "./pkg/eoc_wasm.js";
await init();
const cascade = new WasmCascade();
const r = await cascade.resolve("ping");
console.log(r); // { stage: "kv", payload: "pong", microjoules: 50, ... }

License

Apache-2.0 for the Rust source in this workspace. The EOC specification text in ../spec/ is CC-BY-4.0. See ../LICENSE.