@spendgraph/llms 0.2.0

package/dist/stream.js

@@ -0,0 +1,71 @@
+import { adapterFor, adapterOfShape } from "./adapters/index.js";
+import { pricingId } from "./model.js";
+import { UnknownReplyError } from "./read.js";
+import { emptyUsage, parseArgs, reply } from "./usage.js";
+function newState() {
+    return { text: "", model: "", usage: emptyUsage(), tools: new Map() };
+}
+const FAILED = new Set(["refusal", "content_filter", "content_filtered", "SAFETY", "failed"]);
+function finish(state, provider, opts) {
+    const toolCalls = [...state.tools.values()].map((pending) => ({
+        id: pending.id,
+        name: pending.name,
+        args: parseArgs(pending.json),
+    }));
+    const refused = state.stopReason ? FAILED.has(state.stopReason) : false;
+    return reply({
+        output: state.text,
+        model: opts.model ?? pricingId(provider, state.model),
+        usage: state.usage,
+        toolCalls,
+        citations: state.citations,
+        stopReason: state.stopReason,
+        status: refused ? "failed" : "completed",
+        error: refused ? `stopped: ${state.stopReason}` : undefined,
+    });
+}
+class LlmStream {
+    source;
+    opts;
+    state = newState();
+    adapter;
+    done = false;
+    constructor(source, opts = {}) {
+        this.source = source;
+        this.opts = opts;
+        const chosen = opts.shape
+            ? adapterOfShape(opts.shape)
+            : opts.provider
+                ? adapterFor(opts.provider)
+                : undefined;
+        if (!chosen)
+            throw new UnknownReplyError();
+        this.adapter = chosen;
+    }
+    async *[Symbol.asyncIterator]() {
+        for await (const event of this.source) {
+            const delta = this.adapter.chunk(event, this.state);
+            if (!delta)
+                continue;
+            this.opts.onText?.(delta);
+            yield delta;
+        }
+        this.done = true;
+    }
+    /** Drains any events not yet read, then assembles the reply. */
+    async reply() {
+        if (!this.done) {
+            for await (const _ of this)
+                void _;
+        }
+        return finish(this.state, this.opts.provider ?? this.adapter.provider, this.opts);
+    }
+}
+/** A stream to iterate for text deltas, then ask for the finished reply. */
+export function stream(source, opts = {}) {
+    return new LlmStream(source, opts);
+}
+/** Consumes a stream whole, calling `onText` per delta. */
+export function collect(source, opts = {}) {
+    return new LlmStream(source, opts).reply();
+}

