@agtlantis/core 0.5.0 → 0.5.1

package/dist/patterns/progressive/progressive-pattern.js

@@ -0,0 +1,260 @@
+import { hasToolCall, tool } from 'ai';
+import { z } from 'zod';
+const TOOL_DESCRIPTIONS = {
+    reportProgress: '[OPTIONAL] Report progress during task execution. Use this to show intermediate work. You may call this multiple times, then you MUST call tools::submitResult.',
+    submitResult: '[REQUIRED] Submit the final result. You MUST call this exactly once to complete the task. Without this call, the task FAILS.',
+};
+export const TOOL_CALLING_PROTOCOL = `## CRITICAL INSTRUCTION - READ CAREFULLY
+
+You have 2 tools available:
+1. reportProgress - [OPTIONAL] Show intermediate work (multiple times)
+2. submitResult - [REQUIRED] Submit your final answer
+
+⚠️ IMPORTANT RULES:
+- You may call reportProgress 0-3 times to show progress
+- You MUST call submitResult exactly once to complete the task
+- After calling reportProgress, you MUST call submitResult in your NEXT response
+- If you call reportProgress more than 3 times without submitResult, the task FAILS
+- The task is NOT complete until submitResult is called
+
+CORRECT SEQUENCE:
+1. [Optional] reportProgress
+2. [Required] submitResult (exactly once)
+
+❌ WRONG: reportProgress → reportProgress → reportProgress → reportProgress (no submitResult = FAIL)
+✅ CORRECT: reportProgress → submitResult (SUCCESS)`;
+/**
+ * Creates a progressive pattern for streaming LLM responses with intermediate progress updates.
+ *
+ * The pattern automatically:
+ * - Injects `reportProgress` and `submitResult` tools
+ * - Stops when `submitResult` is called (via `hasToolCall('submitResult')`)
+ * - Appends protocol instructions to the system prompt
+ *
+ * @example Basic usage
+ * ```typescript
+ * const pattern = defineProgressivePattern({
+ *   progressSchema: z.object({ stage: z.string(), message: z.string() }),
+ *   resultSchema: z.object({ summary: z.string(), score: z.number() }),
+ * });
+ *
+ * for await (const event of pattern.run(provider, {
+ *   system: 'You are an analyzer.',
+ *   prompt: 'Analyze this...',
+ * })) {
+ *   console.log(event.type, event.data);
+ * }
+ * ```
+ *
+ * @example With custom stopWhen (add step limit)
+ * ```typescript
+ * import { stepCountIs } from 'ai';
+ *
+ * for await (const event of pattern.run(provider, {
+ *   prompt: 'Analyze...',
+ *   stopWhen: stepCountIs(10), // Stop at submitResult OR after 10 steps
+ * })) { ... }
+ * ```
+ *
+ * @example With custom protocol
+ * ```typescript
+ * for await (const event of pattern.run(provider, {
+ *   prompt: 'Analyze...',
+ *   protocol: 'Call reportProgress for each step, then submitResult.',
+ * })) { ... }
+ * ```
+ *
+ * @example Composable (within a session)
+ * ```typescript
+ * provider.streamingExecution(async function*(session) {
+ *   yield* pattern.runInSession(session, {
+ *     system: 'You are an analyzer.',
+ *     messages: [...],
+ *   });
+ * });
+ * ```
+ */
+export function defineProgressivePattern(config) {
+    return new ProgressivePattern(config.progressSchema, config.resultSchema);
+}
+export class ProgressivePattern {
+    progressSchema;
+    resultSchema;
+    constructor(progressSchema, resultSchema) {
+        this.progressSchema = progressSchema;
+        this.resultSchema = resultSchema;
+    }
+    lastParseError = null;
+    /**
+     * Runs the pattern within an existing session. Use this for composing
+     * multiple patterns or when you need fine-grained control over the session.
+     *
+     * @param session - The streaming session to run within
+     * @param options - Stream options including:
+     *   - `stopWhen` - Additional stop conditions (combined with default `hasToolCall('submitResult')`)
+     *   - `protocol` - Custom protocol instructions (replaces default `TOOL_CALLING_PROTOCOL`)
+     *   - All other `streamText` options except `tools`, `toolChoice`, `stopWhen`
+     *
+     * @example Basic usage
+     * ```typescript
+     * provider.streamingExecution(async function*(session) {
+     *   yield* pattern.runInSession(session, {
+     *     system: 'You are an analyzer.',
+     *     messages: [{ role: 'user', content: 'Analyze...' }],
+     *   });
+     * });
+     * ```
+     *
+     * @example With custom stopWhen
+     * ```typescript
+     * yield* pattern.runInSession(session, {
+     *   prompt: 'Analyze...',
+     *   stopWhen: stepCountIs(5), // Combined: submitResult OR 5 steps
+     * });
+     * ```
+     */
+    async *runInSession(session, options) {
+        const { tools: userTools, system, stopWhen: userStopWhen, protocol, ...restOptions } = options;
+        const internalTools = this.createTools();
+        const allTools = { ...userTools, ...internalTools };
+        const systemString = typeof system === 'string' ? system : undefined;
+        const fullSystem = this.renderSystemPrompt(systemString, protocol);
+        const defaultStopCondition = hasToolCall('submitResult');
+        const stopConditions = this.combineStopConditions(defaultStopCondition, userStopWhen);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const stream = session.streamText({
+            ...restOptions,
+            system: fullSystem,
+            tools: allTools,
+            toolChoice: 'required',
+            stopWhen: stopConditions,
+        });
+        let result = null;
+        for await (const part of stream.fullStream) {
+            if (part.type === 'tool-call') {
+                if (part.toolName === 'reportProgress') {
+                    const input = 'input' in part ? part.input : undefined;
+                    const progressData = this.parseProgressInput(input);
+                    if (progressData !== null) {
+                        // Cast required: TypeScript can't know that TEvent includes a 'progress' variant
+                        yield session.emit({
+                            type: 'progress',
+                            data: progressData,
+                        });
+                    }
+                }
+                else if (part.toolName === 'submitResult') {
+                    const input = 'input' in part ? part.input : undefined;
+                    result = this.parseResultInput(input);
+                }
+            }
+        }
+        if (result === null) {
+            const baseMsg = 'ProgressivePattern: No result received.';
+            const detail = this.lastParseError
+                ? ` Last parse error: ${this.lastParseError.message}`
+                : ' The LLM did not call submitResult tool.';
+            throw new Error(baseMsg + detail);
+        }
+        const completeEvent = await session.done(result);
+        yield completeEvent;
+        return completeEvent;
+    }
+    /**
+     * Standalone execution that creates a new session internally.
+     * Use this for simple, single-pattern executions.
+     *
+     * @param provider - The AI provider to use
+     * @param options - Stream options including:
+     *   - `stopWhen` - Additional stop conditions (combined with default `hasToolCall('submitResult')`)
+     *   - `protocol` - Custom protocol instructions (replaces default `TOOL_CALLING_PROTOCOL`)
+     *
+     * @example Basic usage
+     * ```typescript
+     * for await (const event of pattern.run(provider, {
+     *   system: 'You are an analyzer.',
+     *   prompt: 'Analyze this document...',
+     * })) {
+     *   if (event.type === 'progress') {
+     *     console.log('Progress:', event.data);
+     *   } else if (event.type === 'complete') {
+     *     console.log('Result:', event.data);
+     *   }
+     * }
+     * ```
+     *
+     * @example With step limit
+     * ```typescript
+     * import { stepCountIs } from 'ai';
+     *
+     * for await (const event of pattern.run(provider, {
+     *   prompt: 'Analyze...',
+     *   stopWhen: stepCountIs(10),
+     * })) { ... }
+     * ```
+     */
+    run(provider, options) {
+        const self = this;
+        const execution = provider.streamingExecution(async function* (session) {
+            return yield* self.runInSession(session, options);
+        });
+        return execution.stream();
+    }
+    createTools() {
+        return {
+            reportProgress: tool({
+                description: TOOL_DESCRIPTIONS.reportProgress,
+                inputSchema: z.object({
+                    data: this.progressSchema,
+                }),
+                execute: async () => ({
+                    status: 'progress_recorded',
+                    instruction: 'After all progress reports, you MUST call tools::submitResult to complete the task.',
+                }),
+            }),
+            submitResult: tool({
+                description: TOOL_DESCRIPTIONS.submitResult,
+                inputSchema: z.object({
+                    data: this.resultSchema,
+                }),
+                execute: async () => ({
+                    status: 'result_submitted',
+                    message: 'Task completed successfully.',
+                }),
+            }),
+        };
+    }
+    parseJsonWrapper(input, schema) {
+        try {
+            if (!input || typeof input !== 'object')
+                return null;
+            const wrapper = input;
+            if (wrapper.data === undefined)
+                return null;
+            const parsed = typeof wrapper.data === 'string' ? JSON.parse(wrapper.data) : wrapper.data;
+            return schema.parse(parsed);
+        }
+        catch (error) {
+            this.lastParseError = error instanceof Error ? error : new Error(String(error));
+            return null;
+        }
+    }
+    parseProgressInput(input) {
+        return this.parseJsonWrapper(input, this.progressSchema);
+    }
+    parseResultInput(input) {
+        return this.parseJsonWrapper(input, this.resultSchema);
+    }
+    combineStopConditions(defaultCondition, userConditions) {
+        if (!userConditions) {
+            return [defaultCondition];
+        }
+        const userArray = Array.isArray(userConditions) ? userConditions : [userConditions];
+        return [defaultCondition, ...userArray];
+    }
+    renderSystemPrompt(userSystem, protocol) {
+        const protocolText = protocol ?? TOOL_CALLING_PROTOCOL;
+        return userSystem ? `${userSystem}\n\n${protocolText}` : protocolText;
+    }
+}
+//# sourceMappingURL=progressive-pattern.js.map

