@atlanai/sdk 0.1.0 → 0.2.1

package/README.md

@@ -1,45 +1,113 @@
 # @atlanai/sdk
 
-TypeScript management client for the public Atlan Agent Gateway API. Use
-`AtlanClient` for stable service namespaces. Generated clients are available
-below `client.raw` and package subpaths under `@atlanai/sdk/raw/*`.
+TypeScript/JavaScript SDK for the Atlan Agent Gateway: manage agents, skills,
+sessions, and workspaces, and optionally trace what your agents do.
 
-Tracing is an authored follow-on and is not included in the current TypeScript
-package. It will not be generated from the management OpenAPI contract.
+## Install
 
-## Local install
+```bash
+npm install @atlanai/sdk
+```
 
-Build the package from the repository root:
+## Quickstart
 
-```bash
-npm --prefix typescript ci --ignore-scripts
-npm --prefix typescript run build
+```typescript
+import { AtlanClient } from "@atlanai/sdk";
+
+const client = new AtlanClient({
+  gatewayOrigin: "https://<your-gateway-host>",
+  bearerToken: "<your-api-token>",
+});
+
+const agent = await client.agents.create({
+  name: "support-triage",
+  workspaceId: "workspace_01example",
+});
+
+const page = await client.agents.list({ limit: 10 });
+console.log(`${page.items.length} agents`);
 ```
 
-Install the built checkout into a local project:
+Methods read as `client.<resource>.<action>` — `client.agents.get(agentId)`,
+`client.sessions.messages.create(sessionId, {...})`, and so on. Every public
+Agent Gateway operation is reachable this way; nothing requires reaching into
+a generated client directly.
 
-```bash
-npm install /absolute/path/to/sdk/typescript --ignore-scripts
+Pass a default workspace once instead of repeating it on every call:
+
+```typescript
+const client = new AtlanClient({ gatewayOrigin, bearerToken, workspace: "workspace_01example" });
 ```
 
-Pass the Gateway origin and bearer explicitly:
+## Start an eval run
+
+Resolve an existing dataset by artifact ID or exact name, then create the
+Registry experiment before the runner emits any traces:
 
 ```typescript
-import { AtlanClient, rawAgent } from "@atlanai/sdk";
+import { createContextManifest, startExperiment } from "@atlanai/sdk";
+import { propagateAttributes } from "@atlanai/sdk/tracing";
 
-declare const process: { env: Record<string, string | undefined> };
+const contextManifest = await createContextManifest([{
+  kind: "file",
+  name: "CLAUDE.md",
+  version: "git:0123456789abcdef0123456789abcdef01234567",
+  digest: `sha256:${"0".repeat(64)}`,
+}]);
 
-const client = new AtlanClient({
-  gatewayOrigin: process.env.ATLANAI_GATEWAY_URL!,
-  bearerToken: process.env.ATLANAI_TOKEN!,
+const run = await startExperiment(
+  client,
+  "conversational-studio-daily", // exact name, or dataset_... ID
+  { name: "candidate-run", config: { model: "example-model" } },
+  { contextManifest },
+);
+
+await propagateAttributes(run.traceOptions, () => existingRunner());
+```
+
+`run.experiment` is the generated create response and `run.id` is its
+`experimentId`. The helper pins the resolved dataset version and context
+manifest in the immutable experiment config. Execution, result upload,
+summarization, and terminal status remain the existing `client.experiments`
+operations.
+
+## Tracing
+
+```typescript
+import * as atlan from "@atlanai/sdk/tracing";
+
+const tracer = atlan.init({ apiKey: "<your-tracing-key>", workspaceId: "workspace_01example" });
+
+await tracer.startAsCurrentSpan("handle-request", { asType: "task" }, async (span) => {
+  span.update({ model: "claude-sonnet-5", usage: { inputTokens: 120, outputTokens: 40 } });
 });
+```
+
+Tracing has its own API key and lifecycle — it does not reuse the management
+client's bearer token or transport. It ships as a separate subpath
+(`@atlanai/sdk/tracing`) so importing it doesn't pull OpenTelemetry into a
+management-only bundle.
+
+## Errors
+
+Every non-2xx response rejects with `AtlanAPIError`, with `.status`, `.code`,
+and (where the gateway includes one) `.traceId`:
 
