skynet-graph 1.2.0

package/lib/graph/tasks/taskflow.js

@@ -0,0 +1,247 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+/**
+ * Promise / semaphore manager & task sequencer.
+ *
+ * Vendored, zero-dependency drop-in for the `taskflows` package (originally by
+ * Nathanael Braun). Behaviour-preserving: the engine's stabilize loop relies on
+ * the exact lock/release + followers semantics (see lib/graph/Graph.js `_loopTF`,
+ * `pushMutation`, and the #11.a re-entrancy guard). The only change vs the
+ * published lib is that the unused `require()`s (isfunction/isnumber/merge/
+ * slice/splice) are dropped and `isArray`/`isString` are inlined.
+ *
+ * Mental model: `locks` is a semaphore. Each task run takes a lock; release() drops
+ * one. While locks > 0 new tasks queue (doAfter/todo); when locks hit 0 the flow is
+ * COMPLETE and its one-shot `_followers` fire — that follower is how stabilize.js
+ * hands control back to Graph._loopTF once a whole stabilization pass has drained.
+ *
+ * @class TaskFlow
+ */
+"use strict";
+
+var isArray  = Array.isArray,
+    isString = function ( s ) { return typeof s === 'string'; };
+
+/**
+ * TaskFlow
+ * @param todo      {fn|fn[]}  task(s) to run (string => method name on scope)
+ * @param scope     {object}   execution context passed to tasks
+ * @param followers {fn|fn[]}  one-shot callback(s) fired when locks reach 0
+ * @param name      {string}
+ * @constructor
+ */
+var TaskFlow = function ( todo, scope, followers, name ) {
+	this.scope       = scope || {};
+	this.todo        = isArray(todo) ? todo : todo && [todo] || [];
+	this.doAfter     = [];
+	this.locks       = 0;
+	this.fails       = 0;
+	this._complete   = false;
+	this._followers  = followers instanceof Array ? followers : [followers];
+	this._onfail     = null;
+	this.displayName = name;
+
+	this.release   = this.success   = this.release.bind(this);
+	this.asyncFail = this.fail.bind(this);
+};
+
+module.exports = TaskFlow;
+
+TaskFlow.prototype = {
+	kill : function () {
+		this.doAfter = this.scope = this._onfail = this._followers = 0;
+		this.dead    = true;
+	},
+	reset : function () {
+		if ( this.dead ) return;
+		this._complete = false;
+		this._pos      = 0;
+	},
+	/**
+	 * Add one-shot success callback / TaskFlow.
+	 * A passed TaskFlow is released (so it starts running if it holds no other locks).
+	 * @param cb {function|TaskFlow}
+	 * @returns {TaskFlow}
+	 */
+	then : function () {
+		if ( this.dead ) return;
+		this._followers = (this._followers instanceof Array) && this._followers || [];
+		for ( var i = 0, ln = arguments.length ; i < ln ; i++ ) {
+			if ( arguments[i] instanceof Array ) this.then.apply(this, arguments[i]);
+			else {
+				this._followers.push(arguments[i]);
+				if ( arguments[i] instanceof TaskFlow )
+					arguments[i].locks++;
+			}
+		}
+		if ( this._complete ) {
+			this.locks++;
+			this.release();
+		}
+		return this;
+	},
+	/**
+	 * Add one-shot fail callback.
+	 * @param cb {function|TaskFlow|array}
+	 * @returns {TaskFlow}
+	 */
+	catchFail : function () {
+		if ( this.dead ) return;
+		var done     = this.fails && this._complete;
+		this._onfail = this._onfail || [];
+		for ( var i = 0, ln = arguments.length ; i < ln ; i++ ) {
+			if ( arguments[i] instanceof Array ) this.catchFail.apply(this, arguments[i]);
+			else {
+				if ( !done ) this._onfail.push(arguments[i]);
+				else arguments[i]();
+			}
+		}
+		return this;
+	},
+	/**
+	 * Make this flow fall into failure, triggering one-shot callbacks.
+	 * @param cause
+	 */
+	fail : function ( cause ) {
+		if ( this.dead ) return;
+		var tmp, i = 0;
+		this._fail = cause;
+		if ( this._onfail )
+			while ( i < this._onfail.length ) {
+				tmp = this._onfail[i++];
+				if ( tmp instanceof Function ) tmp(this.scope, cause, this);
+				else if ( tmp instanceof TaskFlow ) tmp.release();
+			}
+	},
+	/**
+	 * Push a task & (re)start running the flow if no remaining locks.
+	 * @returns {TaskFlow}
+	 */
+	push : function () {
+		if ( this.dead ) return;
+		this.locks++;
+		this._complete = false;
+		this.todo.push.apply(this.todo, arguments);
+		this.release();
+		return this;
+	},
+	/**
+	 * Add a lock (optionally waiting on a previous flow).
+	 * @param previous {TaskFlow|TaskFlow[]} optional flow(s) to wait on
+	 * @returns {TaskFlow}
+	 */
+	wait : function ( previous ) {
+		if ( this.dead ) return;
+		if ( isArray(previous) )
+			return previous.map(this.wait.bind(this));
+		if ( previous ) previous.then(this);
+		else this.locks++;
+		return this;
+	},
+	/**
+	 * Decrease locks; at 0, run pending tasks else fire `then` followers.
+	 * @param desync
+	 * @returns {*}
+	 */
+	release : function ( desync ) {
+		if ( this.dead ) return;
+		if ( desync && this.locks > 0 ) return setTimeout(this.success) && this;
+		var tmp;
+
+		if ( !--this.locks ) {
+			if ( this.doAfter.length || this.todo.length > this._pos ) {
+				this.run(tmp);
+				return;
+			}
+			this._complete = true;
+			this.running   = false;
+
+			if ( this._followers instanceof Array ) {
+				while ( this._followers.length ) {
+					tmp = this._followers.shift();
+					if ( tmp instanceof Function ) tmp(this.scope, this);
+					else if ( tmp instanceof TaskFlow ) tmp.release();
+				}
+			} else {
+				tmp = this._followers;
+				if ( tmp instanceof Function ) tmp(this.scope, this);
+				else if ( tmp instanceof TaskFlow ) tmp.release();
+			}
+		}
+		return this;
+	},
+	_pos      : 0,
+	_nextTask : 0,
+	pushSubTask : function ( task ) {
+		if ( this.dead ) return;
+		this.doAfter.push(task);
+	},
+	/**
+	 * Execute one task, then trampoline to the next. `run` calls itself (line ~end)
+	 * rather than looping so a long task chain never grows the call stack. A task may
+	 * be: a fn (called with (scope, this) — if it RETURNS a value, that becomes the
+	 * next step, chaining work); a method name (resolved on scope); a nested TaskFlow
+	 * (this flow waits on it via then); or an ARRAY (a parallel pool — every entry is
+	 * scheduled via setTimeout and gets its own lock, so they run concurrently and the
+	 * flow only completes once all have released). Each step takes a lock; the trailing
+	 * release() balances it so `_followers` fire exactly at quiescence.
+	 * @returns {*}
+	 */
+	run : function ( step, force, releaseAfter ) {
+		if ( this.dead ) return;
+		if ( !step && !this.locks && !this.doAfter.length && (this._pos >= this.todo.length) ) {
+			this.locks++;
+			this.running = false;
+			this.release();
+			return this;
+		}
+		if ( !force && this.locks ) return step && this.pushSubTask(step);
+
+		this.running = true;
+
+		step = step || this.doAfter.length && this.doAfter.shift() || this.todo[this._pos++];
+
+		this.locks++;
+		if ( isString(step) ) {
+			if ( this.scope[step] instanceof Function )
+				step = this.scope[step](null, this.scope, this);
+			else step = this.scope[step];
+		} else if ( step instanceof Function ) {
+			this._succesfull = true;
+			step             = step(this.scope, this);
+			this._succesfull = false;
+		} else if ( step instanceof TaskFlow ) { // sync wf
+			step.then(this);
+			step = null;
+		} else if ( step instanceof Array ) { // async pool
+			this.locks++;
+			for ( var i = 0 ; i < step.length ; i++, this.locks++ )
+				setTimeout(this.run.bind(this, step[i], true, true));
+			setTimeout(this.success);
+			step = null;
+		} else {
+			step = null;
+		}
+
+		!step && releaseAfter && this.release();
+		this.run(step, step && force, step && releaseAfter);
+		this.release();
+
+		return this;
+	}
+};

