steps.ts

// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../core/resource';
import * as MessagesAPI from '../agents/messages';
import * as RunsAPI from '../runs/runs';
import * as FeedbackAPI from './feedback';
import { Feedback, FeedbackCreateParams } from './feedback';
import * as StepsMessagesAPI from './messages';
import { MessageListParams, MessageListResponse, MessageListResponsesArrayPage, Messages } from './messages';
import * as MetricsAPI from './metrics';
import { MetricRetrieveResponse, Metrics } from './metrics';
import * as TraceAPI from './trace';
import { Trace } from './trace';
import { APIPromise } from '../../core/api-promise';
import { ArrayPage, type ArrayPageParams, PagePromise } from '../../core/pagination';
import { RequestOptions } from '../../internal/request-options';
import { path } from '../../internal/utils/path';

export class Steps extends APIResource {
  metrics: MetricsAPI.Metrics = new MetricsAPI.Metrics(this._client);
  trace: TraceAPI.Trace = new TraceAPI.Trace(this._client);
  feedback: FeedbackAPI.Feedback = new FeedbackAPI.Feedback(this._client);
  messages: StepsMessagesAPI.Messages = new StepsMessagesAPI.Messages(this._client);

  /**
   * Get a step by ID.
   */
  retrieve(stepID: string, options?: RequestOptions): APIPromise<Step> {
    return this._client.get(path`/v1/steps/${stepID}`, options);
  }

  /**
   * List steps with optional pagination and date filters.
   */
  list(
    query: StepListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<StepsArrayPage, Step> {
    return this._client.getAPIList('/v1/steps/', ArrayPage<Step>, { query, ...options });
  }
}

export type StepsArrayPage = ArrayPage<Step>;

/**
 * Letta's internal representation of a provider trace.
 *
 * Attributes: id (str): The unique identifier of the provider trace. request_json
 * (Dict[str, Any]): JSON content of the provider request. response_json (Dict[str,
 * Any]): JSON content of the provider response. step_id (str): ID of the step that
 * this trace is associated with. agent_id (str): ID of the agent that generated
 * this trace. agent_tags (list[str]): Tags associated with the agent for
 * filtering. call_type (str): Type of call (agent_step, summarization, etc.).
 * run_id (str): ID of the run this trace is associated with. source (str): Source
 * service that generated this trace (memgpt-server, lettuce-py). organization_id
 * (str): The unique identifier of the organization. user_id (str): The unique
 * identifier of the user who initiated the request. compaction_settings (Dict[str,
 * Any]): Compaction/summarization settings (only for summarization calls).
 * llm_config (Dict[str, Any]): LLM configuration used for this call (only for
 * non-summarization calls). created_at (datetime): The timestamp when the object
 * was created.
 */
export interface ProviderTrace {
  /**
   * JSON content of the provider request
   */
  request_json: { [key: string]: unknown };

  /**
   * JSON content of the provider response
   */
  response_json: { [key: string]: unknown };

  /**
   * The human-friendly ID of the Provider_trace
   */
  id?: string;

  /**
   * ID of the agent that generated this trace
   */
  agent_id?: string | null;

  /**
   * Tags associated with the agent for filtering
   */
  agent_tags?: Array<string> | null;

  /**
   * Billing context for LLM request cost tracking.
   */
  billing_context?: ProviderTrace.BillingContext | null;

  /**
   * Type of call (agent_step, summarization, etc.)
   */
  call_type?: string | null;

  /**
   * Compaction/summarization settings (summarization calls only)
   */
  compaction_settings?: { [key: string]: unknown } | null;

  /**
   * The timestamp when the object was created.
   */
  created_at?: string;

  /**
   * The id of the user that made this object.
   */
  created_by_id?: string | null;

  /**
   * The id of the user that made this object.
   */
  last_updated_by_id?: string | null;

  /**
   * LLM configuration used for this call (non-summarization calls only)
   */
  llm_config?: { [key: string]: unknown } | null;

  /**
   * ID of the organization
   */
  org_id?: string | null;

  /**
   * ID of the run this trace is associated with
   */
  run_id?: string | null;

  /**
   * Source service that generated this trace (memgpt-server, lettuce-py)
   */
  source?: string | null;

  /**
   * ID of the step that this trace is associated with
   */
  step_id?: string | null;

  /**
   * The timestamp when the object was last updated.
   */
  updated_at?: string | null;
}

export namespace ProviderTrace {
  /**
   * Billing context for LLM request cost tracking.
   */
  export interface BillingContext {
    /**
     * Cost source: 'quota' or 'credits'
     */
    cost_source?: string | null;

    /**
     * Customer ID for billing records
     */
    customer_id?: string | null;

    /**
     * Subscription tier
     */
    plan_type?: string | null;
  }
}

export interface Step {
  /**
   * The id of the step. Assigned by the database.
   */
  id: string;

  /**
   * The ID of the agent that performed the step.
   */
  agent_id?: string | null;

