@x12i/graph-composer

LLM-backed graph composer for the worox-graph DAG format: create, modify, or explain graphs using aifunctions-js and OpenRouter. Skill catalogs and mode gates are composed into the system prompt at call time; the function pack (instructions + judge rules) ships with the package.

Install

npm install @x12i/graph-composer

Requires Node.js 18+.

Environment

Variable	Required	Description
`OPENROUTER_API_KEY`	Yes (for API runs)	OpenRouter API key.
`LLM_MODEL_STRONG`	No	Model slug when using `mode: "strong"` (default preset from aifunctions-js).
`LLM_MODEL_NORMAL`	No	Model slug for `normal` mode.
`GRAPH_COMPOSER_LOGS_LEVEL`	No	Log level for logs-gateway (`info`, `warn`, …).

Copy .env.example to .env for local development. Do not commit secrets.

Quick start

import { runGraphComposer } from "@x12i/graph-composer";

const result = await runGraphComposer(
  {
    intent: {
      action: "create",
      description: "Read a record, classify it, persist the result.",
    },
    skillMode: "locked",
    aiSkills: [
      {
        skillKey: "professional-answer",
        description: "Structured analysis with LLM",
        isLocal: false,
      },
    ],
    utilitySkills: [
      {
        skillKey: "scoped-data-reader",
        description: "Read scoped data",
        isLocal: true,
      },
      {
        skillKey: "scoped-answer-writer",
        description: "Persist results",
        isLocal: true,
      },
    ],
    constraints: { requireFinalizer: true },
  },
  { askTimeoutMs: 120_000, maxTokens: 8192 }
);

Explain an existing graph

Pass existingGraph (worox-graph JSON) and intent.action: "explain". Optional helpers:

loadExampleGraph("network-vuln-subnet-triage.v2.json") — loads the bundled sample from examples/.
inputExplainNetworkVulnSubnet() — full sample input for that graph (locked catalog).

CLI (after install)

export OPENROUTER_API_KEY=sk-or-...
npx @x12i/graph-composer explain-basic
npx @x12i/graph-composer network-vuln

Or use the binary name:

graph-composer explain-basic

Arguments are test case ids from the shipped test-cases.json, or network-vuln for the bundled subnet triage example.

API highlights

Export	Purpose
`runGraphComposer(input, options?)`	Main entry: compose prompts, call model, normalize/validate output.
`composeInstructions`, `formatSkillList`	Build system text from base instructions + skill lists + mode gate.
`getPackDir()`	Absolute path to the bundled `functions/graph-composer` pack.
`DEFAULT_UTILITY_SKILLS`	Default local skills when `utilitySkills` is omitted.

RunGraphComposerOptions includes client, mode, model, temperature, maxTokens, and askTimeoutMs (OpenRouter request timeout).

Bundled content

Published tarball includes:

dist/ — compiled ESM + TypeScript declarations
functions/graph-composer/ — strong prompt, rules.json, meta.json, test-cases.json
examples/network-vuln-subnet-triage.v2.json — sample worox graph

It does not include internal docs/, tests, or .env.

Development (this repo)

The repository may keep a duplicate of the sample graph under docs/examples/ for documentation. The published package only ships examples/; keep them in sync if you change the sample.

cp .env.example .env
npm install
npm run build
npm run verify:local
npm run typecheck
npm test          # live tests; needs OPENROUTER_API_KEY in .env

Optional: nx-config2 for scripts that load .env:

npx nx-config2 run --env-file .env -- npm test

Spec

Design and I/O schema: see the internal spec in the repository (docs/specs.md — not published to npm).

Publishing (maintainers)

Scoped package @x12i/graph-composer uses publishConfig.access: "public". Ensure your npm user is a member of the x12i org (or owns the scope) and has a valid token in ~/.npmrc or project .npmrc (never commit tokens).

npm run build
npm publish

Confirm tarball: npm run pack:check (must not list docs/, .env, or test/).

License

MIT — see LICENSE.