-const agentsApi = client.agents.apis.agents as rawAgent.AgentsApi;
-const page = await agentsApi.agentListAgents({ limit: 10 });
-console.log(page.items.length);
+```typescript
+import { AtlanAPIError } from "@atlanai/sdk";
+
+try {
+  await client.agents.get("agent_does_not_exist");
+} catch (error) {
+  if (error instanceof AtlanAPIError) {
+    console.log(error.status, error.code);
+  }
+}
 ```
 
-See [the complete local setup guide](../docs/getting-started.md) for direct
-Registry configuration and the current typed-namespace follow-up. The
-[generated TypeScript reference](../docs/reference/README.md) covers every raw
-operation and model.
+## Runtimes
+
+Node ≥20. The tracing subpath is written to also run in non-Node runtimes
+like Cloudflare Workers — pass configuration to `init()` explicitly there
+rather than relying on environment variables, since Workers has no ambient
+environment.

package/dist/client.js

@@ -37,6 +37,7 @@ exports.AtlanClient = exports.ServiceNamespace = exports.WORKSPACE_HEADER = void
 exports.createService = createService;
 const agentRaw = __importStar(require("./raw/agent/index"));
 const apiRaw = __importStar(require("./raw/api/index"));
+const evalRaw = __importStar(require("./raw/eval/index"));
 const fileRaw = __importStar(require("./raw/file/index"));
 const mcpRaw = __importStar(require("./raw/mcp/index"));
 const modelRaw = __importStar(require("./raw/model/index"));
