@sudobility/shapeshyft_engine 1.0.0

package/dist/services/llm/extract-json.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Pull the JSON out of a model reply that is not obliged to return only JSON.
+ *
+ * Function calling guarantees a clean payload; prompt-instructed output does
+ * not. A model asked in words for JSON may wrap it in a markdown fence, preface
+ * it with a sentence, or — on a reasoning model — put a whole `<think>` block in
+ * front of it. This is the tolerant reader for that case.
+ *
+ * It lived as a private method on the `lm_studio` provider, where it was written
+ * for local servers that support neither `tools` nor `response_format`. It moved
+ * here when DeepSeek needed exactly the same treatment for the opposite reason:
+ * not a server too simple for function calling, but a model too *new* for it —
+ * DeepSeek V4 is a thinking model and its API rejects `tool_choice` outright.
+ * One reader, so a fix to either provider's parsing is a fix to both.
+ */
+export declare function extractJson(text: string): string;
+//# sourceMappingURL=extract-json.d.ts.map

package/dist/services/llm/extract-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-json.d.ts","sourceRoot":"","sources":["../../../src/services/llm/extract-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA6ChD"}

package/dist/services/llm/extract-json.js

@@ -0,0 +1,60 @@
+/**
+ * Pull the JSON out of a model reply that is not obliged to return only JSON.
+ *
+ * Function calling guarantees a clean payload; prompt-instructed output does
+ * not. A model asked in words for JSON may wrap it in a markdown fence, preface
+ * it with a sentence, or — on a reasoning model — put a whole `<think>` block in
+ * front of it. This is the tolerant reader for that case.
+ *
+ * It lived as a private method on the `lm_studio` provider, where it was written
+ * for local servers that support neither `tools` nor `response_format`. It moved
+ * here when DeepSeek needed exactly the same treatment for the opposite reason:
+ * not a server too simple for function calling, but a model too *new* for it —
+ * DeepSeek V4 is a thinking model and its API rejects `tool_choice` outright.
+ * One reader, so a fix to either provider's parsing is a fix to both.
+ */
+export function extractJson(text) {
+    // Thinking blocks first: a reasoning model emits them before the answer, and
+    // they routinely contain braces that would otherwise be mistaken for it.
+    let cleaned = text.replace(/<think>[\s\S]*?<\/think>/g, "").trim();
+    // A fenced block is the strongest signal, so try it before anything looser —
+    // but only accept it if it actually parses, since a model will occasionally
+    // fence its reasoning and leave the real answer outside.
+    const codeBlockMatch = cleaned.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (codeBlockMatch) {
+        try {
+            JSON.parse(codeBlockMatch[1].trim());
+            return codeBlockMatch[1].trim();
+        }
+        catch {
+            // Not the payload. Fall through to the looser strategies.
+        }
+    }
+    cleaned = cleaned
+        .replace(/```(?:json)?\s*/g, "")
+        .replace(/```/g, "")
+        .trim();
+    try {
+        JSON.parse(cleaned);
+        return cleaned;
+    }
+    catch {
+        // Still wrapped in prose.
+    }
+    // The first balanced-looking object or array. Greedy on purpose: the payload
+    // is usually the largest structure present, and a lazy match would stop at
+    // the first nested closing brace.
+    const jsonMatch = cleaned.match(/(\{[\s\S]*\}|\[[\s\S]*\])/);
+    if (jsonMatch) {
+        try {
+            JSON.parse(jsonMatch[1]);
+            return jsonMatch[1];
+        }
+        catch {
+            // Nothing parseable. The caller reports the raw reply, which is more
+            // useful than a guess.
+        }
+    }
+    return cleaned;
+}
+//# sourceMappingURL=extract-json.js.map

