@databricks/appkit 0.72.0 → 0.73.0

package/docs/api/appkit/Class.DatabaseValidationError.md

@@ -0,0 +1,191 @@
+# Class: DatabaseValidationError
+
+Deliberate validation failure raised by a database mutation hook. Generated routes answer `422` and echo only the issues naming a public column; every other failure raised inside a hook stays an opaque server error.
+
+## Extends[​](#extends "Direct link to Extends")
+
+* [`AppKitError`](./docs/api/appkit/Class.AppKitError.md)
+
+## Constructors[​](#constructors "Direct link to Constructors")
+
+### Constructor[​](#constructor "Direct link to Constructor")
+
+```ts
+new DatabaseValidationError(message: string, issues: readonly DatabaseValidationIssue[]): DatabaseValidationError;
+
+```
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                                                                  | Default value |
+| --------- | ----------------------------------------------------------------------------------------------------- | ------------- |
+| `message` | `string`                                                                                              | `undefined`   |
+| `issues`  | readonly [`DatabaseValidationIssue`](./docs/api/appkit/Interface.DatabaseValidationIssue.md)\[] | `[]`          |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`DatabaseValidationError`
+
+#### Overrides[​](#overrides "Direct link to Overrides")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`constructor`](./docs/api/appkit/Class.AppKitError.md#constructor)
+
+## Properties[​](#properties "Direct link to Properties")
+
+### \_clientMessage?[​](#_clientmessage "Direct link to _clientMessage?")
+
+```ts
+protected readonly optional _clientMessage: string;
+
+```
+
+Client-safe error message. When set, callers serializing the error to a client (SSE, HTTP body) MUST prefer `clientMessage` over `message` — `message` may contain raw upstream / SDK text including statement fragments, internal object names, and correlation IDs.
+
+Subclasses can set this in their constructor for a fixed sanitized string. When unset, `clientMessage` defaults to a generic per-code string (see the getter), and the raw `message` is kept server-side only.
+
+#### Inherited from[​](#inherited-from "Direct link to Inherited from")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`_clientMessage`](./docs/api/appkit/Class.AppKitError.md#_clientmessage)
+
+***
+
+### cause?[​](#cause "Direct link to cause?")
+
+```ts
+readonly optional cause: Error;
+
+```
+
+Optional cause of the error
+
+#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`cause`](./docs/api/appkit/Class.AppKitError.md#cause)
+
+***
+
+### code[​](#code "Direct link to code")
+
+```ts
+readonly code: "DATABASE_VALIDATION_ERROR" = "DATABASE_VALIDATION_ERROR";
+
+```
+
+Error code for programmatic error handling
+
+#### Overrides[​](#overrides-1 "Direct link to Overrides")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`code`](./docs/api/appkit/Class.AppKitError.md#code)
+
+***
+
+### context?[​](#context "Direct link to context?")
+
+```ts
+readonly optional context: Record<string, unknown>;
+
+```
+
+Additional context for the error
+
+#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`context`](./docs/api/appkit/Class.AppKitError.md#context)
+
+***
+
+### isRetryable[​](#isretryable "Direct link to isRetryable")
+
+```ts
+readonly isRetryable: false = false;
+
+```
+
+Whether this error type is generally safe to retry
+
+#### Overrides[​](#overrides-2 "Direct link to Overrides")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`isRetryable`](./docs/api/appkit/Class.AppKitError.md#isretryable)
+
+***
+
+### issues[​](#issues "Direct link to issues")
+
+```ts
+readonly issues: readonly DatabaseValidationIssue[];
+
+```
+
+***
+
+### statusCode[​](#statuscode "Direct link to statusCode")
+
+```ts
+readonly statusCode: 422 = 422;
+
+```
+
+HTTP status code suggestion (can be overridden)
+
+#### Overrides[​](#overrides-3 "Direct link to Overrides")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`statusCode`](./docs/api/appkit/Class.AppKitError.md#statuscode)
+
+## Accessors[​](#accessors "Direct link to Accessors")
+
+### clientMessage[​](#clientmessage "Direct link to clientMessage")
+
+#### Get Signature[​](#get-signature "Direct link to Get Signature")
+
+```ts
+get clientMessage(): string;
+
+```
+
+Sanitized message safe to forward to clients. Override in subclasses if a more specific default is appropriate.
+
+##### Returns[​](#returns-1 "Direct link to Returns")
+
+`string`
+
+#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`clientMessage`](./docs/api/appkit/Class.AppKitError.md#clientmessage)
+
+## Methods[​](#methods "Direct link to Methods")
+
+### toJSON()[​](#tojson "Direct link to toJSON()")
+
+```ts
+toJSON(): Record<string, unknown>;
+
+```
+
+Convert error to JSON for logging/serialization. Sensitive values in context are automatically redacted.
+
+#### Returns[​](#returns-2 "Direct link to Returns")
+
+`Record`<`string`, `unknown`>
+
+#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`toJSON`](./docs/api/appkit/Class.AppKitError.md#tojson)
+
+***
+
+### toString()[​](#tostring "Direct link to toString()")
+
+```ts
+toString(): string;
+
+```
+
+Create a human-readable string representation
+
+#### Returns[​](#returns-3 "Direct link to Returns")
+
+`string`
+
+#### Inherited from[​](#inherited-from-5 "Direct link to Inherited from")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`toString`](./docs/api/appkit/Class.AppKitError.md#tostring)

