@jaypie/llm 1.3.11 → 1.3.13

package/dist/esm/operate/adapters/FireworksAdapter.d.ts

@@ -0,0 +1,152 @@
+import { JsonObject, NaturalSchema } from "@jaypie/types";
+import { z } from "zod/v4";
+import { Toolkit } from "../../tools/Toolkit.class.js";
+import { LlmHistory, LlmOperateOptions, LlmUsageItem } from "../../types/LlmProvider.interface.js";
+import { LlmStreamChunk } from "../../types/LlmStreamChunk.interface.js";
+import { ClassifiedError, OperateRequest, ParsedResponse, ProviderToolDefinition, StandardToolCall, StandardToolResult } from "../types.js";
+import { BaseProviderAdapter } from "./ProviderAdapter.interface.js";
+interface FireworksMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content?: string | FireworksContentPart[] | null;
+    toolCalls?: FireworksToolCall[];
+    toolCallId?: string;
+}
+interface FireworksToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface FireworksResponseMessage {
+    role: "assistant";
+    content?: string | null;
+    toolCalls?: FireworksToolCall[];
+    refusal?: string | null;
+    reasoning?: string | null;
+    reasoning_content?: string | null;
+}
+interface FireworksChoice {
+    index: number;
+    message: FireworksResponseMessage;
+    finishReason: string | null;
+    finish_reason?: string | null;
+}
+interface FireworksUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+    completionTokensDetails?: {
+        reasoningTokens?: number;
+    };
+}
+interface FireworksResponse {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: FireworksChoice[];
+    usage?: FireworksUsage;
+}
+interface FireworksTool {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: JsonObject;
+    };
+}
+interface FireworksJsonSchemaConfig {
+    name: string;
+    description?: string;
+    schema: JsonObject;
+    strict?: boolean;
+}
+type FireworksResponseFormat = {
+    type: "json_schema";
+    json_schema: FireworksJsonSchemaConfig;
+} | {
+    type: "json_object";
+} | {
+    type: "text";
+};
+interface FireworksRequest {
+    model: string;
+    messages: FireworksMessage[];
+    tools?: FireworksTool[];
+    tool_choice?: "auto" | "none" | "required";
+    response_format?: FireworksResponseFormat;
+    reasoning_effort?: string;
+    user?: string;
+}
+/**
+ * Fireworks content part types. Fireworks follows the OpenAI Chat Completions
+ * multimodal schema for `image_url` parts (URL or base64 data URI). There is
+ * no OpenAI-style `file` part, and the API rejects `data:` URIs for documents
+ * ("Unsupported URL scheme 'data'"), so file inputs cannot be delivered.
+ */
+type FireworksContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image_url";
+    imageUrl: {
+        url: string;
+    };
+};
+/**
+ * FireworksAdapter implements the ProviderAdapter interface for Fireworks AI's
+ * OpenAI-compatible Chat Completions API. It handles request building,
+ * response parsing, and error classification specific to Fireworks.
+ */
+export declare class FireworksAdapter extends BaseProviderAdapter {
+    readonly name: "fireworks";
+    readonly defaultModel: string;
+    readonly supportsStructuredOutputRetry = true;
+    private runtimeNoStructuredOutputModels;
+    rememberModelRejectsStructuredOutput(model: string): void;
+    clearRuntimeNoStructuredOutputModels(): void;
+    private supportsStructuredOutput;
+    private runtimeNoTemperatureModels;
+    rememberModelRejectsTemperature(model: string): void;
+    clearRuntimeNoTemperatureModels(): void;
+    private supportsTemperature;
+    buildRequest(request: OperateRequest): FireworksRequest;
+    formatTools(toolkit: Toolkit, _outputSchema?: JsonObject): ProviderToolDefinition[];
+    formatOutputSchema(schema: JsonObject | NaturalSchema | z.ZodType): JsonObject;
+    executeRequest(client: unknown, request: unknown, signal?: AbortSignal): Promise<FireworksResponse>;
+    /**
+     * Serialize the internal request into the OpenAI-compatible wire body for
+     * Fireworks' Chat Completions endpoint. Top-level fields (model, tools,
+     * tool_choice, response_format, reasoning_effort, user, temperature, and any
+     * providerOptions) are already wire-shaped (snake_case); only messages carry
+     * camelCase tool fields that must become snake_case on the wire.
+     */
+    private toWireBody;
+    /**
+     * Rebuild a structured-output request without `response_format`, swapping in
+     * the legacy fake-tool emulation. Used as a runtime fallback when a model
+     * rejects native json_schema.
+     */
+    private toFallbackStructuredOutputRequest;
+    executeStreamRequest(client: unknown, request: unknown, signal?: AbortSignal): AsyncIterable<LlmStreamChunk>;
+    parseResponse(response: unknown, _options?: LlmOperateOptions): ParsedResponse;
+    extractToolCalls(response: unknown): StandardToolCall[];
+    extractUsage(response: unknown, model: string): LlmUsageItem;
+    formatToolResult(toolCall: StandardToolCall, result: StandardToolResult): FireworksMessage;
+    appendToolResult(request: unknown, toolCall: StandardToolCall, result: StandardToolResult): FireworksRequest;
+    responseToHistoryItems(response: unknown): LlmHistory;
+    classifyError(error: unknown): ClassifiedError;
+    isComplete(response: unknown): boolean;
+    hasStructuredOutput(response: unknown): boolean;
+    extractStructuredOutput(response: unknown): JsonObject | undefined;
+    private hasToolCalls;
+    private extractContent;
+    private convertMessagesToFireworks;
+}
+export declare const fireworksAdapter: FireworksAdapter;
+export {};