@@ -111,7 +112,7 @@ function forwardOperations(namespace, operationMethods) {
     // operation reads in the contract and how a caller would guess it —
     // `client.agents.createAgent(...)`. Both spellings resolve, because the long
     // one is what every existing caller and published example uses, and across
-    // all 189 operations no short name collides with another, with an OpenAPI
+    // all 221 operations no short name collides with another, with an OpenAPI
     // tag, or with a property of the namespace.
     const prefixed = (property) => namespace.name + property.charAt(0).toUpperCase() + property.slice(1);
     return new Proxy(namespace, {
@@ -187,6 +188,7 @@ class AtlanClient {
             model: modelRaw,
             api: apiRaw,
             otel: otelRaw,
+            eval: evalRaw,
         };
         const namespaces = {};
         for (const service of operations_1.operationManifest.services) {

package/dist/evals.d.ts

@@ -0,0 +1,46 @@
+/** Small lifecycle helpers for evaluation runners. */
+import { AtlanClient } from "./client";
+export declare const CONTEXT_MANIFEST_SCHEMA = "atlan.eval.context-manifest/v1";
+export interface ContextItem {
+    kind: string;
+    name: string;
+    digest: string;
+    version: string;
+    artifactId?: string;
+    versionOrdinal?: number;
+}
+export interface ContextManifestItem {
+    kind: string;
+    name: string;
+    digest: string;
+    version: string;
+    artifact_id?: string;
+    version_ordinal?: number;
+}
+export interface ContextManifest {
+    schema_version: typeof CONTEXT_MANIFEST_SCHEMA;
+    items: readonly ContextManifestItem[];
+    digest: string;
+}
+/** Build the same canonical, order-independent context manifest as the Python SDK. */
+export declare function createContextManifest(input: readonly ContextItem[]): Promise<ContextManifest>;
+/** Resolve one dataset by artifact ID or exact name, never fuzzy matching. */
+export declare function resolveDataset(client: AtlanClient, idOrExactName: string, workspaceId?: string): Promise<unknown>;
+export interface StartExperimentOptions {
+    contextManifest?: ContextManifest;
+}
+export declare class EvalRun {
+    readonly experiment: unknown;
+    readonly dataset: unknown;
+    readonly contextManifest?: ContextManifest | undefined;
+    constructor(experiment: unknown, dataset: unknown, contextManifest?: ContextManifest | undefined);
+    get id(): string;
+    get experimentId(): string;
+    /** Options for `propagateAttributes` from `@atlanai/sdk/tracing`. */
+    get traceOptions(): {
+        experimentId: string;
+        metadata?: Record<string, unknown>;
+    };
+}
+/** Create a running experiment over a dataset ID or exact dataset name. */
+export declare function startExperiment(client: AtlanClient, dataset: string, body: Readonly<Record<string, unknown>>, options?: StartExperimentOptions): Promise<EvalRun>;

package/dist/evals.js

@@ -0,0 +1,230 @@
+"use strict";
+/** Small lifecycle helpers for evaluation runners. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvalRun = exports.CONTEXT_MANIFEST_SCHEMA = void 0;
+exports.createContextManifest = createContextManifest;
+exports.resolveDataset = resolveDataset;
+exports.startExperiment = startExperiment;
+exports.CONTEXT_MANIFEST_SCHEMA = "atlan.eval.context-manifest/v1";
+const SHA256 = /^sha256:[0-9a-f]{64}$/;
+const CONTEXT_KIND = /^[a-z][a-z0-9_.-]{0,63}$/;
+const MAX_LIST_OFFSET = 10_000;
+function asResources(client) {
+    return client;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function field(value, name) {
+    return isRecord(value) ? value[name] : undefined;
+}
+function canonicalJson(value) {
+    const normalize = (item) => {
+        if (item === null || typeof item === "string" || typeof item === "boolean")
+            return item;
+        if (typeof item === "number") {
+            if (!Number.isFinite(item))
+                throw new Error("context manifest is not canonical JSON");
+            return item;
+        }
+        if (Array.isArray(item))
+            return item.map(normalize);
+        if (isRecord(item)) {
+            return Object.fromEntries(Object.keys(item)
+                .sort()
+                .map((key) => [key, normalize(item[key])]));
+        }
+        throw new Error("context manifest is not canonical JSON");
+    };
+    return JSON.stringify(normalize(value));
+}
+function validText(value, name, maximum) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > maximum ||
+        /[\r\n]/.test(value)) {
+        throw new Error(`${name} must be 1-${maximum} characters with no newlines`);
+    }
+}
+function manifestItem(item) {
+    if (!CONTEXT_KIND.test(item.kind)) {
+        throw new Error("context item kind must be a lowercase identifier");
+    }
+    validText(item.name, "context item name", 500);
+    if (!SHA256.test(item.digest)) {
+        throw new Error("context item digest must be sha256:<64 lowercase hex>");
+    }
+    validText(item.version, "context item version", 200);
+    if (item.version.toLowerCase() === "latest") {
+        throw new Error("context item version must be pinned; 'latest' is not a version");
+    }
+    if (item.artifactId !== undefined) {
+        validText(item.artifactId, "context item artifactId", 200);
+    }
+    if (item.versionOrdinal !== undefined &&
+        (!Number.isInteger(item.versionOrdinal) || item.versionOrdinal < 1)) {
+        throw new Error("context item versionOrdinal must be an integer of at least 1");
+    }
+    return {
+        kind: item.kind,
+        name: item.name,
+        digest: item.digest,
+        version: item.version,
+        ...(item.artifactId === undefined ? {} : { artifact_id: item.artifactId }),
+        ...(item.versionOrdinal === undefined ? {} : { version_ordinal: item.versionOrdinal }),
+    };
+}
+/** Build the same canonical, order-independent context manifest as the Python SDK. */
+async function createContextManifest(input) {
+    const items = input.map((item) => Object.freeze(manifestItem(item))).sort((left, right) => {
+        const leftJson = canonicalJson(left);
+        const rightJson = canonicalJson(right);
+        return leftJson < rightJson ? -1 : leftJson > rightJson ? 1 : 0;
+    });
+    const identities = new Set(items.map((item) => `${item.kind}\u0000${item.name}`));
+    if (identities.size !== items.length) {
+        throw new Error("context manifest has duplicate kind/name entries");
+    }
+    const body = { schema_version: exports.CONTEXT_MANIFEST_SCHEMA, items };
+    if (!globalThis.crypto?.subtle) {
+        throw new Error("Web Crypto is required to create a context manifest");
+    }
+    const hash = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonicalJson(body)));
+    const digest = "sha256:" + [...new Uint8Array(hash)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+    return Object.freeze({ ...body, items: Object.freeze(items), digest });
+}
+/** Resolve one dataset by artifact ID or exact name, never fuzzy matching. */
+async function resolveDataset(client, idOrExactName, workspaceId) {
+    if (!idOrExactName || idOrExactName.trim() !== idOrExactName) {
+        throw new Error("dataset must be a non-empty ID or exact name with no outer whitespace");
+    }
+    const resources = asResources(client);
+    const workspace = workspaceId ?? resources.workspace;
+    if (idOrExactName.startsWith("dataset_")) {
+        const dataset = await resources.datasets.get(idOrExactName);
+        if (workspace !== undefined && field(dataset, "workspaceId") !== workspace) {
+            throw new Error("dataset ID resolved outside the requested workspace");
+        }
+        return dataset;
+    }
+    const matches = [];
+    let offset = 0;
+    while (true) {
+        const page = await resources.datasets.list({ limit: 500, offset });
+        const rawItems = field(page, "items");
+        const items = Array.isArray(rawItems) ? rawItems : [];
+        matches.push(...items.filter((item) => field(item, "name") === idOrExactName &&
+            (workspace === undefined || field(item, "workspaceId") === workspace)));
+        if (matches.length > 1)
+            break;
+        offset += items.length;
+        const total = field(field(page, "page"), "total");
+        if (items.length === 0 || (typeof total === "number" && offset >= total))
+            break;
+        if (offset > MAX_LIST_OFFSET) {
+            throw new Error("dataset name resolution exceeded the list limit; pass the dataset ID");
+        }
+    }
+    if (matches.length === 0) {
+        const scope = workspace === undefined ? "" : ` in workspace '${workspace}'`;
+        throw new Error(`no dataset named '${idOrExactName}'${scope}`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`multiple datasets are named '${idOrExactName}'; pass the dataset ID`);
+    }
+    return matches[0];
+}
+class EvalRun {
+    experiment;
+    dataset;
+    contextManifest;
+    constructor(experiment, dataset, contextManifest) {
+        this.experiment = experiment;
+        this.dataset = dataset;
+        this.contextManifest = contextManifest;
+    }
+    get id() {
+        const id = field(this.experiment, "id");
+        if (typeof id !== "string" || id.length === 0) {
+            throw new Error("experiment create response did not contain an ID");
+        }
+        return id;
+    }
+    get experimentId() {
+        return this.id;
+    }
+    /** Options for `propagateAttributes` from `@atlanai/sdk/tracing`. */
+    get traceOptions() {
+        return {
+            experimentId: this.id,
+            ...(this.contextManifest === undefined
+                ? {}
+                : { metadata: { context_manifest_digest: this.contextManifest.digest } }),
+        };
+    }
+}
+exports.EvalRun = EvalRun;
+/** Create a running experiment over a dataset ID or exact dataset name. */
+async function startExperiment(client, dataset, body, options = {}) {
+    const resources = asResources(client);
+    const payload = { ...body };
+    const workspaceId = payload.workspaceId ?? resources.workspace;
+    if (typeof workspaceId !== "string" || workspaceId.length === 0) {
+        throw new Error("workspaceId is required in the body or on the client");
+    }
+    if (resources.workspace !== undefined &&
+        payload.workspaceId !== undefined &&
+        payload.workspaceId !== resources.workspace) {
+        throw new Error("body workspaceId differs from the client's workspace");
+    }
+    payload.workspaceId = workspaceId;
+    const resolved = await resolveDataset(client, dataset, workspaceId);
+    const resolvedId = field(resolved, "id");
+    if (typeof resolvedId !== "string" || resolvedId.length === 0) {
+        throw new Error("dataset response did not contain an ID");
+    }
+    if (payload.datasetId !== undefined && payload.datasetId !== resolvedId) {
+        throw new Error("body datasetId differs from the resolved dataset");
+    }
+    payload.datasetId = resolvedId;
+    if (payload.experimentStatus !== undefined && payload.experimentStatus !== "running") {
+        throw new Error("startExperiment only creates running experiments");
+    }
+    payload.experimentStatus = "running";
+    const rawConfig = payload.config ?? {};
+    if (!isRecord(rawConfig))
+        throw new Error("experiment config must be an object");
+    const config = { ...rawConfig };
+    const datasetPin = Object.fromEntries(Object.entries({
+        id: resolvedId,
+        version_ordinal: field(resolved, "versionOrdinal"),
+        content_hash_hex: field(resolved, "contentHashHex"),
+    }).filter(([, value]) => value !== undefined && value !== null));
+    if (config.registry_dataset !== undefined &&
+        canonicalJson(config.registry_dataset) !== canonicalJson(datasetPin)) {
+        throw new Error("config registry_dataset differs from the resolved dataset version");
+    }
+    config.registry_dataset = datasetPin;
+    const contextManifest = options.contextManifest;
+    if (contextManifest !== undefined) {
+        if (config.context_manifest !== undefined &&
+            canonicalJson(config.context_manifest) !== canonicalJson(contextManifest)) {
+            throw new Error("config context_manifest differs from the supplied manifest");
+        }
+        if (config.context_manifest_digest !== undefined &&
+            config.context_manifest_digest !== contextManifest.digest) {
+            throw new Error("config context_manifest_digest differs from the supplied manifest");
+        }
+        config.context_manifest = contextManifest;
+        config.context_manifest_digest = contextManifest.digest;
+    }
+    payload.config = config;
+    const experiment = await resources.experiments.create(payload);
+    const run = new EvalRun(experiment, resolved, contextManifest);
+    void run.id;
+    const responseDatasetId = field(experiment, "datasetId");
+    if (responseDatasetId !== undefined && responseDatasetId !== resolvedId) {
+        throw new Error("experiment create response contains a different dataset ID");
+    }
+    return run;
+}

package/dist/index.d.ts

@@ -5,8 +5,11 @@ export type { Resource, ResourceOperation } from "./resources";
 export { AtlanAPIError } from "./errors";
 export { operationManifest, operations } from "./operations";
 export type { Operation, OperationManifest, ServiceContract } from "./operations";
+export { CONTEXT_MANIFEST_SCHEMA, EvalRun, createContextManifest, resolveDataset, startExperiment, } from "./evals";
+export type { ContextItem, ContextManifest, ContextManifestItem, StartExperimentOptions, } from "./evals";
 export * as rawAgent from "./raw/agent/index";
 export * as rawAPI from "./raw/api/index";
+export * as rawEval from "./raw/eval/index";
 export * as rawFile from "./raw/file/index";
 export * as rawMCP from "./raw/mcp/index";
 export * as rawModel from "./raw/model/index";

package/dist/index.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.rawSkill = exports.rawSecret = exports.rawRegistry = exports.rawOTel = exports.rawModel = exports.rawMCP = exports.rawFile = exports.rawAPI = exports.rawAgent = exports.operations = exports.operationManifest = exports.AtlanAPIError = exports.resourceMap = exports.buildResources = exports.createService = exports.ServiceNamespace = exports.AtlanClient = void 0;
+exports.rawSkill = exports.rawSecret = exports.rawRegistry = exports.rawOTel = exports.rawModel = exports.rawMCP = exports.rawFile = exports.rawEval = exports.rawAPI = exports.rawAgent = exports.startExperiment = exports.resolveDataset = exports.createContextManifest = exports.EvalRun = exports.CONTEXT_MANIFEST_SCHEMA = exports.operations = exports.operationManifest = exports.AtlanAPIError = exports.resourceMap = exports.buildResources = exports.createService = exports.ServiceNamespace = exports.AtlanClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "AtlanClient", { enumerable: true, get: function () { return client_1.AtlanClient; } });
 Object.defineProperty(exports, "ServiceNamespace", { enumerable: true, get: function () { return client_1.ServiceNamespace; } });
@@ -46,8 +46,15 @@ Object.defineProperty(exports, "AtlanAPIError", { enumerable: true, get: functio
 var operations_1 = require("./operations");
 Object.defineProperty(exports, "operationManifest", { enumerable: true, get: function () { return operations_1.operationManifest; } });
 Object.defineProperty(exports, "operations", { enumerable: true, get: function () { return operations_1.operations; } });
+var evals_1 = require("./evals");
+Object.defineProperty(exports, "CONTEXT_MANIFEST_SCHEMA", { enumerable: true, get: function () { return evals_1.CONTEXT_MANIFEST_SCHEMA; } });
+Object.defineProperty(exports, "EvalRun", { enumerable: true, get: function () { return evals_1.EvalRun; } });
+Object.defineProperty(exports, "createContextManifest", { enumerable: true, get: function () { return evals_1.createContextManifest; } });
+Object.defineProperty(exports, "resolveDataset", { enumerable: true, get: function () { return evals_1.resolveDataset; } });
+Object.defineProperty(exports, "startExperiment", { enumerable: true, get: function () { return evals_1.startExperiment; } });
 exports.rawAgent = __importStar(require("./raw/agent/index"));
 exports.rawAPI = __importStar(require("./raw/api/index"));
+exports.rawEval = __importStar(require("./raw/eval/index"));
 exports.rawFile = __importStar(require("./raw/file/index"));
 exports.rawMCP = __importStar(require("./raw/mcp/index"));
 exports.rawModel = __importStar(require("./raw/model/index"));