@tanstack/ai 0.0.1

package/src/utilities/agent-loop-strategies.ts

@@ -0,0 +1,85 @@
+import type { AgentLoopStrategy } from '../types'
+
+/**
+ * Creates a strategy that continues for a maximum number of iterations
+ *
+ * @param max - Maximum number of iterations to allow
+ * @returns AgentLoopStrategy that stops after max iterations
+ *
+ * @example
+ * ```typescript
+ * const stream = chat({
+ *   adapter: openai(),
+ *   model: "gpt-4o",
+ *   messages: [...],
+ *   tools: [weatherTool],
+ *   agentLoopStrategy: maxIterations(3), // Max 3 iterations
+ * });
+ * ```
+ */
+export function maxIterations(max: number): AgentLoopStrategy {
+  return ({ iterationCount }) => iterationCount < max
+}
+
+/**
+ * Creates a strategy that continues until a specific finish reason is encountered
+ *
+ * @param stopReasons - Finish reasons that should stop the loop
+ * @returns AgentLoopStrategy that stops on specific finish reasons
+ *
+ * @example
+ * ```typescript
+ * const stream = chat({
+ *   adapter: openai(),
+ *   model: "gpt-4o",
+ *   messages: [...],
+ *   tools: [weatherTool],
+ *   agentLoopStrategy: untilFinishReason(["stop", "length"]),
+ * });
+ * ```
+ */
+export function untilFinishReason(
+  stopReasons: Array<string>,
+): AgentLoopStrategy {
+  return ({ finishReason, iterationCount }) => {
+    // Always allow at least one iteration
+    if (iterationCount === 0) return true
+
+    // Stop if we hit a stop reason
+    if (finishReason && stopReasons.includes(finishReason)) {
+      return false
+    }
+
+    // Otherwise continue
+    return true
+  }
+}
+
+/**
+ * Creates a strategy that combines multiple strategies with AND logic
+ * All strategies must return true to continue
+ *
+ * @param strategies - Array of strategies to combine
+ * @returns AgentLoopStrategy that continues only if all strategies return true
+ *
+ * @example
+ * ```typescript
+ * const stream = chat({
+ *   adapter: openai(),
+ *   model: "gpt-4o",
+ *   messages: [...],
+ *   tools: [weatherTool],
+ *   agentLoopStrategy: combineStrategies([
+ *     maxIterations(10),
+ *     ({ messages }) => messages.length < 100,
+ *   ]),
+ * });
+ * ```
+ */
+export function combineStrategies(
+  strategies: Array<AgentLoopStrategy>,
+): AgentLoopStrategy {
+  return (state) => {
+    return strategies.every((strategy) => strategy(state))
+  }
+}

package/src/utilities/chat-options.ts

@@ -0,0 +1,35 @@
+import type { AIAdapter, ChatStreamOptionsUnion } from '../types'
+
+export function chatOptions<
+  TAdapter extends AIAdapter<any, any, any, any, any>,
+  const TModel extends TAdapter extends AIAdapter<
+    infer Models,
+    any,
+    any,
+    any,
+    any
+  >
+    ? Models[number]
+    : string,
+>(
+  options: Omit<
+    ChatStreamOptionsUnion<TAdapter>,
+    'providerOptions' | 'model' | 'messages' | 'abortController'
+  > & {
+    adapter: TAdapter
+    model: TModel
+    providerOptions?: TAdapter extends AIAdapter<
+      any,
+      any,
+      any,
+      any,
+      infer ModelProviderOptions
+    >
+      ? TModel extends keyof ModelProviderOptions
+        ? ModelProviderOptions[TModel]
+        : never
+      : never
+  },
+): typeof options {
+  return options
+}

package/src/utilities/messages.ts

