@pydantic/genai-prices 0.0.20 → 0.0.21

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Pydantic Services Inc. 2025 to present
+
+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

@@ -1,103 +1,54 @@
-# genai-prices package (JS/TS)
+# @pydantic/genai-prices
 
-Library and CLI for calculating LLM API prices, supporting browser, Node.js and other environments.
+JavaScript package and command-line tool for calculating LLM API prices.
 
-## Features
+## Basic usage
 
-- **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.
+### `calcPrice`
 
-## API Usage
+The package exports a function for price calculation that, by default, uses the bundled price data.
 
-The library provides separated input and output pricing, giving you detailed breakdown of costs:
-
-- `result.total_price` - Total cost for the request
-- `result.input_price` - Cost for input/prompt tokens
-- `result.output_price` - Cost for output/completion tokens
-
-### Node.js & Browser (Library)
-
-```js
-import { calcPriceSync, calcPriceAsync } from '@pydantic/genai-prices'
+```ts
+import { calcPrice } 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' })
+const result = calcPrice(usage, 'gpt-3.5-turbo', { providerId: 'openai' })
+
 if (result) {
   console.log(
     `$${result.total_price} (input: $${result.input_price}, output: $${result.output_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.total_price} (input: $${asyncResult.input_price}, output: $${asyncResult.output_price})`,
-    asyncResult.provider.name,
-    asyncResult.model.name,
+    result.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.total_price} (input: $${result.input_price}, output: $${result.output_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:
+### `updatePrices`
 
-```bash
-genai-prices calc gpt-4 --input-tokens 1000 --output-tokens 500
-genai-prices list
-```
+You can optionally use `updatePrices` to implement logic that can periodically update the data used by `calcPrice`.
+See the `src/examples/browser` directory for an example that implements a local storage-backed auto-update and `src/examples/node-script.ts` for an example of a file-based asynchronous auto-update implementation.
 
-### CLI
+`calcPrice` is a synchronous function that uses the currently available data - either the bundled one, or the last data fetched from the `updatePrices` setup. To force `calcPrice` to await potential in-progress data updates that can happen in `enableAutoUpdate`, await the `waitForUpdate()` return value before calling `calcPrice`
 
-After global installation, you can use the CLI as follows:
+```ts
+import { calcPrice, updatePrices } from '@pydantic/genai-prices'
 
-```bash
-# Basic usage
-genai-prices gpt-3.5-turbo --input-tokens 1000 --output-tokens 100
+enableAutoUpdate(/** auto-update logic */)
 
-# 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
+// this guarantees that the latest data is used
+await waitForUpdate()
+const result = calcPrice(usage, 'gpt-5', { providerId: 'openai' })
 
-# List available providers and models
-genai-prices list
-genai-prices list openai
+console.log(
+  `$${result.total_price} (input: $${result.input_price}, output: $${result.output_price})`,
+  result.provider.name,
+  result.model.name
+)
 ```
 
 ### Provider Matching
@@ -105,7 +56,7 @@ genai-prices list openai
 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-")
+2. **Model-based matching**: Uses the 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:**
@@ -116,15 +67,15 @@ The library uses intelligent provider matching:
 
 ### 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:
+When a model or provider is not found, the library returns `null`. This makes it easier to handle cases where pricing information might not be available.
 
 ```js
-import { calcPriceSync, calcPriceAsync } from '@pydantic/genai-prices'
+import { calcPrice } 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')
+const result = calcPrice(usage, 'non-existent-model')
 if (result === null) {
   console.log('No pricing information available for this model')
 } else {
@@ -132,63 +83,14 @@ if (result === null) {
 }
 
 // Async version also returns null
-const asyncResult = await calcPriceAsync(usage, 'non-existent-model', { providerId: 'unknown-provider' })
+const asyncResult = await calcPrice(usage, 'non-existent-model', { awaitAutoUpdate: true, providerId: 'unknown-provider' })
 if (asyncResult === null) {
   console.log('No pricing information available for this model/provider combination')
 } else {
-  console.log(
-    `Total Price: $${asyncResult.total_price} (input: $${asyncResult.input_price}, output: $${asyncResult.output_price})`,
-  )
+  console.log(`Total Price: $${asyncResult.total_price} (input: $${asyncResult.input_price}, output: $${asyncResult.output_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
@@ -198,26 +100,36 @@ src/
   - 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
+## CLI
+
+The easiest way to run the latest version of the package as a CLI tool is through npx:
+
+```bash
+npx @pydantic/genai-prices@latest
+```
+
+For example:
+
+```bash
+npx @pydantic/genai-prices@latest calc gpt-4 --input-tokens 1000 --output-tokens 500
+npx @pydantic/genai-prices@latest list
+```
+
+You can also install it globally and then use the `genai-prices` command:
 
 ```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
+npm i -g @pydantic/genai-prices
 ```
 
-## Maintainers
+```bash
+# Basic usage
+genai-prices gpt-5 --input-tokens 1000 --output-tokens 100
+
+# Specify provider explicitly
+genai-prices openai:gpt-5 --input-tokens 1000 --output-tokens 100
 
-- 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
+# List available providers and models
+genai-prices list
+genai-prices list openai
+```