package/dist/services/llm/extract-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-json.js","sourceRoot":"","sources":["../../../src/services/llm/extract-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,6EAA6E;IAC7E,yEAAyE;IACzE,IAAI,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,2BAA2B,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAEnE,6EAA6E;IAC7E,4EAA4E;IAC5E,yDAAyD;IACzD,MAAM,cAAc,GAAG,OAAO,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;IACrE,IAAI,cAAc,EAAE,CAAC;QACnB,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC,CAAC;YACtC,OAAO,cAAc,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACP,0DAA0D;QAC5D,CAAC;IACH,CAAC;IAED,OAAO,GAAG,OAAO;SACd,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;SAC/B,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;SACnB,IAAI,EAAE,CAAC;IAEV,IAAI,CAAC;QACH,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACpB,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,0BAA0B;IAC5B,CAAC;IAED,6EAA6E;IAC7E,2EAA2E;IAC3E,kCAAkC;IAClC,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC7D,IAAI,SAAS,EAAE,CAAC;QACd,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAE,CAAC,CAAC;YAC1B,OAAO,SAAS,CAAC,CAAC,CAAE,CAAC;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,qEAAqE;YACrE,uBAAuB;QACzB,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/services/llm/finish-reason.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Finish-reason normalization across LLM providers
+ * @description Providers report why generation stopped under different names
+ * (`finish_reason`, `stop_reason`, `finishReason`) and with different
+ * vocabularies. This maps all of them onto the {@link FinishReason} union that
+ * ShapeShyft reports to callers.
+ *
+ * The distinction that matters is `length`: a truncated answer usually fails
+ * schema validation, and without this a caller diagnoses a truncation as a
+ * malformed model -- a different fault with a different correct fix.
+ */
+import type { FinishReason } from "../../types/index.js";
+/**
+ * Normalize a provider's stop reason.
+ *
+ * @param raw - The provider's raw value, in whatever casing it used
+ * @returns The normalized reason, `"other"` for an unrecognized string, or
+ *   `undefined` when the provider reported nothing usable
+ */
+export declare function normalizeFinishReason(raw: unknown): FinishReason | undefined;
+//# sourceMappingURL=finish-reason.d.ts.map

package/dist/services/llm/finish-reason.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finish-reason.d.ts","sourceRoot":"","sources":["../../../src/services/llm/finish-reason.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAqCzD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CAK5E"}

package/dist/services/llm/finish-reason.js

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview Finish-reason normalization across LLM providers
+ * @description Providers report why generation stopped under different names
+ * (`finish_reason`, `stop_reason`, `finishReason`) and with different
+ * vocabularies. This maps all of them onto the {@link FinishReason} union that
+ * ShapeShyft reports to callers.
+ *
+ * The distinction that matters is `length`: a truncated answer usually fails
+ * schema validation, and without this a caller diagnoses a truncation as a
+ * malformed model -- a different fault with a different correct fix.
+ */
+/**
+ * Raw provider values, lowercased, mapped to normalized reasons.
+ *
+ * - OpenAI chat completions: `stop`, `length`, `tool_calls`, `content_filter`, `function_call`
+ * - OpenAI Responses API: `max_output_tokens`, `content_filter`
+ * - Anthropic: `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `refusal`
+ * - Gemini: `STOP`, `MAX_TOKENS`, `SAFETY`, `RECITATION`, `OTHER`
+ */
+const FINISH_REASON_MAP = {
+    // Natural completion
+    stop: "stop",
+    end_turn: "stop",
+    stop_sequence: "stop",
+    complete: "stop",
+    // Hit the token ceiling -- the reason this normalization exists
+    length: "length",
+    max_tokens: "length",
+    max_output_tokens: "length",
+    // Stopped by a safety system
+    content_filter: "content_filter",
+    safety: "content_filter",
+    recitation: "content_filter",
+    refusal: "content_filter",
+    blocklist: "content_filter",
+    // Stopped to call a tool
+    tool_calls: "tool_calls",
+    tool_use: "tool_calls",
+    function_call: "tool_calls",
+    other: "other",
+};
+/**
+ * Normalize a provider's stop reason.
+ *
+ * @param raw - The provider's raw value, in whatever casing it used
+ * @returns The normalized reason, `"other"` for an unrecognized string, or
+ *   `undefined` when the provider reported nothing usable
+ */
+export function normalizeFinishReason(raw) {
+    if (typeof raw !== "string" || raw.length === 0) {
+        return undefined;
+    }
+    return FINISH_REASON_MAP[raw.toLowerCase()] ?? "other";
+}
+//# sourceMappingURL=finish-reason.js.map

