@pydantic/genai-prices 0.0.6

package/README.md

@@ -0,0 +1,203 @@
+# genai-prices package (JS/TS)
+
+Library and CLI for calculating LLM API prices, supporting browser, Node.js and other environments.
+
+## Features
+
+- **Sync API**: Fast, local price calculation using embedded data. Works in browser, Node.js, Cloudflare, Deno, etc.
+- **Async API**: Fetches and caches price data from GitHub, works in browser, Node.js, Cloudflare, Deno, etc.
+- **Environment-agnostic design**: Sync/async distinction is about API style, not environment.
+- **Smart provider and model matching** with flexible options.
+- **CLI** for quick price calculations with auto-update support.
+- **Browser support** with a single bundle and test page.
+
+## API Usage
+
+### Node.js & Browser (Library)
+
+```js
+import { calcPriceSync, calcPriceAsync } from '@pydantic/genai-prices'
+
+const usage = { input_tokens: 1000, output_tokens: 100 }
+
+// Sync (works everywhere, including browser)
+const result = calcPriceSync(usage, 'gpt-3.5-turbo', { providerId: 'openai' })
+if (result) {
+  console.log(result.price, result.provider.name, result.model.name)
+} else {
+  console.log('No price found for this model/provider combination')
+}
+
+// Async (works everywhere)
+const asyncResult = await calcPriceAsync(usage, 'gpt-3.5-turbo', { providerId: 'openai' })
+if (asyncResult) {
+  console.log(asyncResult.price, asyncResult.provider.name, asyncResult.model.name)
+} else {
+  console.log('No price found for this model/provider combination')
+}
+```
+
+### Browser (Direct Bundle)
+
+```js
+import { calcPriceSync, calcPriceAsync } from './dist/index.js'
+const usage = { input_tokens: 1000, output_tokens: 100 }
+const result = calcPriceSync(usage, 'gpt-3.5-turbo', { providerId: 'openai' })
+if (result) {
+  console.log(result.price, result.provider.name, result.model.name)
+}
+```
+
+### Global CLI Installation
+
+You can install the CLI globally to use the `genai-prices` command from anywhere:
+
+```bash
+npm install -g @pydantic/genai-prices
+```
+
+After installing globally, you can run:
+
+```bash
+genai-prices calc gpt-4 --input-tokens 1000 --output-tokens 500
+genai-prices list
+```
+
+### CLI
+
+After global installation, you can use the CLI as follows:
+
+```bash
+# Basic usage
+genai-prices gpt-3.5-turbo --input-tokens 1000 --output-tokens 100
+
+# With auto-update (fetches latest prices from GitHub)
+genai-prices gpt-3.5-turbo --input-tokens 1000 --output-tokens 100 --auto-update
+
+# Specify provider explicitly
+genai-prices openai:gpt-3.5-turbo --input-tokens 1000 --output-tokens 100
+
+# List available providers and models
+genai-prices list
+genai-prices list openai
+```
+
+### Provider Matching
+
+The library uses intelligent provider matching:
+
+1. **Explicit provider**: Use `providerId` parameter or `provider:model` format
+2. **Model-based matching**: Uses provider's `model_match` logic (e.g., OpenAI matches models starting with "gpt-")
+3. **Fallback**: Tries to match based on model name patterns
+
+**Best practices:**
+
+- Always specify `providerId` if you know it (e.g., `openai`, `google`, etc.) for best results
+- Use `provider:model` format in CLI for explicit provider selection
+- The async API with `--auto-update` provides the most up-to-date pricing
+
+### Error Handling
+
+The library returns `null` when a model or provider is not found, rather than throwing errors. This makes it easier to handle cases where pricing information might not be available:
+
+```js
+import { calcPriceSync, calcPriceAsync } from '@pydantic/genai-prices'
+
+const usage = { input_tokens: 1000, output_tokens: 100 }
+
+// Returns null if model/provider not found
+const result = calcPriceSync(usage, 'non-existent-model')
+if (result === null) {
+  console.log('No pricing information available for this model')
+} else {
+  console.log(`Price: $${result.price}`)
+}
+
+// Async version also returns null
+const asyncResult = await calcPriceAsync(usage, 'non-existent-model', { providerId: 'unknown-provider' })
+if (asyncResult === null) {
+  console.log('No pricing information available for this model/provider combination')
+} else {
+  console.log(`Price: $${asyncResult.price}`)
+}
+```
+
+**TypeScript users**: The return type is `PriceCalculation | null` (exported as `PriceCalculationResult`).
+
+## Testing
+
+### Node.js Test
+
+Run:
+
+```bash
+node tests/test-error-handling.js
+```
+
+This tests error handling, sync/async API, and providerId usage.
+
+### Browser Test
+
+1. Build the package: `npm run build`
+2. Serve the directory: `npx serve .` or `python3 -m http.server`
+3. Open `tests/test-browser.html` in your browser.
+4. Enter a provider (e.g., `openai`) and model (e.g., `gpt-3.5-turbo`) and run the test.
+
+## Architecture
+
+### Folder Structure
+
+```
+src/
+├── sync/
+│   └── calcPriceSync.ts      # Sync API implementation
+├── async/
+│   └── calcPriceAsync.ts     # Async API implementation
+├── dataLoader.ts             # Data loader (sync + async)
+├── index.ts                  # Entry point (exports both sync + async)
+├── cli.ts                    # CLI tool
+├── types.ts                  # Shared types (snake_case, matches JSON)
+├── matcher.ts                # Shared matching logic
+├── priceCalc.ts              # Shared price calculation
+└── __tests__/                # Tests
+```
+
+### Design Principles
+
+- **Environment-agnostic APIs**: Sync/async is about API style, not environment
+- **Single data loader**: Handles all environments with embedded data for sync and remote fetch for async
+- **Cross-environment compatibility**: Both sync and async APIs can be used in Node.js, browser, Cloudflare, etc.
+- **No mapping needed**: All types and data use snake_case, matching the JSON schema
+
+## Troubleshooting
+
+### Common Issues
+
+- **No price found (returns null)**:
+  - Make sure you specify the correct `providerId` (e.g., `openai`)
+  - Try using `provider:model` format in CLI
+  - Use `--auto-update` flag to fetch latest data
+  - Check that the model name is correct and supported by the provider
+- **Build errors**: Ensure you have run the build and that your data is up to date.
+
+### Provider Matching Examples
+
+```bash
+# These should work with auto-update
+genai-prices gpt-3.5-turbo --auto-update
+genai-prices claude-3-5-sonnet --auto-update
+genai-prices gemini-1.5-pro --auto-update
+
+# Explicit provider specification
+genai-prices openai:gpt-3.5-turbo
+genai-prices anthropic:claude-3-5-sonnet
+genai-prices google:gemini-1.5-pro
+```
+
+## Maintainers
+
+- When adding new features, keep sync and async logic in separate files
+- Only import Node.js built-ins in Node-only files if absolutely necessary
+- Use the main entry for all environments
+- All types and data should use snake_case to match the JSON schema
+- Provider matching logic is in `matcher.ts` and should be environment-agnostic

