v0.4 · local-first
Route work across the models you already use.
Nymrel Agent applies one deterministic routing contract across a public API, a local CLI, and an MCP server. You supply the model catalog and its evidence. Nymrel Agent filters ineligible options, ranks the rest, and explains the decision.
Quickstart
The public endpoint needs no account or API key. It accepts model metadata, not task or prompt text.
Run the example in your browser, or send the same published payload with curl:
curl -fsSL https://nymrel-agent.vercel.app/examples/route-request.json \
| curl -fsS https://nymrel-agent.vercel.app/v1/route \
-H "content-type: application/json" \
--data-binary @-Download the example at /examples/route-request.json. A successful response includes selectedModelId, the ranked eligible set, every rejected candidate with reason codes, and the score components.
/v2/route is an explicit opt-in contract. Its request includes positive request-budget anchors, its response includes a sorted Pareto frontier, and selection is restricted to that frontier. Download /examples/route-request-v2.json.
Request contract
The root object has exactly two fields: request and models. Unknown fields fail closed. Payloads are capped at 256 KiB and 100 models.
{
"request": {
"phase": "implement",
"risk": "workspace_write",
"objective": "balanced",
"requirements": {
"toolUse": true,
"structuredOutput": true,
"minContextTokens": 32000,
"modalities": ["text"]
},
"constraints": {
"dataBoundary": "approved_provider",
"maxCostMicroUsd": 50000,
"maxLatencyMs": 10000
}
},
"models": [/* 1–100 model profiles */]
}See the complete OpenAPI 3.1 document for enums, limits, and response schemas.
Scoring
Routing happens in two phases. First, a model is rejected if it violates health, risk class, data boundary, capability, context, modality, cost, or latency requirements. Duplicate model IDs are also rejected. Second, eligible candidates receive normalized quality, reliability, cost, latency, health, and optional incumbent-stickiness components. An explicit cost or latency ceiling anchors its matching component, so catalog membership cannot change that component; without a ceiling, the component falls back to normalization against the eligible set. Without changing the closed v1 response shape, every route receipt exposes the selected modes in decisionCodes and the exact numeric bounds in explanation.
v2 retains those hard eligibility filters but requires normalization.basis: "request_budget" plus positive cost and latency anchors. It computes the Pareto frontier with quality, reliability, and health higher-is-better and cost and latency lower-is-better. A v2 winner is always on that frontier; an incumbent can resolve only an exact frontier-score tie and receives no bonus.
The selected objective changes explicit weights:
balanced: quality 35%, reliability 25%, cost 20%, latency 15%, health 5%.quality: quality 60%, reliability 25%, with 5% each for cost, latency, and health.cost: cost 45%, quality and reliability 20% each, latency 10%, health 5%.latency: latency 45%, quality and reliability 20% each, cost 10%, health 5%.
Errors
All API errors are JSON and include a request ID plus a stable code. Expected codes include invalid_json, invalid_content_length, invalid_request, payload_too_large, unsupported_media_type, method_not_allowed, rate_limited, service_misconfigured, service_disabled, and not_found. The Vercel production endpoint applies a project-level WAF limit of 120 routing calls per 60-second window per platform-derived network identity, shared across function instances. Shared networks can share an allowance. Internal stack traces and request bodies are never returned.
Versioned downloads
The reviewed v0.4.0 package and MIT-licensed source archive are public in the GitHub Release. Its release manifest records byte sizes, SHA-256 digests, and the approved source commit; the published assets match those values exactly. The hosted service reports its active version and source identity through /healthz; npm publication remains a separate gate.
CLI
Until npm registry publishing is separately approved, install the versioned package directly:
npm install https://nymrel-agent.vercel.app/downloads/nymrel-agent-0.4.0.tgz
npx nymrel-agent contractThe CLI reads locally by default and writes the result as JSON to stdout. Use --endpoint https://nymrel-agent.vercel.app to call the hosted router. No prompt is sent because route payloads contain metadata only.
Job Mode and Lifecycle
job plan routes a body-free, ordered manifest with caller-supplied policy and catalog evidence. It does not inspect task text, learn user behavior, call a provider, or execute a step. job plan --format summary prints a concise local timeline; non-read steps are external handoffs. Phase labels organize the fixture only; they do not affect routing scores.
The sanitized fictional five-step manifest has a pinned deterministic local summary: research → plan → build handoff → review → release handoff. Each line shows its objective, selected model, dependency, and external-handoff boundary.
nymrel-agent job lifecycle init --file examples/job-48h-game-builder.json
nymrel-agent job lifecycle checkpoint --state-file state.json --file examples/lifecycle-checkpoint.example.json
nymrel-agent job lifecycle complete --state-file state.json --file examples/lifecycle-terminal.example.jsonLifecycle commands print a next local envelope. It contains only digests, counts, ordinals, enums, timestamps, and bounded metrics. Hashes support integrity and correlation, not confidentiality or freshness. One terminal transition applies only to the retained latest state lineage: stale copies can fork because v0.4 has no authority or persistence service. There is no hosted lifecycle endpoint, scheduler, persistence, or provider execution.
MCP
The MCP server exposes route_models, route_models_v2, plan_job, explain_contract, and explain_contract_v2 over stdio. plan_job is read-only and idempotent; it uses the body-free local Job Mode parser and returns no timestamped receipt. Configure your compatible client to run node /absolute/path/to/dist/src/bin/nymrel-agent-mcp.js. Protocol messages use stdout; diagnostics use stderr. The MCP host may retain arguments even though Nymrel sends none over its network.
Local execution
The optional local harness can execute read-only tasks through explicitly configured adapters. Provider keys are read from an environment variable named in your local config and sent directly from your machine to that provider. Keys are never accepted by the public Nymrel endpoint, stored in receipts, or printed by the CLI.
v0.2 includes an OpenAI Responses adapter and a synthetic adapter for offline verification. A profile that claims local_only custody is accepted only when its adapter uses a loopback base URL. Provider responses are size-bounded and must report completed; partial responses fail closed. The public router remains provider-neutral and can rank any provider profile. Write-capable tools and hosted key custody are not enabled.
Security and privacy
- The hosted router accepts no prompts, files, provider keys, or customer identifiers.
- Requests are processed in memory and are not written by application code.
- Standard network metadata may be processed by the hosting platform for delivery, abuse protection, and operational telemetry.
- Local receipts contain SHA-256 correlation digests, not task or output bodies. A digest is not an encryption or confidentiality control.
- The local execution runtime permits read-only runs only in v0.1.
Report a security issue privately to contact@jalenbuilds.com. Do not include provider credentials or customer data.
Managed implementation service
Nymrel can configure a model catalog, evidence collection, routing policy, evals, local adapters, and operational receipts for a real workflow. Hosted provider execution, credentials, data retention, and write-capable tools require a separate scope and security review. Pricing is provided on request.