skynet-graph 1.2.0 → 1.3.0

package/README.md

@@ -14,26 +14,34 @@ for free, and steers the model's output against a certified method vocabulary. N
 <p align="center"><i>Active R&D · a CommonJS library to embed + an <code>sg</code> CLI · Node 18+, no build step · AGPL-3.0</i></p>
 
 <p align="center">
+<a href="https://www.npmjs.com/package/skynet-graph"><img src="https://img.shields.io/npm/v/skynet-graph?logo=npm&amp;color=cb3837" alt="npm version"></a>
+<a href="https://www.npmjs.com/package/skynet-graph"><img src="https://img.shields.io/npm/dm/skynet-graph?color=cb3837" alt="npm downloads"></a>
+<a href="https://nodejs.org"><img src="https://img.shields.io/node/v/skynet-graph" alt="node version"></a>
+<a href="./LICENSE"><img src="https://img.shields.io/npm/l/skynet-graph?color=blue" alt="AGPL-3.0"></a>
 <a href="https://doi.org/10.5281/zenodo.21032471"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.21032471.svg" alt="DOI"></a>
 <a href="https://doi.org/10.5281/zenodo.21201877"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.21201877.svg" alt="DOI"></a>
 </p>
 
-## What you get
+## What it is
 
-A 27B model crushed to 9.5 GB (IQ2) runs on your GPU — but quantization broke part of its judgment,
-and any big task overflows it. This engine gives that model four things, **each measured on real GPUs,
-with negative controls and deterministic re-runs**:
+**skynet-graph is the low-level reasoning substrate + a library of composable combos** — the engine you
+*embed*. The substrate is a versionable, git-like reasoning graph: declarative concept rules + provider
+functions driven to a coherent belief state by stabilization, with native cascading retraction and
+rollback / fork / merge on what the system currently holds true. On top of it, a set of **combos**
+(`Graph.combos.*`, C1–C9 + the forge) each turn on one capability for a task type — the *bricks* an
+application assembles.
 