package/dist/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * One turn. Structurally the `Message` `@spendgraph/prompt` renders.
+ *
+ * `assistant` is here for conversation history — prior turns replayed to the
+ * model. A prompt's own wording still renders a system turn and a user turn.
+ */
+export interface PromptMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+/**
+ * One model call's result. Structurally the `TraceOutcome` that harness's
+ * `prompt.trace()` accepts, so a reply can be returned straight from it.
+ */
+export interface CallOutcome {
+    output: string;
+    model: string;
+    status?: "completed" | "failed";
+    error?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    citationTokens?: number;
+    reasoningTokens?: number;
+}
+/** A slug from `model_pricing.provider`. Open — the table grows with ingest. */
+export type Provider = "anthropic" | "openai" | "bedrock" | "gemini" | "openrouter" | "zai" | "groq" | "together_ai" | "deepseek" | "mistral" | "xai" | "azure" | "fireworks_ai" | "perplexity" | "ollama" | "vertex_ai" | (string & {});
+export interface LlmUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    /** Billed on their own by search-grounded providers. Zero everywhere else. */
+    citationTokens: number;
+    reasoningTokens: number;
+}
+/** One call the model wants made, with its arguments already parsed. */
+export interface LlmToolCall {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+/** A provider reply in the shape `prompt.trace()` returns. */
+export interface LlmReply extends CallOutcome {
+    usage: LlmUsage;
+    toolCalls: LlmToolCall[];
+    /** Source URLs, from search-grounded providers that return them. */
+    citations?: string[];
+    stopReason?: string;
+    latencyMs?: number;
+    /** Set when usage was recorded. */
+    eventId?: string;
+    /** The object asked for, when `schema` was passed. Parsed already. */
+    data?: unknown;
+}
+export interface ReadOptions {
+    /** Pricing slug. Required for OpenAI-compatible gateways, which share a shape. */
+    provider?: Provider;
+    /** Replaces the id the reply reported. */
+    model?: string;
+}
+/** Mutable accumulator a stream folds into, owned by the collector. */
+export interface StreamState {
+    text: string;
+    model: string;
+    stopReason?: string;
+    citations?: string[];
+    usage: LlmUsage;
+    tools: Map<string, {
+        id: string;
+        name: string;
+        json: string;
+    }>;
+}
+export interface Adapter {
+    provider: Provider;
+    detect(value: unknown): boolean;
+    read(reply: unknown, opts?: ReadOptions): LlmReply;
+    /** Folds one stream event into `state` and returns the text it added. */
+    chunk(event: unknown, state: StreamState): string;
+}

package/dist/types.js

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

package/dist/usage.d.ts

@@ -0,0 +1,22 @@
+import type { LlmReply, LlmToolCall, LlmUsage } from "./types.js";
+export declare function emptyUsage(): LlmUsage;
+/** A token count from any provider, coerced to a non-negative integer. */
+export declare function count(value: unknown): number;
+export declare function addUsage(into: LlmUsage, more: Partial<LlmUsage>): LlmUsage;
+/**
+ * Overwrites each field the provider reported, leaving the rest. Stream events
+ * restate running totals rather than sending increments.
+ */
+export declare function setUsage(into: LlmUsage, more: Partial<LlmUsage>): LlmUsage;
+export declare function reply(parts: {
+    output: string;
+    model: string;
+    usage: LlmUsage;
+    toolCalls?: LlmToolCall[];
+    citations?: string[];
+    stopReason?: string;
+    status?: "completed" | "failed";
+    error?: string;
+}): LlmReply;
+/** Tool arguments, which providers send as a JSON string. Malformed reads `{}`. */
+export declare function parseArgs(raw: unknown): Record<string, unknown>;

package/dist/usage.js

@@ -0,0 +1,76 @@
+const USAGE_KEYS = [
+    "inputTokens",
+    "outputTokens",
+    "cacheReadTokens",
+    "cacheWriteTokens",
+    "citationTokens",
+    "reasoningTokens",
+];
+export function emptyUsage() {
+    return {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+        citationTokens: 0,
+        reasoningTokens: 0,
+    };
+}
+/** A token count from any provider, coerced to a non-negative integer. */
+export function count(value) {
+    const n = typeof value === "string" ? Number(value) : value;
+    return typeof n === "number" && Number.isFinite(n) && n > 0 ? Math.round(n) : 0;
+}
+export function addUsage(into, more) {
+    into.inputTokens += more.inputTokens ?? 0;
+    into.outputTokens += more.outputTokens ?? 0;
+    into.cacheReadTokens += more.cacheReadTokens ?? 0;
+    into.cacheWriteTokens += more.cacheWriteTokens ?? 0;
+    into.citationTokens += more.citationTokens ?? 0;
+    into.reasoningTokens += more.reasoningTokens ?? 0;
+    return into;
+}
+/**
+ * Overwrites each field the provider reported, leaving the rest. Stream events
+ * restate running totals rather than sending increments.
+ */
+export function setUsage(into, more) {
+    for (const key of USAGE_KEYS) {
+        const value = more[key] ?? 0;
+        if (value > 0)
+            into[key] = value;
+    }
+    return into;
+}
+export function reply(parts) {
+    return {
+        output: parts.output,
+        model: parts.model,
+        status: parts.status ?? "completed",
+        error: parts.error,
+        inputTokens: parts.usage.inputTokens,
+        outputTokens: parts.usage.outputTokens,
+        cacheReadTokens: parts.usage.cacheReadTokens,
+        cacheWriteTokens: parts.usage.cacheWriteTokens,
+        citationTokens: parts.usage.citationTokens,
+        reasoningTokens: parts.usage.reasoningTokens,
+        usage: parts.usage,
+        toolCalls: parts.toolCalls ?? [],
+        ...(parts.citations?.length ? { citations: parts.citations } : {}),
+        stopReason: parts.stopReason,
+    };
+}
+/** Tool arguments, which providers send as a JSON string. Malformed reads `{}`. */
+export function parseArgs(raw) {
+    if (raw && typeof raw === "object")
+        return raw;
+    if (typeof raw !== "string" || !raw.trim())
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@spendgraph/llms",
+  "version": "0.2.0",
+  "description": "Read any LLM provider reply into one shape. Records usage through @spendgraph/sdk.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fnLog0/spendgraph.git",
+    "directory": "packages/llms"
+  },
+  "keywords": [
+    "llm",
+    "anthropic",
+    "openai",
+    "openrouter",
+    "bedrock",
+    "gemini",
+    "streaming",
+    "tokens"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && vitest run",
+    "test:live": "npm run build && vitest run src/tests/live"
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@spendgraph/sdk": "^0.2.0"
+  }
+}