@x12i/graph-composer

| | Location | |---|----------| | GitHub (source) | woroces/graph-composer — clone: [email protected]:woroces/graph-composer.git | | npm (package) | @x12i/graph-composer |

The Git repo lives under the woroces org with repo name graph-composer. That is separate from the npm scope @x12i.

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,
    connectTimeoutMs: 60_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. | | graphComposerPackRoot() | Same path as getPackDir() (for use without importing runGraphComposer). | | readGraphComposerPromptFile(name) | Read a file under functions/graph-composer/prompts/. | | DEFAULT_UTILITY_SKILLS | Default local skills when utilitySkills is omitted. |

RunGraphComposerOptions includes client, mode, model, temperature, maxTokens, askTimeoutMs (OpenRouter request/response timeout via aifunctions-js), and connectTimeoutMs (forwarded to aifunctions-js createClient({ openrouter: { connectTimeoutMs } }) when this package creates the client — see integration handoff).

Bundled content

Published tarball includes:

• dist/ — compiled ESM + TypeScript declarations
• functions/graph-composer/ — prompts/ (.md / templates, judge-rules.md + JSON block, default-utility-skills.json), plus 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

Documentation in this repo

• Handoff / forward notes: docs/integration-handoff.md — LLM I/O behavior in this package and requests for aifunctions-js.
• aifunctions-js transport report: docs/report-aifunctions-js-undici-http.md — Undici/OpenRouter ownership; optional upstream follow-ups.
• Historical spec: docs/specs.md — not published on 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.