package/dist/esm/operate/adapters/ProviderAdapter.interface.d.ts

@@ -20,6 +20,12 @@ export interface ProviderAdapter {
      * Default model for this provider
      */
     readonly defaultModel: string;
+    /**
+     * Whether OperateLoop may take a corrective turn when a `format` request
+     * completes with prose instead of structured output (tool-emulation
+     * providers opt in).
+     */
+    readonly supportsStructuredOutputRetry?: boolean;
     /**
      * Build a provider-specific request from the standardized format
      *
@@ -169,6 +175,13 @@ export declare abstract class BaseProviderAdapter implements ProviderAdapter {
     abstract responseToHistoryItems(response: unknown): LlmHistory;
     abstract classifyError(error: unknown): ClassifiedError;
     abstract isComplete(response: unknown): boolean;
+    /**
+     * Whether OperateLoop may take a corrective turn when a `format` request
+     * completes with prose instead of structured output. Providers whose
+     * structured output rides a tool emulation (where compliance is a model
+     * decision) opt in; native grammar-constrained providers do not need it.
+     */
+    readonly supportsStructuredOutputRetry: boolean;
     /**
      * Default implementation checks if error is retryable via classifyError
      */

package/dist/esm/operate/adapters/index.d.ts

@@ -2,6 +2,7 @@ export { BaseProviderAdapter } from "./ProviderAdapter.interface.js";
 export type { ProviderAdapter } from "./ProviderAdapter.interface.js";
 export { AnthropicAdapter, anthropicAdapter } from "./AnthropicAdapter.js";
 export { BedrockAdapter, bedrockAdapter } from "./BedrockAdapter.js";
+export { FireworksAdapter, fireworksAdapter } from "./FireworksAdapter.js";
 export { GoogleAdapter, googleAdapter } from "./GoogleAdapter.js";
 export { OpenAiAdapter, openAiAdapter } from "./OpenAiAdapter.js";
 export { OpenRouterAdapter, openRouterAdapter } from "./OpenRouterAdapter.js";

package/dist/esm/operate/index.d.ts

@@ -1,4 +1,4 @@
-export { AnthropicAdapter, anthropicAdapter, BaseProviderAdapter, BedrockAdapter, bedrockAdapter, GoogleAdapter, googleAdapter, OpenAiAdapter, openAiAdapter, OpenRouterAdapter, openRouterAdapter, XaiAdapter, xaiAdapter, } from "./adapters/index.js";
+export { AnthropicAdapter, anthropicAdapter, BaseProviderAdapter, BedrockAdapter, bedrockAdapter, FireworksAdapter, fireworksAdapter, GoogleAdapter, googleAdapter, OpenAiAdapter, openAiAdapter, OpenRouterAdapter, openRouterAdapter, XaiAdapter, xaiAdapter, } from "./adapters/index.js";
 export type { ProviderAdapter } from "./adapters/index.js";
 export { createOperateLoop, OperateLoop } from "./OperateLoop.js";
 export type { OperateLoopConfig } from "./OperateLoop.js";

package/dist/esm/operate/types.d.ts

@@ -77,6 +77,13 @@ export interface OperateRequest {
     stream?: boolean;
     /** Sampling temperature (0-2 for most providers) */
     temperature?: number;
+    /**
+     * Set by OperateLoop on a corrective turn after a format request came back
+     * as prose. Adapters that support the retry (see
+     * `ProviderAdapter.supportsStructuredOutputRetry`) should offer only the
+     * structured-output mechanism on this turn.
+     */
+    structuredOutputRetry?: boolean;
     /** User identifier for tracking */
     user?: string;
 }
@@ -135,6 +142,8 @@ import type { ResponseBuilder } from "./response/ResponseBuilder.js";
 export interface OperateLoopState {
     /** Count of consecutive tool errors (resets on success) */
     consecutiveToolErrors: number;
+    /** Set when the loop has taken a corrective structured-output turn */
+    structuredOutputRetry?: boolean;
     /** Current conversation input/messages */
     currentInput: LlmHistory;
     /** Current turn number (0-indexed, incremented at start of each turn) */

package/dist/esm/providers/fireworks/FireworksProvider.class.d.ts

@@ -0,0 +1,21 @@
+import { JsonObject } from "@jaypie/types";
+import { LlmHistory, LlmInputMessage, LlmMessageOptions, LlmOperateOptions, LlmOperateResponse, LlmProvider } from "../../types/LlmProvider.interface.js";
+import { LlmStreamChunk } from "../../types/LlmStreamChunk.interface.js";
+export declare class FireworksProvider implements LlmProvider {
+    private model;
+    private _client?;
+    private _operateLoop?;
+    private _streamLoop?;
+    private apiKey?;
+    private log;
+    private conversationHistory;
+    constructor(model?: string, { apiKey }?: {
+        apiKey?: string;
+    });
+    private getClient;
+    private getOperateLoop;
+    private getStreamLoop;
+    send(message: string, options?: LlmMessageOptions): Promise<string | JsonObject>;
+    operate(input: string | LlmHistory | LlmInputMessage, options?: LlmOperateOptions): Promise<LlmOperateResponse>;
+    stream(input: string | LlmHistory | LlmInputMessage, options?: LlmOperateOptions): AsyncIterable<LlmStreamChunk>;
+}

package/dist/esm/providers/fireworks/client.d.ts

@@ -0,0 +1,37 @@
+import { JsonObject } from "@jaypie/types";
+export interface FireworksClientOptions {
+    apiKey: string;
+    baseURL?: string;
+}
+export interface ChatCompletionOptions {
+    signal?: AbortSignal;
+}
+/**
+ * HTTP error carrying the upstream status and parsed API message. The
+ * FireworksAdapter classifies errors by reading `.status` / `.statusCode` and
+ * `.message` / `.error.message`.
+ */
+export declare class FireworksHttpError extends Error {
+    readonly status: number;
+    readonly statusCode: number;
+    readonly error?: {
+        message?: string;
+    };
+    constructor(status: number, message: string, error?: {
+        message?: string;
+    });
+}
+/**
+ * Minimal `fetch`-based client for Fireworks AI's OpenAI-compatible Chat
+ * Completions endpoint. The adapter only needs a single POST (streaming and
+ * non-streaming), header auth, and HTTP error surfacing.
+ */
+export declare class FireworksClient {
+    private readonly apiKey;
+    private readonly baseURL;
+    constructor({ apiKey, baseURL, }: FireworksClientOptions);
+    private headers;
+    private toError;
+    chatCompletion(body: Record<string, unknown>, { signal }?: ChatCompletionOptions): Promise<JsonObject>;
+    streamChatCompletion(body: Record<string, unknown>, { signal }?: ChatCompletionOptions): AsyncIterable<JsonObject>;
+}

package/dist/esm/providers/fireworks/index.d.ts

@@ -0,0 +1,2 @@
+export { FireworksProvider } from "./FireworksProvider.class.js";
+export * from "./utils.js";

package/dist/esm/providers/fireworks/utils.d.ts

@@ -0,0 +1,15 @@
+import { createLogger } from "@jaypie/logger";
+import { LlmMessageOptions } from "../../types/LlmProvider.interface.js";
+import { FireworksClient } from "./client.js";
+export declare const getLogger: () => ReturnType<typeof createLogger>;
+export declare function initializeClient({ apiKey, }?: {
+    apiKey?: string;
+}): Promise<FireworksClient>;
+export declare function getDefaultModel(): string;
+export interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+export declare function formatSystemMessage(systemPrompt: string, { data, placeholders }?: Pick<LlmMessageOptions, "data" | "placeholders">): ChatMessage;
+export declare function formatUserMessage(message: string, { data, placeholders }?: Pick<LlmMessageOptions, "data" | "placeholders">): ChatMessage;
+export declare function prepareMessages(message: string, { system, data, placeholders }?: LlmMessageOptions): ChatMessage[];

package/dist/esm/util/effort.d.ts

@@ -39,4 +39,5 @@ export declare function toXaiEffort(effort: LlmEffort): LlmEffortMapping;
 export declare function toAnthropicEffort(effort: LlmEffort): LlmEffortMapping;
 export declare function toGeminiThinkingLevel(effort: LlmEffort): LlmEffortMapping;
 export declare function toGeminiThinkingBudget(effort: LlmEffort): LlmEffortMapping<number>;
+export declare function toFireworksEffort(effort: LlmEffort): LlmEffortMapping;
 export declare function toOpenRouterEffort(effort: LlmEffort): LlmEffortMapping;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/llm",
-  "version": "1.3.11",
+  "version": "1.3.13",
   "description": "Large language model utilities",
   "repository": {
     "type": "git",