package/dist/services/llm/finish-reason.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"finish-reason.js","sourceRoot":"","sources":["../../../src/services/llm/finish-reason.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;;;;;GAOG;AACH,MAAM,iBAAiB,GAAiC;IACtD,qBAAqB;IACrB,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,MAAM;IAChB,aAAa,EAAE,MAAM;IACrB,QAAQ,EAAE,MAAM;IAEhB,gEAAgE;IAChE,MAAM,EAAE,QAAQ;IAChB,UAAU,EAAE,QAAQ;IACpB,iBAAiB,EAAE,QAAQ;IAE3B,6BAA6B;IAC7B,cAAc,EAAE,gBAAgB;IAChC,MAAM,EAAE,gBAAgB;IACxB,UAAU,EAAE,gBAAgB;IAC5B,OAAO,EAAE,gBAAgB;IACzB,SAAS,EAAE,gBAAgB;IAE3B,yBAAyB;IACzB,UAAU,EAAE,YAAY;IACxB,QAAQ,EAAE,YAAY;IACtB,aAAa,EAAE,YAAY;IAE3B,KAAK,EAAE,OAAO;CACf,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAY;IAChD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,iBAAiB,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,IAAI,OAAO,CAAC;AACzD,CAAC"}

package/dist/services/llm/gemini.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Google Gemini LLM provider
+ * @description Implements the ILLMProvider interface for Gemini models.
+ * Uses native responseSchema for structured JSON output. Supports multimodal
+ * input (images, audio, video) via base64 and GCS URLs. Includes stubs
+ * for Imagen image generation and Veo video generation (requires Vertex AI SDK).
+ */
+import type { ILLMProvider, LLMRequest, LLMResponse, ProviderConfig } from "./types.js";
+export declare class GeminiProvider implements ILLMProvider {
+    readonly providerName: "gemini";
+    private genAI;
+    private defaultModel;
+    constructor(config: ProviderConfig);
+    generate(request: LLMRequest): Promise<LLMResponse>;
+    /**
+     * Generate media (images or video) using Imagen or Veo models.
+     * Note: This is a simplified implementation - production would use Vertex AI SDK.
+     */
+    private generateMedia;
+    /**
+     * Convert standard JSON Schema to Gemini's schema format
+     */
+    private convertToGeminiSchema;
+    buildApiPayload(request: LLMRequest): Record<string, unknown>;
+}
+//# sourceMappingURL=gemini.d.ts.map

package/dist/services/llm/gemini.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini.d.ts","sourceRoot":"","sources":["../../../src/services/llm/gemini.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,WAAW,EACX,cAAc,EACf,MAAM,YAAY,CAAC;AAMpB,qBAAa,cAAe,YAAW,YAAY;IACjD,QAAQ,CAAC,YAAY,EAAG,QAAQ,CAAU;IAC1C,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,YAAY,CAAS;gBAEjB,MAAM,EAAE,cAAc;IAQ5B,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IA2EzD;;;OAGG;YACW,aAAa;IAwD3B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAe7B,eAAe,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAoC9D"}

package/dist/services/llm/gemini.js