package/lib/index.js

@@ -0,0 +1,122 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * Package facade. `require('skynet-graph')` returns the Graph constructor, with
+ * standalone-boot helpers attached as statics so a host can spin a graph up from
+ * plain directories without hand-wiring the concept tree + providers:
+ *
+ *   const Graph = require('skynet-graph');
+ *   const g = Graph.fromDirs({ concepts: './concepts', providers: './providers' });
+ *
+ * The engine core (lib/graph) stays filesystem-free; fromDirs composes the edge
+ * loaders (lib/load.js) with the provider registry (lib/providers).
+ */
+const Graph     = require('./graph');
+const providers = require('./providers');
+const { loadConceptMap, loadProviders } = require('./load.js');
+
+/**
+ * Boot a Graph from on-disk concept sets + provider modules.
+ *
+ * @param {object} opts
+ * @param {string|string[]}        [opts.concepts]    concept-set dir(s) (see loadConceptMap)
+ * @param {string|object|Array}    [opts.providers]   provider module dir(s)/file(s) or fragment(s)
+ * @param {object}                 [opts.providerCtx] ctx passed to provider factory modules
+ * @param {boolean|Array}          [opts.builtins]    register packaged providers (true = geo + default llm)
+ * @param {object|string}          [opts.seed]        serialized record, or a path to a JSON snapshot
+ * @param {object}                 [opts.conf]        Graph cfg overrides (conceptSets defaults to all loaded)
+ * @param {object}                 [opts.conceptMap]  pre-built conceptMap (skips loadConceptMap)
+ * @returns {Graph}
+ */
+function fromDirs( opts = {} ) {
+	const conceptMap = opts.conceptMap
+		|| (opts.concepts ? loadConceptMap(opts.concepts) : {});
+
+	const fragments = [];
+	if ( opts.providers ) fragments.push(...loadProviders(opts.providers, opts.providerCtx || {}));
+	if ( fragments.length ) providers.register(Graph, fragments);
+	// builtins: true -> packaged defaults (geo + default llm client); array -> explicit fragments
+	if ( opts.builtins ) providers.register(Graph, opts.builtins === true ? undefined : opts.builtins);
+
+	let seed = opts.seed;
+	if ( typeof seed === 'string' ) seed = JSON.parse(require('fs').readFileSync(require('path').resolve(seed), 'utf8'));
+
+	const conf = { ...(opts.conf || {}) };
+	if ( !conf.conceptSets ) conf.conceptSets = Object.keys(conceptMap);
+
+	return new Graph(seed || {}, conf, conceptMap);
+}
+
+// Attach standalone helpers as statics (keeps `require('skynet-graph')` === Graph).
+Graph.fromDirs        = fromDirs;
+Graph.loadConceptMap  = loadConceptMap;
+Graph.loadProviders   = loadProviders;
+Graph.register        = function ( fragments ) { return providers.register(Graph, fragments); };
+Graph.providers       = providers;
+
+// R0 backends — the preset/config layer over the ask-makers (a provider NAME + key -> a chat `ask`). The
+// shared foundation the serving surfaces / Studio backend panel / client routing consume; every resolved
+// backend carries an `egress` flag (local=false) — the seed a no-egress policy reads.
+Graph.backends        = require('./providers/backends');
+
+// Authoring & R&D toolkit, namespaced (concepts/validate/author/contract/abstract/method/mount/crystallize/…).
+// Exposed as a static so the substrate tools are usable without deep-path requires. Lazy-required (like
+// createStudioServer): an engine-only / providers-only host pays no load cost, and the shelved numerical
+// modules (concept-net/equilibrium/ste) load only when authoring is actually touched.
+Object.defineProperty(Graph, 'authoring', { get: function () { return require('./authoring'); } });
+
+// Combos — thin, delivered assemblies over the bricks (createAppliance/…). Lazy like `authoring`:
+// an engine-only host pays nothing; the substrate/providers load only when a combo is touched.
+Object.defineProperty(Graph, 'combos', { get: function () { return require('./combos'); } });
+
+// The first-class SETTLE verb (Controller-P0): a promise that resolves on the next stabilization (or
+// immediately if already quiescent). Lifts the de-facto `supervise.js#nextStable` so a host can
+// `await Graph.settle(g)` after a mutation instead of wiring an onStabilize callback. Lazy-required.
+Graph.settle = function ( graph ) { return require('./authoring/supervise.js').nextStable(graph); };
+
+// Distributed runtime: dispatch sub-graphs to a worker (worker_threads) or a cross-instance socket runtime.
+const runtime         = require('./runtime');
+Graph.createGraphWorker = runtime.createGraphWorker;
+Graph.spawnGraph        = runtime.spawnGraph;
+Graph.invokeGraph       = runtime.invokeGraph;        // P1: one-shot BOUNDED invoke (only Σ_sep crosses back)
+Graph.createInvokePool  = runtime.createInvokePool;   // P3: warm-worker pool keyed by contract (N cases → 1 instance)
+Graph.serveGraphWorker  = runtime.serveGraphWorker;   // P5: stand up a socket runtime remote clients dispatch to
+
+// Logger factory (for a host that wants to build/inject its own logger via cfg.logger).
+Graph.createLogger    = require('./graph/log').createLogger;
+
+// Durable executor — Layer A (the CheckpointStore: durable marking + content-memo + lease queue). Eager-require
+// is safe: the module loads `node:sqlite` ONLY inside the sqlite factory (so engine-only hosts never touch it).
+// `createCheckpointStore({file})` = the convenience default — a file → the durable SQLite backend, none → memory.
+const durable         = require('./durable/checkpoint-store.js');
+Graph.createCheckpointStore       = function ( opts ) { opts = opts || {}; return opts.file ? durable.createSqliteCheckpointStore(opts) : durable.createMemoryCheckpointStore(opts); };
+Graph.createMemoryCheckpointStore = durable.createMemoryCheckpointStore;
+Graph.createSqliteCheckpointStore = durable.createSqliteCheckpointStore;
+// the full durable executor namespace: the CheckpointStore + C-xlate (compileMethod) + Layer B (runFlow) +
+// the fold-back JOIN's monoid algebra (foldSiblings).
+Graph.durable = Object.assign({}, durable, require('./durable/xlate.js'), require('./durable/interpreter.js'),
+	require('./durable/fold.js'), require('./durable/audit.js'));
+
+// Studio (the web inspector/console): a host can embed the server as a library instead of
+// only via `bin/sg studio`. Lazy-required so the fs/ws/http deps don't load for engine-only use.
+Object.defineProperty(Graph, 'createStudioServer', {
+	get: function () { return require('./studio/server.js').createServer; }
+});
+
+module.exports = Graph;

