@mfui/gemini

@mfui/gemini adapts Gemini SSE streams into MFUI semantic SSE streams.

Use this package when the upstream stream emits Gemini chunks with either text or candidates[].content.parts[].text.

createMFUIResponse()

Creates an MFUI semantic SSE Response from an upstream Gemini stream.

Import

import { createMFUIResponse } from '@mfui/gemini';

Signature

function createMFUIResponse(
  source: GeminiStreamSource,
  mfui: MFUIManifest,
  options?: GeminiMFUIResponseOptions,
): Response

Parameters

Name	Type	Required	Default	Description
source	GeminiStreamSource	Yes	n/a	Provider Response, response body stream, or null.
mfui	MFUIManifest	Yes	n/a	Components available to this request.
options	GeminiMFUIResponseOptions	No	{}	Response, parser, writer, and lifecycle options.

Returns

Type	Description
Response	text/event-stream response that emits MFUI semantic SSE events.

Example

import { createMFUIPrompt } from '@mfui/server';
import { createMFUIResponse } from '@mfui/gemini';

const upstream = await fetch(
  'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      systemInstruction: {
        parts: [
          {
            text: [
              'You are a helpful assistant.',
              createMFUIPrompt(mfui),
            ].join('\n\n'),
          },
        ],
      },
      contents,
    }),
  },
);

return createMFUIResponse(upstream, mfui);

Notes

When provider processing fails, the returned MFUI stream emits an error event and then closes. onError is called when provided.

GeminiStreamSource

Source accepted by createMFUIResponse(), readStream(), and pipeMFUIStream().

Shape

type GeminiStreamSource =
  | Response
  | ReadableStream<Uint8Array>
  | null

GeminiMFUIResponseOptions

Options for createMFUIResponse().

Property	Type	Required	Default	Description
close	boolean	No	true	Whether to close the MFUI parser and writer when the provider stream finishes.
parser	MFUIBlockParserOptions	No	{}	Options passed to createMFUIBlockParser().
writer	MFUIStreamWriterOptions	No	{}	Options passed to createMFUIStreamWriter().
responseInit	ResponseInit	No	{}	Init object passed to the returned Response.
onMessage	MFUIMessageHandler	No	n/a	Called with the final projected message after the MFUI response finishes.
onError	MFUIErrorHandler	No	n/a	Called when provider stream processing or MFUI block parsing fails.

readStream()

Reads Gemini SSE events and yields JSON chunks.

Import

import { readStream } from '@mfui/gemini';

Signature

function readStream(
  source: GeminiStreamSource,
): AsyncIterable<GeminiStreamChunk>

Parameters

Name	Type	Required	Default	Description
source	GeminiStreamSource	Yes	n/a	Provider SSE source.

Returns

Type	Description
AsyncIterable<GeminiStreamChunk>	Parsed provider chunks.

GeminiStreamChunk

Provider chunk shape consumed by writeMFUIStream().

Property	Type	Required	Default	Description
text	string	No	n/a	Direct text chunk. Used before candidate text parts when present.
candidates	Array<Record<string, unknown>>	No	n/a	Candidate objects. Text is read from candidate.content.parts[].text.
usageMetadata	GeminiUsageMetadata	No	n/a	Token usage metadata.
[key]	unknown	No	n/a	Additional provider fields are ignored by MFUI.

GeminiUsageMetadata

Usage metadata read from Gemini chunks.

Property	Type	Required	Default	Description
promptTokenCount	number	No	n/a	Maps to MFUI inputTokens.
candidatesTokenCount	number	No	n/a	Maps to MFUI outputTokens.
[key]	unknown	No	n/a	Additional usage fields are ignored by MFUI.

writeMFUIStream()

Writes parsed Gemini chunks into an MFUI block parser.

Import

import { writeMFUIStream } from '@mfui/gemini';

Signature

function writeMFUIStream(
  stream: AsyncIterable<GeminiStreamChunk>,
  parser: MFUIBlockParser,
  options?: GeminiMFUIStreamOptions,
): Promise<void>

Parameters

Name	Type	Required	Default	Description
stream	AsyncIterable<GeminiStreamChunk>	Yes	n/a	Parsed provider chunks.
parser	MFUIBlockParser	Yes	n/a	MFUI block parser receiving provider text deltas.
options	GeminiMFUIStreamOptions	No	{}	Stream writing options.

Returns

Type	Description
Promise<void>	Resolves after the provider stream is fully consumed and the parser is flushed or closed.

GeminiMFUIStreamOptions

Options for writeMFUIStream() and pipeMFUIStream().

Property	Type	Required	Default	Description
close	boolean	No	true	Whether to call parser.close() when the provider stream ends. When false, parser.flush() is called instead.

pipeMFUIStream()

Reads a provider SSE source and writes it into an MFUI block parser.

Import

import { pipeMFUIStream } from '@mfui/gemini';

Signature

function pipeMFUIStream(
  source: GeminiStreamSource,
  parser: MFUIBlockParser,
  options?: GeminiMFUIStreamOptions,
): Promise<void>

Parameters

Name	Type	Required	Default	Description
source	GeminiStreamSource	Yes	n/a	Provider SSE source.
parser	MFUIBlockParser	Yes	n/a	MFUI block parser receiving provider text deltas.
options	GeminiMFUIStreamOptions	No	{}	Stream writing options.

Returns

Type	Description
Promise<void>	Resolves after the provider stream is consumed.