@cartesia/cartesia-js 2.2.9 → 3.0.0-b4

package/src/resources/agents/calls.ts

@@ -0,0 +1,273 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { CursorIDPage, type CursorIDPageParams, PagePromise } from '../../core/pagination';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Calls extends APIResource {
+  /**
+   * Get Call
+   */
+  retrieve(callID: string, options?: RequestOptions): APIPromise<AgentCall> {
+    return this._client.get(path`/agents/calls/${callID}`, options);
+  }
+
+  /**
+   * Lists calls sorted by start time in descending order for a specific agent.
+   * `agent_id` is required and if you want to include `transcript` in the response,
+   * add `expand=transcript` to the request. This endpoint is paginated.
+   */
+  list(query: CallListParams, options?: RequestOptions): PagePromise<AgentCallsCursorIDPage, AgentCall> {
+    return this._client.getAPIList('/agents/calls', CursorIDPage<AgentCall>, { query, ...options });
+  }
+
+  /**
+   * The downloaded audio file is in .wav format. This endpoint streams the audio
+   * file content (WAV format) to the client.
+   */
+  downloadAudio(callID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.get(path`/agents/calls/${callID}/audio`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export type AgentCallsCursorIDPage = CursorIDPage<AgentCall>;
+
+export interface AgentCall {
+  /**
+   * The unique identifier for the agent call.
+   */
+  id: string;
+
+  /**
+   * The identifier of the agent associated with the call.
+   */
+  agent_id: string;
+
+  /**
+   * The status of the agent call.
+   */
+  status: 'active' | 'completed' | 'failed' | 'cancelled';
+
+  /**
+   * The deployment identifier associated with the call.
+   */
+  deployment_id?: string | null;
+
+  /**
+   * The end time of the agent call.
+   */
+  end_time?: string | null;
+
+  /**
+   * The error message, if any, associated with the call.
+   */
+  error_message?: string | null;
+
+  /**
+   * The start time of the agent call.
+   */
+  start_time?: string | null;
+
+  /**
+   * A summary of the agent call. This is a brief summary of the call that is
+   * generated by Cartesia.
+   */
+  summary?: string | null;
+
+  /**
+   * The telephony parameters associated with the call when the call is made via
+   * phone.
+   */
+  telephony_params?: AgentCall.TelephonyParams | null;
+
+  /**
+   * The transcript of the agent call.
+   */
+  transcript?: Array<AgentTranscript> | null;
+}
+
+export namespace AgentCall {
+  /**
+   * The telephony parameters associated with the call when the call is made via
+   * phone.
+   */
+  export interface TelephonyParams {
+    /**
+     * The phone number of the agent.
+     */
+    from: string;
+
+    /**
+     * The phone number of the caller.
+     */
+    to: string;
+  }
+}
+
+export interface AgentTranscript {
+  /**
+   * The end timestamp in seconds relative to the start of the call.
+   */
+  end_timestamp: number;
+
+  /**
+   * The role of the participant in the conversation. Roles are `user`, `assistant`,
+   * or `system`. `assistant` is the agent. `system` is used to indicate logs during
+   * the conversation such as `log_event` or `log_metric`.
+   */
+  role: string;
+
+  /**
+   * The start timestamp in seconds relative to the start of the call.
+   */
+  start_timestamp: number;
+
+  /**
+   * The reason for why the assistant turn ended. This could be `call_ended`,
+   * `interrupted`, or `tts_completed`.
+   */
+  end_reason?: string | null;
+
+  /**
+   * The log event from user code.
+   */
+  log_event?: AgentTranscript.LogEvent | null;
+
+  /**
+   * The log metric from user code.
+   */
+  log_metric?: AgentTranscript.LogMetric | null;
+
+  /**
+   * The text content of the transcript. This is the text that was spoken by the user
+   * or the agent.
+   */
+  text?: string | null;
+
+  /**
+   * The chunks of text at a more granular level in the transcript with timestamps
+   * relative to the start of the call.
+   */
+  text_chunks?: Array<AgentTranscript.TextChunk> | null;
+
+  /**
+   * The tool calls made during the turn.
+   */
+  tool_calls?: Array<AgentTranscript.ToolCall> | null;
+
+  /**
+   * The time to first byte in seconds from the agent for text-to-speech.
+   */
+  tts_ttfb?: number | null;
+
+  /**
+   * The VAD buffer time in milliseconds.
+   */
+  vad_buffer_ms?: number | null;
+}
+
+export namespace AgentTranscript {
+  /**
+   * The log event from user code.
+   */
+  export interface LogEvent {
+    /**
+     * The event name.
+     */
+    event: string;
+
+    /**
+     * Additional metadata associated with the event.
+     */
+    metadata: { [key: string]: string };
+
+    /**
+     * The timestamp when the event was received relative to the start of the call.
+     */
+    timestamp: number;
+  }
+
+  /**
+   * The log metric from user code.
+   */
+  export interface LogMetric {
+    /**
+     * The name of the metric.
+     */
+    name: string;
+
+    /**
+     * The timestamp when the metric was received relative to the start of the call.
+     */
+    timestamp: number;
+
+    /**
+     * The value of the metric.
+     */
+    value: number;
+  }
+
+  export interface TextChunk {
+    /**
+     * The starting timestamp of the text chunk in seconds relative to the start of the
+     * call.
+     */
+    start_timestamp: number;
+
+    /**
+     * The text content of the chunk.
+     */
+    text: string;
+  }
+
+  export interface ToolCall {
+    /**
+     * The unique identifier for the tool call.
+     */
+    id: string;
+
+    /**
+     * The arguments passed to the tool.
+     */
+    arguments: { [key: string]: string };
+
+    /**
+     * The name of the tool that was called.
+     */
+    name: string;
+  }
+}
+
+export interface CallListParams extends CursorIDPageParams {
+  /**
+   * The ID of the agent.
+   */
+  agent_id: string;
+
+  /**
+   * The fields to expand in the response. Currently, the only supported value is
+   * `transcript`.
+   */
+  expand?: string | null;
+
+  /**
+   * (Pagination option) The number of calls to return per page, ranging between 1
+   * and 100.
+   */
+  limit?: number | null;
+}
+
+export declare namespace Calls {
+  export {
+    type AgentCall as AgentCall,
+    type AgentTranscript as AgentTranscript,
+    type AgentCallsCursorIDPage as AgentCallsCursorIDPage,
+    type CallListParams as CallListParams,
+  };
+}

package/src/resources/agents/deployments.ts

@@ -0,0 +1,119 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Deployments extends APIResource {
+  /**
+   * Get a deployment by its ID.
+   */
+  retrieve(deploymentID: string, options?: RequestOptions): APIPromise<Deployment> {
+    return this._client.get(path`/agents/deployments/${deploymentID}`, options);
+  }
+
+  /**
+   * List of all deployments associated with an agent.
+   */
+  list(agentID: string, options?: RequestOptions): APIPromise<DeploymentListResponse> {
+    return this._client.get(path`/agents/${agentID}/deployments`, options);
+  }
+}
+
+export interface Deployment {
+  /**
+   * The unique identifier for the deployment.
+   */
+  id: string;
+
+  /**
+   * The ID of the agent associated with this deployment.
+   */
+  agent_id: string;
+
+  /**
+   * The UTC timestamp when the build was completed.
+   */
+  build_completed_at: string;
+
+  /**
+   * Logs generated during the build process of the deployment.
+   */
+  build_logs: string;
+
+  /**
+   * The UTC timestamp when the build process started.
+   */
+  build_started_at: string;
+
+  /**
+   * The UTC timestamp when the deployment was created.
+   */
+  created_at: string;
+
+  /**
+   * The UTC timestamp when the deployment process was completed.
+   */
+  deployment_completed_at: string;
+
+  /**
+   * The UTC timestamp when the deployment process started.
+   */
+  deployment_started_at: string;
+
+  /**
+   * The ID of the environment variable collection associated with this deployment.
+   */
+  env_var_collection_id: string;
+
+  /**
+   * The commit hash of the Git repository for this deployment.
+   */
+  git_commit_hash: string;
+
+  /**
+   * True if this deployment is the live production deployment for its associated
+   * `agent_id`. Only one deployment per agent can be live at a time.
+   */
+  is_live: boolean;
+
+  /**
+   * Marks that this deployment is the active deployment for its associated
+   * `agent_id`. Only one deployment per agent can be pinned at a time. Deployments
+   * can be pinned even if they are not live or failed.
+   */
+  is_pinned: boolean;
+
+  /**
+   * The ID of the source code file associated with this deployment.
+   */
+  source_code_file_id: string;
+
+  /**
+   * The current status of the deployment. It can be `queued`, `inactive`,
+   * `deploy_error`, `skipped`, `build_error`, `building`, or `deployed`.
+   */
+  status: string;
+
+  /**
+   * The UTC timestamp when the deployment was last updated.
+   */
+  updated_at: string;
+
+  /**
+   * Any error that occurred during the build process.
+   */
+  build_error?: string | null;
+
+  /**
+   * Any error that occurred during the deployment process.
+   */
+  deployment_error?: string | null;
+}
+
+export type DeploymentListResponse = Array<Deployment>;
+
+export declare namespace Deployments {
+  export { type Deployment as Deployment, type DeploymentListResponse as DeploymentListResponse };
+}

package/src/resources/agents/index.ts

@@ -0,0 +1,27 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Agents,
+  type AgentSummary,
+  type AgentListResponse,
+  type AgentListPhoneNumbersResponse,
+  type AgentListTemplatesResponse,
+  type AgentUpdateParams,
+} from './agents';
+export {
+  Calls,
+  type AgentCall,
+  type AgentTranscript,
+  type CallListParams,
+  type AgentCallsCursorIDPage,
+} from './calls';
+export { Deployments, type Deployment, type DeploymentListResponse } from './deployments';
+export {
+  Metrics,
+  type Metric,
+  type MetricListResponse,
+  type MetricCreateParams,
+  type MetricListParams,
+  type MetricAddToAgentParams,
+  type MetricRemoveFromAgentParams,
+} from './metrics/index';

package/src/resources/agents/metrics/index.ts

@@ -0,0 +1,19 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Metrics,
+  type Metric,
+  type MetricListResponse,
+  type MetricCreateParams,
+  type MetricListParams,
+  type MetricAddToAgentParams,
+  type MetricRemoveFromAgentParams,
+} from './metrics';
+export {
+  Results,
+  type ResultListResponse,
+  type ResultExportResponse,
+  type ResultListParams,
+  type ResultExportParams,
+  type ResultListResponsesCursorIDPage,
+} from './results';

package/src/resources/agents/metrics/metrics.ts

@@ -0,0 +1,188 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as ResultsAPI from './results';
+import {
+  ResultExportParams,
+  ResultExportResponse,
+  ResultListParams,
+  ResultListResponse,
+  ResultListResponsesCursorIDPage,
+  Results,
+} from './results';
+import { APIPromise } from '../../../core/api-promise';
+import { buildHeaders } from '../../../internal/headers';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+export class Metrics extends APIResource {
+  results: ResultsAPI.Results = new ResultsAPI.Results(this._client);
+
+  /**
+   * Create a new metric.
+   */
+  create(body: MetricCreateParams, options?: RequestOptions): APIPromise<Metric> {
+    return this._client.post('/agents/metrics', { body, ...options });
+  }
+
+  /**
+   * Get a metric by its ID.
+   */
+  retrieve(metricID: string, options?: RequestOptions): APIPromise<Metric> {
+    return this._client.get(path`/agents/metrics/${metricID}`, options);
+  }
+
+  /**
+   * List of all LLM-as-a-Judge metrics owned by your account.
+   */
+  list(
+    query: MetricListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<MetricListResponse> {
+    return this._client.get('/agents/metrics', { query, ...options });
+  }
+
+  /**
+   * Add a metric to an agent. Once the metric is added, it will be run on all calls
+   * made to the agent automatically from that point onwards.
+   */
+  addToAgent(metricID: string, params: MetricAddToAgentParams, options?: RequestOptions): APIPromise<void> {
+    const { agent_id } = params;
+    return this._client.post(path`/agents/${agent_id}/metrics/${metricID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Remove a metric from an agent. Once the metric is removed, it will no longer be
+   * run on all calls made to the agent automatically from that point onwards.
+   * Existing metric results will remain.
+   */
+  removeFromAgent(
+    metricID: string,
+    params: MetricRemoveFromAgentParams,
+    options?: RequestOptions,
+  ): APIPromise<void> {
+    const { agent_id } = params;
+    return this._client.delete(path`/agents/${agent_id}/metrics/${metricID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export interface Metric {
+  /**
+   * The unique identifier for the metric.
+   */
+  id: string;
+
+  /**
+   * The timestamp when the metric was created.
+   */
+  created_at: string;
+
+  /**
+   * The name of the metric. This is a unique name that you can use to identify the
+   * metric in the CLI.
+   */
+  name: string;
+
+  /**
+   * The prompt associated with the metric, detailing the task and evaluation
+   * criteria.
+   */
+  prompt: string;
+
+  /**
+   * The display name of the metric, if available. This is the name that is displayed
+   * in the Playground.
+   */
+  display_name?: string | null;
+}
+
+export interface MetricListResponse {
+  /**
+   * List of metrics.
+   */
+  data: Array<Metric>;
+
+  /**
+   * Whether there are more metrics to fetch (using `starting_after=id`, where id is
+   * the ID of the last Metric in the current response).
+   */
+  has_more: boolean;
+
+  /**
+   * The ID of the last Metric in the current response as a cursor for the next page
+   * of results.
+   */
+  next_page?: string | null;
+}
+
+export interface MetricCreateParams {
+  /**
+   * The name of the metric. This must be a unique name that only allows lower case
+   * letters, numbers, and the characters \_, -, and .
+   */
+  name: string;
+
+  /**
+   * The prompt associated with the metric, detailing the task and evaluation
+   * criteria.
+   */
+  prompt: string;
+
+  /**
+   * The display name of the metric.
+   */
+  display_name?: string | null;
+}
+
+export interface MetricListParams {
+  /**
+   * (Pagination option) The number of metrics to return per page, ranging between 1
+   * and 100. The default page limit is 10.
+   */
+  limit?: number | null;
+
+  /**
+   * (Pagination option) The ID of the last Metric in the current response as a
+   * cursor for the next page of results.
+   */
+  starting_after?: string | null;
+}
+
+export interface MetricAddToAgentParams {
+  /**
+   * The ID of the agent.
+   */
+  agent_id: string;
+}
+
+export interface MetricRemoveFromAgentParams {
+  agent_id: string;
+}
+
+Metrics.Results = Results;
+
+export declare namespace Metrics {
+  export {
+    type Metric as Metric,
+    type MetricListResponse as MetricListResponse,
+    type MetricCreateParams as MetricCreateParams,
+    type MetricListParams as MetricListParams,
+    type MetricAddToAgentParams as MetricAddToAgentParams,
+    type MetricRemoveFromAgentParams as MetricRemoveFromAgentParams,
+  };
+
+  export {
+    Results as Results,
+    type ResultListResponse as ResultListResponse,
+    type ResultExportResponse as ResultExportResponse,
+    type ResultListResponsesCursorIDPage as ResultListResponsesCursorIDPage,
+    type ResultListParams as ResultListParams,
+    type ResultExportParams as ResultExportParams,
+  };
+}