-- **Big tasks, piece by piece** — the model never sees the whole problem, only one bounded piece at a
-  time: accuracy **×2.5–3.2** on multi-step tasks, and where whole-context prompting **collapses (0/33)**,
-  the pieces hold (**10/33**).
-- **Repair for low quants** — verified method shapes steer the output: SQL **8→63 %**, finance tables
-  **7→62 %**, at **zero big-model calls** on covered queries.
-- **Task memory that reopens** — a late correction automatically un-does everything that depended on
-  it, and "done" steps **reopen themselves with the reason**. No stale state, ever.
-- **An external think mode** — benched head-to-head: the model's *native* think budget scores
-  **13/24 ≈ a coin flip** on side-judgment; the external critical mind renders **0 wrong verdicts**
-  (24/24 provable on a declared frame, an honest UNDECIDED otherwise).
+For a small local model those bricks add up to four capabilities (one line each here; the measured
+numbers, negative controls, limits and maturity live in **[doc/CAPABILITIES.md](doc/CAPABILITIES.md)**):
+
+- **Piece-by-piece** — works a big task one bounded piece at a time: **×2.5–3.2** on multi-step tasks, and where whole-context prompting collapses (**0/33**) the pieces hold (**10/33**).
+- **Low-quant repair** — certified method shapes steer the output: SQL **8→63 %**, finance **7→62 %**, at zero big-model calls on covered queries.
+- **Task memory that reopens** — a late correction retracts its consequences in cascade; "done" steps reopen with the reason, at 0 model calls.
+- **External think mode** — the model proposes, the graph refutes with the reason: a native think budget scores **13/24 ≈ chance**, the external critical mind **0 wrong verdicts**.
+
+These are the building blocks; **[mindsmith](https://www.npmjs.com/package/mindsmith) is the public façade
+that puts them in users' hands** (an OpenAI endpoint + MCP tools + local rooms). This repo is what mindsmith
+— or your own app — is built on.
 
 **See it in 30 seconds — no model, no GPU** (a deterministic replay of a real end-to-end run — the
 9.5 GB quant analyzing an annual report, erratum and crash included):
@@ -62,22 +70,20 @@ Where it sits in your setup — two zero-integration doors into one local loop:
         [your local GGUF model]    — nothing leaves the machine
 ```
 
----
-
-## The four capabilities, measured
+> **Two packages, one loop.** This repo — **`skynet-graph`** — is the **substrate + the combos**: the
+> reasoning engine and the composable bricks (`Graph.combos.*`, C1–C9 + the forge) that each *activate* a
+> capability for a task type. **[mindsmith](https://www.npmjs.com/package/mindsmith)** is the ready-made
+> **app that actually uses them** — the endpoint + MCP tools + local rooms drawn above, assembled and
+> hardened. **To *run* this on your model → `npx mindsmith serve`. Embed skynet-graph to *build* your own.**
 
-Small local models are fine on a *surface* step; they derail when a request makes them **compose**
-several things at once. This library puts them in front of one surface at a time.
+---
 
-**Proof degrees:** **[live]** = measured on GPU with real local models · **[measured]** = deterministic,
-replayable without a model · **[PoC]** = an accounting demonstration, not a benchmark.
+## Capabilities & maturity
 
-| Capability | What happens | Measured |
-|---|---|---|
-| **Repair low-quants** | a menu of *certified* method shapes steers a heavily-quantized model's output — it recovers most of what compression broke, at **zero big-model calls** | SQL, covered queries: low-quant 8→**63 %** (high-quant 46→92 %), N=201 · finance, traffic view: 7→**62 %** (20→78 %), N=120 · [live] |
-| **Task memory that reopens** | task state = typed facts with provenance (JTMS): a drifted premise **retracts its consequences in cascade**, and a "done" step **reopens itself with the reason** — it never rots | recomputable drift re-derives at **0 model calls**, selectively (independent facts untouched); crash-replay is bit-identical at 0 calls [live] · 100 % recall at **894 constant tokens/call** vs 50 % at 4 286 for a carry-everything baseline [PoC] |
-| **Piece-by-piece (the zoom)** | the task becomes a typed DAG; each piece is served with ONLY its bounded neighbourhood (parent goal + resolved inputs + what to produce) — the model never sees the whole | cross-domain at N=200/domain (560 tasks total): math word problems 16 %→**52 %** (×3.2), financial-table QA 20 %→**50 %** (×2.5), bootstrap CIs hold [live] · **where the lone model collapses, the pieces hold**: deep tasks 0/33 whole vs 10/33 decomposed [live] · on 20 compound "monster" tasks (~20 ops): whole-context floors at **0/20**, hierarchical 2-level split reaches 73 % of sections [live] |
-| **An external think mode** | the model proposes; the graph **refutes with the reason** and enumerates the admissible options (tested through its own gate, never guessed); the model revises — bounded, with honest refusal | one dialogue round: 17/24 → **24/24** correct at zero false admissions [live] · native think budget vs the external critical mind on side-judgment: **13/24 (≈ chance, 11 confident wrong verdicts) vs 0 wrong verdicts** — 24/24 mechanical on a declared perimeter, honest UNDECIDED otherwise [live] · disciplined argument coverage: **77 % vs 58 %** whole-context at 48 arguments [live] · anchored generation of MISSING theses: **0 fabrication** across every negative control [live] |
+The measured detail — numbers, negative controls, limits and snippets per feature — lives in
+**[doc/CAPABILITIES.md](doc/CAPABILITIES.md)**; **[mindsmith](https://www.npmjs.com/package/mindsmith)**
+is where those capabilities are framed and put in users' hands. Maturity uses a 6-rung honest scale
+(rung 6 = external replications, empty pre-launch):
 
 | Feature — details per row in [doc/CAPABILITIES.md](doc/CAPABILITIES.md) | Maturity (6-rung honest scale; rung 6 = external replications, empty pre-launch) |
 |---|---|
@@ -95,20 +101,12 @@ builds `.sgc` method stocks from any dataset that has an executable oracle, behi
 gate (held across every campaign: 0 false shapes admitted, 3 datasets, 2 forge models) — each stock ships
 with an auditable sha256 validation dossier.
 
-### Where it beats what you would reach for today
-
-Each row is a measured delta or a checked absence — details, limits and snippets per row in
-[doc/CAPABILITIES.md](doc/CAPABILITIES.md).
+### Where it beats what you'd reach for
 
-| You would reach for | The known weakness there | Here, measured |
-|---|---|---|
-| a bigger / higher-quant model | needs VRAM you don't have | certified-stock steering on *your* hardware: SQL 8→**63 %**, finance 7→**62 %**, 0 frontier calls on the covered slice |
-| an agent scratchpad / vector memory | boxes only get ticked; similarity retrieval serves **stale** answers | premise drift → cascade retraction + reopen-with-reason: **12/12 vs 0/12** (stale) on drift, 0 model calls |
-| a decomposition framework | free-text plans, unbounded context growth | typed needs/produces + bounded per-piece context: ×2.5–3.2 at N=200, and **0/33 → 10/33** where the whole-task baseline collapses |
-| a native think mode / self-critique loop | self-critique underperforms external feedback (2024-25 literature, + our own refutation ×3) | benched head-to-head: a native think budget scores **13/24 ≈ chance** on side-judgment (11 confident wrong verdicts) — the external critical mind renders **0 wrong verdicts**: 24/24 mechanical on a declared perimeter, honest UNDECIDED otherwise; and the gate **never yields** (17/24 → **24/24** at zero false admissions) |
-| LLM-as-judge / a debate prompt | miscalibrated, gameable, no audit trail | witness-gated coverage (0 fabrication), typed ledger, and a judge that **declines by measured bound** (UNDECIDED below margin) |
-| a prompt hub / RAG index for methods | anything pasted in is trusted | `.sgc` rooms: admission-gated import (a bad bundle never lands), sha256 dossiers, local files you own |
-| a rules engine / event sourcing | fires rules or versions events — never versions *belief* | rollback / diff / fork / merge on what the system currently holds true, **rules included** — no market equivalent found |
+The head-to-head against a bigger model, an agent scratchpad, a decomposition framework, a native think
+mode, LLM-as-judge, a RAG method-index, or a rules engine — each a measured delta or a checked absence —
+is framed for users in **[mindsmith](https://www.npmjs.com/package/mindsmith)**'s "Why not just…?", with
+the per-feature numbers behind each in **[doc/CAPABILITIES.md](doc/CAPABILITIES.md)**.
 
 **What is honestly NOT claimed** (each of these was tested, and the page follows the results):
 - the guarantee is **at admission, not at execution** — at use time the stock *orients*; a suggestion is not
@@ -125,14 +123,19 @@ Each row is a measured delta or a checked absence — details, limits and snippe
 
 ## Quick start
 
+**Run the demos + tests** — from a clone (the demos and the test suite are not in the npm tarball; npm is for
+*embedding the library in your app*, see just below):
+
 ```bash
+git clone https://github.com/9pings/skynet-graph && cd skynet-graph
 npm install        # no build step — pure CommonJS, Node 18+
 npm test           # 1350 tests — 0 failures, 2 known skips
-
 node bin/sg run --concepts ./concepts --builtins --seed ./seed.json
 node examples/integrated-demo/run.js --replay    # the four capabilities assembled, no GPU
 ```
 
+**Embed it in your app** — `npm install skynet-graph`, then:
+
 ```js
 const Graph = require('skynet-graph');
 
@@ -168,13 +171,18 @@ sg ask "your question" --concepts ./concepts --local-model <path.gguf>
 sg studio            # (or: sg serve --studio — live request lines in its trace panel)
 ```
 
-Runnable, deterministic, GPU-free demos of every use-case class live in **`examples/bootstrap/`** —
-one short file per combo and per surface, each printing the guarantee it demonstrates.
+For the ready-made **appliance** — a full local LLM server on **one VRAM load** (the model answers *with*
+think, the graph runs *no-think*, sharing a single gguf), plus local `.sgc` rooms — use
+**[mindsmith](https://www.npmjs.com/package/mindsmith)** `serve --model <gguf>` (`--ctx`, `--gpu`,
+`--gpu-layers`, `--think`, custom llama.cpp build). It's built on these surfaces.
+
+Runnable, deterministic, GPU-free demos of every use-case class live (in the repo) under
+**`examples/bootstrap/`** — one short file per combo and per surface, each printing the guarantee it demonstrates.
 
-> **The ready-made appliance** — if you just want the endpoint + local `.sgc` stock rooms without embedding
-> the library, use **[skynet-dequantizer](https://github.com/9pings/skynet-dequantizer)**: `skynet-dequantizer serve` (OpenAI-compatible,
-> no-egress by default, proven on real sockets) · `skynet-dequantizer rooms list|import|export|freeze` (your own
-> shareable stock mini-repos — no catalog, no subscription, sha256 dossiers).
+> **The app that uses these — [mindsmith](https://www.npmjs.com/package/mindsmith).** The endpoint + rooms
+> above, packaged and hardened: `npx mindsmith serve` (OpenAI-compatible, no-egress by default, proven on
+> real sockets) · `mindsmith rooms list|import|export|freeze` (your own shareable stock mini-repos — no
+> catalog, no subscription, sha256 dossiers). Embed *this* library instead when you are building your own.
 >
 > **For AI agents reading this repo**: `CLAUDE.md` at the root is the machine-oriented map (architecture,
 > commands, gotchas); the MCP surface is one command away (`claude mcp add sg -- node bin/sg mcp …`).

package/doc/CAPABILITIES.md

@@ -23,7 +23,7 @@ measurement → shipped in the library behind a surface, with tests; not yet rep
 
 ## Where each capability is served
 
-| Feature | library | `sg mcp` | dequantizer `serve` | dequantizer `mcp` |
+| Feature | library | `sg mcp` | mindsmith `serve` | mindsmith `mcp` |
 |---|---|---|---|---|
 | F1 low-quant repair | ✓ | `ask` / `hint` / `propose` | ✓ (OpenAI endpoint) | ✓ `ask` / `hint` / `propose` |
 | F2 zoom | ✓ (bricks) | — (known gap, see F2) | — | — |
@@ -33,7 +33,7 @@ measurement → shipped in the library behind a surface, with tests; not yet rep
 | F6 rooms | ✓ | `lattice_load` | rooms CLI | `lattice_load` |
 | F7 substrate | ✓ (the engine itself) | — | — | — |
 
-[skynet-dequantizer](https://github.com/9pings/skynet-dequantizer) is the ready-made appliance over
+[mindsmith](https://github.com/9pings/mindsmith) is the ready-made appliance over
 this library (an OpenAI-compatible local endpoint + `.sgc` rooms); everything else ships here.
 
 ---
@@ -204,7 +204,7 @@ claude mcp add sg -- node bin/sg mcp --frontier-model <path.gguf> --stock ./meth
 # options; `force:true` → recorded UNTRUSTED, never admission. SOFT lane: `hint` (advisory menu).
 ```
 
-Also wired in the dequantizer's `mcp` surface.
+Also wired in the mindsmith's `mcp` surface.
 
 **In plain terms.** Like a chess coach who never moves the pieces for you: when you propose an
 illegal move it says exactly *why* it is illegal and lists the legal ones, and you choose again.
@@ -278,7 +278,7 @@ const cm = Graph.combos.createCriticalMind({ ask });
 const r  = await cm.run({ topic, statements, viewpoints });   // ledger + per-side synthesis + verdict|UNDECIDED
 ```
 
-Over MCP (both `sg mcp` and the dequantizer's `mcp`): the `critique` tool. Its **iteration
+Over MCP (both `sg mcp` and the mindsmith's `mcp`): the `critique` tool. Its **iteration
 contract**: OPEN points and an UNDECIDED verdict are a *typed data request* — the host gathers real
 statements (web, docs, its own context) and calls `critique` again with `statements`; the frame
 upgrades to MATERIAL and the margin can move honestly.
@@ -307,7 +307,7 @@ is refused, never written), and `freeze` pins it under a sha256 dossier you can
 **How to use it, simply:**
 
 ```bash
-skynet-dequantizer rooms list|import|export|freeze     # your own shareable stock mini-repos
+mindsmith rooms list|import|export|freeze     # your own shareable stock mini-repos
 # in this repo, the MCP counterpart is `lattice_load` — learning through the version-gated
 # admission; there is NO direct-write tool.
 ```

package/lib/providers/llm-local.js

@@ -11,9 +11,11 @@
  * embedded-inference study). ZERO-CORE: the ONLY model coupling is `ask({system,user,maxTokens,temperature}) -> string`
  * (mirrors `llm.js#makeOpenAIAsk`); this is a drop-in `ask` for `createLLMProvider({ ask })`.
  *
- * node-llama-cpp is an OPTIONAL native dep (precedent: the durable layer's `node:sqlite`) — declared in
- * `optionalDependencies`, loaded via dynamic import (v3 is ESM-only), so a host that never wires a local model never
- * needs it. GPU auto-detected (CUDA/Metal/Vulkan) with a CPU fallback; the no-build/browser sibling is `wllama` (same
+ * node-llama-cpp is an OPTIONAL native dep (precedent: the durable layer's `node:sqlite`), loaded via dynamic
+ * import (v3 is ESM-only), so a host that never wires a local model never needs it. The `mindsmith` appliance
+ * declares it in `optionalDependencies`; a skynet-graph-direct host that wants embedded inference installs it
+ * (`npm install node-llama-cpp` — prebuilt binaries, no compile). GPU auto-detected (CUDA/Metal/Vulkan) with a
+ * CPU fallback; the no-build/browser sibling is `wllama` (same
  * GGUF, WASM) — a future `makeWasmAsk`.
  *
  * THE CROWN JEWEL — CONSTRAINED DECODING. `opts.jsonSchema` (or `opts.gbnf`) forces the model to emit a grammar-valid
@@ -78,7 +80,7 @@ function makeLocalAsk( opts ) {
 
 	return async function ask( { system, user, maxTokens = 1024, temperature = 0, grammar: callGrammar, reasoningBudget: callRB } ) {
 		return host.ask({
-			modelPath, contextSize: opts.contextSize, gpu: opts.gpu, lora: opts.lora,
+			modelPath, contextSize: opts.contextSize, gpu: opts.gpu, lora: opts.lora, llama: opts.llama, model: opts.model,
 			grammar: callGrammar || grammar, system, user, maxTokens, temperature,
 			reasoningBudget: callRB != null ? callRB : opts.reasoningBudget, seed: opts.seed == null ? 0 : opts.seed
 		});

package/lib/providers/local-host.js

@@ -32,8 +32,12 @@
  */
 
 function modelKey( spec ) {
+	// EVERYTHING that affects the actual VRAM load is in the key (so distinct configs never collide and
+	// identical configs SHARE one load — the single-model, two-budgets case). reasoningBudget is NOT here:
+	// it is a per-CALL parameter, so one loaded model answers both no-think (budget 0) and with-think calls.
 	return [spec.modelPath, 'ctx=' + (spec.contextSize || 4096), 'gpu=' + (spec.gpu === undefined ? 'auto' : spec.gpu),
-		'lora=' + (spec.lora ? JSON.stringify(spec.lora) : '')].join('|');
+		'lora=' + (spec.lora ? JSON.stringify(spec.lora) : ''),
+		'llama=' + (spec.llama ? stable(spec.llama) : ''), 'model=' + (spec.model ? stable(spec.model) : '')].join('|');
 }
 function grammarKey( g ) { return g ? (g.jsonSchema ? 'js:' + stable(g.jsonSchema) : g.gbnf ? 'gb:' + g.gbnf : '') : ''; }
 // Finalize a completion under an optional COMPILED grammar. A JSON-SCHEMA grammar exposes `.parse()` (re-emit canonical
@@ -106,7 +110,7 @@ function createLocalModelHost( opts ) {
 
 	/** The one entry point: resolve/share the model, check the prompt cache, serialize the GPU call. */
 	async function ask( req ) {
-		const spec = { modelPath: req.modelPath, contextSize: req.contextSize, gpu: req.gpu, lora: req.lora };
+		const spec = { modelPath: req.modelPath, contextSize: req.contextSize, gpu: req.gpu, lora: req.lora, llama: req.llama, model: req.model };
 		const mk = modelKey(spec), gk = grammarKey(req.grammar);
 		const ck = cacheKey(mk, gk, req);
 		if ( cacheMax && cache.has(ck) ) { stats.cacheHits++; const v = cache.get(ck); cache.delete(ck); cache.set(ck, v); return v; }
@@ -141,11 +145,14 @@ function defaultLoader( hostOpts ) {
 	return async function load( spec ) {
 		let nlc;
 		try { nlc = await import('node-llama-cpp'); }
-		catch ( e ) { throw new Error('node-llama-cpp is not installed. Run `npm run local-inference:setup`. Cause: ' + e.message); }
+		catch ( e ) { throw new Error('node-llama-cpp is not installed — the embedded gguf backend needs it. Run:  npm install node-llama-cpp  (prebuilt binaries, no compile). Cause: ' + e.message); }
 		const { getLlama, LlamaChatSession } = nlc;
-		const llama   = await getLlama(spec.gpu === undefined ? undefined : { gpu: spec.gpu });
+		// getLlama options (gpu · build:"auto"|"forceRebuild"|"never" · usePrebuiltBinaries:false = build from source ·
+		// cmakeOptions · maxThreads …) = the CUSTOM-BUILD surface; loadModel options (gpuLayers · useMmap · useMlock …).
+		const llamaOpts = Object.assign({}, spec.llama, spec.gpu === undefined ? {} : { gpu: spec.gpu });
+		const llama   = await getLlama(Object.keys(llamaOpts).length ? llamaOpts : undefined);
 		const before  = tryVram(llama);
-		const model   = await llama.loadModel({ modelPath: spec.modelPath });
+		const model   = await llama.loadModel(Object.assign({ modelPath: spec.modelPath }, spec.model));
 		const context = await model.createContext(Object.assign({ contextSize: spec.contextSize || 4096 }, spec.lora ? { lora: spec.lora } : {}));
 		const after   = tryVram(llama);
 		const vramBytes = (before != null && after != null) ? Math.max(0, after - before) : 0;

package/lib/sg/serve.js

@@ -76,8 +76,10 @@ function createServeHandler( opts ) {
 	var nextId = 0;
 
 	var JSON_H = { 'content-type': 'application/json' };
-	var oaiError = function ( status, message, type ) {
-		return { status: status, headers: JSON_H, body: { error: { message: message, type: type || 'invalid_request_error' } } };
+	var oaiError = function ( status, message, type, code ) {
+		var err = { message: message, type: type || 'invalid_request_error' };
+		if ( code ) err.code = code;
+		return { status: status, headers: JSON_H, body: { error: err } };
 	};
 
 	return async function handle( req ) {
@@ -102,7 +104,15 @@ function createServeHandler( opts ) {
 
 			var r;
 			try { r = await proxy.answer(q); }
-			catch ( e ) { return oaiError(500, String(e && e.message || e), 'server_error'); }
+			catch ( e ) {
+				// a DELIBERATE typed refusal is not a server crash → a 4xx so OpenAI clients don't retry it as transient.
+				var msg = String(e && e.message || e), ec = e && e.code;
+				if ( ec === 'NO_REACHABLE_TIER' || /no (reachable )?tier|datapolicy|no-egress|forbidden by policy/i.test(msg) )
+					return oaiError(403, msg, 'policy_refusal', ec || 'no_reachable_tier');
+				if ( ec === 'UPSTREAM_FAILED' || /every reachable tier failed|all tiers failed|upstream/i.test(msg) )
+					return oaiError(502, msg, 'upstream_error', ec || 'upstream_failed');
+				return oaiError(500, msg, 'server_error');
+			}
 			var m = (typeof proxy.metrics === 'function') ? proxy.metrics() : null;
 			if ( typeof opts.onAnswer === 'function' )
 				opts.onAnswer({ query: q, answer: r.answer, source: r.source, cached: !!r.cached, cost: r.cost });

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "skynet-graph",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "license": "AGPL-3.0-or-later",
   "main": "./lib/index.js",
   "author": "Nathanael Braun <pp9ping@gmail.com>",
+  "repository": { "type": "git", "url": "git+https://github.com/9pings/skynet-graph.git" },
+  "homepage": "https://github.com/9pings/skynet-graph#readme",
+  "bugs": "https://github.com/9pings/skynet-graph/issues",
   "bin": {
     "sg": "bin/sg"
   },