@@ -0,0 +1,178 @@
+/**
+ * @fileoverview Google Gemini LLM provider
+ * @description Implements the ILLMProvider interface for Gemini models.
+ * Uses native responseSchema for structured JSON output. Supports multimodal
+ * input (images, audio, video) via base64 and GCS URLs. Includes stubs
+ * for Imagen image generation and Veo video generation (requires Vertex AI SDK).
+ */
+import { GoogleGenerativeAI, } from "@google/generative-ai";
+import { isGenerativeModel } from "../../lib/capability-validator.js";
+import { normalizeFinishReason } from "./finish-reason.js";
+const DEFAULT_MODEL = "gemini-2.5-flash";
+export class GeminiProvider {
+    providerName = "gemini";
+    genAI;
+    defaultModel;
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new Error("Gemini API key is required");
+        }
+        this.genAI = new GoogleGenerativeAI(config.apiKey);
+        this.defaultModel = config.model ?? DEFAULT_MODEL;
+    }
+    async generate(request) {
+        const modelName = request.model ?? this.defaultModel;
+        const startTime = Date.now();
+        // Check if this is a generative model (Imagen, Veo)
+        if (isGenerativeModel(modelName)) {
+            return this.generateMedia(request, modelName, startTime);
+        }
+        // Build multimodal parts
+        const parts = [];
+        if (request.media?.length) {
+            for (const m of request.media) {
+                if (m.format === "base64") {
+                    parts.push({
+                        inlineData: { mimeType: m.mimeType, data: m.data },
+                    });
+                }
+                else if (m.format === "url") {
+                    // Only gs:// URLs are allowed (validated earlier)
+                    parts.push({
+                        fileData: { mimeType: m.mimeType, fileUri: m.data },
+                    });
+                }
+            }
+        }
+        // Add text prompt
+        parts.push({ text: request.prompt });
+        // Create model with system instruction
+        const model = this.genAI.getGenerativeModel({
+            model: modelName,
+            systemInstruction: request.systemPrompt,
+        });
+        // Configure for JSON output with schema
+        const generationConfig = {
+            responseMimeType: "application/json",
+            responseSchema: this.convertToGeminiSchema(request.outputSchema),
+            temperature: request.temperature ?? 0,
+            maxOutputTokens: request.maxTokens,
+        };
+        const result = await model.generateContent({
+            contents: [{ role: "user", parts }],
+            generationConfig,
+        });
+        const latencyMs = Date.now() - startTime;
+        const response = result.response;
+        const rawResponse = response.text();
+        const content = JSON.parse(rawResponse);
+        // Gemini usage metadata
+        const usageMetadata = response.usageMetadata;
+        return {
+            content,
+            rawResponse,
+            usage: {
+                promptTokens: usageMetadata?.promptTokenCount ?? 0,
+                completionTokens: usageMetadata?.candidatesTokenCount ?? 0,
+                totalTokens: usageMetadata?.totalTokenCount ?? 0,
+            },
+            model: modelName,
+            provider: this.providerName,
+            latencyMs,
+            finishReason: normalizeFinishReason(response.candidates?.[0]?.finishReason),
+        };
+    }
+    /**
+     * Generate media (images or video) using Imagen or Veo models.
+     * Note: This is a simplified implementation - production would use Vertex AI SDK.
+     */
+    async generateMedia(_request, modelName, startTime) {
+        // Note: Imagen and Veo require Vertex AI SDK, not the basic genai SDK.
+        // This is a placeholder that shows the structure.
+        // In production, you would:
+        // 1. Use @google-cloud/vertexai package
+        // 2. Call imagen.generateImages() or veo.generateVideo()
+        // 3. Handle the response appropriately
+        if (modelName.includes("imagen")) {
+            // Placeholder for Imagen implementation
+            console.warn("Imagen generation requires Vertex AI SDK - not implemented in v1");
+            // For now, return a structured response indicating the limitation
+            return {
+                content: {
+                    error: "Image generation requires Vertex AI SDK",
+                    model: modelName,
+                },
+                rawResponse: JSON.stringify({ error: "Not implemented" }),
+                usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+                model: modelName,
+                provider: this.providerName,
+                latencyMs: Date.now() - startTime,
+                generatedMedia: undefined,
+            };
+        }
+        if (modelName.includes("veo")) {
+            // Placeholder for Veo implementation
+            console.warn("Veo generation requires Vertex AI SDK - not implemented in v1");
+            return {
+                content: {
+                    error: "Video generation requires Vertex AI SDK",
+                    model: modelName,
+                },
+                rawResponse: JSON.stringify({ error: "Not implemented" }),
+                usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+                model: modelName,
+                provider: this.providerName,
+                latencyMs: Date.now() - startTime,
+                generatedMedia: undefined,
+            };
+        }
+        throw new Error(`Unknown generative model: ${modelName}`);
+    }
+    /**
+     * Convert standard JSON Schema to Gemini's schema format
+     */
+    convertToGeminiSchema(jsonSchema) {
+        // Gemini mostly accepts standard JSON Schema, but may need adjustments
+        const geminiSchema = { ...jsonSchema };
+        // Remove unsupported keywords
+        const unsupportedKeywords = ["$schema", "$id", "definitions", "$defs"];
+        for (const keyword of unsupportedKeywords) {
+            delete geminiSchema[keyword];
+        }
+        return geminiSchema;
+    }
+    buildApiPayload(request) {
+        const modelName = request.model ?? this.defaultModel;
+        // Build multimodal parts
+        const parts = [];
+        if (request.media?.length) {
+            for (const m of request.media) {
+                if (m.format === "base64") {
+                    parts.push({
+                        inlineData: { mimeType: m.mimeType, data: m.data },
+                    });
+                }
+                else if (m.format === "url") {
+                    parts.push({
+                        fileData: { mimeType: m.mimeType, fileUri: m.data },
+                    });
+                }
+            }
+        }
+        parts.push({ text: request.prompt });
+        return {
+            model: modelName,
+            contents: [{ parts }],
+            systemInstruction: request.systemPrompt
+                ? { parts: [{ text: request.systemPrompt }] }
+                : undefined,
+            generationConfig: {
+                responseMimeType: "application/json",
+                responseSchema: this.convertToGeminiSchema(request.outputSchema),
+                temperature: request.temperature ?? 0,
+                maxOutputTokens: request.maxTokens,
+            },
+        };
+    }
+}
+//# sourceMappingURL=gemini.js.map