package/dist/patterns/progressive/progressive-pattern.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progressive-pattern.js","sourceRoot":"","sources":["../../../src/patterns/progressive/progressive-pattern.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,WAAW,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AACzE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgDxB,MAAM,iBAAiB,GAAG;IACtB,cAAc,EACV,iKAAiK;IACrK,YAAY,EACR,8HAA8H;CAC5H,CAAC;AAEX,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;mDAkBc,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,UAAU,wBAAwB,CAGtC,MAAwE,EAAE;IACxE,OAAO,IAAI,kBAAkB,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;AAAA,CAC7E;AAED,MAAM,OAAO,kBAAkB;IAQd,cAAc;IACd,YAAY;IAFzB,YACa,cAA+B,EAC/B,YAA2B,EACtC;8BAFW,cAAc;4BACd,YAAY;IACtB,CAAC;IAEI,cAAc,GAAiB,IAAI,CAAC;IAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,KAAK,CAAC,CAAC,YAAY,CACf,OAAiC,EACjC,OAA6C,EACwB;QACrE,MAAM,EACF,KAAK,EAAE,SAAS,EAChB,MAAM,EACN,QAAQ,EAAE,YAAY,EACtB,QAAQ,EACR,GAAG,WAAW,EACjB,GAAG,OAAO,CAAC;QAEZ,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QACzC,MAAM,QAAQ,GAAG,EAAE,GAAG,SAAS,EAAE,GAAG,aAAa,EAAa,CAAC;QAC/D,MAAM,YAAY,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;QACrE,MAAM,UAAU,GAAG,IAAI,CAAC,kBAAkB,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;QAEnE,MAAM,oBAAoB,GAAG,WAAW,CAAC,cAAc,CAAC,CAAC;QACzD,MAAM,cAAc,GAAG,IAAI,CAAC,qBAAqB,CAAC,oBAAoB,EAAE,YAAY,CAAC,CAAC;QAEtF,8DAA8D;QAC9D,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;YAC9B,GAAG,WAAW;YACd,MAAM,EAAE,UAAU;YAClB,KAAK,EAAE,QAAe;YACtB,UAAU,EAAE,UAAU;YACtB,QAAQ,EAAE,cAAqB;SAClC,CAAC,CAAC;QAEH,IAAI,MAAM,GAAmB,IAAI,CAAC;QAElC,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YACzC,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;gBAC5B,IAAI,IAAI,CAAC,QAAQ,KAAK,gBAAgB,EAAE,CAAC;oBACrC,MAAM,KAAK,GAAG,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;oBACvD,MAAM,YAAY,GAAG,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC;oBACpD,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;wBACxB,iFAAiF;wBACjF,MAAM,OAAO,CAAC,IAAI,CAAC;4BACf,IAAI,EAAE,UAAU;4BAChB,IAAI,EAAE,YAAY;yBACqB,CAAC,CAAC;oBACjD,CAAC;gBACL,CAAC;qBAAM,IAAI,IAAI,CAAC,QAAQ,KAAK,cAAc,EAAE,CAAC;oBAC1C,MAAM,KAAK,GAAG,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;oBACvD,MAAM,GAAG,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;gBAC1C,CAAC;YACL,CAAC;QACL,CAAC;QAED,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YAClB,MAAM,OAAO,GAAG,yCAAyC,CAAC;YAC1D,MAAM,MAAM,GAAG,IAAI,CAAC,cAAc;gBAC9B,CAAC,CAAC,sBAAsB,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE;gBACrD,CAAC,CAAC,0CAA0C,CAAC;YACjD,MAAM,IAAI,KAAK,CAAC,OAAO,GAAG,MAAM,CAAC,CAAC;QACtC,CAAC;QAED,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAA+B,CAAC,CAAC;QAC1E,MAAM,aAAa,CAAC;QACpB,OAAO,aAAa,CAAC;IAAA,CACxB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,GAAG,CACC,QAAsB,EACtB,OAA6C,EACG;QAChD,MAAM,IAAI,GAAG,IAAI,CAAC;QAClB,MAAM,SAAS,GAAG,QAAQ,CAAC,kBAAkB,CAAS,KAAK,SAAS,CAAC,EAAE,OAAO,EAAE;YAC5E,OAAO,KAAK,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAAA,CACrD,CAAC,CAAC;QACH,OAAO,SAAS,CAAC,MAAM,EAAE,CAAC;IAAA,CAC7B;IAEO,WAAW,GAAG;QAClB,OAAO;YACH,cAAc,EAAE,IAAI,CAAC;gBACjB,WAAW,EAAE,iBAAiB,CAAC,cAAc;gBAC7C,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;oBAClB,IAAI,EAAE,IAAI,CAAC,cAAc;iBAC5B,CAAC;gBACF,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;oBAClB,MAAM,EAAE,mBAAmB;oBAC3B,WAAW,EACP,qFAAqF;iBAC5F,CAAC;aACL,CAAC;YACF,YAAY,EAAE,IAAI,CAAC;gBACf,WAAW,EAAE,iBAAiB,CAAC,YAAY;gBAC3C,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;oBAClB,IAAI,EAAE,IAAI,CAAC,YAAY;iBAC1B,CAAC;gBACF,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;oBAClB,MAAM,EAAE,kBAAkB;oBAC1B,OAAO,EAAE,8BAA8B;iBAC1C,CAAC;aACL,CAAC;SACL,CAAC;IAAA,CACL;IAEO,gBAAgB,CAAI,KAAc,EAAE,MAAoB,EAAY;QACxE,IAAI,CAAC;YACD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YACrD,MAAM,OAAO,GAAG,KAA2B,CAAC;YAC5C,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS;gBAAE,OAAO,IAAI,CAAC;YAE5C,MAAM,MAAM,GACR,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;YAE/E,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,CAAM,CAAC;QACrC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,IAAI,CAAC,cAAc,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAChF,OAAO,IAAI,CAAC;QAChB,CAAC;IAAA,CACJ;IAEO,kBAAkB,CAAC,KAAc,EAAoB;QACzD,OAAO,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,CAAqB,CAAC;IAAA,CAChF;IAEO,gBAAgB,CAAC,KAAc,EAAkB;QACrD,OAAO,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,CAAmB,CAAC;IAAA,CAC5E;IAEO,qBAAqB,CACzB,gBAAwC,EACxC,cAAkE,EAC1C;QACxB,IAAI,CAAC,cAAc,EAAE,CAAC;YAClB,OAAO,CAAC,gBAAgB,CAAC,CAAC;QAC9B,CAAC;QACD,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC;QACpF,OAAO,CAAC,gBAAgB,EAAE,GAAG,SAAS,CAAC,CAAC;IAAA,CAC3C;IAEO,kBAAkB,CAAC,UAAmB,EAAE,QAAiB,EAAU;QACvE,MAAM,YAAY,GAAG,QAAQ,IAAI,qBAAqB,CAAC;QACvD,OAAO,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,OAAO,YAAY,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC;IAAA,CACzE;CACJ"}

