Open History to see the last commit
1import { useGeneration } from './use-generation'
2import { reconstructSummarizeResult } from '@tanstack/ai-client'
3import type { StreamChunk, SummarizationResult } from '@tanstack/ai'
4import type {
5 AIDevtoolsDisplayOptions,
6 ConnectConnectionAdapter,
7 GenerationClientState,
8 GenerationFetcher,
9 GenerationPersistenceOptions,
10 InferGenerationOutputFromReturn,
11 SummarizeGenerateInput,
12} from '@tanstack/ai-client'
13
14/**
15 * Options for the useSummarize hook.
16 *
17 * @template TOutput - The output type after optional transform (defaults to SummarizationResult)
18 */
19export interface UseSummarizeOptions<TOutput = SummarizationResult> {
20 /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
21 connection?: ConnectConnectionAdapter
22 /** Direct async function for summarization */
23 fetcher?: GenerationFetcher<SummarizeGenerateInput, SummarizationResult>
24 /**
25 * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).
26 */
27 id?: string
28 /** Additional body parameters to send with connect-based adapter requests */
29 body?: Record<string, any>
30 /** Display options for TanStack AI Devtools. */
31 devtools?: AIDevtoolsDisplayOptions
32 /**
33 * How this generation persists across reloads.
34 * - Omit / `false`: ephemeral, in-memory only.
35 * - `true`: server-driven — on mount the client hydrates the last generation
36 * for its `threadId` from the server (needs a connection with a
37 * `hydrateGeneration` handler) and repaints it; it never auto-starts a run.
38 */
39 persistence?: boolean
40 /**
41 * The **scope** this generation belongs to: a stable, app-chosen name for the
42 * slot successive runs fill — not a link to a chat conversation.
43 *
44 * The hook starts empty and produces many runs over its life; each gets its
45 * own `runId`, but all belong to one scope. Persistence keys on this, so
46 * derive it from your own domain and keep it identical across reloads (e.g.
47 * `` `video-${videoId}-start-frame` ``). It is also sent as the AG-UI thread
48 * id on the wire, which the protocol requires.
49 *
50 * **Required whenever `persistence` is set** — an app that cannot name the
51 * scope has nothing to restore to. Optional for ephemeral generations, where
52 * it falls back to `id` purely to satisfy the wire.
53 */
54 threadId?: string
55 /**
56 * Server-driven hydration handler for `persistence: true` when the
57 * connection doesn't carry one (e.g. alongside `fetcher`, or a `stream()` /
58 * `rpcStream()` adapter built without handlers) — typically a one-line
59 * server-function call. The connection's own handler takes precedence.
60 */
61 hydrateGeneration?: ConnectConnectionAdapter['hydrateGeneration']
62 /**
63 * Re-attach handler that replays a run still generating to completion on
64 * mount, when the connection doesn't carry one. Without it, a restored
65 * `running` snapshot surfaces as an (interrupted) error. The connection's
66 * own handler takes precedence.
67 */
68 joinRun?: ConnectConnectionAdapter['joinRun']
69 /**
70 * Callback when summarization is complete. Can optionally return a transformed value.
71 *
72 * - Return a non-null value to transform and store it as the result
73 * - Return `null` to keep the previous result unchanged
74 * - Return nothing (`void`) to store the raw result as-is
75 */
76 onResult?: (result: SummarizationResult) => TOutput | null | void
77 /** Callback when an error occurs */
78 onError?: (error: Error) => void
79 /** Callback when progress is reported (0-100) */
80 onProgress?: (progress: number, message?: string) => void
81 /** Callback for each stream chunk (connect-based adapter mode only) */
82 onChunk?: (chunk: StreamChunk) => void
83}
84
85/**
86 * Return type for the useSummarize hook.
87 *
88 * @template TOutput - The output type (after optional transform)
89 */
90export interface UseSummarizeReturn<TOutput = SummarizationResult> {
91 /** Trigger summarization */
92 generate: (input: SummarizeGenerateInput) => Promise<void>
93 /** The summarization result, or null */
94 result: TOutput | null
95 /** Whether summarization is in progress */
96 isLoading: boolean
97 /** Current error, if any */
98 error: Error | undefined
99 /** Current state of the generation */
100 status: GenerationClientState
101 /** Abort the current summarization */
102 stop: () => void
103 /** Clear result, error, and return to idle */
104 reset: () => void
105 /**
106 * The id of the generation job currently running, or `null` when nothing is in
107 * flight. Each call to `generate` is one job with its own id. Pass it to your
108 * own endpoint to cancel or poll the provider job — `stop()` only aborts the
109 * local stream, it does not stop work already running on the provider.
110 */
111 runId: string | null
112}
113
114/**
115 * React hook for summarizing text using AI models.
116 *
117 * @example
118 * ```tsx
119 * import { useSummarize } from '@tanstack/ai-react'
120 * import { fetchServerSentEvents } from '@tanstack/ai-client'
121 *
122 * function Summarizer() {
123 * const { generate, result, isLoading } = useSummarize({
124 * connection: fetchServerSentEvents('/api/summarize'),
125 * })
126 *
127 * return (
128 * <div>
129 * <button onClick={() => generate({
130 * text: 'Long article text...',
131 * style: 'bullet-points',
132 * maxLength: 200,
133 * })}>
134 * Summarize
135 * </button>
136 * {isLoading && <p>Summarizing...</p>}
137 * {result && <p>{result.summary}</p>}
138 * </div>
139 * )
140 * }
141 * ```
142 */
143export function useSummarize<TTransformed = void>(
144 options: Omit<
145 UseSummarizeOptions,
146 'onResult' | 'persistence' | 'threadId' | 'id'
147 > & {
148 onResult?: (result: SummarizationResult) => TTransformed
149 } & GenerationPersistenceOptions,
150): UseSummarizeReturn<
151 InferGenerationOutputFromReturn<SummarizationResult, TTransformed>
152> {
153 const devtools = {
154 ...options.devtools,
155 framework: 'react',
156 hookName: 'useSummarize',
157 outputKind: 'text' as const,
158 }
159 const generation = useGeneration<
160 SummarizeGenerateInput,
161 SummarizationResult,
162 TTransformed
163 >({
164 ...options,
165 devtools,
166 reconstructResult: reconstructSummarizeResult,
167 })
168
169 return generation
170}