nuabase 2.3.2 → 2.3.4

package/README.md

@@ -146,33 +146,33 @@ Every call returns a discriminated union. When `success` is `false`, you get an
 
 **Success**
 
-| Field       | Type                                                      | Description                                             |
-| ----------- | --------------------------------------------------------- | ------------------------------------------------------- |
-| `success`   | `true`                                                    | Indicates that the request completed successfully.      |
-| `data`      | `T` (for `get`) or `Array<{ [pk]: value; [output]: T }>` (for `list`) | The typed result matching your schema.    |
-| `usage`     | `{ promptTokens, completionTokens, totalTokens }`         | Token usage statistics for the LLM request.             |
-| `model`     | `string`                                                  | The LLM model used for this request.                    |
-| `latencyMs` | `number`                                                  | Request latency in milliseconds.                        |
-| `source`    | `'gateway'` \| `'direct'`                                 | Which backend processed the request.                    |
-| `meta`      | `object`                                                  | Additional metadata (varies by source).                 |
+| Field       | Type                                                                  | Description                                        |
+| ----------- | --------------------------------------------------------------------- | -------------------------------------------------- |
+| `success`   | `true`                                                                | Indicates that the request completed successfully. |
+| `data`      | `T` (for `get`) or `Array<{ [pk]: value; [output]: T }>` (for `list`) | The typed result matching your schema.             |
+| `usage`     | `{ promptTokens, completionTokens, totalTokens }`                     | Token usage statistics for the LLM request.        |
+| `model`     | `string`                                                              | The LLM model used for this request.               |
+| `latencyMs` | `number`                                                              | Request latency in milliseconds.                   |
+| `source`    | `'gateway'` \| `'direct'`                                             | Which backend processed the request.               |
+| `meta`      | `object`                                                              | Additional metadata (varies by source).            |
 
 **Gateway-specific metadata** (`meta` when `source` is `'gateway'`):
 
-| Field        | Type      | Description                                    |
-| ------------ | --------- | ---------------------------------------------- |
-| `requestId`  | `string`  | Unique identifier for tracing.                 |
-| `cached`     | `boolean` | Whether the result was served from cache.      |
-| `llmUsage`   | `object`  | Token usage from LLM calls.                    |
-| `cacheUsage` | `object`  | Token usage served from cache.                 |
+| Field        | Type      | Description                               |
+| ------------ | --------- | ----------------------------------------- |
+| `requestId`  | `string`  | Unique identifier for tracing.            |
+| `cached`     | `boolean` | Whether the result was served from cache. |
+| `llmUsage`   | `object`  | Token usage from LLM calls.               |
+| `cacheUsage` | `object`  | Token usage served from cache.            |
 
 **Error**
 
-| Field       | Type                          | Description                                              |
-| ----------- | ----------------------------- | -------------------------------------------------------- |
-| `success`   | `false`                       | Indicates the request failed.                            |
-| `error`     | `string`                      | Message describing the error.                            |
-| `source`    | `'gateway'` \| `'direct'`     | Which backend returned the error.                        |
-| `latencyMs` | `number`                      | Time until failure in milliseconds.                      |
+| Field       | Type                      | Description                         |
+| ----------- | ------------------------- | ----------------------------------- |
+| `success`   | `false`                   | Indicates the request failed.       |
+| `error`     | `string`                  | Message describing the error.       |
+| `source`    | `'gateway'` \| `'direct'` | Which backend returned the error.   |
+| `latencyMs` | `number`                  | Time until failure in milliseconds. |
 
 ## SDK API
 
@@ -187,8 +187,22 @@ Creates a client that connects to the Nuabase API gateway. Use this for producti
 **`Nua.direct(config)`**
 Creates a client that calls LLM providers directly (in-process). Use this for serverless, edge functions, or CLI tools where you don't need the gateway infrastructure.
 
-- `model: string` – The model to use (e.g., `'gpt-4o-mini'`).
-- `providers: { openai?: { apiKey: string }, ... }` – Provider credentials.
+- `model?: ModelInput` – Optional default model. Omit it to use `{ alias: 'fast' }`.
+- `providers: { groq?: { apiKey: string }, cerebras?: { apiKey: string }, gemini?: { apiKey: string }, openrouter?: { apiKey: string } }` – Provider credentials.
+
+Model inputs are objects, not provider-prefixed strings:
+
+```ts
+await nua.get('Extract the company name', {
+  output: { name: 'companyName', schema: z.string() },
+  model: { provider: 'openrouter', model: 'z-ai/glm-5.2' },
+});
+
+await nua.get('Extract the company name', {
+  output: { name: 'companyName', schema: z.string() },
+  model: { alias: 'fast' },
+});
+```
 
 ### Methods
 
@@ -196,7 +210,7 @@ Creates a client that calls LLM providers directly (in-process). Use this for se
 Returns a simple string response from the LLM.
 
 ```ts
-const result = await nua.get("Tell me a joke");
+const result = await nua.get('Tell me a joke');
 if (result.success) console.log(result.data); // string
 ```
 
@@ -208,8 +222,8 @@ Returns a typed single value. Parameters:
 - `options.output: { name: string; schema: ZodSchema }` – Output name and Zod schema.
 
 ```ts
-const result = await nua.get("Extract the address", {
-  input: "123 Main St, Springfield, IL 62701",
+const result = await nua.get('Extract the address', {
+  input: '123 Main St, Springfield, IL 62701',
   output: { name: 'address', schema: AddressSchema },
 });
 if (result.success) console.log(result.data); // typed as z.infer<typeof AddressSchema>
@@ -224,20 +238,20 @@ Processes an array of items. Parameters:
 - `options.output: { name: string; schema: ZodSchema }` – Output configuration.
 
 ```ts
-const result = await nua.list("Classify each lead", {
+const result = await nua.list('Classify each lead', {
   input: leads,
   primaryKey: 'id',
   output: { name: 'classification', schema: ClassificationSchema },
 });
 if (result.success) {
-  result.data.forEach(row => console.log(row.id, row.classification));
+  result.data.forEach((row) => console.log(row.id, row.classification));
 }
 ```
 
-**`nua.queueGet(prompt, options?)`** *(Gateway mode only)*
+**`nua.queueGet(prompt, options?)`** _(Gateway mode only)_
 Submits an async job for single-value operations. Returns `{ success: true, jobId }`.
 
-**`nua.queueList(prompt, options)`** *(Gateway mode only)*
+**`nua.queueList(prompt, options)`** _(Gateway mode only)_
 Submits an async job for array operations. Returns `{ success: true, jobId }`.
 
 ## Next Steps