@databricks/appkit 0.71.0 → 0.73.0

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

@@ -0,0 +1,74 @@
+# Interface: EvalDefinition
+
+A single eval, default-exported from a `*.eval.ts` file.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### agent?[​](#agent "Direct link to agent?")
+
+```ts
+optional agent: string;
+
+```
+
+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
+optional description: string;
+
+```
+
+Short human description, shown in reports.
+
+## Methods[​](#methods "Direct link to Methods")
+
+### test()[​](#test "Direct link to test()")
+
+```ts
+test(t: TestContext): void | Promise<void>;
+
+```
+
+The eval body: drive the agent and assert on its behavior.
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                              |
+| --------- | ----------------------------------------------------------------- |
+| `t`       | [`TestContext`](./docs/api/appkit/Interface.TestContext.md) |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`void` | `Promise`<`void`>

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

@@ -0,0 +1,37 @@
+# Interface: EvalDriver
+
+Abstraction over how the agent is driven. The HTTP driver posts to a running app's agents endpoint; future drivers (in-process) implement the same shape.
+
+## 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
+send(message: string): Promise<DriveResult>;
+
+```
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type     |
+| --------- | -------- |
+| `message` | `string` |
+
+#### Returns[​](#returns-1 "Direct link to Returns")
+
+`Promise`<[`DriveResult`](./docs/api/appkit/Interface.DriveResult.md)>

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

@@ -0,0 +1,83 @@
+# Interface: EvalResult
+
+The outcome of running one eval.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### assertions[​](#assertions "Direct link to assertions")
+
+```ts
+assertions: AssertionResult[];
+
+```
+
+***
+
+### description?[​](#description "Direct link to description?")
+
+```ts
+optional description: string;
+
+```
+
+***
+
+### error?[​](#error "Direct link to error?")
+
+```ts
+optional error: string;
+
+```
+
+Set when the eval threw before completing.
+
+***
+
+### id[​](#id "Direct link to id")
+
+```ts
+id: string;
+
+```
+
+***
+
+### passed[​](#passed "Direct link to passed")
+
+```ts
+passed: boolean;
+
+```
+
+True when all gates passed (and, under strict, all soft assertions too).
+
+***
+
+### skipped?[​](#skipped "Direct link to skipped?")
+
+```ts
+optional skipped: {
+  reason?: string;
+};
+
+```
+
+Set when the eval called `t.skip`.
+
+#### reason?[​](#reason "Direct link to reason?")
+
+```ts
+optional reason: string;
+
+```
+
+***
+
+### traceId?[​](#traceid "Direct link to traceId?")
+
+```ts
+optional traceId: string;
+
+```
+
+MLflow trace id of the eval's last turn, for attaching assessments.

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

@@ -0,0 +1,46 @@
+# Interface: EvalRunSummary
+
+## Properties[​](#properties "Direct link to Properties")
+
+### mlflow?[​](#mlflow "Direct link to mlflow?")
+
+```ts
+optional mlflow: {
+  finish: FinishOutcome;
+  report: ReportOutcome;
+  runId: string;
+};
+
+```
+
+Present when an MLflow evaluation run was created.
+
+#### finish[​](#finish "Direct link to finish")
+
+```ts
+finish: FinishOutcome;
+
+```
+
+#### report[​](#report "Direct link to report")
+
+```ts
+report: ReportOutcome;
+
+```
+
+#### runId[​](#runid "Direct link to runId")
+
+```ts
+runId: string;
+
+```
+
+***
+
+### results[​](#results "Direct link to results")
+
+```ts
+results: EvalResult[];
+
+```

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

