@cavi-ai/api-client/providers/gemini

/** Build inline batch request entries keyed by customId. */
export declare function buildGeminiBatchInlineEntries(requests: RuntimeBatchRequest[], defaultModel?: string): {
    model: string;
    entries: GeminiBatchInlineEntry[];
};

/** Build JSONL for file-based batch submission. */
export declare function buildGeminiBatchInputJsonl(requests: RuntimeBatchRequest[], defaultModel?: string): {
    model: string;
    jsonl: string;
};

/**
 * Build the Gemini request body from the universal run-start body. Full role
 * fidelity: `system`-role array messages and `instructions` both feed
 * `systemInstruction`; `assistant`->`model`, everything else->`user`. Throws
 * ValidationFailed if no model is resolvable.
 */
export declare function buildGeminiRequestBody(body: RuntimeRunStartBody, defaultModel?: string): {
    model: string;
    payload: Record<string, unknown>;
};

export declare function createGeminiProviderModule(config: GeminiApiClientOptions): RuntimeProviderModule;

export declare function estimateGeminiBatchInlineBytes(entries: GeminiBatchInlineEntry[]): number;

/**
 * Flatten Gemini `usageMetadata` into a flat numeric record. usageMetadata is a
 * flat object of token counts (promptTokenCount, candidatesTokenCount,
 * totalTokenCount, cachedContentTokenCount?); newer responses add nested
 * `*Details` arrays which are not named counts and are ignored. The core
 * `normalizeRuntimeUsage` already aliases the Gemini keys.
 */
export declare function flattenGeminiUsageMetadata(value: unknown): Record<string, number> | undefined;

export declare const GEMINI_API_BASE_URL = "https://generativelanguage.googleapis.com";

export declare const GEMINI_API_VERSION = "v1beta";

export declare const GEMINI_BATCH_INLINE_MAX_BYTES: number;

export declare const GEMINI_FILES_UPLOAD_PATH = "/upload/v1beta/files";

export declare const GEMINI_RUNTIME_SUPPORT: Readonly<{
    runs: true;
    streaming: true;
    batch: true;
}>;

export declare class GeminiApiClient extends BaseHttpApiClient implements RuntimeClient {
    readonly request: HttpApiTransport;
    private readonly defaultModel?;
    private readonly files;
    constructor(options: GeminiApiClientOptions);
    getRuntimeCapabilities(): Promise<RuntimeCapabilities>;
    startRun(body: RuntimeRunStartBody): Promise<RuntimeRunStatus>;
    streamRun(body: RuntimeRunStartBody, handlers: RunEventStreamHandlers, options?: {
        signal?: AbortSignal;
    }): Promise<void>;
    getRun(_runId: string): Promise<RuntimeRunStatus>;
    cancelRun(_runId: string): Promise<{
        status: string;
    }>;
    submitBatch(requests: RuntimeBatchRequest[]): Promise<RuntimeBatchStatus>;
    getBatch(batchId: string): Promise<RuntimeBatchStatus>;
    cancelBatch(batchId: string): Promise<RuntimeBatchStatus>;
    getBatchResults(batchId: string): Promise<RuntimeBatchResult[]>;
    private readBatchModel;
    private stateless;
}

export type GeminiApiClientOptions = {
    /** Gemini Developer API (AI Studio) key. Keep backend-owned; do not embed in browsers/mobile. */
    apiKey: string;
    /** Default model when a run does not specify one. No id ships by default. */
    defaultModel?: string;
    baseUrl?: string;
    fetchImpl?: typeof fetch;
    onTrace?: HttpApiClientOptions["onTrace"];
};

export declare function geminiBatchCancelPath(batchId: string): string;

export declare function geminiBatchGenerateContentPath(model: string): string;

export declare function geminiBatchPath(batchId: string): string;

export declare function geminiFileDownloadPath(fileName: string): string;

export type GeminiFileObject = {
    name: string;
} & Record<string, unknown>;

export declare function geminiFilePath(fileName: string): string;

/** Gemini Files API client (resumable upload + download). */
export declare class GeminiFilesClient extends BaseHttpApiClient {
    readonly request: HttpApiTransport;
    private readonly uploadFetch;
    constructor(options: GeminiFilesClientOptions);
    /** Upload text content via Google's resumable upload protocol. */
    uploadFile(content: string, options?: {
        displayName?: string;
        mimeType?: string;
    }): Promise<GeminiFileObject>;
    /** Download raw file content (batch output JSONL). */
    downloadFile(fileName: string): Promise<string>;
    retrieveFile(fileName: string): Promise<GeminiFileObject>;
    deleteFile(fileName: string): Promise<Record<string, unknown>>;
}

export type GeminiFilesClientOptions = {
    /** Gemini Developer API (AI Studio) key. Keep backend-owned. */
    apiKey: string;
    baseUrl?: string;
    fetchImpl?: typeof fetch;
    onTrace?: HttpApiClientOptions["onTrace"];
    defaultTimeoutMs?: number;
};

export declare function geminiGenerateContentPath(model: string): string;

export type GeminiGenerateContentResponse = {
    candidates?: GeminiCandidate[];
    promptFeedback?: {
        blockReason?: string;
    };
    usageMetadata?: Record<string, unknown>;
    modelVersion?: string;
};

export declare function geminiStreamGenerateContentPath(model: string): string;

/** Map a Gemini batch job object to canonical batch status. */
export declare function mapGeminiBatch(raw: unknown): RuntimeBatchStatus;

/** Map a Gemini generateContent response to the universal run status. */
export declare function mapGeminiGenerateContentToRunStatus(model: string, response: GeminiGenerateContentResponse): RuntimeRunStatus;

/** Map one Gemini SSE chunk to a MESSAGE_DELTA, or null when it carries no text. */
export declare function mapGeminiStreamChunk(sse: SseMessage, runId: string): RunStreamEvent | null;

export declare function normalizeGeminiBatchName(batchId: string): string;

/** Parse file-based batch result JSONL. */
export declare function parseGeminiBatchOutputJsonl(jsonlText: string, model: string, mapResponse?: (response: GeminiGenerateContentResponse) => RuntimeRunStatus, options?: ParseGeminiBatchResultsOptions): RuntimeBatchResult[];

export type ParseGeminiBatchResultsOptions = {
    malformedLine?: "skip" | "throw";
};

/** Parse inline batch responses from a GET batch payload. */
export declare function parseGeminiInlineBatchResults(raw: unknown, model: string, mapResponse?: (response: GeminiGenerateContentResponse) => RuntimeRunStatus): RuntimeBatchResult[];

export declare function readGeminiBatchResponsesFile(raw: unknown): string | undefined;

/** Return the first candidate's finishReason, if the chunk is terminal. */
export declare function readGeminiFinishReason(sse: SseMessage): string | null;

/** Extract the flat usageMetadata numbers from a chunk, if present. */
export declare function readGeminiStreamUsage(sse: SseMessage): Record<string, number> | null;

/** Resolve one model for the whole batch; throws when models disagree or are missing. */
export declare function resolveGeminiBatchModel(requests: RuntimeBatchRequest[], defaultModel?: string): string;