@stratchai/llm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stratchai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# @stratchai/llm
+
+Provider-agnostic **forced-JSON** LLM adapter for the stratchai trading agents. One interface,
+two providers — [Anthropic](https://docs.anthropic.com) (forced tool-use + prompt caching) and
+[OpenRouter](https://openrouter.ai/docs) (OpenAI-style function calling) — with **cache-aware
+per-call cost accounting** so budget meters stay honest across vendors.
+
+Built for decision gates that must never act on malformed output: the only operation offered is
+*"produce an object matching this schema, or throw."* Free-text JSON is deliberately not exposed —
+it empties/mis-formats in bursts on some models (~34% of live calls observed on our crypto gate),
+and a silently-defaulted decision is worse than a loud error.
+
+## Install
+
+```bash
+npm install @stratchai/llm
+```
+
+Zero runtime dependencies (built on `fetch`, Node ≥ 18).
+
+## Use
+
+```ts
+import { createProvider } from '@stratchai/llm'
+
+const llm = createProvider({ model: process.env.GATE_MODEL }) // provider from LLM_PROVIDER (default anthropic)
+
+const res = await llm.jsonCall({
+  system: STATIC_RULEBOOK,          // byte-identical across calls → provider prompt-caching engages
+  user: perCandidatePrompt,
+  tool: {
+    name: 'record_verdict',
+    description: 'Record the entry-gate verdict.',
+    schema: {
+      type: 'object',
+      properties: {
+        take: { type: 'boolean' },
+        reason: { type: 'string' },
+        confidence: { type: 'number' },
+      },
+      required: ['take', 'reason', 'confidence'],
+    },
+  },
+})
+res.object        // schema-shaped verdict (never null — failure throws)
+res.usage.costUsd // cache-aware $ for this call
+```
+
+### Error contract (load-bearing)
+
+- Transport/HTTP failures **throw with `.status`** set to the HTTP code.
+- Parse/shape failures (missing tool call, bad JSON) **throw with `.status` undefined**.
+
+Callers that retry only on `e.status == null` — the parse-only retry pattern our agents use, since
+HTTP-level retries belong to backoff logic — work unchanged across both providers. The recommended
+gate pattern is **fail-closed**: catch, log, and return a conservative skip.
+
+## Configuration
+
+| env | meaning | default |
+|---|---|---|
+| `LLM_PROVIDER` | `anthropic` \| `openrouter` | `anthropic` |
+| `LLM_MODEL` | model id in the provider's namespace | — (callers usually pass `model`) |
+| `ANTHROPIC_API_KEY` / `OPENROUTER_API_KEY` | credentials | — |
+| `LLM_PRICE_IN_PER_MTOK` / `LLM_PRICE_OUT_PER_MTOK` | $/1M-token overrides for cost metering | built-in table |
+
+Built-in prices (USD per 1M tokens): Anthropic haiku 1/5, sonnet 3/15, opus 15/75 — cache reads
+at 0.1×, cache writes at 1.25×. OpenRouter: deepseek 0.3/1.2, llama-3.3-70b 0.2/0.6, qwen 0.3/1.2;
+**unknown models fall back conservative (1/2)** so a budget ceiling errs on the safe side —
+override the price envs when running anything else.
+
+### Provider notes
+
+- **Anthropic**: `tool_choice` forces the verdict tool; the system block carries
+  `cache_control: ephemeral` (disable per-call with `cacheSystem: false`).
+- **OpenRouter**: function calling is the primary path. If the chosen model rejects tools
+  (4xx mentioning tools), one fallback attempt uses `response_format: json_object` plus a
+  schema-in-prompt instruction with first-`{…}` extraction. Prompt caching is automatic on
+  supporting models (no marker to send); reported cached tokens are billed at the read discount.
+
+## Why this exists
+
+Our agents are published to npm and must not be vendor-locked, but their decision gates carry a
+forward evidence record earned on a specific model. This package makes the provider a config
+choice while changing nothing about behavior on the default path — swap-safety is the point:
+promote a cheaper provider only after it earns the switch in a shadow A/B, not because the
+adapter made it easy.
+
+## Development
+
+```bash
+npm test   # tsc build + node:test (mocked fetch — no network, no keys)
+```
+
+Issues: https://github.com/stratchai/llm/issues

package/dist/anthropic.d.ts

@@ -0,0 +1,20 @@
+/**
+ * AnthropicProvider — forced tool-use against the Messages API (raw fetch, zero deps).
+ * Preserves the crypto-gate's proven mechanics exactly:
+ *   • tool_choice forces a schema-valid verdict (free-text JSON empties in bursts; some
+ *     models reject assistant prefill — the forced tool call is the reliable path).
+ *   • the system block carries cache_control: ephemeral (byte-identical prefix across
+ *     calls → prompt-cache reads at 0.1× price).
+ *   • usage is reported cache-aware and costed with the same math as gate-cost.ts.
+ */
+import { JsonCallRequest, JsonCallResult, LlmProvider } from './types.js';
+import { Price } from './pricing.js';
+export declare class AnthropicProvider implements LlmProvider {
+    private apiKey;
+    readonly model: string;
+    private priceOverride?;
+    private timeoutMs;
+    readonly id: "anthropic";
+    constructor(apiKey: string, model: string, priceOverride?: Partial<Price> | undefined, timeoutMs?: number);
+    jsonCall(req: JsonCallRequest): Promise<JsonCallResult>;
+}

package/dist/anthropic.js

@@ -0,0 +1,85 @@
+/**
+ * AnthropicProvider — forced tool-use against the Messages API (raw fetch, zero deps).
+ * Preserves the crypto-gate's proven mechanics exactly:
+ *   • tool_choice forces a schema-valid verdict (free-text JSON empties in bursts; some
+ *     models reject assistant prefill — the forced tool call is the reliable path).
+ *   • the system block carries cache_control: ephemeral (byte-identical prefix across
+ *     calls → prompt-cache reads at 0.1× price).
+ *   • usage is reported cache-aware and costed with the same math as gate-cost.ts.
+ */
+import { LlmError } from './types.js';
+import { computeCost, priceFor } from './pricing.js';
+const API = process.env.ANTHROPIC_BASE_URL || 'https://api.anthropic.com';
+export class AnthropicProvider {
+    apiKey;
+    model;
+    priceOverride;
+    timeoutMs;
+    id = 'anthropic';
+    constructor(apiKey, model, priceOverride, timeoutMs = 60_000) {
+        this.apiKey = apiKey;
+        this.model = model;
+        this.priceOverride = priceOverride;
+        this.timeoutMs = timeoutMs;
+        if (!apiKey)
+            throw new LlmError('AnthropicProvider: missing API key');
+        if (!model)
+            throw new LlmError('AnthropicProvider: missing model');
+    }
+    async jsonCall(req) {
+        const cache = req.cacheSystem !== false;
+        const body = {
+            model: this.model,
+            max_tokens: req.maxTokens ?? 512,
+            system: cache
+                ? [{ type: 'text', text: req.system, cache_control: { type: 'ephemeral' } }]
+                : req.system,
+            tools: [{ name: req.tool.name, description: req.tool.description ?? '', input_schema: req.tool.schema }],
+            tool_choice: { type: 'tool', name: req.tool.name },
+            messages: [{ role: 'user', content: req.user }],
+        };
+        let res;
+        try {
+            res = await fetch(`${API}/v1/messages`, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'x-api-key': this.apiKey,
+                    'anthropic-version': '2023-06-01',
+                },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (e) {
+            throw new LlmError(`anthropic transport: ${e?.message || e}`); // no status → caller may retry
+        }
+        if (!res.ok) {
+            const detail = await res.text().catch(() => '');
+            throw new LlmError(`anthropic ${res.status}: ${detail.slice(0, 300)}`, res.status);
+        }
+        const d = await res.json();
+        const tu = (d.content ?? []).find((b) => b.type === 'tool_use');
+        if (!tu?.input || typeof tu.input !== 'object')
+            throw new LlmError('no tool_use in response');
+        const u = d.usage ?? {};
+        const inTok = u.input_tokens ?? 0;
+        const cacheRead = u.cache_read_input_tokens ?? 0;
+        const cacheWrite = u.cache_creation_input_tokens ?? 0;
+        const outTok = u.output_tokens ?? 0;
+        const price = priceFor('anthropic', this.model, this.priceOverride);
+        return {
+            object: tu.input,
+            raw: JSON.stringify(tu.input),
+            usage: {
+                inputTokens: inTok + cacheRead + cacheWrite,
+                outputTokens: outTok,
+                cacheReadTokens: cacheRead,
+                cacheWriteTokens: cacheWrite,
+                costUsd: computeCost(price, inTok, outTok, cacheRead, cacheWrite),
+            },
+            provider: this.id,
+            model: this.model,
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export * from './types.js';
+export { AnthropicProvider } from './anthropic.js';
+export { OpenRouterProvider } from './openrouter.js';
+export { priceFor, computeCost } from './pricing.js';
+import { LlmProvider, ProviderOptions } from './types.js';
+/**
+ * Build a provider from options + environment. Nothing is baked in: the model always comes
+ * from the caller or LLM_MODEL, so an agent's proven configuration can't silently change by
+ * upgrading this package. Env surface:
+ *   LLM_PROVIDER   anthropic | openrouter        (default anthropic)
+ *   LLM_MODEL      model id in the provider's namespace
+ *   ANTHROPIC_API_KEY / OPENROUTER_API_KEY
+ *   LLM_PRICE_IN_PER_MTOK / LLM_PRICE_OUT_PER_MTOK   optional $ overrides for cost metering
+ */
+export declare function createProvider(opts?: ProviderOptions, env?: Record<string, string | undefined>): LlmProvider;

package/dist/index.js

@@ -0,0 +1,31 @@
+export * from './types.js';
+export { AnthropicProvider } from './anthropic.js';
+export { OpenRouterProvider } from './openrouter.js';
+export { priceFor, computeCost } from './pricing.js';
+import { LlmError } from './types.js';
+import { AnthropicProvider } from './anthropic.js';
+import { OpenRouterProvider } from './openrouter.js';
+/**
+ * Build a provider from options + environment. Nothing is baked in: the model always comes
+ * from the caller or LLM_MODEL, so an agent's proven configuration can't silently change by
+ * upgrading this package. Env surface:
+ *   LLM_PROVIDER   anthropic | openrouter        (default anthropic)
+ *   LLM_MODEL      model id in the provider's namespace
+ *   ANTHROPIC_API_KEY / OPENROUTER_API_KEY
+ *   LLM_PRICE_IN_PER_MTOK / LLM_PRICE_OUT_PER_MTOK   optional $ overrides for cost metering
+ */
+export function createProvider(opts = {}, env = process.env) {
+    const provider = (opts.provider ?? env.LLM_PROVIDER ?? 'anthropic');
+    const model = opts.model ?? env.LLM_MODEL ?? '';
+    const override = {
+        in: opts.priceInPerMtok ?? (env.LLM_PRICE_IN_PER_MTOK ? Number(env.LLM_PRICE_IN_PER_MTOK) : undefined),
+        out: opts.priceOutPerMtok ?? (env.LLM_PRICE_OUT_PER_MTOK ? Number(env.LLM_PRICE_OUT_PER_MTOK) : undefined),
+    };
+    if (provider === 'anthropic') {
+        return new AnthropicProvider(opts.apiKey ?? env.ANTHROPIC_API_KEY ?? '', model, override, opts.timeoutMs);
+    }
+    if (provider === 'openrouter') {
+        return new OpenRouterProvider(opts.apiKey ?? env.OPENROUTER_API_KEY ?? '', model, override, opts.timeoutMs);
+    }
+    throw new LlmError(`unknown LLM_PROVIDER: ${provider}`);
+}

package/dist/openrouter.d.ts

@@ -0,0 +1,23 @@
+/**
+ * OpenRouterProvider — the same forced-JSON contract over OpenAI-style function calling.
+ * Primary path: tools + tool_choice (supported by the models we run, e.g. deepseek-chat).
+ * Fallback (one retry, only when the provider rejects tools): strict-JSON instruction +
+ * first-{...} extraction — so a model without function calling still satisfies the contract
+ * or throws a parse error (status undefined → caller's parse-only retry applies).
+ *
+ * Prompt caching: OpenRouter/deepseek cache automatically on repeated prefixes — there is no
+ * cache_control marker to send; `cacheSystem` is accepted and ignored. Cached prompt tokens,
+ * when reported (usage.prompt_tokens_details.cached_tokens), are billed at the read discount.
+ */
+import { JsonCallRequest, JsonCallResult, LlmProvider } from './types.js';
+import { Price } from './pricing.js';
+export declare class OpenRouterProvider implements LlmProvider {
+    private apiKey;
+    readonly model: string;
+    private priceOverride?;
+    private timeoutMs;
+    readonly id: "openrouter";
+    constructor(apiKey: string, model: string, priceOverride?: Partial<Price> | undefined, timeoutMs?: number);
+    private post;
+    jsonCall(req: JsonCallRequest): Promise<JsonCallResult>;
+}

package/dist/openrouter.js

@@ -0,0 +1,122 @@
+/**
+ * OpenRouterProvider — the same forced-JSON contract over OpenAI-style function calling.
+ * Primary path: tools + tool_choice (supported by the models we run, e.g. deepseek-chat).
+ * Fallback (one retry, only when the provider rejects tools): strict-JSON instruction +
+ * first-{...} extraction — so a model without function calling still satisfies the contract
+ * or throws a parse error (status undefined → caller's parse-only retry applies).
+ *
+ * Prompt caching: OpenRouter/deepseek cache automatically on repeated prefixes — there is no
+ * cache_control marker to send; `cacheSystem` is accepted and ignored. Cached prompt tokens,
+ * when reported (usage.prompt_tokens_details.cached_tokens), are billed at the read discount.
+ */
+import { LlmError } from './types.js';
+import { computeCost, priceFor } from './pricing.js';
+const API = process.env.OPENROUTER_BASE_URL || 'https://openrouter.ai/api/v1';
+export class OpenRouterProvider {
+    apiKey;
+    model;
+    priceOverride;
+    timeoutMs;
+    id = 'openrouter';
+    constructor(apiKey, model, priceOverride, timeoutMs = 60_000) {
+        this.apiKey = apiKey;
+        this.model = model;
+        this.priceOverride = priceOverride;
+        this.timeoutMs = timeoutMs;
+        if (!apiKey)
+            throw new LlmError('OpenRouterProvider: missing API key');
+        if (!model)
+            throw new LlmError('OpenRouterProvider: missing model');
+    }
+    async post(body) {
+        let res;
+        try {
+            res = await fetch(`${API}/chat/completions`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', authorization: `Bearer ${this.apiKey}` },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (e) {
+            throw new LlmError(`openrouter transport: ${e?.message || e}`);
+        }
+        if (!res.ok) {
+            const detail = await res.text().catch(() => '');
+            throw new LlmError(`openrouter ${res.status}: ${detail.slice(0, 300)}`, res.status);
+        }
+        return res.json();
+    }
+    async jsonCall(req) {
+        const base = {
+            model: this.model,
+            max_tokens: req.maxTokens ?? 512,
+            temperature: 0,
+        };
+        const messages = [
+            { role: 'system', content: req.system },
+            { role: 'user', content: req.user },
+        ];
+        let object = null;
+        let d;
+        try {
+            d = await this.post({
+                ...base,
+                messages,
+                tools: [{ type: 'function', function: { name: req.tool.name, description: req.tool.description ?? '', parameters: req.tool.schema } }],
+                tool_choice: { type: 'function', function: { name: req.tool.name } },
+            });
+            const call = d.choices?.[0]?.message?.tool_calls?.[0];
+            if (call?.function?.arguments) {
+                try {
+                    object = JSON.parse(call.function.arguments);
+                }
+                catch { /* falls through to parse error below */ }
+            }
+            if (!object)
+                throw new LlmError('no tool_call in response');
+        }
+        catch (e) {
+            // Only a provider-side "tools unsupported" 4xx earns the fallback; transport/5xx/parse rethrow.
+            const toolRejected = e?.status != null && e.status < 500 && /tool|function/i.test(String(e?.message));
+            if (!toolRejected)
+                throw e;
+            d = await this.post({
+                ...base,
+                response_format: { type: 'json_object' },
+                messages: [
+                    { role: 'system', content: `${req.system}\n\nReply ONLY with a JSON object matching this schema (no prose): ${JSON.stringify(req.tool.schema)}` },
+                    { role: 'user', content: req.user },
+                ],
+            });
+            const text = d.choices?.[0]?.message?.content ?? '';
+            const m = String(text).match(/\{[\s\S]*\}/);
+            if (!m)
+                throw new LlmError('no JSON object in fallback response');
+            try {
+                object = JSON.parse(m[0]);
+            }
+            catch {
+                throw new LlmError('unparseable JSON in fallback response');
+            }
+        }
+        const u = d.usage ?? {};
+        const promptTok = u.prompt_tokens ?? 0;
+        const cached = u.prompt_tokens_details?.cached_tokens ?? 0;
+        const outTok = u.completion_tokens ?? 0;
+        const price = priceFor('openrouter', this.model, this.priceOverride);
+        return {
+            object: object,
+            raw: JSON.stringify(object),
+            usage: {
+                inputTokens: promptTok,
+                outputTokens: outTok,
+                cacheReadTokens: cached,
+                cacheWriteTokens: 0,
+                costUsd: computeCost(price, promptTok - cached, outTok, cached, 0),
+            },
+            provider: this.id,
+            model: this.model,
+        };
+    }
+}

package/dist/pricing.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Cache-aware per-call cost. USD per MILLION tokens by model family, mirroring the
+ * agents' proven gate-cost meter (crypto-agent src/entry/gate-cost.ts): Anthropic
+ * cache READS bill at 0.1×, cache WRITES at 1.25×. OpenRouter prices vary per model —
+ * a small table covers the ones we run, and callers/env can override exactly
+ * (LLM_PRICE_IN_PER_MTOK / LLM_PRICE_OUT_PER_MTOK) when a different model is chosen.
+ * Unknown models fall back CONSERVATIVE (over-estimate) so a budget meter errs safe.
+ */
+export interface Price {
+    in: number;
+    out: number;
+}
+export declare function priceFor(provider: 'anthropic' | 'openrouter', model: string, override?: Partial<Price>): Price;
+export declare function computeCost(p: Price, inputTokens: number, outputTokens: number, cacheReadTokens?: number, cacheWriteTokens?: number): number;

package/dist/pricing.js

@@ -0,0 +1,30 @@
+/**
+ * Cache-aware per-call cost. USD per MILLION tokens by model family, mirroring the
+ * agents' proven gate-cost meter (crypto-agent src/entry/gate-cost.ts): Anthropic
+ * cache READS bill at 0.1×, cache WRITES at 1.25×. OpenRouter prices vary per model —
+ * a small table covers the ones we run, and callers/env can override exactly
+ * (LLM_PRICE_IN_PER_MTOK / LLM_PRICE_OUT_PER_MTOK) when a different model is chosen.
+ * Unknown models fall back CONSERVATIVE (over-estimate) so a budget meter errs safe.
+ */
+const ANTHROPIC = {
+    haiku: { in: 1, out: 5 },
+    sonnet: { in: 3, out: 15 },
+    opus: { in: 15, out: 75 },
+};
+const OPENROUTER = {
+    'deepseek': { in: 0.3, out: 1.2 },
+    'llama-3.3-70b': { in: 0.2, out: 0.6 },
+    'qwen': { in: 0.3, out: 1.2 },
+};
+export function priceFor(provider, model, override) {
+    const table = provider === 'anthropic' ? ANTHROPIC : OPENROUTER;
+    const key = Object.keys(table).find((k) => model.includes(k));
+    const base = key ? table[key] : provider === 'anthropic' ? ANTHROPIC.sonnet : { in: 1, out: 2 }; // conservative fallback
+    return { in: override?.in ?? base.in, out: override?.out ?? base.out };
+}
+export function computeCost(p, inputTokens, outputTokens, cacheReadTokens = 0, cacheWriteTokens = 0) {
+    return ((inputTokens / 1e6) * p.in +
+        (cacheReadTokens / 1e6) * p.in * 0.1 +
+        (cacheWriteTokens / 1e6) * p.in * 1.25 +
+        (outputTokens / 1e6) * p.out);
+}

package/dist/test/providers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/providers.test.js

@@ -0,0 +1,93 @@
+import { test, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { AnthropicProvider } from '../anthropic.js';
+import { OpenRouterProvider } from '../openrouter.js';
+import { createProvider } from '../index.js';
+import { computeCost, priceFor } from '../pricing.js';
+const realFetch = globalThis.fetch;
+let calls = [];
+function mockFetch(sequence) {
+    let i = 0;
+    globalThis.fetch = (async (url, init) => {
+        calls.push({ url: String(url), body: JSON.parse(init.body) });
+        const step = sequence[Math.min(i++, sequence.length - 1)];
+        return {
+            ok: step.status >= 200 && step.status < 300,
+            status: step.status,
+            json: async () => step.json,
+            text: async () => step.text ?? JSON.stringify(step.json ?? {}),
+        };
+    });
+}
+beforeEach(() => { calls = []; });
+afterEach(() => { globalThis.fetch = realFetch; });
+const TOOL = { name: 'record_verdict', schema: { type: 'object', properties: { take: { type: 'boolean' } }, required: ['take'] } };
+const REQ = { system: 'rulebook', user: 'candidate', tool: TOOL };
+test('anthropic: forced tool-use parses + cache-aware cost + cached system block', async () => {
+    mockFetch([{
+            status: 200,
+            json: {
+                content: [{ type: 'tool_use', input: { take: true, reason: 'ok', confidence: 0.7 } }],
+                usage: { input_tokens: 100, output_tokens: 50, cache_read_input_tokens: 2000, cache_creation_input_tokens: 0 },
+            },
+        }]);
+    const p = new AnthropicProvider('k', 'claude-sonnet-5');
+    const r = await p.jsonCall(REQ);
+    assert.equal(r.object.take, true);
+    assert.equal(r.usage.inputTokens, 2100); // fresh + cache read
+    // sonnet: 100/1e6*3 + 2000/1e6*3*0.1 + 50/1e6*15
+    assert.ok(Math.abs(r.usage.costUsd - (0.0003 + 0.0006 + 0.00075)) < 1e-9);
+    const body = calls[0].body;
+    assert.equal(body.tool_choice.name, 'record_verdict');
+    assert.equal(body.system[0].cache_control.type, 'ephemeral');
+});
+test('anthropic: HTTP error carries .status; missing tool_use does not', async () => {
+    mockFetch([{ status: 429, text: 'rate limited' }]);
+    const p = new AnthropicProvider('k', 'claude-haiku-4-5');
+    await assert.rejects(p.jsonCall(REQ), (e) => e.status === 429);
+    mockFetch([{ status: 200, json: { content: [], usage: {} } }]);
+    await assert.rejects(p.jsonCall(REQ), (e) => e.status == null && /no tool_use/.test(e.message));
+});
+test('openrouter: function-calling path parses + cost with cached tokens', async () => {
+    mockFetch([{
+            status: 200,
+            json: {
+                choices: [{ message: { tool_calls: [{ function: { name: 'record_verdict', arguments: '{"take":false}' } }] } }],
+                usage: { prompt_tokens: 1000, completion_tokens: 100, prompt_tokens_details: { cached_tokens: 600 } },
+            },
+        }]);
+    const p = new OpenRouterProvider('k', 'deepseek/deepseek-chat');
+    const r = await p.jsonCall(REQ);
+    assert.equal(r.object.take, false);
+    assert.equal(r.usage.cacheReadTokens, 600);
+    // deepseek 0.3/1.2: fresh 400 in + 600 cached at 0.1x + 100 out
+    const want = (400 / 1e6) * 0.3 + (600 / 1e6) * 0.3 * 0.1 + (100 / 1e6) * 1.2;
+    assert.ok(Math.abs(r.usage.costUsd - want) < 1e-12);
+    assert.equal(calls[0].body.tool_choice.function.name, 'record_verdict');
+});
+test('openrouter: tools-rejected 400 falls back to json_object extraction', async () => {
+    mockFetch([
+        { status: 400, text: 'this model does not support tool use' },
+        { status: 200, json: { choices: [{ message: { content: 'sure: {"take":true} done' } }], usage: { prompt_tokens: 10, completion_tokens: 5 } } },
+    ]);
+    const p = new OpenRouterProvider('k', 'some/no-tools-model');
+    const r = await p.jsonCall(REQ);
+    assert.equal(r.object.take, true);
+    assert.equal(calls.length, 2);
+    assert.equal(calls[1].body.response_format.type, 'json_object');
+});
+test('openrouter: 5xx does NOT trigger fallback and keeps .status', async () => {
+    mockFetch([{ status: 503, text: 'overloaded' }]);
+    const p = new OpenRouterProvider('k', 'deepseek/deepseek-chat');
+    await assert.rejects(p.jsonCall(REQ), (e) => e.status === 503);
+    assert.equal(calls.length, 1);
+});
+test('factory: env selection + price override + unknown-model conservative fallback', () => {
+    const a = createProvider({}, { LLM_PROVIDER: 'anthropic', LLM_MODEL: 'claude-sonnet-5', ANTHROPIC_API_KEY: 'k' });
+    assert.equal(a.id, 'anthropic');
+    const o = createProvider({}, { LLM_PROVIDER: 'openrouter', LLM_MODEL: 'deepseek/deepseek-chat', OPENROUTER_API_KEY: 'k' });
+    assert.equal(o.id, 'openrouter');
+    assert.deepEqual(priceFor('openrouter', 'mystery/model'), { in: 1, out: 2 });
+    assert.deepEqual(priceFor('openrouter', 'x', { in: 0.5, out: 0.9 }), { in: 0.5, out: 0.9 });
+    assert.ok(computeCost({ in: 3, out: 15 }, 1e6, 0, 0, 1e6) === 3 + 3.75); // write surcharge 1.25x
+});

package/dist/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @stratchai/llm — provider-agnostic LLM adapter for the stratchai agents.
+ *
+ * One capability, done carefully: a FORCED-JSON call ("give me an object matching this schema,
+ * or throw") with cache-aware per-call cost accounting. Free-text JSON is not offered — it
+ * empties/mis-formats in bursts on some models (~34% observed live on the crypto gate,
+ * 2026-08-04), so schema-forced structured output is the only path this package exposes.
+ *
+ * Error contract (load-bearing): transport/HTTP errors THROW with `.status` set to the HTTP
+ * code; parse/shape errors THROW with `.status` undefined. Callers that retry only on
+ * `e.status == null` (parse-only retry — the agents' pattern) keep working unchanged.
+ */
+/** JSON-schema-shaped tool the model MUST answer through. */
+export interface JsonTool {
+    name: string;
+    description?: string;
+    /** Standard JSON schema object: { type:'object', properties, required } */
+    schema: Record<string, unknown>;
+}
+export interface JsonCallRequest {
+    /** Static rulebook — byte-identical across calls so provider prompt-caching engages. */
+    system: string;
+    /** Per-call content (the candidate). */
+    user: string;
+    tool: JsonTool;
+    /** Default 512. */
+    maxTokens?: number;
+    /** Mark the system block cacheable where the provider supports it (default true). */
+    cacheSystem?: boolean;
+}
+export interface Usage {
+    /** Total input volume seen by the provider (fresh + cache read + cache write). */
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    /** Cache-aware USD for this call (reads discounted, writes surcharged where applicable). */
+    costUsd: number;
+}
+export interface JsonCallResult {
+    /** The schema-shaped object the model produced. Never null — a missing object throws. */
+    object: Record<string, unknown>;
+    /** JSON.stringify(object) — logging parity with the previous free-text era. */
+    raw: string;
+    usage: Usage;
+    provider: ProviderId;
+    model: string;
+}
+export type ProviderId = 'anthropic' | 'openrouter';
+export interface LlmProvider {
+    readonly id: ProviderId;
+    readonly model: string;
+    jsonCall(req: JsonCallRequest): Promise<JsonCallResult>;
+}
+export interface ProviderOptions {
+    /** 'anthropic' | 'openrouter'. Default: env LLM_PROVIDER, else 'anthropic'. */
+    provider?: ProviderId;
+    /** Model id in the provider's namespace. Default: env LLM_MODEL (no baked-in product default). */
+    model?: string;
+    /** Default: env ANTHROPIC_API_KEY / OPENROUTER_API_KEY per provider. */
+    apiKey?: string;
+    /** USD per MILLION tokens overrides (OpenRouter models vary; env LLM_PRICE_IN_PER_MTOK / LLM_PRICE_OUT_PER_MTOK). */
+    priceInPerMtok?: number;
+    priceOutPerMtok?: number;
+    /** Request timeout ms (default 60000). */
+    timeoutMs?: number;
+}
+/** Error thrown by providers; `status` present only for HTTP-level failures. */
+export declare class LlmError extends Error {
+    status?: number;
+    constructor(message: string, status?: number);
+}

package/dist/types.js

@@ -0,0 +1,22 @@
+/**
+ * @stratchai/llm — provider-agnostic LLM adapter for the stratchai agents.
+ *
+ * One capability, done carefully: a FORCED-JSON call ("give me an object matching this schema,
+ * or throw") with cache-aware per-call cost accounting. Free-text JSON is not offered — it
+ * empties/mis-formats in bursts on some models (~34% observed live on the crypto gate,
+ * 2026-08-04), so schema-forced structured output is the only path this package exposes.
+ *
+ * Error contract (load-bearing): transport/HTTP errors THROW with `.status` set to the HTTP
+ * code; parse/shape errors THROW with `.status` undefined. Callers that retry only on
+ * `e.status == null` (parse-only retry — the agents' pattern) keep working unchanged.
+ */
+/** Error thrown by providers; `status` present only for HTTP-level failures. */
+export class LlmError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = 'LlmError';
+        if (status != null)
+            this.status = status;
+    }
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@stratchai/llm",
+  "version": "0.1.0",
+  "description": "Provider-agnostic forced-JSON LLM adapter for stratchai trading agents — Anthropic (tool-use + prompt caching) and OpenRouter (function calling) behind one interface, with cache-aware per-call cost accounting.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test dist/test/",
+    "prepublishOnly": "npm test"
+  },
+  "repository": { "type": "git", "url": "git+https://github.com/stratchai/llm.git" },
+  "bugs": { "url": "https://github.com/stratchai/llm/issues" },
+  "homepage": "https://github.com/stratchai/llm#readme",
+  "keywords": ["llm", "anthropic", "openrouter", "structured-output", "trading"],
+  "engines": { "node": ">=18" },
+  "devDependencies": { "@types/node": "^20.14.0", "typescript": "^5.5.0" }
+}