@@ -0,0 +1,48 @@
+# Interface: EvalSummary
+
+## Properties[​](#properties "Direct link to Properties")
+
+### allPassed[​](#allpassed "Direct link to allPassed")
+
+```ts
+allPassed: boolean;
+
+```
+
+True when no eval failed (skips don't count as failures).
+
+***
+
+### failed[​](#failed "Direct link to failed")
+
+```ts
+failed: number;
+
+```
+
+***
+
+### passed[​](#passed "Direct link to passed")
+
+```ts
+passed: number;
+
+```
+
+***
+
+### skipped[​](#skipped "Direct link to skipped")
+
+```ts
+skipped: number;
+
+```
+
+***
+
+### total[​](#total "Direct link to total")
+
+```ts
+total: number;
+
+```

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.HttpDriverOptions.md

@@ -0,0 +1,67 @@
+# Interface: HttpDriverOptions
+
+## Properties[​](#properties "Direct link to Properties")
+
+### agent?[​](#agent "Direct link to agent?")
+
+```ts
+optional agent: string;
+
+```
+
+Agent alias to target. Omit to use the app's default agent.
+
+***
+
+### baseUrl[​](#baseurl "Direct link to baseUrl")
+
+```ts
+baseUrl: string;
+
+```
+
+Base URL of the running app, e.g. `http://localhost:3000`.
+
+***
+
+### headers?[​](#headers "Direct link to headers?")
+
+```ts
+optional headers: Record<string, string>;
+
+```
+
+Extra request headers (e.g. auth for a deployed app).
+
+***
+
+### mlflowRunId?[​](#mlflowrunid "Direct link to mlflowRunId?")
+
+```ts
+optional mlflowRunId: string;
+
+```
+
+MLflow run id to link each turn's trace to (for evaluation runs).
+
+***
+
+### path?[​](#path "Direct link to path?")
+
+```ts
+optional path: string;
+
+```
+
+Chat endpoint path. Defaults to `/api/agents/chat`.
+
+***
+
+### timeoutMs?[​](#timeoutms "Direct link to timeoutMs?")
+
+```ts
+optional timeoutMs: number;
+
+```
+
+Max wall-clock time for a single turn before it is abandoned as a failed turn (`succeeded: false`). Without this a hung agent — a blocked tool, a stalled model — never ends the SSE stream (heartbeats keep it alive), so the read loop spins forever and wedges the whole sequential suite. Defaults to 120s.

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

@@ -0,0 +1,34 @@
+# Interface: JudgeConfig
+
+## Properties[​](#properties "Direct link to Properties")
+
+### client[​](#client "Direct link to client")
+
+```ts
+client: MlflowClient;
+
+```
+
+Client for the workspace hosting the judge serving endpoint.
+
+***
+
+### model[​](#model "Direct link to model")
+
+```ts
+model: string;
+
+```
+
+Serving endpoint name used as the judge model.
+
+***
+
+### token[​](#token "Direct link to token")
+
+```ts
+token: string;
+
+```
+
+Bearer token for the serving endpoint.

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

@@ -0,0 +1,21 @@
+# Interface: JudgeScore
+
+A normalized judge result. `score` is 0..1.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### rationale?[​](#rationale "Direct link to rationale?")
+
+```ts
+optional rationale: string;
+
+```
+
+***
+
+### score[​](#score "Direct link to score")
+
+```ts
+score: number;
+
+```

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

@@ -0,0 +1,34 @@
+# Interface: MatchResult
+
+Result of a deterministic matcher run against a value.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### detail?[​](#detail "Direct link to detail?")
+
+```ts
+optional detail: string;
+
+```
+
+Human-readable explanation, shown on failure.
+
+***
+
+### pass[​](#pass "Direct link to pass")
+
+```ts
+pass: boolean;
+
+```
+
+***
+
+### score?[​](#score "Direct link to score?")
+
+```ts
+optional score: number;
+
+```
+
+Optional 0..1 score for scored matchers (similarity, judges).

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

@@ -0,0 +1,30 @@
+# Interface: PostResult
+
+Structured result for a best-effort POST that must not throw.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### error?[​](#error "Direct link to error?")
+
+```ts
+optional error: string;
+
+```
+
+***
+
+### ok[​](#ok "Direct link to ok")
+
+```ts
+ok: boolean;
+
+```
+
+***
+
+### status?[​](#status "Direct link to status?")
+
+```ts
+optional status: number;
+
+```