package/dist/services/llm/gemini.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini.js","sourceRoot":"","sources":["../../../src/services/llm/gemini.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,kBAAkB,GAGnB,MAAM,uBAAuB,CAAC;AAO/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,aAAa,GAAG,kBAAkB,CAAC;AAEzC,MAAM,OAAO,cAAc;IAChB,YAAY,GAAG,QAAiB,CAAC;IAClC,KAAK,CAAqB;IAC1B,YAAY,CAAS;IAE7B,YAAY,MAAsB;QAChC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAChD,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,IAAI,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACnD,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,KAAK,IAAI,aAAa,CAAC;IACpD,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,OAAmB;QAChC,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC;QACrD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,oDAAoD;QACpD,IAAI,iBAAiB,CAAC,SAAS,CAAC,EAAE,CAAC;YACjC,OAAO,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;QAC3D,CAAC;QAED,yBAAyB;QACzB,MAAM,KAAK,GAAW,EAAE,CAAC;QAEzB,IAAI,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;YAC1B,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;gBAC9B,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;oBAC1B,KAAK,CAAC,IAAI,CAAC;wBACT,UAAU,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;qBACnD,CAAC,CAAC;gBACL,CAAC;qBAAM,IAAI,CAAC,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;oBAC9B,kDAAkD;oBAClD,KAAK,CAAC,IAAI,CAAC;wBACT,QAAQ,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE;qBACpD,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QAED,kBAAkB;QAClB,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QAErC,uCAAuC;QACvC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAAC;YAC1C,KAAK,EAAE,SAAS;YAChB,iBAAiB,EAAE,OAAO,CAAC,YAAY;SACxC,CAAC,CAAC;QAEH,wCAAwC;QACxC,MAAM,gBAAgB,GAAqB;YACzC,gBAAgB,EAAE,kBAAkB;YACpC,cAAc,EAAE,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,YAAY,CAAC;YAChE,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,CAAC;YACrC,eAAe,EAAE,OAAO,CAAC,SAAS;SACnC,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,eAAe,CAAC;YACzC,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;YACnC,gBAAgB;SACjB,CAAC,CAAC;QAEH,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QAEzC,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QACjC,MAAM,WAAW,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAExC,wBAAwB;QACxB,MAAM,aAAa,GAAG,QAAQ,CAAC,aAAa,CAAC;QAE7C,OAAO;YACL,OAAO;YACP,WAAW;YACX,KAAK,EAAE;gBACL,YAAY,EAAE,aAAa,EAAE,gBAAgB,IAAI,CAAC;gBAClD,gBAAgB,EAAE,aAAa,EAAE,oBAAoB,IAAI,CAAC;gBAC1D,WAAW,EAAE,aAAa,EAAE,eAAe,IAAI,CAAC;aACjD;YACD,KAAK,EAAE,SAAS;YAChB,QAAQ,EAAE,IAAI,CAAC,YAAY;YAC3B,SAAS;YACT,YAAY,EAAE,qBAAqB,CACjC,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,CACvC;SACF,CAAC;IACJ,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,aAAa,CACzB,QAAoB,EACpB,SAAiB,EACjB,SAAiB;QAEjB,uEAAuE;QACvE,kDAAkD;QAClD,4BAA4B;QAC5B,wCAAwC;QACxC,yDAAyD;QACzD,uCAAuC;QAEvC,IAAI,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjC,wCAAwC;YACxC,OAAO,CAAC,IAAI,CACV,kEAAkE,CACnE,CAAC;YAEF,kEAAkE;YAClE,OAAO;gBACL,OAAO,EAAE;oBACP,KAAK,EAAE,yCAAyC;oBAChD,KAAK,EAAE,SAAS;iBACjB;gBACD,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,iBAAiB,EAAE,CAAC;gBACzD,KAAK,EAAE,EAAE,YAAY,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE;gBAC/D,KAAK,EAAE,SAAS;gBAChB,QAAQ,EAAE,IAAI,CAAC,YAAY;gBAC3B,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;gBACjC,cAAc,EAAE,SAAS;aAC1B,CAAC;QACJ,CAAC;QAED,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,qCAAqC;YACrC,OAAO,CAAC,IAAI,CACV,+DAA+D,CAChE,CAAC;YAEF,OAAO;gBACL,OAAO,EAAE;oBACP,KAAK,EAAE,yCAAyC;oBAChD,KAAK,EAAE,SAAS;iBACjB;gBACD,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,iBAAiB,EAAE,CAAC;gBACzD,KAAK,EAAE,EAAE,YAAY,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE;gBAC/D,KAAK,EAAE,SAAS;gBAChB,QAAQ,EAAE,IAAI,CAAC,YAAY;gBAC3B,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;gBACjC,cAAc,EAAE,SAAS;aAC1B,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,6BAA6B,SAAS,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED;;OAEG;IACK,qBAAqB,CAC3B,UAAmC;QAEnC,uEAAuE;QACvE,MAAM,YAAY,GAAG,EAAE,GAAG,UAAU,EAAE,CAAC;QAEvC,8BAA8B;QAC9B,MAAM,mBAAmB,GAAG,CAAC,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;QACvE,KAAK,MAAM,OAAO,IAAI,mBAAmB,EAAE,CAAC;YAC1C,OAAO,YAAY,CAAC,OAAO,CAAC,CAAC;QAC/B,CAAC;QAED,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,eAAe,CAAC,OAAmB;QACjC,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC;QAErD,yBAAyB;QACzB,MAAM,KAAK,GAAmC,EAAE,CAAC;QAEjD,IAAI,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;YAC1B,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;gBAC9B,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;oBAC1B,KAAK,CAAC,IAAI,CAAC;wBACT,UAAU,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;qBACnD,CAAC,CAAC;gBACL,CAAC;qBAAM,IAAI,CAAC,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;oBAC9B,KAAK,CAAC,IAAI,CAAC;wBACT,QAAQ,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE;qBACpD,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QAErC,OAAO;YACL,KAAK,EAAE,SAAS;YAChB,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC;YACrB,iBAAiB,EAAE,OAAO,CAAC,YAAY;gBACrC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC,EAAE;gBAC7C,CAAC,CAAC,SAAS;YACb,gBAAgB,EAAE;gBAChB,gBAAgB,EAAE,kBAAkB;gBACpC,cAAc,EAAE,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,YAAY,CAAC;gBAChE,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,CAAC;gBACrC,eAAe,EAAE,OAAO,CAAC,SAAS;aACnC;SACF,CAAC;IACJ,CAAC;CACF"}