package/lib/load.js

@@ -0,0 +1,132 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * Directory loaders — turn on-disk concept sets and provider modules into the
+ * shapes the engine expects, so a host (or the `sg` CLI) can boot a graph from
+ * plain folders passed by path. Kept OUT of lib/graph/* on purpose: the engine
+ * core stays filesystem-free (hermetic/portable); all fs lives here at the edge.
+ */
+const fs   = require('fs');
+const path = require('path');
+const { buildConceptTree } = require('./authoring/concepts.js');
+
+/**
+ * Build a conceptMap ({ <setName>: tree }) from one or more directories.
+ *
+ * Each argument dir is auto-classified:
+ *  - if it directly contains top-level *.json -> it IS a single set (name = its
+ *    basename), e.g. loadConceptMap('./concepts/common') -> { common: tree };
+ *  - else each immediate sub-directory holding *.json is a set, e.g.
+ *    loadConceptMap('./concepts') -> { common: tree, ... }.
+ *
+ * @param {string|string[]} concepts  dir path(s)
+ * @param {object} [opts]   { validate: true } runs validateConceptTree per set and THROWS an
+ *                          aggregated error if any set has errors (a strict validating load).
+ * @returns {Object} conceptMap keyed by set name
+ */
+function loadConceptMap( concepts, opts = {} ) {
+	const dirs = Array.isArray(concepts) ? concepts : [concepts];
+	const map  = {};
+	for ( const d of dirs ) {
+		const abs     = path.resolve(d);
+		const entries = fs.readdirSync(abs, { withFileTypes: true });
+		const hasTopJson = entries.some(e => e.isFile() && e.name.endsWith('.json'));
+		if ( hasTopJson ) {
+			map[path.basename(abs)] = buildConceptTree(abs);
+		} else {
+			for ( const e of entries ) {
+				if ( !e.isDirectory() ) continue;
+				const setDir = path.join(abs, e.name);
+				if ( fs.readdirSync(setDir).some(f => f.endsWith('.json')) )
+					map[e.name] = buildConceptTree(setDir);
+			}
+		}
+	}
+	if ( opts.validate ) {
+		const { validateConceptTree } = require('./authoring/validate.js');
+		const fails = [];
+		for ( const set of Object.keys(map) )
+			for ( const err of validateConceptTree(map[set], opts.validateOpts || {}).errors )
+				fails.push(`[${set}] ${err.concept} — ${err.kind}: ${err.message}`);
+		if ( fails.length ) throw new Error('concept validation failed:\n' + fails.join('\n'));
+	}
+	return map;
+}
+
+// Keys re-derived from the file path on load (concepts.js#buildConceptTree), so they are NOT
+// written back out — and childConcepts becomes a sibling directory, not a key.
+const NON_FILE_KEYS = new Set(['_id', '_name', 'childConcepts']);
+
+/**
+ * Write a serialized concept tree back to the on-disk JSONC layout (the inverse of
+ * buildConceptTree / loadConceptMap): one `<Name>.json` per concept, a `<Name>/` sub-directory
+ * for its children. Comments are NOT preserved (prose belongs in a typed `_description`/`note`
+ * field); the result reloads to the identical tree. fs lives here at the edge, not in the core.
+ * @param tree  a `{ childConcepts: {...} }` tree (e.g. graph.exportConcepts())
+ * @param dir   target directory (created if missing)
+ * @returns dir
+ */
+function exportConceptsToDir( tree, dir ) {
+	fs.mkdirSync(dir, { recursive: true });
+	const kids = (tree && tree.childConcepts) || {};
+	for ( const name of Object.keys(kids) ) {
+		const node   = kids[name];
+		const schema = {};
+		for ( const k of Object.keys(node) ) if ( !NON_FILE_KEYS.has(k) ) schema[k] = node[k];
+		fs.writeFileSync(path.join(dir, name + '.json'), JSON.stringify(schema, null, 2) + '\n');
+		if ( node.childConcepts && Object.keys(node.childConcepts).length )
+			exportConceptsToDir(node, path.join(dir, name));
+	}
+	return dir;
+}
+
+/**
+ * Collect provider-map fragments from module file(s)/dir(s) (or pass-through
+ * fragment objects). A provider module exports either:
+ *  - a fragment map `{ Namespace: { fn } }`,
+ *  - `{ default: fragment }`, or
+ *  - a factory `(ctx) => fragment` (so it can self-configure from `ctx`, e.g. an
+ *    LLM `ask` backend or env). `ctx` is whatever the caller passes.
+ *
+ * Returns an array suitable for `register(Graph, fragments)`.
+ *
+ * @param {string|object|Array} providers  dir/file path(s) and/or fragment object(s)
+ * @param {object} [ctx]  passed to any factory module
+ * @returns {object[]} fragments
+ */
+function loadProviders( providers, ctx = {} ) {
+	const items     = Array.isArray(providers) ? providers : [providers];
+	const fragments = [];
+	for ( const item of items ) {
+		if ( item && typeof item === 'object' ) { fragments.push(item); continue; } // already a fragment
+		const abs   = path.resolve(item);
+		const files = fs.statSync(abs).isDirectory()
+			? fs.readdirSync(abs).filter(f => f.endsWith('.js')).sort().map(f => path.join(abs, f))
+			: [abs];
+		for ( const f of files ) {
+			let mod = require(f);
+			if ( typeof mod === 'function' ) mod = mod(ctx);                       // factory(ctx)
+			else if ( mod && typeof mod.default !== 'undefined' ) mod = mod.default; // esm-interop default
+			if ( mod && typeof mod === 'object' ) fragments.push(mod);
+		}
+	}
+	return fragments;
+}
+
+module.exports = { loadConceptMap, loadProviders, exportConceptsToDir };

