hearth-engine 0.1.0__tar.gz

hearth_engine-0.1.0/Cargo.lock

@@ -0,0 +1,423 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "bitflags"
+version = "2.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "convert_case"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec182b0ca2f35d8fc196cf3404988fd8b8c739a4d270ff118a398feb0cbec1ca"
+dependencies = [
+ "unicode-segmentation",
+]
+
+[[package]]
+name = "ctor"
+version = "0.2.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a2785755761f3ddc1492979ce1e48d2c00d09311c39e4466429188f3dd6501"
+dependencies = [
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "hearth-core"
+version = "0.1.0"
+dependencies = [
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "hearth-node"
+version = "0.1.0"
+dependencies = [
+ "hearth-core",
+ "napi",
+ "napi-build",
+ "napi-derive",
+ "serde_json",
+]
+
+[[package]]
+name = "hearth-py"
+version = "0.1.0"
+dependencies = [
+ "hearth-core",
+ "pyo3",
+ "serde_json",
+]
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "indoc"
+version = "2.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "libc"
+version = "0.2.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[package]]
+name = "libloading"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
+dependencies = [
+ "cfg-if",
+ "windows-link",
+]
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "napi"
+version = "2.16.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "55740c4ae1d8696773c78fdafd5d0e5fe9bc9f1b071c7ba493ba5c413a9184f3"
+dependencies = [
+ "bitflags",
+ "ctor",
+ "napi-derive",
+ "napi-sys",
+ "once_cell",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "napi-build"
+version = "2.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60fdf9b392c50e7c4170fa633bd909490ed7835cea4c046776d1a4dd8d2ae0ab"
+
+[[package]]
+name = "napi-derive"
+version = "2.16.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7cbe2585d8ac223f7d34f13701434b9d5f4eb9c332cccce8dee57ea18ab8ab0c"
+dependencies = [
+ "cfg-if",
+ "convert_case",
+ "napi-derive-backend",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "napi-derive-backend"
+version = "1.0.75"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1639aaa9eeb76e91c6ae66da8ce3e89e921cd3885e99ec85f4abacae72fc91bf"
+dependencies = [
+ "convert_case",
+ "once_cell",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "semver",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "napi-sys"
+version = "2.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "427802e8ec3a734331fec1035594a210ce1ff4dc5bc1950530920ab717964ea3"
+dependencies = [
+ "libloading",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f402062616ab18202ae8319da13fa4279883a2b8a9d9f83f20dbade813ce1884"
+dependencies = [
+ "cfg-if",
+ "indoc",
+ "libc",
+ "memoffset",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+ "unindent",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b14b5775b5ff446dd1056212d778012cbe8a0fbffd368029fd9e25b514479c38"
+dependencies = [
+ "once_cell",
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ab5bcf04a2cdcbb50c7d6105de943f543f9ed92af55818fd17b660390fc8636"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fd24d897903a9e6d80b968368a34e1525aeb719d568dba8b3d4bfa5dc67d453"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36c011a03ba1e50152b4b394b479826cad97e7a21eb52df179cd91ac411cbfbe"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "pyo3-build-config",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "regex"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+
+[[package]]
+name = "rustversion"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+
+[[package]]
+name = "semver"
+version = "1.0.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.4",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.151"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6275cddf4610d1775e6d1fe9469b2e77d0f39fd98fb7450901b821e0c53649f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.12.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unicode-segmentation"
+version = "1.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"
+
+[[package]]
+name = "unindent"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"

hearth_engine-0.1.0/Cargo.toml

@@ -0,0 +1,14 @@
+[workspace]
+resolver = "2"
+members = ["crates/hearth-core", "crates/hearth-py"]
+
+[workspace.package]
+version = "0.1.0"
+edition = "2021"
+license = "BUSL-1.1"
+repository = "https://github.com/aiassistsecure/hearth"
+authors = ["Interchained LLC"]
+
+[workspace.dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"

hearth_engine-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: hearth-engine
+Version: 0.1.0
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Distributed Computing
+Summary: Deterministic model residency — keep declared models warm, and tell the truth about which ones are.
+Keywords: llm,inference,gpu,vram,residency,ollama,llama.cpp
+Author: Interchained LLC
+License: BUSL-1.1
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/Eth-Interchained/hearth
+Project-URL: Repository, https://github.com/Eth-Interchained/hearth
+
+# hearth
+
+**Deterministic model residency.** Keep declared models warm, and tell the truth about which ones are.
+
+Not an inference engine. llama.cpp and vLLM have spent years on kernels, samplers and tokenizers, and none of that is the problem. The problem is that no serving stack will *promise* a model stays loaded, and none of them can say *why* one stopped being.
+
+## The night this came from
+
+A PIN operator on one rented RTX A6000 stopped answering. Requests hung, then failed. Four pull requests landed against the streaming path in a single evening and none of them were the cause — because the cause was never visible. Three completely different failures were arriving as the same timeout:
+
+- the runtime evicted a model to free VRAM,
+- the host detached the GPU and gave it to another tenant,
+- a 32B model was simply still loading.
+
+One of those is a capacity problem you own. One is your provider's and no configuration will touch it. One is not a problem at all. A timeout cannot tell you which, so all three got "fixed" repeatedly and none of them went away.
+
+Worse, the operator was being **scored down** for a card their host reclaimed. A reputation system fed that kind of data slowly deletes its own honest operators.
+
+## What it does
+
+```
+$ hearth status
+42.0 / 44.2 GiB held  (5 declared, 2 admitted)
+  muse-local:latest            resident for 14203s
+  deepseek-r1:32b              loading for 47s
+  gemma4:26b                   not admitted — short by 14.8 GiB
+  qwen3.6:27b                  not admitted — short by 15.8 GiB
+  gemma4-extract:31b           not admitted — short by 17.8 GiB
+```
+
+Three things, none of which you can get today:
+
+**1. Residency is a named state with a named reason.**
+
+```
+Unknown    never probed
+Loading    weights materializing — with elapsed, so it can say how long
+Resident   loaded AND answering AND accounted for
+Lost       with a reason: Evicted · GpuDetached · ProcessExited · Unhealthy
+Failed     won't load, and what the runtime said
+Stopped    unloaded on purpose
+```
+
+`Evicted` and `GpuDetached` are the two states nothing else reports, and they were the two that mattered. They are distinguished by one bit — whether the GPU was still present when the probe failed — and that bit is the entire diagnosis.
+
+**2. The card's size is arithmetic, checked before anything loads.**
+
+Declare four 20 GiB models on a 48 GiB card and no runtime errors. It loads, evicts, loads, evicts, forever, and presents as "the models got slow." hearth refuses the fifth model at declare time and tells you it was short by 17.8 GiB. Nothing is ever evicted to make room for a load — if it doesn't fit, the honest answer is that it doesn't fit.
+
+**3. Routers get an answer they can act on.**
+
+| answer | what a router should do |
+|---|---|
+| `Ready` | send it |
+| `Warming{for_ms}` | wait, or try elsewhere — but do **not** fault this node |
+| `Lost{GpuDetached}` | try elsewhere, and do **not** score this operator down |
+| `Lost{Evicted}` | try elsewhere; this box is over-committed |
+| `NotAdmitted{short}` | stop asking — it will never fit here |
+| `Unknown` | we genuinely don't know yet, and we say so |
+
+## Design rules
+
+**Nothing fails on a clock.** A 32B materializing over a network fabric can legitimately spend minutes before its first token, and killing it at an arbitrary deadline turns a slow success into a fast failure. `Loading` reports how long it has been loading; deciding what to do about that belongs to whoever knows if a human is waiting. Progress is reported — patience is a policy, not a constant.
+
+**`Loading` is not `Ready`.** The most common way a serving stack lies is routing to something still coming up and calling the inevitable timeout an error.
+
+**Declaration order is priority order.** First fit, never best fit. Reordering to squeeze in one more model would silently demote whatever the operator listed first, and on a serving box first means most important. A planner that outsmarts the operator surprises them at 3am.
+
+**The reserve is never planned into.** Weights aren't the whole cost — KV cache grows with context and parallelism, the CUDA context is hundreds of megabytes, and fragmentation is real on a card that's been up for weeks.
+
+## Status
+
+`hearth-core` — state machine, VRAM planner, fleet routing. 33 tests, all pure logic, no GPU required to run them.
+
+Next: supervisor over `llama-server` children · NVML probe · HTTP surface (OpenAI-compatible + `/residency`) · CLI · napi + PyO3 bindings · NEDB event log.
+
+That last one is the interesting one. Every state transition becomes an event in [NEDB](https://github.com/Eth-Interchained/nedb), which is bi-temporal — so *"what was resident **as of** 03:14?"* is a real query against a real causal chain. When a model goes cold at 3am you get the answer instead of a theory.
+
+## Integration
+
+hearth speaks OpenAI-compatible, so [pin-clientd](https://github.com/aiassistsecure/pin-clientd) works with it today: set `apiMode: "openai"` and point `inferenceUri` at hearth. `/residency` then adds the truth that the OpenAI shape has no way to express.
+
+## Build
+
+```bash
+cargo test          # 33 tests, no GPU needed
+cargo run --example a6000
+```
+
+---
+
+© Interchained LLC · BUSL-1.1 (converts to Apache-2.0 on 2030-08-27)
+

hearth_engine-0.1.0/README.md

@@ -0,0 +1,92 @@
+# hearth
+
+**Deterministic model residency.** Keep declared models warm, and tell the truth about which ones are.
+
+Not an inference engine. llama.cpp and vLLM have spent years on kernels, samplers and tokenizers, and none of that is the problem. The problem is that no serving stack will *promise* a model stays loaded, and none of them can say *why* one stopped being.
+
+## The night this came from
+
+A PIN operator on one rented RTX A6000 stopped answering. Requests hung, then failed. Four pull requests landed against the streaming path in a single evening and none of them were the cause — because the cause was never visible. Three completely different failures were arriving as the same timeout:
+
+- the runtime evicted a model to free VRAM,
+- the host detached the GPU and gave it to another tenant,
+- a 32B model was simply still loading.
+
+One of those is a capacity problem you own. One is your provider's and no configuration will touch it. One is not a problem at all. A timeout cannot tell you which, so all three got "fixed" repeatedly and none of them went away.
+
+Worse, the operator was being **scored down** for a card their host reclaimed. A reputation system fed that kind of data slowly deletes its own honest operators.
+
+## What it does
+
+```
+$ hearth status
+42.0 / 44.2 GiB held  (5 declared, 2 admitted)
+  muse-local:latest            resident for 14203s
+  deepseek-r1:32b              loading for 47s
+  gemma4:26b                   not admitted — short by 14.8 GiB
+  qwen3.6:27b                  not admitted — short by 15.8 GiB
+  gemma4-extract:31b           not admitted — short by 17.8 GiB
+```
+
+Three things, none of which you can get today:
+
+**1. Residency is a named state with a named reason.**
+
+```
+Unknown    never probed
+Loading    weights materializing — with elapsed, so it can say how long
+Resident   loaded AND answering AND accounted for
+Lost       with a reason: Evicted · GpuDetached · ProcessExited · Unhealthy
+Failed     won't load, and what the runtime said
+Stopped    unloaded on purpose
+```
+
+`Evicted` and `GpuDetached` are the two states nothing else reports, and they were the two that mattered. They are distinguished by one bit — whether the GPU was still present when the probe failed — and that bit is the entire diagnosis.
+
+**2. The card's size is arithmetic, checked before anything loads.**
+
+Declare four 20 GiB models on a 48 GiB card and no runtime errors. It loads, evicts, loads, evicts, forever, and presents as "the models got slow." hearth refuses the fifth model at declare time and tells you it was short by 17.8 GiB. Nothing is ever evicted to make room for a load — if it doesn't fit, the honest answer is that it doesn't fit.
+
+**3. Routers get an answer they can act on.**
+
+| answer | what a router should do |
+|---|---|
+| `Ready` | send it |
+| `Warming{for_ms}` | wait, or try elsewhere — but do **not** fault this node |
+| `Lost{GpuDetached}` | try elsewhere, and do **not** score this operator down |
+| `Lost{Evicted}` | try elsewhere; this box is over-committed |
+| `NotAdmitted{short}` | stop asking — it will never fit here |
+| `Unknown` | we genuinely don't know yet, and we say so |
+
+## Design rules
+
+**Nothing fails on a clock.** A 32B materializing over a network fabric can legitimately spend minutes before its first token, and killing it at an arbitrary deadline turns a slow success into a fast failure. `Loading` reports how long it has been loading; deciding what to do about that belongs to whoever knows if a human is waiting. Progress is reported — patience is a policy, not a constant.
+
+**`Loading` is not `Ready`.** The most common way a serving stack lies is routing to something still coming up and calling the inevitable timeout an error.
+
+**Declaration order is priority order.** First fit, never best fit. Reordering to squeeze in one more model would silently demote whatever the operator listed first, and on a serving box first means most important. A planner that outsmarts the operator surprises them at 3am.
+
+**The reserve is never planned into.** Weights aren't the whole cost — KV cache grows with context and parallelism, the CUDA context is hundreds of megabytes, and fragmentation is real on a card that's been up for weeks.
+
+## Status
+
+`hearth-core` — state machine, VRAM planner, fleet routing. 33 tests, all pure logic, no GPU required to run them.
+
+Next: supervisor over `llama-server` children · NVML probe · HTTP surface (OpenAI-compatible + `/residency`) · CLI · napi + PyO3 bindings · NEDB event log.
+
+That last one is the interesting one. Every state transition becomes an event in [NEDB](https://github.com/Eth-Interchained/nedb), which is bi-temporal — so *"what was resident **as of** 03:14?"* is a real query against a real causal chain. When a model goes cold at 3am you get the answer instead of a theory.
+
+## Integration
+
+hearth speaks OpenAI-compatible, so [pin-clientd](https://github.com/aiassistsecure/pin-clientd) works with it today: set `apiMode: "openai"` and point `inferenceUri` at hearth. `/residency` then adds the truth that the OpenAI shape has no way to express.
+
+## Build
+
+```bash
+cargo test          # 33 tests, no GPU needed
+cargo run --example a6000
+```
+
+---
+
+© Interchained LLC · BUSL-1.1 (converts to Apache-2.0 on 2030-08-27)

hearth_engine-0.1.0/crates/hearth-core/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "hearth-core"
+description = "Deterministic model residency: pin models warm, and tell the truth about which ones are."
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+authors.workspace = true
+
+[dependencies]
+serde = { workspace = true }
+serde_json = { workspace = true }

hearth_engine-0.1.0/crates/hearth-core/examples/a6000.rs

@@ -0,0 +1,33 @@
+//! What actually fits on one RTX A6000, given the roster that was registered
+//! when PIN stopped answering.
+use hearth_core::budget::gib;
+use hearth_core::{plan, Budget, Declared, GIB};
+
+fn m(model: &str, w: u64, kv: u64) -> Declared {
+    Declared {
+        model: model.into(),
+        weights_bytes: w,
+        kv_bytes: kv,
+    }
+}
+
+fn main() {
+    let card = Budget::with_reserve_pct(48 * GIB, 8);
+    println!(
+        "RTX A6000 — {:.0} GiB total, {:.1} GiB reserved, {:.1} GiB usable\n",
+        gib(card.total_bytes),
+        gib(card.reserve_bytes),
+        gib(card.usable_bytes())
+    );
+
+    let roster = vec![
+        m("muse-local:latest", 20 * GIB, GIB),
+        m("deepseek-r1:32b", 20 * GIB, GIB),
+        m("gemma4:26b", 16 * GIB, GIB),
+        m("qwen3.6:27b", 17 * GIB, GIB),
+        m("gemma4-extract:31b", 19 * GIB, GIB),
+    ];
+    let p = plan(card, &roster);
+    println!("{}", p.explain());
+    println!("\nheadroom: {:.1} GiB", gib(p.headroom_bytes()));
+}