package/dist/services/llm/groq.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Groq LLM Provider
+ *
+ * Groq provides fast inference for various models including Whisper for transcription.
+ * For chat completions, Groq uses an OpenAI-compatible API format.
+ * For Whisper transcription, a dedicated implementation is needed.
+ */
+import type { ILLMProvider, LLMRequest, LLMResponse, ProviderConfig } from "./types.js";
+export declare class GroqProvider implements ILLMProvider {
+    readonly providerName: "groq";
+    private client;
+    private defaultModel;
+    private apiKey;
+    constructor(config: ProviderConfig);
+    generate(request: LLMRequest): Promise<LLMResponse>;
+    /**
+     * Generate transcription using Whisper model.
+     * If an extraction model is configured, the transcription is fed through
+     * that model to produce structured output.
+     */
+    private generateTranscription;
+    /**
+     * Generate chat completion using Groq's OpenAI-compatible API.
+     */
+    private generateChatCompletion;
+    buildApiPayload(request: LLMRequest): Record<string, unknown>;
+}
+//# sourceMappingURL=groq.d.ts.map

package/dist/services/llm/groq.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"groq.d.ts","sourceRoot":"","sources":["../../../src/services/llm/groq.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,WAAW,EACX,cAAc,EACf,MAAM,YAAY,CAAC;AA4CpB,qBAAa,YAAa,YAAW,YAAY;IAC/C,QAAQ,CAAC,YAAY,EAAG,MAAM,CAAU;IACxC,OAAO,CAAC,MAAM,CAAO;IACrB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,cAAc;IAS5B,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAYzD;;;;OAIG;YACW,qBAAqB;IAmGnC;;OAEG;YACW,sBAAsB;IAmEpC,eAAe,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAyC9D"}