package/dist/pricing/calculator.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Cost calculation functions.
+ *
+ * @module pricing/calculator
+ *
+ * NOTE: Cost calculations use standard JavaScript floating-point arithmetic.
+ * For high-volume usage tracking, accumulated totals may have minor precision drift.
+ * For financial reporting, consider rounding results to appropriate decimal places
+ * (e.g., `Math.round(cost * 100) / 100` for cents).
+ */
+import type { LanguageModelUsage } from 'ai';
+import type { CalculateCostParams, CostResult, ModelPricing, ProviderPricing, ProviderType } from './types.js';
+/**
+ * Get pricing for a specific model.
+ *
+ * Resolution order:
+ * 1. Provider-level config (providerPricing param)
+ * 2. Global config (configurePricing)
+ * 3. Built-in defaults
+ * 4. Fallback pricing
+ */
+export declare function getModelPricing(model: string, provider: ProviderType, providerPricing?: ProviderPricing): ModelPricing;
+/**
+ * Calculate cost from token counts.
+ *
+ * @throws Error if token counts are negative, non-finite, or if cachedInputTokens > inputTokens
+ *
+ * @example
+ * ```typescript
+ * const cost = calculateCost({
+ *   inputTokens: 1000,
+ *   outputTokens: 500,
+ *   cachedInputTokens: 200,
+ *   model: 'gemini-2.5-flash',
+ *   provider: 'google',
+ * });
+ * console.log(cost.total); // 0.000315
+ * ```
+ */
+export declare function calculateCost(params: CalculateCostParams, providerPricing?: ProviderPricing): CostResult;
+/**
+ * Calculate cost from AI SDK LanguageModelUsage.
+ *
+ * Convenience function that extracts token counts from the
+ * AI SDK's LanguageModelUsage type and calculates the cost.
+ *
+ * @example
+ * ```typescript
+ * const usage = await result.usage;
+ * const cost = calculateCostFromUsage(usage, 'gemini-2.5-flash', 'google');
+ * ```
+ */
+export declare function calculateCostFromUsage(usage: LanguageModelUsage, model: string, provider: ProviderType, providerPricing?: ProviderPricing): CostResult;
+/**
+ * Calculate total cost for multiple LLM calls.
+ *
+ * Aggregates costs from multiple calls, grouping by model.
+ *
+ * @returns Object with:
+ *   - `totalCost`: Sum of all call costs in USD
+ *   - `costByModel`: Map where key format is `${provider}/${model}`
+ */
+export declare function calculateTotalCost(calls: Array<{
+    usage: LanguageModelUsage;
+    model: string;
+    provider: ProviderType;
+}>, providerPricing?: ProviderPricing): {
+    totalCost: number;
+    costByModel: Record<string, number>;
+};
+//# sourceMappingURL=calculator.d.ts.map

