@amigo-ai/platform-sdk 0.39.0 → 0.41.0

package/dist/resources/prompt-logs.js

@@ -0,0 +1,86 @@
+import { WorkspaceScopedResource, extractData } from './base.js';
+/**
+ * Prompt-log read surface — full LLM input/output (system prompt,
+ * conversation history, tool catalog, model, response) per turn for
+ * auditing, debugging, and post-hoc trace analysis.
+ *
+ * Reads the Delta ``world_events`` ledger via Databricks SQL (typical
+ * latency 1-5s, 15s ceiling). **Admin or owner role required** —
+ * responses can include PHI from prompt history.
+ *
+ * The canonical filter is ``conversation_id`` (UUID from
+ * ``world.entities``) which works across voice / text / sim / scribe
+ * modalities. ``call_sid`` remains for legacy callers and external
+ * systems holding the SID directly. The two are mutually exclusive.
+ *
+ * @example
+ * ```ts
+ * // Cross-modality: filter by conversation entity UUID.
+ * const page = await client.promptLogs.list({
+ *   conversation_id: '<entity-uuid>',
+ *   limit: 50,
+ * })
+ *
+ * // Direct call SID (Twilio CA-SID for voice).
+ * const callPage = await client.promptLogs.list({
+ *   call_sid: 'CA01a2b3...',
+ *   prompt_type: 'engage_user',
+ * })
+ *
+ * // Auto-paged sweep over a workspace's last 7 days
+ * for await (const entry of client.promptLogs.listAutoPaging({
+ *   prompt_type: 'navigation',
+ * })) {
+ *   console.log(entry.event_id, entry.state_name, entry.llm_model)
+ * }
+ * ```
+ */
+export class PromptLogsResource extends WorkspaceScopedResource {
+    /**
+     * One page of prompt-log entries, newest-first.
+     *
+     * When ``params.conversation_id`` is supplied, the response surfaces
+     * ``resolved_call_sid`` (the call_sid the lookup mapped to) and
+     * ``resolved_conversation_kind`` (``"call"`` for voice/sim/scribe,
+     * ``"conversation"`` for text/sms/whatsapp/email) so you can drill
+     * into per-call surfaces afterward without re-querying
+     * ``world.entities``.
+     *
+     * When no selectivity-bearing filter is supplied (no conversation_id /
+     * call_sid / time range), the query is auto-capped to the last 7 days.
+     * The applied window is reported in ``applied_time_window_days``.
+     */
+    async list(params) {
+        return extractData(await this.client.GET('/v1/{workspace_id}/prompt-logs', {
+            params: { path: { workspace_id: this.workspaceId }, query: params },
+        }));
+    }
+    /**
+     * Auto-paginating async iterator over prompt-log entries. Walks
+     * ``next_offset`` until ``has_more`` is false, yielding individual
+     * entries. Use this when consuming logs at scale (e.g. nightly
+     * backfills) rather than rendering one page in a UI.
+     *
+     * Bounded by the same per-call hard caps as ``list`` (200 items per
+     * page, 10,000 cumulative offset).
+     */
+    async *listAutoPaging(params) {
+        let offset = 0;
+        while (true) {
+            const page = await this.list({ ...params, offset });
+            for (const entry of page.items) {
+                yield entry;
+            }
+            if (!page.has_more || page.next_offset == null) {
+                return;
+            }
+            // Advance to the offset the server told us to use; guard against a
+            // non-advancing token to avoid an infinite loop on a buggy backend.
+            if (page.next_offset === offset) {
+                return;
+            }
+            offset = page.next_offset;
+        }
+    }
+}
+//# sourceMappingURL=prompt-logs.js.map

package/dist/resources/prompt-logs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-logs.js","sourceRoot":"","sources":["../../src/resources/prompt-logs.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAgBhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,OAAO,kBAAmB,SAAQ,uBAAuB;IAC7D;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,IAAI,CAAC,MAA6B;QACtC,OAAO,WAAW,CAChB,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,gCAAgC,EAAE;YACtD,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,YAAY,EAAE,IAAI,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE;SACpE,CAAC,CACH,CAAA;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,CAAC,cAAc,CACnB,MAA6C;QAE7C,IAAI,MAAM,GAAG,CAAC,CAAA;QACd,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;YACnD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBAC/B,MAAM,KAAK,CAAA;YACb,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,WAAW,IAAI,IAAI,EAAE,CAAC;gBAC/C,OAAM;YACR,CAAC;YACD,mEAAmE;YACnE,oEAAoE;YACpE,IAAI,IAAI,CAAC,WAAW,KAAK,MAAM,EAAE,CAAC;gBAChC,OAAM;YACR,CAAC;YACD,MAAM,GAAG,IAAI,CAAC,WAAW,CAAA;QAC3B,CAAC;IACH,CAAC;CACF"}