package/docs/api/appkit/Function.defineSchema.md

@@ -5,7 +5,7 @@ function defineSchema<TTables>(builder: (context: SchemaBuilderContext) => TTabl
 
 ```
 
-Compile one declared schema. The returned type keeps the table names the builder returned, so `crudRoutes` and `hooks` can name only real tables.
+Compile one declared schema. The returned type keeps the table names the builder returned, so `api.tables` and `hooks` can name only real tables.
 
 ## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
 

package/docs/api/appkit/Function.readEvalDataset.md

@@ -0,0 +1,21 @@
+# Function: readEvalDataset()
+
+```ts
+function readEvalDataset(client: WorkspaceClient, options: ReadEvalDatasetOptions): Promise<DatasetRow[]>;
+
+```
+
+Read a Databricks managed evaluation dataset (a Unity Catalog table with `inputs`/`expectations` columns) into rows, over the public SQL Statement Execution API. Reuses SQLWarehouseConnector for submit/poll/transform — its result transform already JSON-parses string columns into objects, so `inputs`/`expectations` come back as records whether the table stores them as JSON strings or structs.
+
+The Python `mlflow.genai.datasets` API needs a Spark session (no TS equivalent), so we read the backing table directly.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                                                    |
+| --------- | --------------------------------------------------------------------------------------- |
+| `client`  | [`WorkspaceClient`](./docs/api/appkit/Interface.WorkspaceClient.md)               |
+| `options` | [`ReadEvalDatasetOptions`](./docs/api/appkit/Interface.ReadEvalDatasetOptions.md) |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`Promise`<[`DatasetRow`](./docs/api/appkit/Interface.DatasetRow.md)\[]>

package/docs/api/appkit/Function.resolveWorkspaceClient.md

@@ -0,0 +1,18 @@
+# Function: resolveWorkspaceClient()
+
+```ts
+function resolveWorkspaceClient(options: ResolveDatabricksAuthOptions): WorkspaceClient | undefined;
+
+```
+
+Construct a Databricks `WorkspaceClient` for the eval runner — the object the SDK-backed connectors (e.g. `SQLWarehouseConnector`) take. An explicit host+token builds a PAT client; otherwise the profile (or ambient config) is used and the SDK resolves credentials, minting OAuth as needed. Returns `undefined` if construction throws (missing/invalid config).
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                                                                |
+| --------- | --------------------------------------------------------------------------------------------------- |
+| `options` | [`ResolveDatabricksAuthOptions`](./docs/api/appkit/Interface.ResolveDatabricksAuthOptions.md) |
+
+## Returns[​](#returns "Direct link to Returns")
+
+[`WorkspaceClient`](./docs/api/appkit/Interface.WorkspaceClient.md) | `undefined`

package/docs/api/appkit/Interface.AssertionHandle.md

@@ -11,7 +11,7 @@ atLeast(threshold: number): AssertionHandle;
 
 ```
 
-Soft assertion that passes only when the score is at least `threshold`.
+Set the pass threshold for a scored assertion: it passes only when the score is at least `threshold`. Keeps the current severity (gate unless also chained with `.soft()`).
 
 #### Parameters[​](#parameters "Direct link to Parameters")
 

package/docs/api/appkit/Interface.DatabaseValidationIssue.md

@@ -0,0 +1,21 @@
+# Interface: DatabaseValidationIssue
+
+One rejected field; `path` names public columns, never their values.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### message[​](#message "Direct link to message")
+
+```ts
+readonly message: string;
+
+```
+
+***
+
+### path[​](#path "Direct link to path")
+
+```ts
+readonly path: readonly string[];
+
+```

package/docs/api/appkit/Interface.DatasetRow.md

@@ -0,0 +1,21 @@
+# Interface: DatasetRow
+
+One row of a managed evaluation dataset. `inputs` are the kwargs passed to the agent for the turn; `expectations` (when present) is the row's ground truth / guidelines. Mirrors the `{inputs, expectations}` shape of `mlflow.genai` datasets and of the Unity Catalog table backing a managed eval dataset.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### expectations?[​](#expectations "Direct link to expectations?")
+
+```ts
+optional expectations: Record<string, unknown>;
+
+```
+
+***
+
+### inputs[​](#inputs "Direct link to inputs")
+
+```ts
+inputs: Record<string, unknown>;
+
+```

package/docs/api/appkit/Interface.EntityMutationHooks.md

@@ -0,0 +1,173 @@
+# Interface: EntityMutationHooks\<TTable>
+
+Mutation lifecycle for one entity. A before hook may return a replacement payload, which is revalidated against the trusted schema before it is persisted. Every hook, the mutation, and any write a hook issues through `ctx.app.database` share one transaction, so a rejection anywhere rolls all of them back. Throw `DatabaseValidationError` to answer a generated route with `422`; any other failure stays an opaque server error.
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter              | Default type |
+| --------------------------- | ------------ |
+| `TTable` *extends* `string` | `string`     |
+
+## Methods[​](#methods "Direct link to Methods")
+
+### afterCreate()?[​](#aftercreate "Direct link to afterCreate()?")
+
+```ts
+optional afterCreate(row: FacetOf<TTable, "row">, context: HookContext): MaybePromise<void>;
+
+```
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                              |
+| --------- | ----------------------------------------------------------------- |
+| `row`     | `FacetOf`<`TTable`, `"row"`>                                      |
+| `context` | [`HookContext`](./docs/api/appkit/Interface.HookContext.md) |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`MaybePromise`<`void`>
+
+***
+
+### afterDelete()?[​](#afterdelete "Direct link to afterDelete()?")
+
+```ts
+optional afterDelete(id: IdValue, context: HookContext): MaybePromise<void>;
+
+```
+
+#### Parameters[​](#parameters-1 "Direct link to Parameters")
+
+| Parameter | Type                                                              |
+| --------- | ----------------------------------------------------------------- |
+| `id`      | `IdValue`                                                         |
+| `context` | [`HookContext`](./docs/api/appkit/Interface.HookContext.md) |
+
+#### Returns[​](#returns-1 "Direct link to Returns")
+
+`MaybePromise`<`void`>
+
+***
+
+### afterUpdate()?[​](#afterupdate "Direct link to afterUpdate()?")
+
+```ts
+optional afterUpdate(row: FacetOf<TTable, "row">, context: HookContext): MaybePromise<void>;
+
+```
+
+#### Parameters[​](#parameters-2 "Direct link to Parameters")
+
+| Parameter | Type                                                              |
+| --------- | ----------------------------------------------------------------- |
+| `row`     | `FacetOf`<`TTable`, `"row"`>                                      |
+| `context` | [`HookContext`](./docs/api/appkit/Interface.HookContext.md) |
+
+#### Returns[​](#returns-2 "Direct link to Returns")
+
+`MaybePromise`<`void`>
+
+***
+
+### afterUpsert()?[​](#afterupsert "Direct link to afterUpsert()?")
+
+```ts
+optional afterUpsert(row: FacetOf<TTable, "row">, context: HookContext): MaybePromise<void>;
+
+```
+
+#### Parameters[​](#parameters-3 "Direct link to Parameters")
+
+| Parameter | Type                                                              |
+| --------- | ----------------------------------------------------------------- |
+| `row`     | `FacetOf`<`TTable`, `"row"`>                                      |
+| `context` | [`HookContext`](./docs/api/appkit/Interface.HookContext.md) |
+
+#### Returns[​](#returns-3 "Direct link to Returns")
+
+`MaybePromise`<`void`>
+
+***
+
+### beforeCreate()?[​](#beforecreate "Direct link to beforeCreate()?")
+
+```ts
+optional beforeCreate(values: FacetOf<TTable, "insert">, context: HookContext): MaybePromise<void | FacetOf<TTable, "insert">>;
+
+```
+
+#### Parameters[​](#parameters-4 "Direct link to Parameters")
+
+| Parameter | Type                                                              |
+| --------- | ----------------------------------------------------------------- |
+| `values`  | `FacetOf`<`TTable`, `"insert"`>                                   |
+| `context` | [`HookContext`](./docs/api/appkit/Interface.HookContext.md) |
+
+#### Returns[​](#returns-4 "Direct link to Returns")
+
+`MaybePromise`<`void` | `FacetOf`<`TTable`, `"insert"`>>
+
+***
+
+### beforeDelete()?[​](#beforedelete "Direct link to beforeDelete()?")
+
+```ts
+optional beforeDelete(id: IdValue, context: HookContext): MaybePromise<void>;
+
+```
+
+#### Parameters[​](#parameters-5 "Direct link to Parameters")
+
+| Parameter | Type                                                              |
+| --------- | ----------------------------------------------------------------- |
+| `id`      | `IdValue`                                                         |
+| `context` | [`HookContext`](./docs/api/appkit/Interface.HookContext.md) |
+
+#### Returns[​](#returns-5 "Direct link to Returns")
+
+`MaybePromise`<`void`>
+
+***
+
+### beforeUpdate()?[​](#beforeupdate "Direct link to beforeUpdate()?")
+
+```ts
+optional beforeUpdate(
+   id: IdValue, 
+   values: FacetOf<TTable, "update">, 
+context: HookContext): MaybePromise<void | FacetOf<TTable, "update">>;
+
+```
+
+#### Parameters[​](#parameters-6 "Direct link to Parameters")
+
+| Parameter | Type                                                              |
+| --------- | ----------------------------------------------------------------- |
+| `id`      | `IdValue`                                                         |
+| `values`  | `FacetOf`<`TTable`, `"update"`>                                   |
+| `context` | [`HookContext`](./docs/api/appkit/Interface.HookContext.md) |
+
+#### Returns[​](#returns-6 "Direct link to Returns")
+
+`MaybePromise`<`void` | `FacetOf`<`TTable`, `"update"`>>
+
+***
+
+### beforeUpsert()?[​](#beforeupsert "Direct link to beforeUpsert()?")
+
+```ts
+optional beforeUpsert(values: FacetOf<TTable, "insert">, context: HookContext): MaybePromise<void | FacetOf<TTable, "insert">>;
+
+```
+
+#### Parameters[​](#parameters-7 "Direct link to Parameters")
+
+| Parameter | Type                                                              |
+| --------- | ----------------------------------------------------------------- |
+| `values`  | `FacetOf`<`TTable`, `"insert"`>                                   |
+| `context` | [`HookContext`](./docs/api/appkit/Interface.HookContext.md) |
+
+#### Returns[​](#returns-7 "Direct link to Returns")
+
+`MaybePromise`<`void` | `FacetOf`<`TTable`, `"insert"`>>

package/docs/api/appkit/Interface.EvalDefinition.md

@@ -15,6 +15,34 @@ Target agent id. Defaults to the eval's parent `server/agents/<id>` dir.
 
 ***
 
+### dataset?[​](#dataset "Direct link to dataset?")
+
+```ts
+optional dataset: {
+  limit?: number;
+  table: string;
+};
+
+```
+
+Run this eval once per row of a Databricks managed evaluation dataset (a Unity Catalog `catalog.schema.table` with `inputs`/`expectations` columns). Each row is bound to `t.input`/`t.expected`. Requires the runner to have a workspace client + warehouse (`--warehouse-id`). Omit for a single-run eval.
+
+#### limit?[​](#limit "Direct link to limit?")
+
+```ts
+optional limit: number;
+
+```
+
+#### table[​](#table "Direct link to table")
+
+```ts
+table: string;
+
+```
+
+***
+
 ### description?[​](#description "Direct link to description?")
 
 ```ts

package/docs/api/appkit/Interface.EvalDriver.md

@@ -4,6 +4,21 @@ Abstraction over how the agent is driven. The HTTP driver posts to a running app
 
 ## Methods[​](#methods "Direct link to Methods")
 
+### reset()?[​](#reset "Direct link to reset()?")
+
+```ts
+optional reset(): void;
+
+```
+
+Drop the current conversation so the next `send` starts a fresh thread. Optional: drivers without a session concept omit it.
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`void`
+
+***
+
 ### send()[​](#send "Direct link to send()")
 
 ```ts
@@ -17,6 +32,6 @@ send(message: string): Promise<DriveResult>;
 | --------- | -------- |
 | `message` | `string` |
 
-#### Returns[​](#returns "Direct link to Returns")
+#### Returns[​](#returns-1 "Direct link to Returns")
 
 `Promise`<[`DriveResult`](./docs/api/appkit/Interface.DriveResult.md)>

package/docs/api/appkit/Interface.HookApp.md

@@ -0,0 +1,12 @@
+# Interface: HookApp
+
+The only capability a hook receives: entities bound to its transaction.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### database[​](#database "Direct link to database")
+
+```ts
+readonly database: TransactionClient;
+
+```

package/docs/api/appkit/Interface.HookContext.md

@@ -0,0 +1,21 @@
+# Interface: HookContext
+
+Which entity is being mutated, and the surface a hook may write through.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### app[​](#app "Direct link to app")
+
+```ts
+readonly app: HookApp;
+
+```
+
+***
+
+### entity[​](#entity "Direct link to entity")
+
+```ts
+readonly entity: string;
+
+```

package/docs/api/appkit/Interface.ReadEvalDatasetOptions.md

@@ -0,0 +1,34 @@
+# Interface: ReadEvalDatasetOptions
+
+## Properties[​](#properties "Direct link to Properties")
+
+### limit?[​](#limit "Direct link to limit?")
+
+```ts
+optional limit: number;
+
+```
+
+Optional row cap.
+
+***
+
+### table[​](#table "Direct link to table")
+
+```ts
+table: string;
+
+```
+
+Fully-qualified UC table: `catalog.schema.table`.
+
+***
+
+### warehouseId[​](#warehouseid "Direct link to warehouseId")
+
+```ts
+warehouseId: string;
+
+```
+
+SQL warehouse id to run the read against.

package/docs/api/appkit/Interface.ReadSerializerContext.md

@@ -0,0 +1,21 @@
+# Interface: ReadSerializerContext
+
+Which entity and generated operation produced the row being shaped.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### entity[​](#entity "Direct link to entity")
+
+```ts
+readonly entity: string;
+
+```
+
+***
+
+### operation[​](#operation "Direct link to operation")
+
+```ts
+readonly operation: "detail" | "list";
+
+```

package/docs/api/appkit/Interface.RunEvalOptions.md

@@ -24,6 +24,17 @@ Stable id for the eval (e.g. its file path relative to the evals dir).
 
 ***
 
+### row?[​](#row "Direct link to row?")
+
+```ts
+optional row: DatasetRow;
+
+```
+
+Dataset row bound to `t.input`/`t.expected` for dataset-driven evals.
+
+***
+
 ### strict?[​](#strict "Direct link to strict?")
 
 ```ts

package/docs/api/appkit/Interface.RunEvalsOptions.md

@@ -190,3 +190,25 @@ optional timeoutMs: number;
 ```
 
 Per-turn wall-clock timeout (ms) before a turn is failed. Defaults to 120s.
+
+***
+
+### warehouseId?[​](#warehouseid "Direct link to warehouseId?")
+
+```ts
+optional warehouseId: string;
+
+```
+
+SQL warehouse id used to read managed evaluation datasets.
+
+***
+
+### workspaceClient?[​](#workspaceclient "Direct link to workspaceClient?")
+
+```ts
+optional workspaceClient: WorkspaceClient;
+
+```
+
+Workspace client used to read managed evaluation datasets (for evals that declare `dataset`). Required alongside [warehouseId](#warehouseid) for those evals.