package/dist/pricing/calculator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calculator.d.ts","sourceRoot":"","sources":["../../src/pricing/calculator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,IAAI,CAAC;AAC7C,OAAO,KAAK,EACV,mBAAmB,EACnB,UAAU,EACV,YAAY,EACZ,eAAe,EACf,YAAY,EACb,MAAM,YAAY,CAAC;AAMpB;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,YAAY,EACtB,eAAe,CAAC,EAAE,eAAe,GAChC,YAAY,CAoBd;AAsBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,mBAAmB,EAC3B,eAAe,CAAC,EAAE,eAAe,GAChC,UAAU,CA8BZ;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,kBAAkB,EACzB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,YAAY,EACtB,eAAe,CAAC,EAAE,eAAe,GAChC,UAAU,CAWZ;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,KAAK,CAAC;IACX,KAAK,EAAE,kBAAkB,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,YAAY,CAAC;CACxB,CAAC,EACF,eAAe,CAAC,EAAE,eAAe,GAChC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAkB5D"}

package/dist/pricing/calculator.js

@@ -0,0 +1,127 @@
+/**
+ * Cost calculation functions.
+ *
+ * @module pricing/calculator
+ *
+ * NOTE: Cost calculations use standard JavaScript floating-point arithmetic.
+ * For high-volume usage tracking, accumulated totals may have minor precision drift.
+ * For financial reporting, consider rounding results to appropriate decimal places
+ * (e.g., `Math.round(cost * 100) / 100` for cents).
+ */
+import { DEFAULT_PRICING_CONFIG, DEFAULT_FALLBACK_PRICING } from './defaults.js';
+import { getPricingConfig } from './config.js';
+const TOKENS_PER_MILLION = 1_000_000;
+/**
+ * Get pricing for a specific model.
+ *
+ * Resolution order:
+ * 1. Provider-level config (providerPricing param)
+ * 2. Global config (configurePricing)
+ * 3. Built-in defaults
+ * 4. Fallback pricing
+ */
+export function getModelPricing(model, provider, providerPricing) {
+    if (providerPricing?.[model]) {
+        return providerPricing[model];
+    }
+    const globalConfig = getPricingConfig();
+    if (globalConfig?.providers?.[provider]?.[model]) {
+        return globalConfig.providers[provider][model];
+    }
+    const defaultProviderPricing = DEFAULT_PRICING_CONFIG.providers[provider];
+    if (defaultProviderPricing?.[model]) {
+        return defaultProviderPricing[model];
+    }
+    return (globalConfig?.fallback ??
+        DEFAULT_PRICING_CONFIG.fallback ??
+        DEFAULT_FALLBACK_PRICING);
+}
+function validateCostParams(params) {
+    const { inputTokens, outputTokens, cachedInputTokens = 0 } = params;
+    if (inputTokens < 0 || outputTokens < 0 || cachedInputTokens < 0) {
+        throw new Error('Token counts must be non-negative');
+    }
+    if (cachedInputTokens > inputTokens) {
+        throw new Error('cachedInputTokens cannot exceed inputTokens');
+    }
+    if (!Number.isFinite(inputTokens) ||
+        !Number.isFinite(outputTokens) ||
+        !Number.isFinite(cachedInputTokens)) {
+        throw new Error('Token counts must be finite numbers');
+    }
+}
+/**
+ * Calculate cost from token counts.
+ *
+ * @throws Error if token counts are negative, non-finite, or if cachedInputTokens > inputTokens
+ *
+ * @example
+ * ```typescript
+ * const cost = calculateCost({
+ *   inputTokens: 1000,
+ *   outputTokens: 500,
+ *   cachedInputTokens: 200,
+ *   model: 'gemini-2.5-flash',
+ *   provider: 'google',
+ * });
+ * console.log(cost.total); // 0.000315
+ * ```
+ */
+export function calculateCost(params, providerPricing) {
+    validateCostParams(params);
+    const { inputTokens, outputTokens, cachedInputTokens = 0, model, provider, } = params;
+    const pricing = getModelPricing(model, provider, providerPricing);
+    const nonCachedInputTokens = inputTokens - cachedInputTokens;
+    const inputCost = (nonCachedInputTokens / TOKENS_PER_MILLION) * pricing.inputPricePerMillion;
+    const outputCost = (outputTokens / TOKENS_PER_MILLION) * pricing.outputPricePerMillion;
+    const cachedInputPricePerMillion = pricing.cachedInputPricePerMillion ?? pricing.inputPricePerMillion;
+    const cachedInputCost = (cachedInputTokens / TOKENS_PER_MILLION) * cachedInputPricePerMillion;
+    return {
+        total: inputCost + outputCost + cachedInputCost,
+        inputCost,
+        outputCost,
+        cachedInputCost,
+    };
+}
+/**
+ * Calculate cost from AI SDK LanguageModelUsage.
+ *
+ * Convenience function that extracts token counts from the
+ * AI SDK's LanguageModelUsage type and calculates the cost.
+ *
+ * @example
+ * ```typescript
+ * const usage = await result.usage;
+ * const cost = calculateCostFromUsage(usage, 'gemini-2.5-flash', 'google');
+ * ```
+ */
+export function calculateCostFromUsage(usage, model, provider, providerPricing) {
+    return calculateCost({
+        inputTokens: usage.inputTokens ?? 0,
+        outputTokens: usage.outputTokens ?? 0,
+        cachedInputTokens: usage.inputTokenDetails?.cacheReadTokens ?? 0,
+        model,
+        provider,
+    }, providerPricing);
+}
+/**
+ * Calculate total cost for multiple LLM calls.
+ *
+ * Aggregates costs from multiple calls, grouping by model.
+ *
+ * @returns Object with:
+ *   - `totalCost`: Sum of all call costs in USD
+ *   - `costByModel`: Map where key format is `${provider}/${model}`
+ */
+export function calculateTotalCost(calls, providerPricing) {
+    const costByModel = {};
+    let totalCost = 0;
+    for (const call of calls) {
+        const cost = calculateCostFromUsage(call.usage, call.model, call.provider, providerPricing);
+        totalCost += cost.total;
+        const key = `${call.provider}/${call.model}`;
+        costByModel[key] = (costByModel[key] ?? 0) + cost.total;
+    }
+    return { totalCost, costByModel };
+}
+//# sourceMappingURL=calculator.js.map

