notdiamond 1.1.4 → 2.0.0-rc10

package/README.md

@@ -1,6 +1,29 @@
-# NotDiamond Node API Library
+# Not Diamond TypeScript API Library
 
-This library provides convenient access to the NotDiamond model routing API from TypeScript or JavaScript. NotDiamond helps you select the best AI model for your specific use case, optimizing for factors like cost, latency, or performance.
+[![NPM version](<https://img.shields.io/npm/v/notdiamond.svg?label=npm%20(stable)>)](https://npmjs.org/package/notdiamond) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/notdiamond)
+
+This library provides convenient access to the Not Diamond REST API from server-side TypeScript or JavaScript.
+
+The library includes type definitions for all request params and response fields.
+
+It is generated with [Stainless](https://www.stainless.com/).
+
+## What is Prompt Adaptation?
+
+Not Diamond specializes in **Prompt Adaptation** - automatically optimizing your prompts to work optimally across different LLMs. Each language model has unique characteristics, instruction-following patterns, and preferred prompt formats. A prompt that works perfectly for GPT-4 might perform poorly on Claude or Gemini.
+
+**The Problem**: Manually rewriting prompts for each model is time-consuming and requires deep expertise in each model's quirks.
+
+**The Solution**: Not Diamond automatically adapts your prompts through:
+
+- Systematic optimization using your evaluation dataset
+- Automated testing across target models
+- Performance metrics to validate improvements
+- Both system prompt and user message template optimization
+
+## Documentation
+
+The REST API documentation can be found on [docs.notdiamond.ai](https://docs.notdiamond.ai). The full API of this library can be found in [api.md](api.md).
 
 ## Installation
 
@@ -8,135 +31,658 @@ This library provides convenient access to the NotDiamond model routing API from
 npm install notdiamond
 ```
 
-For Deno users:
+## Usage
+
+### Prompt Adaptation
+
+Automatically optimize your prompts to work better across different language models. Each model has unique characteristics and preferences - what works well for GPT-4 might not work as well for Claude or Gemini. Prompt Adaptation helps you get optimal performance from each model.
+
+#### Quick Start
+
+<!-- prettier-ignore -->
+```ts
+import NotDiamond from 'notdiamond';
+
+const client = new NotDiamond({
+  apiKey: process.env['NOT_DIAMOND_API_KEY'], // This is the default and can be omitted
+});
+
+// Step 1: Start a prompt adaptation job
+const adaptation = await client.prompt.adapt.create({
+  fields: ['question'],
+  system_prompt: 'You are a helpful assistant that answers questions accurately.',
+  target_models: [
+    {
+      model: 'claude-sonnet-4-5-20250929',
+      provider: 'anthropic',
+    },
+    {
+      model: 'gemini-2.5-flash',
+      provider: 'google',
+    },
+  ],
+  template: 'Question: {question}\nAnswer:',
+  train_goldens: [
+    { fields: { question: 'What is 2+2?' }, answer: '4' },
+    { fields: { question: 'What is the capital of France?' }, answer: 'Paris' },
+    { fields: { question: 'Who wrote Romeo and Juliet?' }, answer: 'William Shakespeare' },
+    // Add at least 25 training examples for best results
+    // More examples = better adaptation quality
+  ],
+  test_goldens: [
+    { fields: { question: 'What is 3*3?' }, answer: '9' },
+    { fields: { question: 'What is the largest ocean?' }, answer: 'Pacific Ocean' },
+    // Add test examples to validate performance
+  ],
+  evaluation_metric: 'LLMaaJ:Sem_Sim_1', // Or use custom evaluation
+});
+
+console.log(`Adaptation started: ${adaptation.adaptation_run_id}`);
+
+// Step 2: Poll for completion (typically takes 10-30 minutes)
+let status;
+while (true) {
+  status = await client.prompt.getAdaptStatus(adaptation.adaptation_run_id);
+  console.log(`Status: ${status.status}`);
+  
+  if (status.status === 'queued') {
+    console.log(`Queue position: ${status.queue_position}`);
+  }
+  
+  if (status.status === 'completed' || status.status === 'failed') {
+    break;
+  }
+  
+  await new Promise(resolve => setTimeout(resolve, 30000)); // Poll every 30 seconds
+}
+
+// Step 3: Get the optimized prompts
+if (status.status === 'completed') {
+  const results = await client.prompt.getAdaptResults(adaptation.adaptation_run_id);
+  
+  console.log(`\nOrigin model baseline: ${results.origin_model.score.toFixed(2)}`);
+  
+  for (const target of results.target_models) {
+    console.log('\n' + '='.repeat(50));
+    console.log(`Model: ${target.model.model} (${target.model.provider})`);
+    console.log(`Optimized System Prompt:\n${target.system_prompt}`);
+    console.log(`Optimized Template:\n${target.user_message_template}`);
+    console.log(`Pre-optimization score: ${target.pre_optimization_score.toFixed(2)}`);
+    console.log(`Post-optimization score: ${target.post_optimization_score.toFixed(2)}`);
+    console.log(`Improvement: ${((target.post_optimization_score / target.pre_optimization_score - 1) * 100).toFixed(1)}%`);
+    console.log(`Cost: $${target.cost.toFixed(4)}`);
+  }
+}
+```
+
+#### Key Features
+
+- **Automatic Optimization**: Adapts both system prompts and user message templates
+- **Evaluation Metrics**: Choose from standard metrics (semantic similarity, JSON matching, SQL) or provide custom evaluation
+- **Dataset Requirements**: Minimum 25 training examples (more examples = better results)
+- **Processing Time**: Typically 10-30 minutes depending on dataset size and number of target models
+- **Subscription Tiers**: Support for 1-10 target models depending on your plan
+
+#### Evaluation Metrics
+
+Choose from standard metrics:
+
+- `LLMaaJ:Sem_Sim_1`, `LLMaaJ:Sem_Sim_3`, `LLMaaJ:Sem_Sim_10` - Semantic similarity
+- `LLMaaJ:SQL` - SQL query validation
+- `JSON_Match` - JSON structure matching
+
+Or provide custom evaluation configuration with your own LLM judge.
+
+#### Best Practices
+
+1. **Use Representative Examples**: Include diverse examples from your production workload
+2. **Sufficient Dataset Size**: Use at least 25 training examples (50+ recommended)
+3. **Train/Test Split**: Separate train_goldens and test_goldens for proper validation
+4. **A/B Test Results**: Validate optimized prompts in production before full deployment
+
+For more details, see the [Prompt Adaptation documentation](https://docs.notdiamond.ai/docs/adapting-prompts-to-new-models).
+
+### Model Routing
+
+Not Diamond also provides intelligent model routing to select the best model for your query:
+
+<!-- prettier-ignore -->
+```ts
+const response = await client.modelRouter.selectModel({
+  llm_providers: [
+    { model: 'gpt-4o', provider: 'openai' },
+    { model: 'claude-sonnet-4-5-20250929', provider: 'anthropic' },
+    { model: 'gemini-2.5-flash', provider: 'google' },
+  ],
+  messages: [
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'Explain quantum computing in simple terms' },
+  ],
+});
+
+console.log(response.providers);
+```
+
+### Request & Response types
+
+This library includes TypeScript definitions for all request params and response fields. You may import and use them like so:
 
+<!-- prettier-ignore -->
 ```ts
-import { NotDiamond } from 'https://deno.land/x/notdiamond@v1.0.0/mod.ts';
+import NotDiamond from 'notdiamond';
+
+const client = new NotDiamond({
+  apiKey: process.env['NOT_DIAMOND_API_KEY'], // This is the default and can be omitted
+});
+
+const params: NotDiamond.PromptAdaptCreateParams = {
+  fields: ['question', 'context'],
+  system_prompt: 'You are a helpful assistant.',
+  target_models: [
+    {
+      model: 'claude-sonnet-4-5-20250929',
+      provider: 'anthropic',
+    },
+  ],
+  template: 'Context: {context}\nQuestion: {question}\nAnswer:',
+  train_goldens: [
+    {
+      fields: {
+        question: 'What is 2+2?',
+        context: 'Basic arithmetic',
+      },
+      answer: '4',
+    },
+    // Add at least 25 examples for best results
+  ],
+  test_goldens: [
+    {
+      fields: {
+        question: 'What is 3*3?',
+        context: 'Basic arithmetic',
+      },
+      answer: '9',
+    },
+  ],
+};
+const response: NotDiamond.PromptAdaptCreateResponse = await client.prompt.adapt.create(params);
+console.log(response.adaptation_run_id);
 ```
 
-## Quick Start
+Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.
+
+## File uploads
 
-To use the API, you need to sign up for a NotDiamond account and obtain an API key. [Sign up here](https://app.notdiamond.ai).
+Request parameters that correspond to file uploads can be passed in many different forms:
 
-### Basic Usage
+- `File` (or an object with the same structure)
+- a `fetch` `Response` (or an object with the same structure)
+- an `fs.ReadStream`
+- the return value of our `toFile` helper
+
+```ts
+import fs from 'fs';
+import NotDiamond, { toFile } from 'notdiamond';
+
+const client = new NotDiamond();
+
+// If you have access to Node `fs` we recommend using `fs.createReadStream()`:
+await client.customRouter.trainCustomRouter({
+  dataset_file: fs.createReadStream('/path/to/file'),
+  language: 'english',
+  llm_providers:
+    '[{"provider": "openai", "model": "gpt-4o"}, {"provider": "anthropic", "model": "claude-sonnet-4-5-20250929"}]',
+  maximize: true,
+  prompt_column: 'prompt',
+});
 
-Here's a simple example of how to use NotDiamond to select the best model between GPT-4o, Claude 3.5 Sonnet, and Gemini 1.5 Pro, while optimizing for latency and outputting the raw text:
+// Or if you have the web `File` API you can pass a `File` instance:
+await client.customRouter.trainCustomRouter({
+  dataset_file: new File(['my bytes'], 'file'),
+  language: 'english',
+  llm_providers:
+    '[{"provider": "openai", "model": "gpt-4o"}, {"provider": "anthropic", "model": "claude-sonnet-4-5-20250929"}]',
+  maximize: true,
+  prompt_column: 'prompt',
+});
 
-```typescript
-import { NotDiamond } from 'notdiamond';
+// You can also pass a `fetch` `Response`:
+await client.customRouter.trainCustomRouter({
+  dataset_file: await fetch('https://somesite/file'),
+  language: 'english',
+  llm_providers:
+    '[{"provider": "openai", "model": "gpt-4o"}, {"provider": "anthropic", "model": "claude-sonnet-4-5-20250929"}]',
+  maximize: true,
+  prompt_column: 'prompt',
+});
 
-const notDiamond = new NotDiamond({
-  // Optional - automatically loads from environment variable
-  apiKey: process.env.NOTDIAMOND_API_KEY,
+// Finally, if none of the above are convenient, you can use our `toFile` helper:
+await client.customRouter.trainCustomRouter({
+  dataset_file: await toFile(Buffer.from('my bytes'), 'file'),
+  language: 'english',
+  llm_providers:
+    '[{"provider": "openai", "model": "gpt-4o"}, {"provider": "anthropic", "model": "claude-sonnet-4-5-20250929"}]',
+  maximize: true,
+  prompt_column: 'prompt',
+});
+await client.customRouter.trainCustomRouter({
+  dataset_file: await toFile(new Uint8Array([0, 1, 2]), 'file'),
+  language: 'english',
+  llm_providers:
+    '[{"provider": "openai", "model": "gpt-4o"}, {"provider": "anthropic", "model": "claude-sonnet-4-5-20250929"}]',
+  maximize: true,
+  prompt_column: 'prompt',
 });
+```
+
+## Handling errors
+
+When the library is unable to connect to the API,
+or if the API returns a non-success status code (i.e., 4xx or 5xx response),
+a subclass of `APIError` will be thrown:
 
-async function basicExample() {
-  // 1. Select the best model
-  const result = await notDiamond.create({
-    // Define the user's message
-    messages: [{ content: 'What is 12x12?', role: 'user' }],
-    // Specify the LLM providers and models to choose from
-    llmProviders: [
-      { provider: 'openai', model: 'gpt-4o-2024-05-13' },
-      { provider: 'anthropic', model: 'claude-3-5-sonnet-20240620' },
-      { provider: 'google', model: 'gemini-1.5-pro-latest' },
+<!-- prettier-ignore -->
+```ts
+import NotDiamond from 'notdiamond';
+
+const client = new NotDiamond();
+
+try {
+  await client.prompt.adapt.create({
+    fields: ['question'],
+    system_prompt: 'You are a helpful assistant.',
+    target_models: [
+      {
+        model: 'claude-sonnet-4-5-20250929',
+        provider: 'anthropic',
+      },
+      {
+        model: 'gemini-2.5-flash',
+        provider: 'google',
+      },
+    ],
+    template: 'Question: {question}\nAnswer:',
+    train_goldens: [
+      { fields: { question: 'What is 2+2?' }, answer: '4' },
+      // Add at least 25 examples...
+    ],
+    test_goldens: [
+      { fields: { question: 'What is 3*3?' }, answer: '9' },
     ],
-    // Set the optimization criteria to latency
-    tradeoff: 'latency',
   });
-
-  // 2. Handle potential errors
-  if ('detail' in result) {
-    console.error('Error:', result.detail);
-    return;
+} catch (err) {
+  if (err instanceof NotDiamond.APIConnectionError) {
+    console.log('The server could not be reached');
+    console.log(err.cause); // an underlying Error, likely from fetch()
+  } else if (err instanceof NotDiamond.RateLimitError) {
+    console.log('A 429 status code was received; we should back off a bit.');
+  } else if (err instanceof NotDiamond.APIError) {
+    console.log(err.status); // 400
+    console.log(err.name); // BadRequestError
+    console.log(err.headers); // {server: 'nginx', ...}
+  } else {
+    throw err;
   }
-
-  // 3. Log the results
-  // Display the text response
-  console.log('LLM output:', result.content);
-  // Display the selected provider(s)
-  console.log('Selected providers:', result.providers);
-  // Show the unique session ID for this request
-  console.log('Session ID:', result.session_id);
 }
+```
+
+Error codes are as follows:
+
+| Status Code | Error Type                 |
+| ----------- | -------------------------- |
+| 400         | `BadRequestError`          |
+| 401         | `AuthenticationError`      |
+| 403         | `PermissionDeniedError`    |
+| 404         | `NotFoundError`            |
+| 422         | `UnprocessableEntityError` |
+| 429         | `RateLimitError`           |
+| >=500       | `InternalServerError`      |
+| N/A         | `APIConnectionError`       |
+
+### Retries
+
+Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
+Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,
+429 Rate Limit, and >=500 Internal errors will all be retried by default.
+
+You can use the `maxRetries` option to configure or disable this:
+
+<!-- prettier-ignore -->
+```js
+// Configure the default for all requests:
+const client = new NotDiamond({
+  maxRetries: 0, // default is 2
+});
+
+// Or, configure per-request:
+await client.prompt.adapt.create({
+  fields: ['question'],
+  system_prompt: 'You are a helpful assistant.',
+  target_models: [
+    {
+      model: 'claude-sonnet-4-5-20250929',
+      provider: 'anthropic',
+    },
+    {
+      model: 'gemini-2.5-flash',
+      provider: 'google',
+    },
+  ],
+  template: 'Question: {question}\nAnswer:',
+  train_goldens: [
+    { fields: { question: 'What is 2+2?' }, answer: '4' },
+    // Add at least 25 examples...
+  ],
+  test_goldens: [
+    { fields: { question: 'What is 3*3?' }, answer: '9' },
+  ],
+}, {
+  maxRetries: 5,
+});
+```
+
+### Timeouts
+
+Requests time out after 1 minute by default. You can configure this with a `timeout` option:
+
+<!-- prettier-ignore -->
+```ts
+// Configure the default for all requests:
+const client = new NotDiamond({
+  timeout: 20 * 1000, // 20 seconds (default is 1 minute)
+});
 
-basicExample();
+// Override per-request (note: prompt adaptation may take 10-30 minutes, so increase timeout accordingly):
+await client.prompt.getAdaptStatus('your-adaptation-run-id', {
+  timeout: 120 * 1000, // 2 minutes
+});
 ```
 
-### Advanced Usage with Tools
+On timeout, an `APIConnectionTimeoutError` is thrown.
+
+Note that requests which time out will be [retried twice by default](#retries).
 
-You can also use NotDiamond with custom tools:
+## Advanced Usage
 
-```typescript
-import { NotDiamond, Tool } from 'notdiamond';
+### Accessing raw Response data (e.g., headers)
 
-const notDiamond = new NotDiamond();
+The "raw" `Response` returned by `fetch()` can be accessed through the `.asResponse()` method on the `APIPromise` type that all methods return.
+This method returns as soon as the headers for a successful response are received and does not consume the response body, so you are free to write custom parsing or streaming logic.
 
-// Define custom tools for the AI to use
-const tools: Tool[] = [
-  {
-    type: 'function',
-    function: {
-      name: 'multiply',
-      description: 'Multiplies two numbers.',
-      parameters: {
-        type: 'object',
-        properties: {
-          a: { type: 'integer' },
-          b: { type: 'integer' },
-        },
-        required: ['a', 'b'],
+You can also use the `.withResponse()` method to get the raw `Response` along with the parsed data.
+Unlike `.asResponse()` this method consumes the body, returning once it is parsed.
+
+<!-- prettier-ignore -->
+```ts
+const client = new NotDiamond();
+
+const response = await client.prompt.adapt
+  .create({
+    fields: ['question'],
+    system_prompt: 'You are a helpful assistant.',
+    target_models: [
+      {
+        model: 'claude-sonnet-4-5-20250929',
+        provider: 'anthropic',
+      },
+      {
+        model: 'gemini-2.5-flash',
+        provider: 'google',
       },
-    },
-  },
-];
-
-async function toolCallingExample() {
-  const result = await notDiamond.modelSelect({
-    messages: [{ content: 'What is 12x12?', role: 'user' }],
-    llmProviders: [
-      { provider: 'openai', model: 'gpt-4-1106-preview' },
-      { provider: 'anthropic', model: 'claude-3-sonnet-20240229' },
     ],
-    // Include custom tools in the request
-    tools: tools,
-    // Optimize for cost instead of latency
-    tradeoff: 'cost',
-    // Allow selection of up to 2 models
-    maxModelDepth: 2,
-  });
+    template: 'Question: {question}\nAnswer:',
+    train_goldens: [
+      { fields: { question: 'What is 2+2?' }, answer: '4' },
+      // Add at least 25 examples...
+    ],
+    test_goldens: [
+      { fields: { question: 'What is 3*3?' }, answer: '9' },
+    ],
+  })
+  .asResponse();
+console.log(response.headers.get('X-My-Header'));
+console.log(response.statusText); // access the underlying Response object
+
+const { data: adaptResponse, response: raw } = await client.prompt.adapt
+  .create({
+    fields: ['question'],
+    system_prompt: 'You are a helpful assistant.',
+    target_models: [
+      {
+        model: 'claude-sonnet-4-5-20250929',
+        provider: 'anthropic',
+      },
+      {
+        model: 'gemini-2.5-flash',
+        provider: 'google',
+      },
+    ],
+    template: 'Question: {question}\nAnswer:',
+    train_goldens: [
+      { fields: { question: 'What is 2+2?' }, answer: '4' },
+      // Add at least 25 examples...
+    ],
+    test_goldens: [
+      { fields: { question: 'What is 3*3?' }, answer: '9' },
+    ],
+  })
+  .withResponse();
+console.log(raw.headers.get('X-My-Header'));
+console.log(adaptResponse.adaptation_run_id);
+```
 
-  if ('detail' in result) {
-    console.error('Error:', result.detail);
-    return;
-  }
+### Logging
 
-  console.log('Selected providers:', result.providers);
-  console.log('Session ID:', result.session_id);
-}
+> [!IMPORTANT]
+> All log messages are intended for debugging only. The format and content of log messages
+> may change between releases.
+
+#### Log levels
+
+The log level can be configured in two ways:
+
+1. Via the `NOT_DIAMOND_LOG` environment variable
+2. Using the `logLevel` client option (overrides the environment variable if set)
+
+```ts
+import NotDiamond from 'notdiamond';
+
+const client = new NotDiamond({
+  logLevel: 'debug', // Show all log messages
+});
+```
+
+Available log levels, from most to least verbose:
+
+- `'debug'` - Show debug messages, info, warnings, and errors
+- `'info'` - Show info messages, warnings, and errors
+- `'warn'` - Show warnings and errors (default)
+- `'error'` - Show only errors
+- `'off'` - Disable all logging
+
+At the `'debug'` level, all HTTP requests and responses are logged, including headers and bodies.
+Some authentication-related headers are redacted, but sensitive data in request and response bodies
+may still be visible.
+
+#### Custom logger
+
+By default, this library logs to `globalThis.console`. You can also provide a custom logger.
+Most logging libraries are supported, including [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale), and [@std/log](https://jsr.io/@std/log). If your logger doesn't work, please open an issue.
+
+When providing a custom logger, the `logLevel` option still controls which messages are emitted, messages
+below the configured level will not be sent to your logger.
+
+```ts
+import NotDiamond from 'notdiamond';
+import pino from 'pino';
+
+const logger = pino();
+
+const client = new NotDiamond({
+  logger: logger.child({ name: 'NotDiamond' }),
+  logLevel: 'debug', // Send all messages to pino, allowing it to filter
+});
+```
+
+### Making custom/undocumented requests
+
+This library is typed for convenient access to the documented API. If you need to access undocumented
+endpoints, params, or response properties, the library can still be used.
+
+#### Undocumented endpoints
+
+To make requests to undocumented endpoints, you can use `client.get`, `client.post`, and other HTTP verbs.
+Options on the client, such as retries, will be respected when making these requests.
+
+```ts
+await client.post('/some/path', {
+  body: { some_prop: 'foo' },
+  query: { some_query_arg: 'bar' },
+});
+```
+
+#### Undocumented request params
+
+To make requests using undocumented parameters, you may use `// @ts-expect-error` on the undocumented
+parameter. This library doesn't validate at runtime that the request matches the type, so any extra values you
+send will be sent as-is.
+
+```ts
+client.prompt.adapt.create({
+  fields: ['question'],
+  system_prompt: 'You are a helpful assistant.',
+  target_models: [{ model: 'claude-sonnet-4-5-20250929', provider: 'anthropic' }],
+  template: 'Question: {question}\nAnswer:',
+  train_goldens: [{ fields: { question: 'What is 2+2?' }, answer: '4' }],
+  // @ts-expect-error experimental_feature is not yet public
+  experimental_feature: true,
+});
+```
+
+For requests with the `GET` verb, any extra params will be in the query, all other requests will send the
+extra param in the body.
 
-toolCallingExample();
+If you want to explicitly send an extra argument, you can do so with the `query`, `body`, and `headers` request
+options.
+
+#### Undocumented response properties
+
+To access undocumented response properties, you may access the response object with `// @ts-expect-error` on
+the response object, or cast the response object to the requisite type. Like the request params, we do not
+validate or strip extra properties from the response from the API.
+
+### Customizing the fetch client
+
+By default, this library expects a global `fetch` function is defined.
+
+If you want to use a different `fetch` function, you can either polyfill the global:
+
+```ts
+import fetch from 'my-fetch';
+
+globalThis.fetch = fetch;
+```
+
+Or pass it to the client:
+
+```ts
+import NotDiamond from 'notdiamond';
+import fetch from 'my-fetch';
+
+const client = new NotDiamond({ fetch });
+```
+
+### Fetch options
+
+If you want to set custom `fetch` options without overriding the `fetch` function, you can provide a `fetchOptions` object when instantiating the client or making a request. (Request-specific options override client options.)
+
+```ts
+import NotDiamond from 'notdiamond';
+
+const client = new NotDiamond({
+  fetchOptions: {
+    // `RequestInit` options
+  },
+});
+```
+
+#### Configuring proxies
+
+To modify proxy behavior, you can provide custom `fetchOptions` that add runtime-specific proxy
+options to requests:
+
+<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/node.svg" align="top" width="18" height="21"> **Node** <sup>[[docs](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md#example---proxyagent-with-fetch)]</sup>
+
+```ts
+import NotDiamond from 'notdiamond';
+import * as undici from 'undici';
+
+const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
+const client = new NotDiamond({
+  fetchOptions: {
+    dispatcher: proxyAgent,
+  },
+});
+```
+
+<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/bun.svg" align="top" width="18" height="21"> **Bun** <sup>[[docs](https://bun.sh/guides/http/proxy)]</sup>
+
+```ts
+import NotDiamond from 'notdiamond';
+
+const client = new NotDiamond({
+  fetchOptions: {
+    proxy: 'http://localhost:8888',
+  },
+});
+```
+
+<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/deno.svg" align="top" width="18" height="21"> **Deno** <sup>[[docs](https://docs.deno.com/api/deno/~/Deno.createHttpClient)]</sup>
+
+```ts
+import NotDiamond from 'npm:notdiamond';
+
+const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
+const client = new NotDiamond({
+  fetchOptions: {
+    client: httpClient,
+  },
+});
 ```
 
-## API Reference
+## Frequently Asked Questions
+
+## Semantic versioning
+
+This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:
+
+1. Changes that only affect static types, without breaking runtime behavior.
+2. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_
+3. Changes that we do not expect to impact the vast majority of users in practice.
+
+We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
 
-For a complete API reference and more detailed documentation, please check our [API Documentation](https://notdiamond.readme.io/docs/what-is-not-diamond#getting-started).
+We are keen for your feedback; please open an [issue](https://www.github.com/Not-Diamond/not-diamond-typescript/issues) with questions, bugs, or suggestions.
 
-## Key Concepts
+## Requirements
 
-- **llmProviders**: An array of AI providers and models you want NotDiamond to choose from.
-- **tradeoff**: The factor to optimize for (e.g., 'latency', 'cost', 'performance').
-- **tools**: Custom functions that the AI can use to perform specific tasks.
-- **maxModelDepth**: The maximum number of models to include in the response (for advanced use cases).
+TypeScript >= 4.9 is supported.
 
-## Error Handling
+The following runtimes are supported:
 
-NotDiamond uses typed responses. If there's an error, the response will have a `detail` property with the error message. Always check for this property when handling responses.
+- Web browsers (Up-to-date Chrome, Firefox, Safari, Edge, and more)
+- Node.js 20 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.
+- Deno v1.28.0 or higher.
+- Bun 1.0 or later.
+- Cloudflare Workers.
+- Vercel Edge Runtime.
+- Jest 28 or greater with the `"node"` environment (`"jsdom"` is not supported at this time).
+- Nitro v2.6 or greater.
 
-## Support
+Note that React Native is not supported at this time.
 
-If you encounter any issues or have questions, please [open an issue](https://github.com/Not-Diamond/notdiamond-node) on our GitHub repository.
+If you are interested in other runtime environments, please open or upvote an issue on GitHub.
 
-## License
+## Contributing
 
-This library is released under the MIT License.
+See [the contributing documentation](./CONTRIBUTING.md).