package/dist/services/llm/groq.js

@@ -0,0 +1,237 @@
+/**
+ * Groq LLM Provider
+ *
+ * Groq provides fast inference for various models including Whisper for transcription.
+ * For chat completions, Groq uses an OpenAI-compatible API format.
+ * For Whisper transcription, a dedicated implementation is needed.
+ */
+import Groq from "groq-sdk";
+import { toFile } from "groq-sdk/uploads";
+import { createLLMProvider } from "./index.js";
+import { getProviderForModel } from "../../config/providers.js";
+import { isTranscriptionModel } from "../../lib/capability-validator.js";
+import { normalizeFinishReason } from "./finish-reason.js";
+const DEFAULT_MODEL = "llama-3.3-70b-versatile";
+const DEFAULT_WHISPER_MODEL = "whisper-large-v3";
+/**
+ * Convert base64 audio data to an Uploadable for the Groq SDK.
+ */
+async function base64ToUploadable(base64Data, mimeType, fieldName) {
+    // Validate base64 before decoding
+    if (!/^[A-Za-z0-9+/=]+$/.test(base64Data)) {
+        throw new Error("Invalid base64 encoding in audio data");
+    }
+    // Decode base64 to binary
+    const binaryString = atob(base64Data);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+        bytes[i] = binaryString.charCodeAt(i);
+    }
+    // Validate buffer is not empty
+    if (bytes.length === 0) {
+        throw new Error("Audio data decoded to empty buffer");
+    }
+    // Determine file extension from MIME type
+    const extension = mimeType.split("/")[1] ?? "mp3";
+    const filename = fieldName
+        ? `${fieldName}.${extension}`
+        : `audio.${extension}`;
+    // Use Groq SDK's toFile utility to create a proper Uploadable
+    return toFile(bytes, filename, { type: mimeType });
+}
+export class GroqProvider {
+    providerName = "groq";
+    client;
+    defaultModel;
+    apiKey;
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new Error("Groq API key is required");
+        }
+        this.apiKey = config.apiKey;
+        this.client = new Groq({ apiKey: config.apiKey });
+        this.defaultModel = config.model ?? DEFAULT_MODEL;
+    }
+    async generate(request) {
+        const model = request.model ?? this.defaultModel;
+        // Check if this is a transcription model (Whisper)
+        if (isTranscriptionModel(model)) {
+            return this.generateTranscription(request, model);
+        }
+        // For non-Whisper models, use chat completions (OpenAI-compatible)
+        return this.generateChatCompletion(request, model);
+    }
+    /**
+     * Generate transcription using Whisper model.
+     * If an extraction model is configured, the transcription is fed through
+     * that model to produce structured output.
+     */
+    async generateTranscription(request, model) {
+        const startTime = Date.now();
+        // Validate: exactly one audio input
+        const audioMedia = request.media?.filter(m => m.type === "audio");
+        if (!audioMedia || audioMedia.length === 0) {
+            throw new Error("Whisper requires exactly one audio input");
+        }
+        if (audioMedia.length > 1) {
+            throw new Error(`Whisper accepts only one audio input, got ${audioMedia.length}`);
+        }
+        const audio = audioMedia[0];
+        // Convert base64 to Uploadable for SDK
+        let audioFile;
+        try {
+            audioFile = await base64ToUploadable(audio.data, audio.mimeType, audio.fieldName);
+        }
+        catch (error) {
+            throw new Error(`Invalid audio data: ${error instanceof Error ? error.message : error}`);
+        }
+        // Transcribe using Groq Whisper
+        const transcription = await this.client.audio.transcriptions.create({
+            file: audioFile,
+            model: model || DEFAULT_WHISPER_MODEL,
+        });
+        const transcriptionText = transcription.text;
+        const transcriptionLatency = Date.now() - startTime;
+        // If no extraction model configured, return raw transcription
+        if (!request.extractionModel) {
+            return {
+                content: { transcription: transcriptionText },
+                rawResponse: transcriptionText,
+                usage: {
+                    promptTokens: 0,
+                    completionTokens: 0,
+                    totalTokens: 0,
+                },
+                model: model || DEFAULT_WHISPER_MODEL,
+                provider: this.providerName,
+                latencyMs: transcriptionLatency,
+                // Whisper transcribes to completion; there is no token ceiling to hit.
+                finishReason: "stop",
+            };
+        }
+        // Feed transcription through extraction model for structured output
+        const extractionProvider = createLLMProvider(getProviderForModel(request.extractionModel), {
+            apiKey: request.extractionApiKey,
+            model: request.extractionModel,
+        });
+        // Build extraction prompt that includes the transcription
+        const extractionPrompt = request.prompt
+            ? `${request.prompt}\n\nTranscription:\n${transcriptionText}`
+            : `Extract structured data from this transcription:\n\n${transcriptionText}`;
+        const extractionRequest = {
+            prompt: extractionPrompt,
+            systemPrompt: request.systemPrompt,
+            outputSchema: request.outputSchema,
+            model: request.extractionModel,
+            temperature: request.temperature,
+            maxTokens: request.maxTokens,
+        };
+        const extractionResponse = await extractionProvider.generate(extractionRequest);
+        // Combine latency from both steps
+        return {
+            ...extractionResponse,
+            // Override latency to include both transcription and extraction
+            latencyMs: Date.now() - startTime,
+            // Include raw transcription in response for debugging
+            rawResponse: JSON.stringify({
+                transcription: transcriptionText,
+                extraction: extractionResponse.rawResponse,
+            }),
+        };
+    }
+    /**
+     * Generate chat completion using Groq's OpenAI-compatible API.
+     */
+    async generateChatCompletion(request, model) {
+        const startTime = Date.now();
+        // Build messages
+        const messages = [];
+        if (request.systemPrompt) {
+            messages.push({ role: "system", content: request.systemPrompt });
+        }
+        // For Groq chat models, we don't have native multimodal support
+        // Media should have been extracted and replaced with placeholders
+        messages.push({ role: "user", content: request.prompt });
+        // Use function calling for structured output
+        const tools = [
+            {
+                type: "function",
+                function: {
+                    name: "structured_response",
+                    description: "Generate structured response matching the schema",
+                    parameters: request.outputSchema,
+                },
+            },
+        ];
+        const response = await this.client.chat.completions.create({
+            model,
+            messages,
+            tools,
+            tool_choice: {
+                type: "function",
+                function: { name: "structured_response" },
+            },
+            temperature: request.temperature ?? 0,
+            max_tokens: request.maxTokens,
+        });
+        const latencyMs = Date.now() - startTime;
+        // Extract structured response from function call
+        const toolCall = response.choices[0]?.message.tool_calls?.[0];
+        if (!toolCall || toolCall.function.name !== "structured_response") {
+            throw new Error("Expected function call response from Groq");
+        }
+        const rawResponse = toolCall.function.arguments;
+        const content = JSON.parse(rawResponse);
+        return {
+            content,
+            rawResponse,
+            usage: {
+                promptTokens: response.usage?.prompt_tokens ?? 0,
+                completionTokens: response.usage?.completion_tokens ?? 0,
+                totalTokens: response.usage?.total_tokens ?? 0,
+            },
+            model: response.model,
+            provider: this.providerName,
+            latencyMs,
+            finishReason: normalizeFinishReason(response.choices[0]?.finish_reason),
+        };
+    }
+    buildApiPayload(request) {
+        const model = request.model ?? this.defaultModel;
+        // For Whisper, return transcription request format
+        if (isTranscriptionModel(model)) {
+            return {
+                model,
+                // Note: file would be added separately as multipart form data
+                response_format: "json",
+            };
+        }
+        // For chat models, return chat completion format
+        const messages = [];
+        if (request.systemPrompt) {
+            messages.push({ role: "system", content: request.systemPrompt });
+        }
+        messages.push({ role: "user", content: request.prompt });
+        return {
+            model,
+            messages,
+            tools: [
+                {
+                    type: "function",
+                    function: {
+                        name: "structured_response",
+                        description: "Generate structured response matching the schema",
+                        parameters: request.outputSchema,
+                    },
+                },
+            ],
+            tool_choice: {
+                type: "function",
+                function: { name: "structured_response" },
+            },
+            temperature: request.temperature ?? 0,
+            max_tokens: request.maxTokens,
+        };
+    }
+}
+//# sourceMappingURL=groq.js.map