  /**
   * The number of input tokens written to cache (Anthropic only). None if not
   * reported by provider.
   */
  cache_write_tokens?: number | null;

  /**
   * The number of input tokens served from cache. None if not reported by provider.
   */
  cached_input_tokens?: number | null;

  /**
   * The number of tokens generated by the agent during this step.
   */
  completion_tokens?: number | null;

  /**
   * Detailed completion token breakdown (e.g., reasoning_tokens).
   */
  completion_tokens_details?: { [key: string]: unknown } | null;

  /**
   * The context window limit configured for this step.
   */
  context_window_limit?: number | null;

  /**
   * Error details including message, traceback, and additional context
   */
  error_data?: { [key: string]: unknown } | null;

  /**
   * The type/class of the error that occurred
   */
  error_type?: string | null;

  /**
   * The feedback for this step. Must be either 'positive' or 'negative'.
   */
  feedback?: 'positive' | 'negative' | null;

  /**
   * @deprecated The messages generated during this step. Deprecated: use
   * `GET /v1/steps/{step_id}/messages` endpoint instead
   */
  messages?: Array<MessagesAPI.InternalMessage>;

  /**
   * The name of the model used for this step.
   */
  model?: string | null;

  /**
   * The model endpoint url used for this step.
   */
  model_endpoint?: string | null;

  /**
   * The model handle (e.g., 'openai/gpt-4o-mini') used for this step.
   */
  model_handle?: string | null;

  /**
   * The surface that this agent step was initiated from.
   */
  origin?: string | null;

  /**
   * The project that the agent that executed this step belongs to (cloud only).
   */
  project_id?: string | null;

  /**
   * The number of tokens in the prompt during this step.
   */
  prompt_tokens?: number | null;

  /**
   * Detailed prompt token breakdown (e.g., cached_tokens, cache_read_tokens,
   * cache_creation_tokens).
   */
  prompt_tokens_details?: { [key: string]: unknown } | null;

  /**
   * The category of the provider used for this step.
   */
  provider_category?: string | null;

  /**
   * The unique identifier of the provider that was configured for this step
   */
  provider_id?: string | null;

  /**
   * The name of the provider used for this step.
   */
  provider_name?: string | null;

  /**
   * The number of reasoning/thinking tokens generated. None if not reported by
   * provider.
   */
  reasoning_tokens?: number | null;

  /**
   * The API request log ID from cloud-api for correlating steps with API requests.
   */
  request_id?: string | null;

  /**
   * The unique identifier of the run that this step belongs to. Only included for
   * async calls.
   */
  run_id?: string | null;

  /**
   * Status of a step execution
   */
  status?: 'pending' | 'success' | 'failed' | 'cancelled' | null;

  /**
   * The stop reason associated with the step.
   */
  stop_reason?: RunsAPI.StopReasonType | null;

  /**
   * Metadata tags.
   */
  tags?: Array<string>;

  /**
   * The unique identifier of the transaction that processed this step.
   */
  tid?: string | null;

  /**
   * The total number of tokens processed by the agent during this step.
   */
  total_tokens?: number | null;

  /**
   * The trace id of the agent step.
   */
  trace_id?: string | null;
}

export interface StepListParams extends ArrayPageParams {
  /**
   * Filter by the ID of the agent that performed the step
   */
  agent_id?: string | null;

  /**
   * Return steps before this ISO datetime (e.g. "2025-01-29T15:01:19-08:00")
   */
  end_date?: string | null;

  /**
   * Filter by feedback
   */
  feedback?: 'positive' | 'negative' | null;

  /**
   * Filter by whether steps have feedback (true) or not (false)
   */
  has_feedback?: boolean | null;

  /**
   * Filter by the name of the model used for the step
   */
  model?: string | null;

  /**
   * Filter by the project ID that is associated with the step (cloud only).
   */
  project_id?: string | null;

  /**
   * Return steps after this ISO datetime (e.g. "2025-01-29T15:01:19-08:00")
   */
  start_date?: string | null;

  /**
   * Filter by tags
   */
  tags?: Array<string> | null;

  /**
   * Filter by trace ids returned by the server
   */
  trace_ids?: Array<string> | null;
}

Steps.Metrics = Metrics;
Steps.Trace = Trace;
Steps.Feedback = Feedback;
Steps.Messages = Messages;

export declare namespace Steps {
  export {
    type ProviderTrace as ProviderTrace,
    type Step as Step,
    type StepsArrayPage as StepsArrayPage,
    type StepListParams as StepListParams,
  };

  export { Metrics as Metrics, type MetricRetrieveResponse as MetricRetrieveResponse };

  export { Trace as Trace };

  export { Feedback as Feedback, type FeedbackCreateParams as FeedbackCreateParams };

  export {
    Messages as Messages,
    type MessageListResponse as MessageListResponse,
    type MessageListResponsesArrayPage as MessageListResponsesArrayPage,
    type MessageListParams as MessageListParams,
  };
}