@tanstack/ai-solid 0.6.3 → 0.6.6

package/src/use-transcription.ts

@@ -0,0 +1,123 @@
+import { useGeneration } from './use-generation'
+import type { StreamChunk, TranscriptionResult } from '@tanstack/ai'
+import type {
+  ConnectionAdapter,
+  GenerationClientState,
+  GenerationFetcher,
+  InferGenerationOutput,
+  TranscriptionGenerateInput,
+} from '@tanstack/ai-client'
+import type { Accessor } from 'solid-js'
+
+/**
+ * Options for the useTranscription hook.
+ *
+ * @template TOutput - The transformed output type (defaults to TranscriptionResult)
+ */
+export interface UseTranscriptionOptions<TOutput = TranscriptionResult> {
+  /** Connection adapter for streaming transport (SSE, HTTP stream, custom) */
+  connection?: ConnectionAdapter
+  /** Direct async function for transcription */
+  fetcher?: GenerationFetcher<TranscriptionGenerateInput, TranscriptionResult>
+  /** Unique identifier for this generation instance */
+  id?: string
+  /** Additional body parameters to send with ConnectionAdapter requests */
+  body?: Record<string, any>
+  /**
+   * Callback when transcription 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: TranscriptionResult) => 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 useTranscription hook.
+ *
+ * @template TOutput - The transformed output type (defaults to TranscriptionResult)
+ */
+export interface UseTranscriptionReturn<TOutput = TranscriptionResult> {
+  /** Trigger transcription */
+  generate: (input: TranscriptionGenerateInput) => Promise<void>
+  /** The transcription result, or null */
+  result: Accessor<TOutput | null>
+  /** Whether transcription 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 transcription */
+  stop: () => void
+  /** Clear result, error, and return to idle */
+  reset: () => void
+}
+
+/**
+ * Solid hook for transcribing audio to text using AI models.
+ *
+ * @example
+ * ```tsx
+ * import { useTranscription } from '@tanstack/ai-solid'
+ * import { fetchServerSentEvents } from '@tanstack/ai-client'
+ *
+ * function Transcriber() {
+ *   const { generate, result, isLoading } = useTranscription({
+ *     connection: fetchServerSentEvents('/api/transcribe'),
+ *   })
+ *
+ *   const handleFile = (e: Event) => {
+ *     const input = e.target as HTMLInputElement
+ *     const file = input.files?.[0]
+ *     if (file) {
+ *       const reader = new FileReader()
+ *       reader.onload = () => {
+ *         generate({ audio: reader.result as string, language: 'en' })
+ *       }
+ *       reader.readAsDataURL(file)
+ *     }
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <input type="file" accept="audio/*" onChange={handleFile} />
+ *       {isLoading() && <p>Transcribing...</p>}
+ *       {result() && <p>{result()!.text}</p>}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useTranscription<
+  TOnResult extends ((result: TranscriptionResult) => any) | undefined =
+    undefined,
+>(
+  options: Omit<UseTranscriptionOptions, 'onResult'> & {
+    onResult?: TOnResult
+  },
+): UseTranscriptionReturn<
+  InferGenerationOutput<TranscriptionResult, TOnResult>
+> {
+  const { generate, result, isLoading, error, status, stop, reset } =
+    useGeneration<TranscriptionGenerateInput, TranscriptionResult, TOnResult>(
+      options,
+    )
+
+  return {
+    generate: generate as (input: TranscriptionGenerateInput) => Promise<void>,
+    result,
+    isLoading,
+    error,
+    status,
+    stop,
+    reset,
+  }
+}