@spendgraph/llms 0.2.0 → 0.3.0

package/README.md

@@ -352,3 +352,7 @@ what it checks is the part fakes cannot:
 | streaming | deltas arrive and usage still lands |
 | gemini `maxTokens` | lands as `generationConfig.maxOutputTokens`, where it is actually read |
 | history | an assistant turn survives as `model` on Gemini, rather than being replayed as the caller |
+
+## License
+
+MIT

package/dist/adapters/index.js

@@ -12,12 +12,7 @@ const BY_SHAPE = {
     gemini,
     perplexity,
 };
-/** Sniffed in this order, with OpenAI last because its shape is the loosest. */
 const ORDERED = [anthropic, bedrock, responses, gemini, perplexity, openai];
-/**
- * Which wire shape a provider speaks. Everything absent is OpenAI-compatible,
- * which is what most gateways and self-hosted servers expose.
- */
 const SHAPE_OF = {
     anthropic: "anthropic",
     bedrock: "bedrock",

package/dist/affordable.js

@@ -1,14 +1,5 @@
-/** Every field a provider carries the output ceiling in. */
 const CEILINGS = ["max_tokens", "max_completion_tokens", "maxOutputTokens"];
 const AFFORDS = /can only afford\s+(\d[\d,]*)/i;
-/**
- * What a provider says it can afford, read off a refusal.
- *
- * `402` alone is not enough to act on — it is also what an empty account
- * returns, and shrinking a ceiling will not fix that. The number is the signal:
- * a provider that names one is telling you the request would have been accepted
- * smaller.
- */
 export function affordableCeiling(err) {
     const status = err?.status;
     const message = err instanceof Error ? err.message : String(err ?? "");
@@ -33,26 +24,6 @@ function shrink(body, to) {
     }
     return undefined;
 }
-/**
- * A provider client that lowers its ceiling rather than failing over it.
- *
- * `max_tokens` is a request for headroom, not a bill — output is charged on what
- * is written. A provider that reserves the ceiling against a prepaid balance
- * refuses the whole call over headroom that was never going to be used:
- *
- * ```
- * 402 You requested up to 4096 tokens, but can only afford 4000.
- * ```
- *
- * This retries that once at the number the provider named. It is a decorator
- * rather than something inside `Llm` because how a client copes with a
- * provider's billing is the client's business, and because it then works for
- * every shape — the wrapper mirrors whatever it is given, so `driverFor` still
- * recognises an Anthropic, OpenAI or Gemini client through it.
- *
- * A `402` that names no number is passed through untouched. That one is an
- * empty account, and no ceiling will fix it.
- */
 export function affordable(client, opts = {}) {
     const floor = opts.floor ?? 0;
     const retries = opts.retries ?? 1;

package/dist/llm/invoke.js

@@ -13,7 +13,6 @@ function walk(client, keys) {
 export function has(client, path) {
     return typeof walk(client, path)?.fn === "function";
 }
-/** Calls `client.a.b.c(body)` with `client.a.b` as the receiver. */
 export async function invoke(client, path, body) {
     const found = walk(client, path);
     if (typeof found?.fn !== "function") {

package/dist/llm/llm.js

@@ -12,13 +12,6 @@ export class UnsupportedClientError extends Error {
     }
 }
 const DEFAULT_MAX_STEPS = 8;
-/**
- * Worth trying another model for.
- *
- * Overload, rate limit and server fault are about the provider's day. A 400 or
- * a 401 is about the request, and is the same answer everywhere — retrying it
- * across three models spends three round trips to be told so three times.
- */
 function worthAnotherModel(err) {
     const status = err?.status;
     if (typeof status !== "number")
@@ -35,16 +28,11 @@ function warnOnEmptyUsage(reply) {
     console.warn("[llms] recorded a call with no tokens, which prices as nothing. The provider " +
         "reported no usage — on a stream, ask for it (OpenAI needs stream_options.include_usage).");
 }
-/** A bare schema is shorthand for `{ schema }`. */
 function asStructured(schema) {
     if (!schema)
         return undefined;
     return "schema" in schema ? schema : { schema };
 }
-/**
- * A provider client and its defaults. Calls the model, normalises the reply,
- * and records what it consumed.
- */
 export class Llm {
     opts;
     driver;
@@ -63,7 +51,6 @@ export class Llm {
     get model() {
         return this.opts.model;
     }
-    /** The same client with different defaults — another model, tools, no tracing. */
     with(overrides) {
         return new Llm({
             ...this.opts,
@@ -72,19 +59,11 @@ export class Llm {
             metadata: { ...this.opts.metadata, ...overrides.metadata },
         });
     }
-    /** Calls the model, looping over tools when a bus is attached. */
     async call(messages, opts = {}) {
         const settings = this.settings(opts);
         const reply = await this.attempt(messages, settings);
         return this.record(this.withData(reply, settings), settings, opts);
     }
-    /**
-     * The call, then each fallback model in turn.
-     *
-     * The last error is thrown rather than the first: a caller reading the stack
-     * wants to know how it finished, and the first failure is the one that is
-     * already in the `onFallback` log.
-     */
     async attempt(messages, settings) {
         const models = [settings.model, ...(this.opts.fallbacks ?? [])];
         let last;
@@ -105,7 +84,6 @@ export class Llm {
         }
         throw last;
     }
-    /** The same, streamed. `onText` receives each delta as it arrives. */
     async stream(messages, opts = {}) {
         const settings = this.settings(opts);
         if (settings.tools) {
@@ -204,17 +182,6 @@ export class Llm {
             params: settings.params ?? {},
         };
     }
-    /**
-     * Attaches the object a `schema` asked for.
-     *
-     * Anthropic answers a forced tool call, so the value is already parsed in the
-     * call's arguments; the JSON modes answer as text. A reply that satisfies
-     * neither throws rather than coming back with `data` quietly missing.
-     *
-     * A forced call leaves no text block, so `output` is filled from the object:
-     * it is what a recorded rollout stores as the reply, and blank there reads as
-     * a model that said nothing.
-     */
     withData(reply, settings) {
         if (!settings.schema || reply.status === "failed")
             return reply;

package/dist/llm/schema/schema.js

@@ -2,12 +2,6 @@ const DEFAULT_NAME = "reply";
 function named(output) {
     return output.name ?? DEFAULT_NAME;
 }
-/**
- * Anthropic has no JSON mode, so a forced tool call is the schema.
- *
- * `tool_choice` pins it, which is the difference between "you may" and "you
- * will" — asking politely in the prompt gets prose back often enough to matter.
- */
 export function anthropicStructured(output) {
     return {
         tools: [
@@ -20,7 +14,6 @@ export function anthropicStructured(output) {
         tool_choice: { type: "tool", name: named(output) },
     };
 }
-/** OpenAI takes a schema directly, and `strict` is what makes it a guarantee. */
 export function openaiStructured(output) {
     return {
         response_format: {
@@ -33,7 +26,6 @@ export function openaiStructured(output) {
         },
     };
 }
-/** Gemini needs the mime type as well; the schema alone still returns prose. */
 export function geminiStructured(output) {
     return {
         responseMimeType: "application/json",
@@ -48,14 +40,6 @@ export class StructuredOutputError extends Error {
         this.name = "StructuredOutputError";
     }
 }
-/**
- * The object the model was asked for.
- *
- * A tool-forced reply already arrives parsed; a JSON-mode reply arrives as text
- * and is parsed here. A reply that is neither throws rather than returning
- * undefined, because a caller that asked for a shape and silently got nothing
- * writes the empty case into their data.
- */
 export function readStructured(output, toolArgs) {
     if (toolArgs && Object.keys(toolArgs).length > 0)
         return toolArgs;
@@ -72,7 +56,6 @@ export function readStructured(output, toolArgs) {
                 return JSON.parse(fenced[1]);
             }
             catch {
-                // falls through to the throw below
             }
         }
         throw new StructuredOutputError("The model did not return JSON.", output);

package/dist/model.js

@@ -1,15 +1,4 @@
-/**
- * Providers whose `model_pricing` rows are keyed on the id the API reports.
- * `anthropic` and `openai` because litellm treats them as the unprefixed
- * defaults, `bedrock` because its ids are already namespaced by the lab that
- * made the model.
- */
 const KEYED_ON_REPORTED_ID = new Set(["anthropic", "openai", "bedrock"]);
-/**
- * The model id `model_pricing` is keyed on. An unmatched id records a call
- * costing zero, so this is the difference between a priced call and an
- * unpriced one.
- */
 export function pricingId(provider, reported) {
     const id = reported.trim();
     if (!id)

package/dist/read.js

@@ -5,11 +5,6 @@ export class UnknownReplyError extends Error {
         this.name = "UnknownReplyError";
     }
 }
-/**
- * Reads any supported provider reply into the shape `prompt.trace()` returns.
- * Without `provider` the shape is sniffed, which cannot tell OpenAI-compatible
- * gateways apart and so prices them as OpenAI.
- */
 export function read(value, opts = {}) {
     const adapter = opts.provider ? adapterFor(opts.provider) : detect(value);
     if (!adapter)

package/dist/report/ingest.js

@@ -1,5 +1,4 @@
 import { MAX_EVENTS, Spendgraph } from "@spendgraph/sdk";
-/** The route takes up to this many events per request. */
 export { MAX_EVENTS };
 export function newEventId() {
     return `ev_${crypto.randomUUID().replace(/-/g, "")}`;
@@ -10,12 +9,6 @@ export class MissingCredentialsError extends Error {
         this.name = "MissingCredentialsError";
     }
 }
-/**
- * Where usage goes.
- *
- * The HTTP call belongs to `@spendgraph/sdk`, which is the one package that
- * talks to the app — this one never opens a socket.
- */
 export function ingestFor(opts) {
     if (opts.via)
         return opts.via;

package/dist/request.js

@@ -9,7 +9,6 @@ function split(messages) {
     }
     return { system: preamble.length ? preamble.join("\n\n") : undefined, turns };
 }
-/** Anthropic and Bedrock Converse take the system prompt beside the messages. */
 export function anthropicMessages(messages) {
     const { system, turns } = split(messages);
     const turned = turns.map((m) => ({
@@ -21,7 +20,6 @@ export function anthropicMessages(messages) {
 export function openaiMessages(messages) {
     return { messages: [...messages] };
 }
-/** Gemini calls the assistant "model", which is the one role name it renames. */
 export function geminiMessages(messages) {
     const { system, turns } = split(messages);
     const contents = turns.map((m) => ({

package/dist/stream.js

@@ -52,7 +52,6 @@ class LlmStream {
         }
         this.done = true;
     }
-    /** Drains any events not yet read, then assembles the reply. */
     async reply() {
         if (!this.done) {
             for await (const _ of this)
@@ -61,11 +60,9 @@ class LlmStream {
         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/usage.js

@@ -16,7 +16,6 @@ export function emptyUsage() {
         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;
@@ -30,10 +29,6 @@ export function addUsage(into, more) {
     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;
@@ -60,7 +55,6 @@ export function reply(parts) {
         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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spendgraph/llms",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Read any LLM provider reply into one shape. Records usage through @spendgraph/sdk.",
   "license": "MIT",
   "repository": {
@@ -33,7 +33,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments",
     "test": "npm run build && vitest run",
     "test:live": "npm run build && vitest run src/tests/live"
   },
@@ -47,6 +47,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@spendgraph/sdk": "^0.2.0"
+    "@spendgraph/sdk": "^0.3.0"
   }
 }