notdiamond 1.1.3 → 2.0.0-rc1

package/README.md

@@ -1,6 +1,12 @@
-# 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 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).
+
+It is generated with [Stainless](https://www.stainless.com/).
 
 ## Installation
 
@@ -8,135 +14,473 @@ This library provides convenient access to the NotDiamond model routing API from
 npm install notdiamond
 ```
 
-For Deno users:
+## Usage
+
+The full API of this library can be found in [api.md](api.md).
+
+<!-- prettier-ignore -->
+```js
+import NotDiamond from 'notdiamond';
+
+const client = new NotDiamond({
+  apiKey: process.env['NOT_DIAMOND_API_KEY'], // This is the default and can be omitted
+  environment: 'staging', // defaults to 'production'
+});
+
+const response = await client.routing.selectModel({
+  llm_providers: [
+    { model: 'gpt-4o', provider: 'openai' },
+    { model: 'claude-3-5-sonnet-20241022', provider: 'anthropic' },
+    { model: 'gemini-1.5-pro', 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
+  environment: 'staging', // defaults to 'production'
+});
+
+const params: NotDiamond.RoutingSelectModelParams = {
+  llm_providers: [
+    { model: 'gpt-4o', provider: 'openai' },
+    { model: 'claude-3-5-sonnet-20241022', provider: 'anthropic' },
+    { model: 'gemini-1.5-pro', provider: 'google' },
+  ],
+  messages: [
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'Explain quantum computing in simple terms' },
+  ],
+};
+const response: NotDiamond.RoutingSelectModelResponse = await client.routing.selectModel(params);
 ```
 
-## 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
+
+Request parameters that correspond to file uploads can be passed in many different forms:
 
-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).
+- `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
 
-### Basic Usage
+```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.routing.createSurveyResponse({
+  constraint_priorities: 'constraint_priorities',
+  email: 'email',
+  llm_providers: 'llm_providers',
+  use_case_desc: 'use_case_desc',
+  user_id: 'user_id',
+  'x-token': 'x-token',
+  dataset_file: fs.createReadStream('/path/to/file'),
+});
 
-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.routing.createSurveyResponse({
+  constraint_priorities: 'constraint_priorities',
+  email: 'email',
+  llm_providers: 'llm_providers',
+  use_case_desc: 'use_case_desc',
+  user_id: 'user_id',
+  'x-token': 'x-token',
+  dataset_file: new File(['my bytes'], 'file'),
+});
 
-```typescript
-import { NotDiamond } from 'notdiamond';
+// You can also pass a `fetch` `Response`:
+await client.routing.createSurveyResponse({
+  constraint_priorities: 'constraint_priorities',
+  email: 'email',
+  llm_providers: 'llm_providers',
+  use_case_desc: 'use_case_desc',
+  user_id: 'user_id',
+  'x-token': 'x-token',
+  dataset_file: await fetch('https://somesite/file'),
+});
 
-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.routing.createSurveyResponse({
+  constraint_priorities: 'constraint_priorities',
+  email: 'email',
+  llm_providers: 'llm_providers',
+  use_case_desc: 'use_case_desc',
+  user_id: 'user_id',
+  'x-token': 'x-token',
+  dataset_file: await toFile(Buffer.from('my bytes'), 'file'),
+});
+await client.routing.createSurveyResponse({
+  constraint_priorities: 'constraint_priorities',
+  email: 'email',
+  llm_providers: 'llm_providers',
+  use_case_desc: 'use_case_desc',
+  user_id: 'user_id',
+  'x-token': 'x-token',
+  dataset_file: await toFile(new Uint8Array([0, 1, 2]), 'file'),
 });
+```
+
+## Handling errors
 
-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' },
+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:
+
+<!-- prettier-ignore -->
+```ts
+const response = await client.routing
+  .selectModel({
+    llm_providers: [
+      { model: 'gpt-4o', provider: 'openai' },
+      { model: 'claude-3-5-sonnet-20241022', provider: 'anthropic' },
+      { model: 'gemini-1.5-pro', provider: 'google' },
     ],
-    // Set the optimization criteria to latency
-    tradeoff: 'latency',
+    messages: [
+      { role: 'system', content: 'You are a helpful assistant.' },
+      { role: 'user', content: 'Explain quantum computing in simple terms' },
+    ],
+  })
+  .catch(async (err) => {
+    if (err instanceof NotDiamond.APIError) {
+      console.log(err.status); // 400
+      console.log(err.name); // BadRequestError
+      console.log(err.headers); // {server: 'nginx', ...}
+    } else {
+      throw err;
+    }
   });
+```
 
-  // 2. Handle potential errors
-  if ('detail' in result) {
-    console.error('Error:', result.detail);
-    return;
-  }
-
-  // 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);
-}
-
-basicExample();
-```
-
-### Advanced Usage with Tools
-
-You can also use NotDiamond with custom tools:
-
-```typescript
-import { NotDiamond, Tool } from 'notdiamond';
-
-const notDiamond = new NotDiamond();
-
-// 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'],
-      },
-    },
-  },
-];
-
-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' },
+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.routing.selectModel({ llm_providers: [{ model: 'gpt-4o', provider: 'openai' }, { model: 'claude-3-5-sonnet-20241022', provider: 'anthropic' }, { model: 'gemini-1.5-pro', provider: 'google' }], messages: [{ role: 'system', content: 'You are a helpful assistant.' }, { role: 'user', content: 'Explain quantum computing in simple terms' }] }, {
+  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)
+});
+
+// Override per-request:
+await client.routing.selectModel({ llm_providers: [{ model: 'gpt-4o', provider: 'openai' }, { model: 'claude-3-5-sonnet-20241022', provider: 'anthropic' }, { model: 'gemini-1.5-pro', provider: 'google' }], messages: [{ role: 'system', content: 'You are a helpful assistant.' }, { role: 'user', content: 'Explain quantum computing in simple terms' }] }, {
+  timeout: 5 * 1000,
+});
+```
+
+On timeout, an `APIConnectionTimeoutError` is thrown.
+
+Note that requests which time out will be [retried twice by default](#retries).
+
+## Advanced Usage
+
+### Accessing raw Response data (e.g., headers)
+
+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.
+
+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.routing
+  .selectModel({
+    llm_providers: [
+      { model: 'gpt-4o', provider: 'openai' },
+      { model: 'claude-3-5-sonnet-20241022', provider: 'anthropic' },
+      { model: 'gemini-1.5-pro', provider: 'google' },
     ],
-    // 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,
-  });
+    messages: [
+      { role: 'system', content: 'You are a helpful assistant.' },
+      { role: 'user', content: 'Explain quantum computing in simple terms' },
+    ],
+  })
+  .asResponse();
+console.log(response.headers.get('X-My-Header'));
+console.log(response.statusText); // access the underlying Response object
+
+const { data: response, response: raw } = await client.routing
+  .selectModel({
+    llm_providers: [
+      { model: 'gpt-4o', provider: 'openai' },
+      { model: 'claude-3-5-sonnet-20241022', provider: 'anthropic' },
+      { model: 'gemini-1.5-pro', provider: 'google' },
+    ],
+    messages: [
+      { role: 'system', content: 'You are a helpful assistant.' },
+      { role: 'user', content: 'Explain quantum computing in simple terms' },
+    ],
+  })
+  .withResponse();
+console.log(raw.headers.get('X-My-Header'));
+console.log(response.providers);
+```
+
+### Logging
+
+> [!IMPORTANT]
+> All log messages are intended for debugging only. The format and content of log messages
+> may change between releases.
+
+#### Log levels
 
-  if ('detail' in result) {
-    console.error('Error:', result.detail);
-    return;
-  }
+The log level can be configured in two ways:
 
-  console.log('Selected providers:', result.providers);
-  console.log('Session ID:', result.session_id);
-}
+1. Via the `NOT_DIAMOND_LOG` environment variable
+2. Using the `logLevel` client option (overrides the environment variable if set)
 
-toolCallingExample();
+```ts
+import NotDiamond from 'notdiamond';
+
+const client = new NotDiamond({
+  logLevel: 'debug', // Show all log messages
+});
 ```
 
-## API Reference
+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.routing.selectModel({
+  // ...
+  // @ts-expect-error baz is not yet public
+  baz: 'undocumented option',
+});
+```
+
+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.
+
+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,
+  },
+});
+```
+
+## 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).

package/api-promise.d.mts

@@ -0,0 +1,2 @@
+export * from "./core/api-promise.mjs";
+//# sourceMappingURL=api-promise.d.mts.map

package/api-promise.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-promise.d.mts","sourceRoot":"","sources":["src/api-promise.ts"],"names":[],"mappings":""}

package/api-promise.d.ts

@@ -0,0 +1,2 @@
+export * from "./core/api-promise.js";
+//# sourceMappingURL=api-promise.d.ts.map

package/api-promise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-promise.d.ts","sourceRoot":"","sources":["src/api-promise.ts"],"names":[],"mappings":""}

package/api-promise.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("./internal/tslib.js");
+/** @deprecated Import from ./core/api-promise instead */
+tslib_1.__exportStar(require("./core/api-promise.js"), exports);
+//# sourceMappingURL=api-promise.js.map

package/api-promise.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-promise.js","sourceRoot":"","sources":["src/api-promise.ts"],"names":[],"mappings":";;;AAAA,yDAAyD;AACzD,gEAAmC"}

package/api-promise.mjs

@@ -0,0 +1,2 @@
+export * from "./core/api-promise.mjs";
+//# sourceMappingURL=api-promise.mjs.map

package/api-promise.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-promise.mjs","sourceRoot":"","sources":["src/api-promise.ts"],"names":[],"mappings":""}