optimus/README.md

optimus

A deliberately small project runtime for initialized modules, settings, named artifacts, and transformer-node helpers.

Project shape

A host project provides JSON settings in ./settings/:

settings/
    modules.json
    artifacts.json
    anything-else.json

modules.json maps semantic module names to initializer modules:

{
  "chatter": "./tree/chatter/index.js",
  "markdown-builder": "./tree/markdown-builder/index.js"
}

Each module exports an initializer that receives the same shared utils object:

module.exports = utils => {
    function doSomething() {
        const chatter = utils.loadModule("chatter");
        const llm = utils.getSettings("llm");
    }

    return { doSomething };
};

Utilities

utils.loadModule(name)

Returns the initialized module registered under that semantic name.

utils.getSettings(name)

Returns the parsed contents of ./settings/<name>.json.

utils.hashPayload(value)

Returns a SHA-256 hex hash of JSON.stringify(value). No key sorting or normalization is performed.

utils.buildNode(payload, sources = {})

Builds a transformer-node packet from a payload and already-loaded source nodes:

const node = utils.buildNode(payload, {
    hebrew: hebrewNode,
    guidance: guidanceNode,
});

Result:

{
  "sourceHash": {
    "hebrew": "<hebrewNode.hash>",
    "guidance": "<guidanceNode.hash>"
  },
  "hash": "<hash of payload>",
  "payload": "<payload>"
}

Optimus does not persist or validate the node. The owning module decides where its artifacts live and when to rebuild them.

utils.buildBinaryNode(filePath, sources = {})

Builds the binary equivalent of a transformer-node packet. The supplied path is kept as the usable binary payload locator, while hash is computed from the file bytes:

const node = utils.buildBinaryNode(resolvedCoverPath);

Result:

{
  "sourceHash": {},
  "hash": "<SHA-256 of file bytes>",
  "payloadBin": "<filePath>"
}

Derived binary artifacts can name source nodes in the same way as buildNode():

return utils.buildBinaryNode(pdfPath, {
    volume: volumeNode,
    style: styleNode,
});

buildBinaryNode() does not copy the file, interpret the path, or know what kind of binary it represents. It hashes the bytes currently at filePath and returns that path unchanged as payloadBin.

Artifacts

settings/artifacts.json explicitly names the module and public builder function for each top-level artifact:

{
  "job.en.md": {
    "module": "unpointed-hebrew-markdown-builder",
    "builder": "buildMarkdownOutput",
    "params": ["job", "en"]
  }
}

Build one artifact:

npx optimus --artifact job.en.md

Build every declared artifact:

npx optimus

Artifacts are logical requested outcomes. Their modules own filenames, directories, persistence, cache policy, and dependency behavior.

A builder may call utils.setArtifactOutcome("up to date") (or another concise outcome) before returning. Optimus prints the requested artifact ID before invoking the builder and prints that outcome afterward; builders that do not report one receive the generic completed — success result.

Invocation setting overlays

Optimus loads the project defaults from direct settings/*.json files. Each filename remains a free-form settings name available through utils.getSettings(name).

A process can layer one or more JSON overlays on top of those defaults:

npx optimus --artifact psalms.en.md --setting settings/overlays/remote.json

Multiple overlays are applied left-to-right:

npx optimus --artifact psalms.en.md \
    --setting settings/overlays/remote.json \
    --setting settings/overlays/experimental-model.json

An overlay is one object whose top-level keys are ordinary settings names:

{
  "llm": {
    "host": "remote-box",
    "model": "remote-model"
  }
}

Overlay behavior is deliberately small:

• object over object: recursively overlay properties;
• arrays: replace the previous array;
• scalars: replace the previous value;
• null: replace the previous value with null;
• omitted properties: inherit the value underneath;
• an overlay may introduce a new free-form settings name.

utils.getSettings("llm") sees only the resulting effective settings. Modules do not know which values came from defaults versus invocation overlays.

Overlay paths are resolved relative to the project root unless absolute.

Build-all memory behavior

buildAll() awaits each declared artifact sequentially and does not retain prior artifact results. Artifact builders may still return either ordinary values or Promises; the runtime remains compatible with genuinely asynchronous work such as LLM requests.