@tanstack/ai-solid 0.6.3 → 0.6.4

package/src/use-generate-speech.ts

@@ -0,0 +1,109 @@
+import { useGeneration } from './use-generation'
+import type { StreamChunk, TTSResult } from '@tanstack/ai'
+import type {
+  ConnectionAdapter,
+  GenerationClientState,
+  GenerationFetcher,
+  InferGenerationOutput,
+  SpeechGenerateInput,
+} from '@tanstack/ai-client'
+import type { Accessor } from 'solid-js'
+
+/**
+ * Options for the useGenerateSpeech hook.
+ *
+ * @template TOutput - The transformed output type (defaults to TTSResult)
+ */
+export interface UseGenerateSpeechOptions<TOutput = TTSResult> {
+  /** Connection adapter for streaming transport (SSE, HTTP stream, custom) */
+  connection?: ConnectionAdapter
+  /** Direct async function for speech generation */
+  fetcher?: GenerationFetcher<SpeechGenerateInput, TTSResult>
+  /** Unique identifier for this generation instance */
+  id?: string
+  /** Additional body parameters to send with ConnectionAdapter requests */
+  body?: Record<string, any>
+  /**
+   * Callback when speech is generated. Can optionally return a transformed value.
+   *
+   * - Return a non-null value to transform and store it as the result
+   * - Return `null` to keep the previous result unchanged
+   * - Return nothing (`void`) to store the raw result as-is
+   */
+  onResult?: (result: TTSResult) => TOutput | null | void
+  /** Callback when an error occurs */
+  onError?: (error: Error) => void
+  /** Callback when progress is reported (0-100) */
+  onProgress?: (progress: number, message?: string) => void
+  /** Callback for each stream chunk (ConnectionAdapter mode only) */
+  onChunk?: (chunk: StreamChunk) => void
+}
+
+/**
+ * Return type for the useGenerateSpeech hook.
+ *
+ * @template TOutput - The transformed output type (defaults to TTSResult)
+ */
+export interface UseGenerateSpeechReturn<TOutput = TTSResult> {
+  /** Trigger speech generation */
+  generate: (input: SpeechGenerateInput) => Promise<void>
+  /** The TTS result containing audio data, or null */
+  result: Accessor<TOutput | null>
+  /** Whether generation is in progress */
+  isLoading: Accessor<boolean>
+  /** Current error, if any */
+  error: Accessor<Error | undefined>
+  /** Current state of the generation */
+  status: Accessor<GenerationClientState>
+  /** Abort the current generation */
+  stop: () => void
+  /** Clear result, error, and return to idle */
+  reset: () => void
+}
+
+/**
+ * Solid hook for generating speech (text-to-speech) using AI models.
+ *
+ * @example
+ * ```tsx
+ * import { useGenerateSpeech } from '@tanstack/ai-solid'
+ * import { fetchServerSentEvents } from '@tanstack/ai-client'
+ *
+ * function SpeechGenerator() {
+ *   const { generate, result, isLoading } = useGenerateSpeech({
+ *     connection: fetchServerSentEvents('/api/generate/speech'),
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => generate({ text: 'Hello world', voice: 'alloy' })}>
+ *         Generate Speech
+ *       </button>
+ *       {result() && (
+ *         <audio src={`data:audio/${result()!.format};base64,${result()!.audio}`} controls />
+ *       )}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useGenerateSpeech<
+  TOnResult extends ((result: TTSResult) => any) | undefined = undefined,
+>(
+  options: Omit<UseGenerateSpeechOptions, 'onResult'> & {
+    onResult?: TOnResult
+  },
+): UseGenerateSpeechReturn<InferGenerationOutput<TTSResult, TOnResult>> {
+  const { generate, result, isLoading, error, status, stop, reset } =
+    useGeneration<SpeechGenerateInput, TTSResult, TOnResult>(options)
+
+  return {
+    generate: generate as (input: SpeechGenerateInput) => Promise<void>,
+    result,
+    isLoading,
+    error,
+    status,
+    stop,
+    reset,
+  }
+}

package/src/use-generate-video.ts

@@ -0,0 +1,207 @@
+import { VideoGenerationClient } from '@tanstack/ai-client'
+import {
+  createEffect,
+  createMemo,
+  createSignal,
+  createUniqueId,
+} from 'solid-js'
+import type { StreamChunk } from '@tanstack/ai'
+import type {
+  ConnectionAdapter,
+  GenerationClientState,
+  GenerationFetcher,
+  InferGenerationOutput,
+  VideoGenerateInput,
+  VideoGenerateResult,
+  VideoStatusInfo,
+} from '@tanstack/ai-client'
+import type { Accessor } from 'solid-js'
+
+/**
+ * Options for the useGenerateVideo hook.
+ *
+ * @template TOutput - The transformed output type (defaults to VideoGenerateResult)
+ */
+export interface UseGenerateVideoOptions<TOutput = VideoGenerateResult> {
+  /** Connection adapter for streaming transport (server handles polling) */
+  connection?: ConnectionAdapter
+  /** Direct async function that returns a completed video result */
+  fetcher?: GenerationFetcher<VideoGenerateInput, VideoGenerateResult>
+  /** Unique identifier for this generation instance */
+  id?: string
+  /** Additional body parameters to send with ConnectionAdapter requests */
+  body?: Record<string, any>
+  /**
+   * Callback when video generation completes. Can optionally return a transformed value.
+   *
+   * - Return a non-null value to transform and store it as the result
+   * - Return `null` to keep the previous result unchanged
+   * - Return nothing (`void`) to store the raw result as-is
+   */
+  onResult?: (result: VideoGenerateResult) => TOutput | null | void
+  /** Callback when an error occurs */
+  onError?: (error: Error) => void
+  /** Callback when progress is reported (0-100) */
+  onProgress?: (progress: number, message?: string) => void
+  /** Callback when a video job is created */
+  onJobCreated?: (jobId: string) => void
+  /** Callback on each status update */
+  onStatusUpdate?: (status: VideoStatusInfo) => void
+  /** Callback for each stream chunk (ConnectionAdapter mode only) */
+  onChunk?: (chunk: StreamChunk) => void
+}
+
+/**
+ * Return type for the useGenerateVideo hook.
+ *
+ * @template TOutput - The transformed output type (defaults to VideoGenerateResult)
+ */
+export interface UseGenerateVideoReturn<TOutput = VideoGenerateResult> {
+  /** Trigger video generation */
+  generate: (input: VideoGenerateInput) => Promise<void>
+  /** The final video result (with URL), or null */
+  result: Accessor<TOutput | null>
+  /** The current job ID, or null */
+  jobId: Accessor<string | null>
+  /** Current video generation status info, or null */
+  videoStatus: Accessor<VideoStatusInfo | null>
+  /** Whether generation/polling is in progress */
+  isLoading: Accessor<boolean>
+  /** Current error, if any */
+  error: Accessor<Error | undefined>
+  /** Current state of the generation */
+  status: Accessor<GenerationClientState>
+  /** Abort the current generation/polling */
+  stop: () => void
+  /** Clear all state and return to idle */
+  reset: () => void
+}
+
+/**
+ * Solid hook for generating videos using AI models.
+ *
+ * Video generation is asynchronous: a job is created, then polled for status
+ * until completion. This hook handles the full lifecycle.
+ *
+ * @example
+ * ```tsx
+ * import { useGenerateVideo } from '@tanstack/ai-solid'
+ * import { fetchServerSentEvents } from '@tanstack/ai-client'
+ *
+ * function VideoGenerator() {
+ *   const { generate, result, videoStatus, isLoading } = useGenerateVideo({
+ *     connection: fetchServerSentEvents('/api/generate/video'),
+ *     onStatusUpdate: (status) => console.log(`Progress: ${status.progress}%`),
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => generate({ prompt: 'A flying car over a city' })}>
+ *         Generate Video
+ *       </button>
+ *       {isLoading() && videoStatus() && (
+ *         <p>Status: {videoStatus()!.status} ({videoStatus()!.progress}%)</p>
+ *       )}
+ *       {result() && <video src={result()!.url} controls />}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useGenerateVideo<
+  TOnResult extends ((result: VideoGenerateResult) => any) | undefined =
+    undefined,
+>(
+  options: Omit<UseGenerateVideoOptions, 'onResult'> & {
+    onResult?: TOnResult
+  },
+): UseGenerateVideoReturn<
+  InferGenerationOutput<VideoGenerateResult, TOnResult>
+> {
+  type TOutput = InferGenerationOutput<VideoGenerateResult, TOnResult>
+  const hookId = createUniqueId()
+  const clientId = options.id || hookId
+
+  const [result, setResult] = createSignal<TOutput | null>(null)
+  const [jobId, setJobId] = createSignal<string | null>(null)
+  const [videoStatus, setVideoStatus] = createSignal<VideoStatusInfo | null>(
+    null,
+  )
+  const [isLoading, setIsLoading] = createSignal(false)
+  const [error, setError] = createSignal<Error | undefined>(undefined)
+  const [status, setStatus] = createSignal<GenerationClientState>('idle')
+
+  const client = createMemo(() => {
+    const baseOptions = {
+      id: clientId,
+      body: options.body,
+      onResult: (r: VideoGenerateResult) => options.onResult?.(r),
+      onError: (e: Error) => options.onError?.(e),
+      onProgress: (p: number, m?: string) => options.onProgress?.(p, m),
+      onChunk: (c: StreamChunk) => options.onChunk?.(c),
+      onJobCreated: (id: string) => options.onJobCreated?.(id),
+      onStatusUpdate: (s: VideoStatusInfo) => options.onStatusUpdate?.(s),
+      onResultChange: setResult,
+      onLoadingChange: setIsLoading,
+      onErrorChange: setError,
+      onStatusChange: setStatus,
+      onJobIdChange: setJobId,
+      onVideoStatusChange: setVideoStatus,
+    }
+
+    if (options.connection) {
+      return new VideoGenerationClient<TOutput>({
+        ...baseOptions,
+        connection: options.connection,
+      })
+    }
+
+    if (options.fetcher) {
+      return new VideoGenerationClient<TOutput>({
+        ...baseOptions,
+        fetcher: options.fetcher,
+      })
+    }
+
+    throw new Error(
+      'useGenerateVideo requires either a connection or fetcher option',
+    )
+  }, [clientId])
+
+  // Sync body changes without recreating client
+  createEffect(() => {
+    const currentBody = options.body
+    client().updateOptions({ body: currentBody })
+  })
+
+  // Cleanup on unmount: stop any in-flight requests
+  createEffect(() => {
+    return () => {
+      client().stop()
+    }
+  })
+
+  const generate = async (input: VideoGenerateInput) => {
+    await client().generate(input)
+  }
+
+  const stop = () => {
+    client().stop()
+  }
+
+  const reset = () => {
+    client().reset()
+  }
+
+  return {
+    generate,
+    result,
+    jobId,
+    videoStatus,
+    isLoading,
+    error,
+    status,
+    stop,
+    reset,
+  }
+}

package/src/use-generation.ts

@@ -0,0 +1,179 @@
+import { GenerationClient } from '@tanstack/ai-client'
+import {
+  createEffect,
+  createMemo,
+  createSignal,
+  createUniqueId,
+} from 'solid-js'
+import type { StreamChunk } from '@tanstack/ai'
+import type {
+  ConnectionAdapter,
+  GenerationClientOptions,
+  GenerationClientState,
+  GenerationFetcher,
+  InferGenerationOutput,
+} from '@tanstack/ai-client'
+import type { Accessor } from 'solid-js'
+
+/**
+ * Options for the useGeneration hook.
+ *
+ * Accepts either a `connection` (streaming transport) or a `fetcher` (direct async call).
+ *
+ * @template TInput - The input type for the generation request
+ * @template TResult - The result type returned by the generation
+ * @template TOutput - The transformed output type (defaults to TResult)
+ */
+export interface UseGenerationOptions<TInput, TResult, TOutput = TResult> {
+  /** Connection adapter for streaming transport (SSE, HTTP stream, custom) */
+  connection?: ConnectionAdapter
+  /** Direct async function for one-shot generation (no streaming protocol needed) */
+  fetcher?: GenerationFetcher<TInput, TResult>
+  /** Unique identifier for this generation instance */
+  id?: string
+  /** Additional body parameters to send with ConnectionAdapter requests */
+  body?: Record<string, any>
+  /**
+   * Callback when a result is received. Can optionally return a transformed value.
+   *
+   * - Return a non-null value to transform and store it as the result
+   * - Return `null` to keep the previous result unchanged
+   * - Return nothing (`void`) to store the raw result as-is
+   */
+  onResult?: (result: TResult) => TOutput | null | void
+  /** Callback when an error occurs */
+  onError?: (error: Error) => void
+  /** Callback when progress is reported (0-100) */
+  onProgress?: (progress: number, message?: string) => void
+  /** Callback for each stream chunk (ConnectionAdapter mode only) */
+  onChunk?: (chunk: StreamChunk) => void
+}
+
+/**
+ * Return type for the useGeneration hook.
+ *
+ * @template TOutput - The output type (possibly transformed from the raw result)
+ */
+export interface UseGenerationReturn<TOutput> {
+  /** Trigger a generation request */
+  generate: (input: Record<string, any>) => Promise<void>
+  /** The generation result, or null if not yet generated */
+  result: Accessor<TOutput | null>
+  /** Whether a generation is currently in progress */
+  isLoading: Accessor<boolean>
+  /** Current error, if any */
+  error: Accessor<Error | undefined>
+  /** Current state of the generation client */
+  status: Accessor<GenerationClientState>
+  /** Abort the current generation */
+  stop: () => void
+  /** Clear result, error, and return to idle */
+  reset: () => void
+}
+
+/**
+ * Generic Solid hook for one-shot generation tasks.
+ *
+ * This is the base hook used by `useGenerateImage`, `useGenerateSpeech`,
+ * `useTranscription`, and `useSummarize`. You can also use it directly
+ * for custom generation types.
+ *
+ * @template TInput - The input type for the generation request
+ * @template TResult - The result type returned by the generation
+ * @template TOutput - The transformed output type (defaults to TResult)
+ *
+ * @example
+ * ```tsx
+ * const { generate, result, isLoading } = useGeneration<MyInput, MyResult>({
+ *   connection: fetchServerSentEvents('/api/generate/custom'),
+ * })
+ *
+ * await generate({ prompt: 'Hello' })
+ * ```
+ */
+export function useGeneration<
+  TInput extends Record<string, any>,
+  TResult,
+  TOnResult extends ((result: TResult) => any) | undefined = undefined,
+>(
+  options: Omit<UseGenerationOptions<TInput, TResult>, 'onResult'> & {
+    onResult?: TOnResult
+  },
+): UseGenerationReturn<InferGenerationOutput<TResult, TOnResult>> {
+  type TOutput = InferGenerationOutput<TResult, TOnResult>
+  const hookId = createUniqueId()
+  const clientId = options.id || hookId
+
+  const [result, setResult] = createSignal<TOutput | null>(null)
+  const [isLoading, setIsLoading] = createSignal(false)
+  const [error, setError] = createSignal<Error | undefined>(undefined)
+  const [status, setStatus] = createSignal<GenerationClientState>('idle')
+
+  const client = createMemo(() => {
+    const clientOptions: GenerationClientOptions<TInput, TResult, TOutput> = {
+      id: clientId,
+      body: options.body,
+      onResult: (r: TResult) => options.onResult?.(r),
+      onError: (e: Error) => options.onError?.(e),
+      onProgress: (p: number, m?: string) => options.onProgress?.(p, m),
+      onChunk: (c: StreamChunk) => options.onChunk?.(c),
+      onResultChange: setResult,
+      onLoadingChange: setIsLoading,
+      onErrorChange: setError,
+      onStatusChange: setStatus,
+    }
+
+    if (options.connection) {
+      return new GenerationClient<TInput, TResult, TOutput>({
+        ...clientOptions,
+        connection: options.connection,
+      })
+    }
+
+    if (options.fetcher) {
+      return new GenerationClient<TInput, TResult, TOutput>({
+        ...clientOptions,
+        fetcher: options.fetcher,
+      })
+    }
+
+    throw new Error(
+      'useGeneration requires either a connection or fetcher option',
+    )
+  }, [clientId])
+
+  // Sync body changes without recreating client
+  createEffect(() => {
+    const currentBody = options.body
+    client().updateOptions({ body: currentBody })
+  })
+
+  // Cleanup on unmount: stop any in-flight requests
+  createEffect(() => {
+    return () => {
+      client().stop()
+    }
+  })
+
+  const generate = async (input: TInput) => {
+    await client().generate(input)
+  }
+
+  const stop = () => {
+    client().stop()
+  }
+
+  const reset = () => {
+    client().reset()
+  }
+
+  return {
+    generate: generate as (input: Record<string, any>) => Promise<void>,
+    result,
+    isLoading,
+    error,
+    status,
+    stop,
+    reset,
+  }
+}