package/dist/pricing/calculator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calculator.js","sourceRoot":"","sources":["../../src/pricing/calculator.ts"],"names":[],"mappings":"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"}

package/dist/pricing/config.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Global pricing configuration.
+ *
+ * Priority order (highest to lowest):
+ * 1. Provider.withPricing() - per-provider override
+ * 2. configurePricing() - global override
+ * 3. Built-in defaults (defaults.ts)
+ * 4. Fallback pricing
+ *
+ * @module pricing/config
+ */
+import type { ModelPricing, PricingConfig, ProviderType } from './types.js';
+/**
+ * Configure global pricing overrides.
+ *
+ * WARNING: This uses global mutable state and is not thread-safe.
+ * For multi-tenant scenarios or concurrent requests with different pricing,
+ * use `Provider.withPricing()` instead for proper isolation.
+ *
+ * @example
+ * ```typescript
+ * configurePricing({
+ *   providers: {
+ *     google: {
+ *       'gemini-2.5-flash': { inputPricePerMillion: 0.5, outputPricePerMillion: 3.0 },
+ *     },
+ *   },
+ * });
+ *
+ * // Reset to built-in defaults
+ * configurePricing(undefined);
+ * ```
+ */
+export declare function configurePricing(config: PricingConfig | undefined): void;
+export declare function getPricingConfig(): PricingConfig | undefined;
+/**
+ * Reset global pricing configuration.
+ * Useful for testing to ensure clean state between tests.
+ */
+export declare function resetPricingConfig(): void;
+export type PricingSource = 'global' | 'default' | 'fallback';
+export interface EffectivePricingResult {
+    pricing: ModelPricing;
+    source: PricingSource;
+}
+/**
+ * Get effective pricing for a model with source information.
+ * Useful for debugging to understand which pricing layer is applied.
+ *
+ * @example
+ * ```typescript
+ * const result = getEffectivePricing('gemini-2.5-flash', 'google');
+ * console.log(result.source); // 'default' (using built-in pricing)
+ *
+ * configurePricing({ providers: { google: { 'gemini-2.5-flash': {...} } } });
+ * const result2 = getEffectivePricing('gemini-2.5-flash', 'google');
+ * console.log(result2.source); // 'global' (using configured override)
+ * ```
+ */
+export declare function getEffectivePricing(model: string, provider: ProviderType): EffectivePricingResult;
+//# sourceMappingURL=config.d.ts.map

