types.ts · Source

types.tspackages/ai/src/types.tsraw ← src4,012 B← Back to the app
1/**
2 * @factory/ai — core types (ai-architecture §2.1).
3 *
4 * These are the gateway's canonical types. Provider SDK types never leak past
5 * the adapter boundary: adapters map provider payloads onto these shapes, and
6 * everything above the gateway speaks only this dialect.
7 */
8 
9/** The provider families the gateway understands. */
10export type ProviderId = "openai" | "anthropic" | "google" | "oss" | "custom";
11 
12/** A model the gateway can route to (from a provider catalog or static table). */
13export interface ModelInfo {
14  id: string;
15  provider: ProviderId;
16  kind: "chat" | "embed" | "chat+embed";
17  contextWindow: number;
18  maxOutput: number;
19  toolCalls: boolean;
20  vision: boolean;
21  /** USD per 1k input tokens (0 for self-hosted OSS). */
22  pricePer1kIn: number;
23  /** USD per 1k output tokens (0 for self-hosted OSS). */
24  pricePer1kOut: number;
25  /** Embedding dimension (0 for chat-only models). */
26  dimension: number;
27}
28 
29export type Role = "system" | "user" | "assistant" | "tool";
30 
31/** A content part: plain text, or an image_url part (vision models). */
32export type ContentPart =
33  | { type: "text"; text: string }
34  | { type: "image_url"; image_url: { url: string } };
35 
36export interface ToolCall {
37  id: string;
38  name: string;
39  arguments: Record<string, unknown>;
40}
41 
42/**
43 * A tool definition. The ONLY tool-schema dialect the gateway accepts is a
44 * strict JSON-Schema subset (see `tools.ts`): object root;
45 * `string|number|boolean|integer|array|object` types; `enum`, `items`,
46 * `required`, `description` — no `pattern`, no `$ref`. Adapters translate to
47 * provider shapes (OpenAI `function.parameters`, Anthropic `input_schema`,
48 * Google `parameters`).
49 */
50export interface ToolSpec {
51  name: string;
52  description: string;
53  parameters: Record<string, unknown>;
54}
55 
56export interface ChatMessage {
57  role: Role;
58  content: string | ContentPart[];
59  /** Assistant messages only: the tool calls the model requested. */
60  toolCalls?: ToolCall[];
61  /** Tool-result messages only: which call this is the result for. */
62  toolCallId?: string;
63  /** Tool name (tool messages). */
64  name?: string;
65}
66 
67export interface ChatRequest {
68  model: string;
69  messages: ChatMessage[];
70  tools?: ToolSpec[];
71  toolChoice?: "auto" | "none" | { name: string };
72  temperature?: number;
73  maxTokens?: number;
74  stream?: boolean;
75  /** {capability, workspaceId, userId, requestId} — used for usage metering. */
76  metadata?: Record<string, string>;
77  /**
78   * TASK-0122: optional caller cancellation. When aborted the adapter stops
79   * pulling the provider stream and throws an abort error (the gateway maps
80   * it to a non-retryable `ai_aborted` error so no retry/fallback re-sends).
81   */
82  signal?: AbortSignal;
83}
84 
85/** One streaming increment (the base primitive; non-streaming collects these). */
86export interface ChatChunk {
87  delta?: string;
88  toolCallDelta?: ToolCall;
89  usage?: { in: number; out: number; total: number };
90  finishReason?: ChatResult["finishReason"];
91  done: boolean;
92}
93 
94export interface ChatResult {
95  content: string;
96  toolCalls: ToolCall[];
97  usage: { in: number; out: number; total: number };
98  model: string;
99  latencyMs: number;
100  provider: ProviderId;
101  finishReason: "stop" | "tool_calls" | "length" | "error";
102}
103 
104export interface EmbedRequest {
105  model: string;
106  texts: string[];
107  metadata?: Record<string, string>;
108}
109 
110export interface EmbedResult {
111  model: string;
112  dimension: number;
113  vectors: number[][];
114  usage: { tokens: number };
115  latencyMs: number;
116  provider: ProviderId;
117}
118 
119/**
120 * The provider contract. `chat` is streaming-only at the adapter level; the
121 * gateway collects the stream for non-streaming callers. `embed` is
122 * Anthropic-unsupported (the gateway routes embed to a fallback provider).
123 */
124export interface ProviderAdapter {
125  id: ProviderId;
126  models(): Promise<ModelInfo[]>;
127  chat(req: ChatRequest): AsyncIterable<ChatChunk>;
128  embed(req: EmbedRequest): Promise<EmbedResult>;
129  health(): Promise<{ ok: boolean; latencyMs: number }>;
130}
131