Wolfram Router

Wolfram Router is a Node.js service that runs multi-agent workflows and optional Wolfram queries behind one HTTP API and browser dashboard. It stores runs in SQLite and can combine built-in agents, remote HTTP agents, and a dedicated Wolfram query path.

Features

• Single HTTP service plus browser dashboard
• Built-in agents and remote HTTP agents
• Run history stored in SQLite
• Direct Wolfram query endpoint
• mock, direct, and local claw backends
• Cache, in-flight request coalescing, and upstream budget controls
• Local tests and E2E checks

Requirements

• Node >=24

Optional:

• WOLFRAM_APPID for direct Wolfram API access
• private/Claw if you want the local adapter backend

Quick start

git clone https://github.com/RAPIDENN/wolfram-router.git
cd wolfram-router
cp .env.example .env

For a simple local setup, put this in .env:

API_KEYS=test-key
WOLFRAM_PROVIDER=mock
ALLOW_LOOPBACK_AGENT_ENDPOINTS=1

Start the server:

node src/server.mjs

Open:

http://127.0.0.1:8787/

If you want live Wolfram queries, set WOLFRAM_APPID in .env and keep WOLFRAM_PROVIDER=auto or live.

How it works

• POST /v1/runs executes selected agents for a topic and ranks the resulting experiments.
• POST /v1/labs/wolfram runs one Wolfram query directly.
• GET /v1/runs/:id returns stored agent reports and the ranked summary.
• / serves the dashboard from the same backend.

Wolfram backends

• mock: local mock responses, no credentials required
• direct: calls the public Wolfram API when WOLFRAM_APPID is set
• claw: uses the local private/Claw adapter if it exists

With WOLFRAM_PROVIDER=auto, the server chooses:

1. claw if the local adapter is available
2. direct if WOLFRAM_APPID is set
3. mock otherwise

Useful result notes:

• verification.liveWolframValidated=true means the request reached Wolfram successfully.
• selectedPod: n/a means Wolfram returned no useful pod for that query. It does not necessarily mean the request failed.
• source.mode=mock-local means mock data was used.
• source.mode=live-v1-result means the public Wolfram API answered directly.
• source.mode=live-v2 means the local private/Claw adapter answered the query.

Main endpoints

• GET /healthz: service health and active Wolfram backend
• GET /v1/agents: built-in agents and default plan
• GET /v1/templates: dashboard templates
• GET /v1/metrics: aggregate run metrics
• GET /v1/runs: recent runs
• GET /v1/runs/:id: full run with agent reports and summary
• POST /v1/runs: create a run
• POST /v1/labs/wolfram: run a direct Wolfram query

Example: create a run

curl \
  -H 'content-type: application/json' \
  -H 'x-api-key: test-key' \
  -d '{
    "topic":"increase useful throughput with deterministic routing",
    "sync":true,
    "context":{
      "goal":"produce deployable experiments",
      "constraint":"keep infra lightweight",
      "wolframQuery":"resistivity of copper at 180 Celsius",
      "wolframDomain":"engineering"
    },
    "agents":[
      {"name":"systems","kind":"builtin","strategy":"systems"},
      {"name":"wolfram","kind":"builtin","strategy":"wolfram"}
    ]
  }' \
  http://127.0.0.1:8787/v1/runs

If context.wolframQuery is present, the server canonicalizes it before execution. Equivalent phrasings can share the same cache key, and the canonical form is stored as request.context.wolframQueryCanonical.

Example: run a Wolfram query

curl \
  -H 'content-type: application/json' \
  -H 'x-api-key: test-key' \
  -d '{"input":"resistivity of copper at 180 Celsius","domain":"engineering","provider":"mock"}' \
  http://127.0.0.1:8787/v1/labs/wolfram

Key response fields:

• payloads
• textSummary
• selectedPod
• harvestPath
• verification.liveWolframValidated
• source.mode
• surface.cache.status

Configuration

Defaults live in .env.example and src/config.mjs.

Core variables:

• HOST
• PORT
• DATABASE_PATH
• REQUEST_TIMEOUT_MS
• MAX_BODY_BYTES
• API_KEYS
• CORS_ORIGIN
• ALLOWED_AGENT_ORIGINS
• ALLOW_LOOPBACK_AGENT_ENDPOINTS
• WOLFRAM_PROVIDER
• WOLFRAM_APPID
• WOLFRAM_HARVEST_PATH
• WOLFRAM_CACHE_TTL_MS
• WOLFRAM_UPSTREAM_BUDGET_PER_MINUTE
• WOLFRAM_MAX_CONCURRENCY

Advanced or legacy variables:

• CLAW_REPO_PATH
• CLAW_HARVEST_PATH
• CLAW_WOLFRAM_PROVIDER

Security notes

• /v1/* requires x-api-key when API_KEYS is set.
• Remote HTTP agents are blocked unless their origin is listed in ALLOWED_AGENT_ORIGINS.
• Loopback agent endpoints are blocked unless ALLOW_LOOPBACK_AGENT_ENDPOINTS=1.
• Wildcard CORS is disabled when API keys are active.
• Static files are served from public/ only.

External agent contract

An external agent must expose a JSON POST endpoint such as /infer.

Request shape:

{
  "runId": "uuid",
  "topic": "string",
  "context": {},
  "agent": {
    "name": "string",
    "kind": "http",
    "promptPrefix": "string"
  }
}

Response shape:

{
  "notes": "string",
  "experiments": [
    {
      "title": "string",
      "hypothesis": "string",
      "method": "string",
      "successMetric": "string",
      "risk": "string",
      "estimatedDays": 3,
      "scores": {
        "novelty": 0.8,
        "feasibility": 0.7,
        "impact": 0.9
      }
    }
  ],
  "metadata": {
    "source": "external-http"
  }
}

Verification

Run the local checks with:

node --test
node scripts/e2e.mjs

CI uses WOLFRAM_PROVIDER=mock, so forks and PRs do not need private Wolfram credentials.

Docker

Build:

docker build -t wolfram-router .

Run in mock mode:

docker run --rm -p 8787:8787 \
  -e API_KEYS=test-key \
  -e WOLFRAM_PROVIDER=mock \
  -v wolfram-router-data:/data \
  wolfram-router