@@ -0,0 +1,63 @@
+import type {
+  AIAdapter,
+  ConstrainedModelMessage,
+  Modality,
+  ModelMessage,
+} from '../types'
+
+/**
+ * Type-safe helper to create a messages array constrained by a model's supported modalities.
+ *
+ * This function provides compile-time checking that your messages only contain
+ * content types supported by the specified model. It's particularly useful when
+ * combining typed messages with untyped data (like from request.json()).
+ *
+ * @example
+ * ```typescript
+ * import { messages, chat } from '@tanstack/ai'
+ * import { openai } from '@tanstack/ai-openai'
+ *
+ * const adapter = openai()
+ *
+ * // This will error at compile time because gpt-4o only supports text+image
+ * const msgs = messages({ adapter, model: 'gpt-4o' }, [
+ *   {
+ *     role: 'user',
+ *     content: [
+ *       { type: 'video', source: { type: 'url', value: '...' } } // Error!
+ *     ]
+ *   }
+ * ])
+ * ```
+ */
+export function messages<
+  TAdapter extends AIAdapter<any, any, any, any, any, any>,
+  const TModel extends TAdapter extends AIAdapter<
+    infer Models,
+    any,
+    any,
+    any,
+    any,
+    any
+  >
+    ? Models[number]
+    : string,
+>(
+  _options: { adapter: TAdapter; model: TModel },
+  msgs: TAdapter extends AIAdapter<
+    any,
+    any,
+    any,
+    any,
+    any,
+    infer ModelInputModalities
+  >
+    ? TModel extends keyof ModelInputModalities
+      ? ModelInputModalities[TModel] extends ReadonlyArray<Modality>
+        ? Array<ConstrainedModelMessage<ModelInputModalities[TModel]>>
+        : Array<ModelMessage>
+      : Array<ModelMessage>
+    : Array<ModelMessage>,
+): typeof msgs {
+  return msgs
+}

package/src/utilities/stream-to-response.ts

@@ -0,0 +1,116 @@
+import type { StreamChunk } from '../types'
+
+/**
+ * Convert a StreamChunk async iterable to a ReadableStream in Server-Sent Events format
+ *
+ * This creates a ReadableStream that emits chunks in SSE format:
+ * - Each chunk is prefixed with "data: "
+ * - Each chunk is followed by "\n\n"
+ * - Stream ends with "data: [DONE]\n\n"
+ *
+ * @param stream - AsyncIterable of StreamChunks from chat()
+ * @param abortController - Optional AbortController to abort when stream is cancelled
+ * @returns ReadableStream in Server-Sent Events format
+ *
+ * @example
+ * ```typescript
+ * const stream = chat({ adapter: openai(), model: "gpt-4o", messages: [...] });
+ * const readableStream = toServerSentEventsStream(stream);
+ * // Use with Response, or any API that accepts ReadableStream
+ * ```
+ */
+export function toServerSentEventsStream(
+  stream: AsyncIterable<StreamChunk>,
+  abortController?: AbortController,
+): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder()
+
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const chunk of stream) {
+          // Check if stream was cancelled/aborted
+          if (abortController?.signal.aborted) {
+            break
+          }
+
+          // Send each chunk as Server-Sent Events format
+          controller.enqueue(
+            encoder.encode(`data: ${JSON.stringify(chunk)}\n\n`),
+          )
+        }
+
+        // Send completion marker
+        controller.enqueue(encoder.encode('data: [DONE]\n\n'))
+        controller.close()
+      } catch (error: any) {
+        // Don't send error if aborted
+        if (abortController?.signal.aborted) {
+          controller.close()
+          return
+        }
+
+        // Send error chunk
+        controller.enqueue(
+          encoder.encode(
+            `data: ${JSON.stringify({
+              type: 'error',
+              error: {
+                message: error.message || 'Unknown error occurred',
+                code: error.code,
+              },
+            })}\n\n`,
+          ),
+        )
+        controller.close()
+      }
+    },
+    cancel() {
+      // When the ReadableStream is cancelled (e.g., client disconnects),
+      // abort the underlying stream
+      if (abortController) {
+        abortController.abort()
+      }
+    },
+  })
+}
+
+/**
+ * Create a streaming HTTP response from a StreamChunk async iterable
+ * Includes proper headers for Server-Sent Events
+ *
+ * @param stream - AsyncIterable of StreamChunks from chat()
+ * @param init - Optional Response initialization options
+ * @param abortController - Optional AbortController to abort when client disconnects
+ * @returns Response object with SSE headers and streaming body
+ *
+ * @example
+ * ```typescript
+ * export async function POST(request: Request) {
+ *   const { messages } = await request.json();
+ *   const abortController = new AbortController();
+ *   const stream = chat({
+ *     adapter: openai(),
+ *     model: "gpt-4o",
+ *     messages,
+ *     options: { abortSignal: abortController.signal }
+ *   });
+ *   return toStreamResponse(stream, undefined, abortController);
+ * }
+ * ```
+ */
+export function toStreamResponse(
+  stream: AsyncIterable<StreamChunk>,
+  init?: ResponseInit & { abortController?: AbortController },
+): Response {
+  const { headers, abortController, ...responseInit } = init ?? {}
+  return new Response(toServerSentEventsStream(stream, abortController), {
+    ...responseInit,
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+      ...(headers || {}),
+    },
+  })
+}