package/src/use-summarize.ts

@@ -0,0 +1,115 @@
+import { useGeneration } from './use-generation'
+import type { StreamChunk, SummarizationResult } from '@tanstack/ai'
+import type {
+  ConnectionAdapter,
+  GenerationClientState,
+  GenerationFetcher,
+  InferGenerationOutput,
+  SummarizeGenerateInput,
+} from '@tanstack/ai-client'
+import type { Accessor } from 'solid-js'
+
+/**
+ * Options for the useSummarize hook.
+ *
+ * @template TOutput - The transformed output type (defaults to SummarizationResult)
+ */
+export interface UseSummarizeOptions<TOutput = SummarizationResult> {
+  /** Connection adapter for streaming transport (SSE, HTTP stream, custom) */
+  connection?: ConnectionAdapter
+  /** Direct async function for summarization */
+  fetcher?: GenerationFetcher<SummarizeGenerateInput, SummarizationResult>
+  /** Unique identifier for this generation instance */
+  id?: string
+  /** Additional body parameters to send with ConnectionAdapter requests */
+  body?: Record<string, any>
+  /**
+   * Callback when summarization is complete. Can optionally return a transformed value.
+   *
+   * - Return a non-null value to transform and store it as the result
+   * - Return `null` to keep the previous result unchanged
+   * - Return nothing (`void`) to store the raw result as-is
+   */
+  onResult?: (result: SummarizationResult) => TOutput | null | void
+  /** Callback when an error occurs */
+  onError?: (error: Error) => void
+  /** Callback when progress is reported (0-100) */
+  onProgress?: (progress: number, message?: string) => void
+  /** Callback for each stream chunk (ConnectionAdapter mode only) */
+  onChunk?: (chunk: StreamChunk) => void
+}
+
+/**
+ * Return type for the useSummarize hook.
+ *
+ * @template TOutput - The transformed output type (defaults to SummarizationResult)
+ */
+export interface UseSummarizeReturn<TOutput = SummarizationResult> {
+  /** Trigger summarization */
+  generate: (input: SummarizeGenerateInput) => Promise<void>
+  /** The summarization result, or null */
+  result: Accessor<TOutput | null>
+  /** Whether summarization is in progress */
+  isLoading: Accessor<boolean>
+  /** Current error, if any */
+  error: Accessor<Error | undefined>
+  /** Current state of the generation */
+  status: Accessor<GenerationClientState>
+  /** Abort the current summarization */
+  stop: () => void
+  /** Clear result, error, and return to idle */
+  reset: () => void
+}
+
+/**
+ * Solid hook for summarizing text using AI models.
+ *
+ * @example
+ * ```tsx
+ * import { useSummarize } from '@tanstack/ai-solid'
+ * import { fetchServerSentEvents } from '@tanstack/ai-client'
+ *
+ * function Summarizer() {
+ *   const { generate, result, isLoading } = useSummarize({
+ *     connection: fetchServerSentEvents('/api/summarize'),
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => generate({
+ *         text: 'Long article text...',
+ *         style: 'bullet-points',
+ *         maxLength: 200,
+ *       })}>
+ *         Summarize
+ *       </button>
+ *       {isLoading() && <p>Summarizing...</p>}
+ *       {result() && <p>{result()!.summary}</p>}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useSummarize<
+  TOnResult extends ((result: SummarizationResult) => any) | undefined =
+    undefined,
+>(
+  options: Omit<UseSummarizeOptions, 'onResult'> & {
+    onResult?: TOnResult
+  },
+): UseSummarizeReturn<InferGenerationOutput<SummarizationResult, TOnResult>> {
+  const { generate, result, isLoading, error, status, stop, reset } =
+    useGeneration<SummarizeGenerateInput, SummarizationResult, TOnResult>(
+      options,
+    )
+
+  return {
+    generate: generate as (input: SummarizeGenerateInput) => Promise<void>,
+    result,
+    isLoading,
+    error,
+    status,
+    stop,
+    reset,
+  }
+}