package/dist/pricing/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/pricing/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAM5E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI,CAKxE;AAED,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAE5D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AAE9D,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,YAAY,GACrB,sBAAsB,CAuBxB"}

package/dist/pricing/config.js

@@ -0,0 +1,87 @@
+/**
+ * Global pricing configuration.
+ *
+ * Priority order (highest to lowest):
+ * 1. Provider.withPricing() - per-provider override
+ * 2. configurePricing() - global override
+ * 3. Built-in defaults (defaults.ts)
+ * 4. Fallback pricing
+ *
+ * @module pricing/config
+ */
+import { validatePricingConfig } from './validator.js';
+import { DEFAULT_PRICING_CONFIG, DEFAULT_FALLBACK_PRICING } from './defaults.js';
+let globalConfig;
+/**
+ * Configure global pricing overrides.
+ *
+ * WARNING: This uses global mutable state and is not thread-safe.
+ * For multi-tenant scenarios or concurrent requests with different pricing,
+ * use `Provider.withPricing()` instead for proper isolation.
+ *
+ * @example
+ * ```typescript
+ * configurePricing({
+ *   providers: {
+ *     google: {
+ *       'gemini-2.5-flash': { inputPricePerMillion: 0.5, outputPricePerMillion: 3.0 },
+ *     },
+ *   },
+ * });
+ *
+ * // Reset to built-in defaults
+ * configurePricing(undefined);
+ * ```
+ */
+export function configurePricing(config) {
+    if (config) {
+        validatePricingConfig(config);
+    }
+    globalConfig = config;
+}
+export function getPricingConfig() {
+    return globalConfig;
+}
+/**
+ * Reset global pricing configuration.
+ * Useful for testing to ensure clean state between tests.
+ */
+export function resetPricingConfig() {
+    globalConfig = undefined;
+}
+/**
+ * Get effective pricing for a model with source information.
+ * Useful for debugging to understand which pricing layer is applied.
+ *
+ * @example
+ * ```typescript
+ * const result = getEffectivePricing('gemini-2.5-flash', 'google');
+ * console.log(result.source); // 'default' (using built-in pricing)
+ *
+ * configurePricing({ providers: { google: { 'gemini-2.5-flash': {...} } } });
+ * const result2 = getEffectivePricing('gemini-2.5-flash', 'google');
+ * console.log(result2.source); // 'global' (using configured override)
+ * ```
+ */
+export function getEffectivePricing(model, provider) {
+    if (globalConfig?.providers?.[provider]?.[model]) {
+        return {
+            pricing: globalConfig.providers[provider][model],
+            source: 'global',
+        };
+    }
+    const defaultPricing = DEFAULT_PRICING_CONFIG.providers[provider];
+    if (defaultPricing?.[model]) {
+        return {
+            pricing: defaultPricing[model],
+            source: 'default',
+        };
+    }
+    return {
+        pricing: globalConfig?.fallback ??
+            DEFAULT_PRICING_CONFIG.fallback ??
+            DEFAULT_FALLBACK_PRICING,
+        source: 'fallback',
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/pricing/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/pricing/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAEjF,IAAI,YAAuC,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAiC,EAAQ;IACxE,IAAI,MAAM,EAAE,CAAC;QACX,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IACD,YAAY,GAAG,MAAM,CAAC;AAAA,CACvB;AAED,MAAM,UAAU,gBAAgB,GAA8B;IAC5D,OAAO,YAAY,CAAC;AAAA,CACrB;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,GAAS;IACzC,YAAY,GAAG,SAAS,CAAC;AAAA,CAC1B;AASD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAa,EACb,QAAsB,EACE;IACxB,IAAI,YAAY,EAAE,SAAS,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,OAAO;YACL,OAAO,EAAE,YAAY,CAAC,SAAS,CAAC,QAAQ,CAAE,CAAC,KAAK,CAAC;YACjD,MAAM,EAAE,QAAQ;SACjB,CAAC;IACJ,CAAC;IAED,MAAM,cAAc,GAAG,sBAAsB,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAClE,IAAI,cAAc,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO;YACL,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC;YAC9B,MAAM,EAAE,SAAS;SAClB,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO,EACL,YAAY,EAAE,QAAQ;YACtB,sBAAsB,CAAC,QAAQ;YAC/B,wBAAwB;QAC1B,MAAM,EAAE,UAAU;KACnB,CAAC;AAAA,CACH"}

package/dist/pricing/defaults.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Built-in pricing tables (USD per million tokens).
+ *
+ * These are the default prices for common models. They can be overridden
+ * using `configurePricing()` (global) or `Provider.withPricing()` (per-provider).
+ *
+ * Last updated: January 2025
+ *
+ * @module pricing/defaults
+ */
+import type { ModelPricing, PricingConfig, ProviderPricing } from './types.js';
+/**
+ * OpenAI model pricing.
+ * @see https://openai.com/pricing
+ */
+export declare const OPENAI_PRICING: ProviderPricing;
+/**
+ * Google Gemini model pricing.
+ * @see https://ai.google.dev/gemini-api/docs/pricing
+ */
+export declare const GOOGLE_PRICING: ProviderPricing;
+/**
+ * Anthropic Claude model pricing.
+ * @see https://www.anthropic.com/pricing
+ */
+export declare const ANTHROPIC_PRICING: ProviderPricing;
+export declare const DEFAULT_PRICING_CONFIG: Required<PricingConfig>;
+export declare const DEFAULT_FALLBACK_PRICING: ModelPricing;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/pricing/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/pricing/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE/E;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,eAoB5B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,eA0C5B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,eAoC/B,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,aAAa,CAU1D,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,YAGtC,CAAC"}