package/dist/__tests__/calcPrice.test.d.ts

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

package/dist/async/calcPriceAsync.d.ts

@@ -0,0 +1,8 @@
+import { Usage, PriceCalculationResult } from '../types.js';
+export type { Usage, PriceCalculation, PriceCalculationResult } from '../types.js';
+export interface CalcPriceOptions {
+    providerId?: string;
+    providerApiUrl?: string;
+    timestamp?: Date;
+}
+export declare function calcPriceAsync(usage: Usage, modelRef: string, options?: CalcPriceOptions): Promise<PriceCalculationResult>;

package/dist/async/calcPriceAsync.js

@@ -0,0 +1,22 @@
+import { getProvidersAsync } from '../dataLoader.js';
+import { matchProvider, matchModel } from '../matcher.js';
+import { calcPrice as calcModelPrice, getActiveModelPrice } from '../priceCalc.js';
+export async function calcPriceAsync(usage, modelRef, options = {}) {
+    const providers = await getProvidersAsync();
+    const provider = matchProvider(providers, modelRef, options.providerId, options.providerApiUrl);
+    if (!provider)
+        return null;
+    const model = matchModel(provider.models, modelRef);
+    if (!model)
+        return null;
+    const timestamp = options.timestamp || new Date();
+    const model_price = getActiveModelPrice(model, timestamp);
+    const price = calcModelPrice(usage, model_price);
+    return {
+        price,
+        provider,
+        model,
+        model_price,
+        auto_update_timestamp: undefined,
+    };
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { calcPriceSync, calcPriceAsync, enableAutoUpdate } from './index.js';
+const argv = yargs(hideBin(process.argv))
+    .scriptName('genai-prices')
+    .command('list [provider]', 'List providers and models', (y) => y.positional('provider', { type: 'string', describe: 'Provider ID to filter' }))
+    .command('calc <model...>', 'Calculate price', (y) => y
+    .positional('model', { type: 'string', describe: 'Model(s) (optionally provider:model)', array: true })
+    .option('input-tokens', { type: 'number' })
+    .option('cache-write-tokens', { type: 'number' })
+    .option('cache-read-tokens', { type: 'number' })
+    .option('output-tokens', { type: 'number' })
+    .option('input-audio-tokens', { type: 'number' })
+    .option('cache-audio-read-tokens', { type: 'number' })
+    .option('output-audio-tokens', { type: 'number' })
+    .option('requests', { type: 'number' })
+    .option('provider', { type: 'string' })
+    .option('auto-update', { type: 'boolean', default: false })
+    .option('timestamp', { type: 'string', describe: 'RFC3339 timestamp' }))
+    .option('auto-update', { type: 'boolean', describe: 'Enable auto-update from GitHub' })
+    .option('input-tokens', { type: 'number' })
+    .option('cache-write-tokens', { type: 'number' })
+    .option('cache-read-tokens', { type: 'number' })
+    .option('output-tokens', { type: 'number' })
+    .option('input-audio-tokens', { type: 'number' })
+    .option('cache-audio-read-tokens', { type: 'number' })
+    .option('output-audio-tokens', { type: 'number' })
+    .option('requests', { type: 'number' })
+    .option('provider', { type: 'string' })
+    .option('timestamp', { type: 'string', describe: 'RFC3339 timestamp' })
+    .version('0.1.0')
+    .help()
+    .parseSync();
+async function main() {
+    if (argv['auto-update'])
+        enableAutoUpdate();
+    // Handle list command
+    if (argv._[0] === 'list') {
+        if (argv['auto-update']) {
+            const { getProvidersAsync } = await import('./dataLoader.js');
+            const providers = await getProvidersAsync();
+            if (argv.provider) {
+                const p = providers.find((p) => p.id === argv.provider);
+                if (!p) {
+                    console.error(`Provider ${argv.provider} not found.`);
+                    process.exit(1);
+                }
+                console.log(`${p.name}: (${p.models.length} models)`);
+                for (const m of p.models) {
+                    console.log(`  ${p.id}:${m.id}${m.name ? ': ' + m.name : ''}`);
+                }
+            }
+            else {
+                for (const p of providers) {
+                    console.log(`${p.name}: (${p.models.length} models)`);
+                    for (const m of p.models) {
+                        console.log(`  ${p.id}:${m.id}${m.name ? ': ' + m.name : ''}`);
+                    }
+                }
+            }
+        }
+        else {
+            const { getProvidersSync } = await import('./dataLoader.js');
+            const providers = getProvidersSync();
+            if (argv.provider) {
+                const p = providers.find((p) => p.id === argv.provider);
+                if (!p) {
+                    console.error(`Provider ${argv.provider} not found.`);
+                    process.exit(1);
+                }
+                console.log(`${p.name}: (${p.models.length} models)`);
+                for (const m of p.models) {
+                    console.log(`  ${p.id}:${m.id}${m.name ? ': ' + m.name : ''}`);
+                }
+            }
+            else {
+                for (const p of providers) {
+                    console.log(`${p.name}: (${p.models.length} models)`);
+                    for (const m of p.models) {
+                        console.log(`  ${p.id}:${m.id}${m.name ? ': ' + m.name : ''}`);
+                    }
+                }
+            }
+        }
+        process.exit(0);
+    }
+    // Handle calc command or direct model names
+    const isCalcCommand = argv._[0] === 'calc';
+    const models = isCalcCommand
+        ? Array.isArray(argv.model)
+            ? argv.model
+            : [argv.model]
+        : argv._.filter((arg) => typeof arg === 'string');
+    if (models.length > 0) {
+        const usage = {
+            input_tokens: argv['input-tokens'] !== undefined ? Number(argv['input-tokens']) : undefined,
+            cache_write_tokens: argv['cache-write-tokens'] !== undefined ? Number(argv['cache-write-tokens']) : undefined,
+            cache_read_tokens: argv['cache-read-tokens'] !== undefined ? Number(argv['cache-read-tokens']) : undefined,
+            output_tokens: argv['output-tokens'] !== undefined ? Number(argv['output-tokens']) : undefined,
+            input_audio_tokens: argv['input-audio-tokens'] !== undefined ? Number(argv['input-audio-tokens']) : undefined,
+            cache_audio_read_tokens: argv['cache-audio-read-tokens'] !== undefined ? Number(argv['cache-audio-read-tokens']) : undefined,
+            output_audio_tokens: argv['output-audio-tokens'] !== undefined ? Number(argv['output-audio-tokens']) : undefined,
+            requests: argv['requests'] !== undefined ? Number(argv['requests']) : undefined,
+        };
+        const timestamp = argv.timestamp ? new Date(String(argv.timestamp)) : undefined;
+        const fn = argv['auto-update'] ? calcPriceAsync : calcPriceSync;
+        let hadError = false;
+        for (const modelArg of models) {
+            let providerId;
+            let modelRef = modelArg;
+            if (modelRef.includes(':')) {
+                ;
+                [providerId, modelRef] = modelRef.split(':', 2);
+            }
+            try {
+                const result = await fn(usage, modelRef, { providerId, timestamp });
+                if (!result) {
+                    hadError = true;
+                    console.error(`No price found for model ${modelArg}`);
+                    continue;
+                }
+                const w = result.model.context_window;
+                const output = [
+                    ['Provider', result.provider.name],
+                    ['Model', result.model.name || result.model.id],
+                    ['Model Prices', JSON.stringify(result.model_price)],
+                    ['Context Window', w !== undefined ? w.toLocaleString() : undefined],
+                    ['Price', `$${result.price}`],
+                ];
+                for (const [key, value] of output) {
+                    if (value !== undefined) {
+                        console.log(`${key.padStart(14)}: ${value}`);
+                    }
+                }
+                console.log('');
+            }
+            catch (e) {
+                hadError = true;
+                console.error(`Error for model ${modelArg}:`, e.message);
+            }
+        }
+        process.exit(hadError ? 1 : 0);
+    }
+    // If no command matched
+    yargs().showHelp();
+    process.exit(1);
+}
+main();

package/dist/data.d.ts

@@ -0,0 +1,2 @@
+import { Provider } from './types.js';
+export declare const data: Provider[];