package/dist/types/generated/api.d.ts

@@ -5225,7 +5225,9 @@ export interface paths {
          * List prompt logs for a workspace
          * @description Lists ``prompt_log`` events emitted by agent-engine — full system prompt, conversation history, tool catalog, LLM model, and response — for auditing and debugging. Reads the Delta ``world_events`` ledger via Databricks SQL; typical latency is 1-5s with a 15s ceiling on cold-start.
          *
-         *     **Filters**: ``call_sid``, ``prompt_type``, ``state_name``, ``from_ts``, ``to_ts``. When no selectivity-bearing filter (call_sid / time range) is supplied, the query is auto-capped to the last 7 days; the applied window is reported in ``applied_time_window_days``.
+         *     **Conversation filter**: pass ``conversation_id`` (UUID from ``world.entities``) for the canonical mental model — works uniformly across voice, text, sim, and scribe modalities. ``call_sid`` is the legacy direct-SID filter (Twilio CA-SID for voice, session_id UUID otherwise) and is mutually exclusive with ``conversation_id``.
+         *
+         *     **Other filters**: ``prompt_type``, ``state_name``, ``from_ts``, ``to_ts``. When no selectivity-bearing filter (conversation_id / call_sid / time range) is supplied, the query is auto-capped to the last 7 days; the applied window is reported in ``applied_time_window_days``.
          *
          *     **Pagination**: peek-ahead — ``has_more`` is true when more rows exist; use ``next_offset`` to fetch the next page.
          *
@@ -21423,6 +21425,16 @@ export interface components {
              * @description Pass back as offset to fetch the next page; null when has_more is false
              */
             next_offset?: number | null;
+            /**
+             * Resolved Call Sid
+             * @description When ``conversation_id`` was supplied, this is the underlying ``call_sid`` that the lookup resolved to. Useful for callers that want to drill into per-call surfaces afterward without re-querying ``world.entities``. Null when the caller filtered by ``call_sid`` directly or did not filter by conversation.
+             */
+            resolved_call_sid?: string | null;
+            /**
+             * Resolved Conversation Kind
+             * @description ``entity_type`` of the conversation entity when ``conversation_id`` was supplied (``call`` for voice/sim/scribe, ``conversation`` for text/sms/whatsapp/email). Null otherwise.
+             */
+            resolved_conversation_kind?: ("call" | "conversation") | null;
         };
         /**
          * ProviderType
@@ -41117,7 +41129,9 @@ export interface operations {
     "list-prompt-logs": {
         parameters: {
             query?: {
-                /** @description Filter to a single call (Twilio SID or simulation session id) */
+                /** @description Conversation entity UUID (canonical identifier across all modalities — voice, text/web, sms, sim, scribe). Resolves to the underlying ``call_sid`` via ``world.entities``. Mutually exclusive with the ``call_sid`` query parameter. */
+                conversation_id?: string | null;
+                /** @description Direct conversation identifier as stored on the prompt-log event: Twilio CA-SID for voice calls, session_id UUID for text/sim/scribe sessions. Most callers should use ``conversation_id`` instead — this is kept for legacy callers and external systems that hold the SID directly. Mutually exclusive with ``conversation_id``. */
                 call_sid?: string | null;
                 /** @description Filter by prompt_type (e.g. engage_user, navigation, tool) */
                 prompt_type?: string | null;
@@ -41149,6 +41163,13 @@ export interface operations {
                     "application/json": components["schemas"]["PromptLogListResponse"];
                 };
             };
+            /** @description Mutually exclusive filters supplied */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
             /** @description Caller is not admin/owner */
             403: {
                 headers: {
@@ -41156,6 +41177,13 @@ export interface operations {
                 };
                 content?: never;
             };
+            /** @description conversation_id does not match any conversation in this workspace */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
             /** @description Validation Error */
             422: {
                 headers: {