package/lib/providers/backends.js

@@ -0,0 +1,117 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * backends — the PRESET / CONFIG layer over the ask-makers (`llm.js`, `llm-local.js`). One thin,
+ * data-driven place to answer "given a provider NAME + a key, hand me a chat `ask`". It invents no
+ * protocol and no router: every hosted provider worth targeting is OpenAI-compatible except Anthropic
+ * (its own `/v1/messages`) and the embedded local model (`node-llama-cpp`) — so the table is small and
+ * a new provider is one row (base + flavour + key-env).
+ *
+ * It is the SHARED foundation the serving surfaces, the Studio backend panel, and the client's N-tier
+ * routing all consume: the public preset table here = the free config brick; the client wraps it with a
+ * policy (order + `dataPolicy:'no-egress'`); the pro adds per-task routing. The `egress` flag carried on
+ * every resolved backend (local=false, remote=true) is the SEED that a no-egress policy reads to decide
+ * what a query is allowed to leave the machine for.
+ *
+ *   const ask = makeBackend({ preset: 'deepseek' });                 // key from $DEEPSEEK_API_KEY
+ *   const ask = makeBackend({ preset: 'custom', base: 'http://localhost:8000', key: 'sk-x' });  // any vLLM
+ *   const ask = makeBackend({ preset: 'local', modelPath: '/models/qwen.gguf' });               // embedded
+ *
+ * The returned `ask` is the standard chat seam: `async ({system,user,maxTokens,temperature}) -> text`.
+ */
+const llm = require('./llm');
+
+// The preset table. `base` is the API ROOT (the OpenAI maker appends `/v1/chat/completions`, the
+// Anthropic maker `/v1/messages`) — so bases here carry NO `/v1`. `defaultModel` is only a convenience
+// default (always overridable via spec.model or $LLM_MODEL), kept minimal so the table does not rot.
+const BACKENDS = {
+	local:       { api: 'local',     label: 'Local (embedded GGUF)',       egress: false, needsKey: false },
+	openai:      { api: 'openai',    label: 'OpenAI',        base: 'https://api.openai.com',        egress: true, needsKey: true, keyEnv: 'OPENAI_API_KEY',    defaultModel: 'gpt-4o-mini' },
+	anthropic:   { api: 'anthropic', label: 'Anthropic (Claude)', base: 'https://api.anthropic.com', egress: true, needsKey: true, keyEnv: 'ANTHROPIC_API_KEY', defaultModel: 'claude-3-5-sonnet-latest' },
+	huggingface: { api: 'openai',    label: 'Hugging Face',  base: 'https://router.huggingface.co',  egress: true, needsKey: true, keyEnv: 'HF_TOKEN' },
+	deepseek:    { api: 'openai',    label: 'DeepSeek',      base: 'https://api.deepseek.com',       egress: true, needsKey: true, keyEnv: 'DEEPSEEK_API_KEY',  defaultModel: 'deepseek-chat' },
+	openrouter:  { api: 'openai',    label: 'OpenRouter',    base: 'https://openrouter.ai/api',      egress: true, needsKey: true, keyEnv: 'OPENROUTER_API_KEY' },
+	// `custom` = any OpenAI-compatible endpoint you point at (a local vLLM / llama-server / LM Studio, a
+	// LAN model, a self-host). No key required by default; set `api:'anthropic'` for a Claude-shaped one.
+	custom:      { api: 'openai',    label: 'Custom (bring your own base)', egress: true, needsKey: false }
+};
+
+const ALIASES = { claude: 'anthropic', hf: 'huggingface', 'gguf': 'local' };
+
+function err( message, code ) { return Object.assign(new Error(message), { code: code }); }
+
+/**
+ * Normalize a backend spec into a descriptor (PURE — no maker call, no secret logged). Precedence per
+ * field: `spec > environment > preset default`. Default preset is `custom` (a bare OpenAI-compatible
+ * endpoint), so `resolveBackend({ base, key })` just works for a self-hosted model.
+ * @param spec { preset?, base?, model?, key?, modelPath?, api?, egress? }
+ * @returns { name, api, base, model, key, modelPath, egress, needsKey, keyEnv, label }
+ */
+function resolveBackend( spec ) {
+	spec = spec || {};
+	const asked = spec.preset || spec.backend || spec.name || 'custom';
+	const name = ALIASES[asked] || asked;
+	const preset = BACKENDS[name];
+	if ( !preset ) throw err('unknown backend preset "' + asked + '" — known: ' + Object.keys(BACKENDS).join(', '), 'UNKNOWN_BACKEND');
+
+	const api = spec.api || preset.api;
+	const base = spec.base || preset.base || process.env.LLM_BASE || null;
+	const model = spec.model || process.env.LLM_MODEL || preset.defaultModel || null;
+	const key = spec.key || (preset.keyEnv && process.env[preset.keyEnv]) || process.env.LLM_KEY || null;
+	const modelPath = api === 'local' ? (spec.modelPath || process.env.LOCAL_MODEL || null) : null;
+	const egress = spec.egress != null ? !!spec.egress : !!preset.egress;
+
+	return { name: name, api: api, base: base, model: model, key: key, modelPath: modelPath,
+		egress: egress, needsKey: !!preset.needsKey, keyEnv: preset.keyEnv || null, label: preset.label };
+}
+
+/**
+ * Build a chat `ask` for a backend spec. Dispatches on the resolved flavour; a needs-key preset with no
+ * resolvable key is a typed `NO_API_KEY` error UP FRONT (a clear message beats an opaque 401 mid-call).
+ * @returns async ({system,user,maxTokens,temperature}) -> text
+ */
+function makeBackend( spec ) {
+	spec = spec || {};
+	const d = resolveBackend(spec);
+	if ( d.needsKey && !d.key ) throw err('backend "' + d.name + '" needs an API key — set ' + (d.keyEnv || 'a key') + ' or pass { key }', 'NO_API_KEY');
+
+	if ( d.api === 'local' ) {
+		// lazy: only a host that actually uses the embedded model pays for the optional native dep.
+		const makeLocalAsk = require('./llm-local').makeLocalAsk;
+		return makeLocalAsk(Object.assign({}, spec.localOpts, { modelPath: d.modelPath, reasoningBudget: spec.reasoningBudget }));
+	}
+	const opts = { api: d.api, base: d.base, model: d.model, key: d.key };
+	if ( spec.extraBody ) opts.extraBody = spec.extraBody;
+	if ( spec.assistantPrefill != null ) opts.assistantPrefill = spec.assistantPrefill;
+	return llm.makeAsk(opts);   // dispatches openai/anthropic on opts.api
+}
+
+/**
+ * The presets as a SECRET-FREE list (for a Studio dropdown / `sg` help): name, label, flavour, whether a
+ * key is needed and from which env, and the egress class. Never returns a resolved key.
+ */
+function listBackends() {
+	return Object.keys(BACKENDS).map(function ( name ) {
+		const p = BACKENDS[name];
+		return { name: name, label: p.label, api: p.api, base: p.base || null,
+			egress: !!p.egress, needsKey: !!p.needsKey, keyEnv: p.keyEnv || null };
+	});
+}
+
+module.exports = { BACKENDS: BACKENDS, ALIASES: ALIASES, resolveBackend: resolveBackend, makeBackend: makeBackend, listBackends: listBackends };