@volter/twin-togetherai 0.1.0

package/src/togetherai-types.ts

@@ -0,0 +1,222 @@
+// Shared wire-shape types for the Together AI surface. These mirror the REAL vendor JSON shapes
+// as published by Together's own OpenAPI (https://docs.together.ai/openapi.yaml, fetched
+// 2026-09-16) and the Stainless-generated `together-ai@0.53.0` SDK — NOT the SDK's internal
+// types (the twin never imports the SDK at runtime; the SDK is exercised only in *.test.ts).
+//
+// TOGETHER IS NOT OPENAI, and the differences below are load-bearing (they are what a
+// "just copy the openai pack" twin gets wrong):
+//   • `n` spans 1–128 (OpenAI-compatible; Groq pins it at 1) and `logprobs` is an INTEGER 0–20
+//     (OpenAI's boolean) — Together serves both;
+//   • `finish_reason` adds **`eos`** (Together's end-of-sequence token) alongside stop/length;
+//   • the response carries a REQUIRED `prompt: []` array (the echoed prompt when `echo:true`);
+//   • the error envelope is `{ error: { message, type, param, code } }` with `param`/`code`
+//     nullable, and Together's STATUS TABLE is its own: 402 = monthly spending limit,
+//     **403 = context length exceeded** (a BAD REQUEST, not a permission denial),
+//     503 = engine overloaded, 524 = Cloudflare timeout, 529 = server error;
+//   • the batch surface is Together-NATIVE: `GET /v1/batches` answers a bare ARRAY (not an
+//     OpenAI `{object:'list',data}` envelope), `POST /v1/batches` answers 201 with
+//     `BatchJobWithWarning { job, warning? }`, and every batch error is `{ error: string }`
+//     (a bare string, NOT an ErrorData object);
+//   • files carry Together's own `FileType` (csv|jsonl|parquet) and the validation pipeline's
+//     `processing_status` / `validation_report`;
+//   • model ids are slash-namespaced (`meta-llama/Llama-3.3-70B-Instruct-Turbo`) and an
+//     OpenAI-style flat id like `gpt-4o` is a 404;
+//   • `service_tier` / `store` / `metadata` / `prediction` are ACCEPTED BUT IGNORED (the
+//     OpenAI-compat page's own wording) — accepted here, never echoed into the response.
+
+// ── Chat Completions ────────────────────────────────────────────────────────────────────
+/** A chat message param as the caller sends it. Together's `ChatCompletionMessageParam` oneOf
+ *  covers system/user/assistant/tool/function; content is a string (Together's schema types
+ *  every param's content as `string | null` — no content-part arrays). */
+export type TogetheraiMessageParam = {
+  role: 'system' | 'user' | 'assistant' | 'tool' | 'function';
+  content?: string | null;
+  name?: string;
+  tool_calls?: TogetheraiToolCall[];
+  tool_call_id?: string;
+  // Assistant-turn fields Together's own schema declares:
+  reasoning?: string | null;
+  reasoning_content?: string | null;
+};
+
+/** A function tool_call inside an assistant message (Together's `ToolChoice`). */
+export type TogetheraiToolCall = {
+  id: string;
+  type: 'function';
+  function: { name: string; arguments: string };
+};
+
+/** Together's `UsageData`: the three token counts, REQUIRED and NULLABLE (Together reports
+ *  `null` usage on some streamed/failed turns). No timing fields — that is Groq's block. */
+export type TogetheraiUsage = {
+  prompt_tokens: number | null;
+  completion_tokens: number | null;
+  total_tokens: number | null;
+  /** Reasoning models nest the detail blocks (Together's docs: cached/reasoning token splits). */
+  prompt_tokens_details?: { cached_tokens: number } | null;
+  completion_tokens_details?: { reasoning_tokens: number } | null;
+};
+
+/** Together's assistant message. `reasoning`/`reasoning_content` vary by model (Together's docs:
+ *  "varies by model" — both are declared on the schema). No `refusal` field. */
+export type TogetheraiAssistantMessage = {
+  role: 'assistant';
+  content: string | null;
+  tool_calls?: TogetheraiToolCall[];
+  function_call?: { name: string; arguments: string };
+  reasoning?: string | null;
+  reasoning_content?: string | null;
+};
+
+/** Together's `FinishReason`: adds **`eos`** to the OpenAI set. */
+export type TogetheraiFinishReason = 'stop' | 'eos' | 'length' | 'tool_calls' | 'function_call';
+
+export type TogetheraiChoice = {
+  index: number;
+  message?: TogetheraiAssistantMessage;
+  text?: string;
+  seed?: number;
+  logprobs?: unknown | null;
+  finish_reason: TogetheraiFinishReason | null;
+};
+
+/** The unary chat.completion response. `prompt` is REQUIRED on Together's schema — the echoed
+ *  prompt parts (empty unless `echo:true`); `warnings` is Together's inference-warnings array. */
+export type TogetheraiChatCompletion = {
+  id: string;
+  object: 'chat.completion';
+  created: number;
+  model: string;
+  choices: TogetheraiChoice[];
+  prompt: Array<{ text?: string; logprobs?: unknown }>;
+  usage?: TogetheraiUsage | null;
+  warnings?: unknown[];
+};
+
+// ── Streaming ───────────────────────────────────────────────────────────────────────────
+/** A single Server-Sent Event the streaming path emits (collected, never socketed in tests).
+ *  `data` is the JSON payload; `[DONE]` is signalled with `done: true` (no data object). */
+export type SseEvent = { data?: Record<string, unknown>; done?: boolean };
+
+/** A sink the streaming path writes events into (an injected collector in tests / a real
+ *  HTTP SSE writer in the server). NO real sockets or setTimeout in the handler. */
+export type SseSink = (event: SseEvent) => void;
+
+/** A streaming chunk. Together's `ChatCompletionChunk` carries `usage` (nullable) and
+ *  `warnings` on EVERY chunk (OpenAI puts usage only in an opt-in tail chunk). */
+export type TogetheraiChunk = {
+  id: string;
+  object: 'chat.completion.chunk';
+  created: number;
+  model: string;
+  system_fingerprint?: string;
+  choices: Array<{ index: number; delta: Record<string, unknown>; logprobs?: unknown | null; finish_reason: TogetheraiFinishReason | null }>;
+  usage?: TogetheraiUsage | null;
+  warnings?: unknown[];
+};
+
+// ── Models ──────────────────────────────────────────────────────────────────────────────
+/** Together's `ModelInfo`: REQUIRED keys are id/object/created/type — `type` is Together's OWN
+ *  enum (chat|language|code|image|embedding|moderation|rerank), not OpenAI's flat model object. */
+export type TogetheraiModel = {
+  id: string;
+  object: 'model';
+  created: number;
+  type: 'chat' | 'language' | 'code' | 'image' | 'embedding' | 'moderation' | 'rerank';
+  display_name?: string;
+  organization?: string;
+  link?: string;
+  license?: string;
+  context_length?: number;
+  pricing?: Record<string, unknown>;
+};
+
+// ── Embeddings ──────────────────────────────────────────────────────────────────────────
+export type TogetheraiEmbedding = { object: 'embedding'; index: number; embedding: number[] };
+/** Together's `EmbeddingsResponse`: REQUIRED object/model/data — and NO `usage` key on the
+ *  schema (Together does not document one on this endpoint). */
+export type TogetheraiEmbeddingResponse = {
+  object: 'list';
+  model: string;
+  data: TogetheraiEmbedding[];
+};
+
+// ── Rerank ──────────────────────────────────────────────────────────────────────────────
+/** Together's `RerankResponse` — Together-native (NOT an OpenAI endpoint at all). */
+export type TogetheraiRerankResponse = {
+  object: 'rerank';
+  id?: string;
+  model: string;
+  results: Array<{ index: number; relevance_score: number; document?: { text?: string | null } }>;
+  usage?: TogetheraiUsage | null;
+};
+
+// ── Images ──────────────────────────────────────────────────────────────────────────────
+/** Together's `ImageResponse`: `object:'list'` with a discriminated data union
+ *  (`type:'url'` | `type:'b64_json'`). */
+export type TogetheraiImageResponse = {
+  id: string;
+  model: string;
+  object: 'list';
+  data: Array<{ index: number; url?: string; b64_json?: string; type: 'url' | 'b64_json' }>;
+};
+
+// ── Files ───────────────────────────────────────────────────────────────────────────────
+/** Together's `FilePurpose` — a CLOSED set (`fine-tune` | `eval` | `batch-api`), NOT OpenAI's. */
+export type TogetheraiFilePurpose = 'fine-tune' | 'eval' | 'batch-api';
+/** Together's `FileType` — csv|jsonl|parquet. */
+export type TogetheraiFileType = 'csv' | 'jsonl' | 'parquet';
+/** The validation pipeline's lifecycle state (fine-tune files only). */
+export type TogetheraiFileProcessingStatus = 'PENDING' | 'QUEUED' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'INVALID_FORMAT';
+
+/** Together's `FileResponse`. REQUIRED keys include Together's own `FileType` (capital F) and
+ *  the deprecated `Processed` boolean. */
+export type TogetheraiFile = {
+  id: string;
+  object: 'file';
+  created_at: number;
+  filename: string;
+  bytes: number;
+  purpose: TogetheraiFilePurpose;
+  Processed: boolean;
+  FileType: TogetheraiFileType;
+  processing_status?: TogetheraiFileProcessingStatus;
+  validation_report?: { valid: boolean; [k: string]: unknown };
+};
+
+// ── Batches (Together-native) ───────────────────────────────────────────────────────────
+/** Together's `BatchJobStatus` — UPPER-CASE, not OpenAI's lowercase set. */
+export type TogetheraiBatchStatus = 'VALIDATING' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED' | 'EXPIRED' | 'CANCELLED';
+/** Together's `CreateBatchRequest.endpoint` — the three documented endpoints. */
+export type TogetheraiBatchEndpoint = '/v1/chat/completions' | '/v1/audio/transcriptions' | '/v1/audio/translations';
+
+/** Together's `BatchJob`. `error` is a bare STRING (not an ErrorData object), and the
+ *  timestamps are ISO date-time STRINGS (not OpenAI's unix integers). */
+export type TogetheraiBatch = {
+  id: string;
+  user_id?: string;
+  input_file_id: string;
+  file_size_bytes?: number;
+  status: TogetheraiBatchStatus;
+  job_deadline?: string | null;
+  created_at: string;
+  endpoint: string;
+  progress?: number;
+  model_id?: string;
+  output_file_id?: string | null;
+  error_file_id?: string | null;
+  error?: string | null;
+  completed_at?: string | null;
+};
+
+// ── Errors ──────────────────────────────────────────────────────────────────────────────
+/** Together's `ErrorData`: `{ error: { message, type, param, code } }` with `message`+`type`
+ *  REQUIRED and `param`/`code` nullable with default null. */
+export type TogetheraiError = {
+  error: {
+    message: string;
+    type: string;
+    param?: string | null;
+    code?: string | null;
+  };
+};