@mixio-pro/kalaasetu-mcp 1.2.1 → 2.0.1-beta

package/src/tools/perplexity.ts

@@ -4,21 +4,26 @@ import { safeToolExecute } from "../utils/tool-wrapper";
 export const perplexityImages = {
   name: "perplexityImages",
   description:
-    "Searches for images using the Perplexity API. Returns a formatted text response that includes a summary and a numbered list of image URLs with citations mapped to the text.",
+    "Search for and discover real-world images using the Perplexity Sonar API. " +
+    "This tool provides a summarized text description of findings along with a verified list of image URLs. " +
+    "Citations in the text are mapped [N] to the numbered images in the list. " +
+    "Ideal for finding visual inspiration, reference photos, or stock-like images from the web.",
   parameters: z.object({
-    query: z.string().describe("The search query for images."),
+    query: z
+      .string()
+      .describe(
+        "Descriptive search terms (e.g., 'SpaceX Starship launch photos')."
+      ),
     image_domain_filter: z
       .array(z.string())
       .optional()
       .describe(
-        "A list of domains to include or exclude. To exclude, prefix with '-'. E.g., ['wikimedia.org', '-gettyimages.com']."
+        "Filter results by domain. Use 'domain.com' to include, or '-domain.com' to exclude. (e.g., ['wikimedia.org', '-pinterest.com'])."
       ),
     image_format_filter: z
       .array(z.string())
       .optional()
-      .describe(
-        "A list of allowed image formats. E.g., ['jpg', 'png', 'gif']."
-      ),
+      .describe("Target specific formats: 'jpg', 'png', 'gif', etc."),
   }),
   timeoutMs: 300000,
   execute: async (args: {
@@ -33,28 +38,26 @@ export const perplexityImages = {
       }
 
       const url = "https://api.perplexity.ai/chat/completions";
-      const headers = {
+      const headers: Record<string, string> = {
         Authorization: `Bearer ${apiKey}`,
         "Content-Type": "application/json",
         accept: "application/json",
       };
 
-      const payload: any = {
+      const payload = {
         model: "sonar",
         messages: [
           { role: "user", content: `Show me images of ${args.query}` },
         ],
         return_images: true,
+        ...(args.image_domain_filter
+          ? { image_domain_filter: args.image_domain_filter }
+          : {}),
+        ...(args.image_format_filter
+          ? { image_format_filter: args.image_format_filter }
+          : {}),
       };
 
-      if (args.image_domain_filter) {
-        payload.image_domain_filter = args.image_domain_filter;
-      }
-
-      if (args.image_format_filter) {
-        payload.image_format_filter = args.image_format_filter;
-      }
-
       const res = await fetch(url, {
         method: "POST",
         headers: headers,
@@ -66,51 +69,49 @@ export const perplexityImages = {
         throw new Error(`Perplexity API request failed: ${res.status} ${text}`);
       }
 
-      const data: any = await res.json();
+      const data = (await res.json()) as any;
       let content = data.choices?.[0]?.message?.content;
-      const images = data.images;
-      const citations = data.citations;
+      const images = (data.images || []) as any[];
+      const citations = (data.citations || []) as string[];
 
-      if (!images || images.length === 0) {
+      if (images.length === 0) {
         return `No direct image URLs found in the API response. The text content was: ${content}`;
       }
 
       // Create a map of origin_url -> new 1-based index
-      const originUrlToImageIndex: { [key: string]: number } = {};
-      images.forEach((img: any, index: number) => {
+      const originUrlToImageIndex: Record<string, number> = {};
+      images.forEach((img, index) => {
         if (img.origin_url) {
           originUrlToImageIndex[img.origin_url] = index + 1;
         }
       });
 
       // Create a map of old citation index -> new image index
-      const oldToNewCitationMap: { [key: number]: number } = {};
-      if (citations && Array.isArray(citations)) {
-        citations.forEach((citationUrl: string, index: number) => {
-          if (originUrlToImageIndex[citationUrl]) {
-            oldToNewCitationMap[index + 1] = originUrlToImageIndex[citationUrl];
-          }
-        });
-      }
+      const oldToNewCitationMap: Record<number, number> = {};
+      citations.forEach((citationUrl, index) => {
+        if (originUrlToImageIndex[citationUrl]) {
+          oldToNewCitationMap[index + 1] = originUrlToImageIndex[citationUrl];
+        }
+      });
 
       // Replace citations in the content
       if (content && typeof content === "string") {
         content = content
-          .replace(/\[(\d+)\]/g, (match: string, oldIndexStr: string) => {
+          .replace(/\[(\d+)\]/g, (_match, oldIndexStr) => {
             const oldIndex = parseInt(oldIndexStr, 10);
             const newIndex = oldToNewCitationMap[oldIndex];
             if (newIndex) {
               return `[${newIndex}]`;
             }
-            return ""; // Remove citation if it doesn't correspond to an image
+            return "";
           })
           .replace(/(\s\s+)/g, " ")
-          .trim(); // Clean up extra spaces
+          .trim();
       }
 
       // Build the final formatted output
       let output = content + "\n\n--- Images ---\n";
-      images.forEach((img: any, index: number) => {
+      images.forEach((img, index) => {
         output += `${index + 1}. ${img.image_url}\n   (Source: ${
           img.origin_url
         })\n`;
@@ -124,14 +125,16 @@ export const perplexityImages = {
 export const perplexityVideos = {
   name: "perplexityVideos",
   description:
-    "Searches for videos using the Perplexity API. Returns a formatted text response that includes a summary and a numbered list of video URLs with citations mapped to the text.",
+    "Search for web videos (e.g., from YouTube, Vimeo) using Perplexity Sonar Pro. " +
+    "Provides a textual summary of the content found and direct links to the videos. " +
+    "Perfect for finding research material or specific clips based on natural language queries.",
   parameters: z.object({
-    query: z.string().describe("The search query for videos."),
+    query: z.string().describe("The natural language search query for videos."),
     search_domain_filter: z
       .array(z.string())
       .optional()
       .describe(
-        "A list of domains to limit the search to (e.g., ['youtube.com']). Use a '-' prefix to exclude a domain."
+        "Optional: Restrict search to specific domains (e.g., ['youtube.com']) or exclude them with '-' prefix."
       ),
   }),
   timeoutMs: 300000,
@@ -143,24 +146,23 @@ export const perplexityVideos = {
       }
 
       const url = "https://api.perplexity.ai/chat/completions";
-      const headers = {
+      const headers: Record<string, string> = {
         Authorization: `Bearer ${apiKey}`,
         "Content-Type": "application/json",
         accept: "application/json",
       };
 
-      const payload: any = {
+      const payload = {
         model: "sonar-pro",
         messages: [
           { role: "user", content: `Show me videos of ${args.query}` },
         ],
         media_response: { overrides: { return_videos: true } },
+        ...(args.search_domain_filter
+          ? { search_domain_filter: args.search_domain_filter }
+          : {}),
       };
 
-      if (args.search_domain_filter) {
-        payload.search_domain_filter = args.search_domain_filter;
-      }
-
       const res = await fetch(url, {
         method: "POST",
         headers: headers,
@@ -172,12 +174,12 @@ export const perplexityVideos = {
         throw new Error(`Perplexity API request failed: ${res.status} ${text}`);
       }
 
-      const data: any = await res.json();
+      const data = (await res.json()) as any;
       let content = data.choices?.[0]?.message?.content;
-      const videos = data.videos;
-      const citations = data.citations;
+      const videos = (data.videos || []) as any[];
+      const citations = (data.citations || []) as string[];
 
-      if (!videos || videos.length === 0) {
+      if (videos.length === 0) {
         return `No direct video URLs found in the API response. Full API Response: ${JSON.stringify(
           data,
           null,
@@ -186,41 +188,39 @@ export const perplexityVideos = {
       }
 
       // Create a map of video url -> new 1-based index
-      const urlToVideoIndex: { [key: string]: number } = {};
-      videos.forEach((video: any, index: number) => {
+      const urlToVideoIndex: Record<string, number> = {};
+      videos.forEach((video, index) => {
         if (video.url) {
           urlToVideoIndex[video.url] = index + 1;
         }
       });
 
       // Create a map of old citation index -> new video index
-      const oldToNewCitationMap: { [key: number]: number } = {};
-      if (citations && Array.isArray(citations)) {
-        citations.forEach((citationUrl: string, index: number) => {
-          if (urlToVideoIndex[citationUrl]) {
-            oldToNewCitationMap[index + 1] = urlToVideoIndex[citationUrl];
-          }
-        });
-      }
+      const oldToNewCitationMap: Record<number, number> = {};
+      citations.forEach((citationUrl, index) => {
+        if (urlToVideoIndex[citationUrl]) {
+          oldToNewCitationMap[index + 1] = urlToVideoIndex[citationUrl];
+        }
+      });
 
       // Replace citations in the content
       if (content && typeof content === "string") {
         content = content
-          .replace(/\[(\d+)\]/g, (match: string, oldIndexStr: string) => {
+          .replace(/\[(\d+)\]/g, (_match, oldIndexStr) => {
             const oldIndex = parseInt(oldIndexStr, 10);
             const newIndex = oldToNewCitationMap[oldIndex];
             if (newIndex) {
               return `[${newIndex}]`;
             }
-            return ""; // Remove citation if it doesn't correspond to a video
+            return "";
           })
           .replace(/(\s\s+)/g, " ")
-          .trim(); // Clean up extra spaces
+          .trim();
       }
 
       // Build the final formatted output
       let output = content + "\n\n--- Videos ---\n";
-      videos.forEach((video: any, index: number) => {
+      videos.forEach((video, index) => {
         output += `${index + 1}. ${video.url}\n`;
       });
 

package/src/tools/youtube.ts

@@ -9,16 +9,21 @@ const ai = new GoogleGenAI({
 export const analyzeYoutubeVideo = {
   name: "analyzeYoutubeVideo",
   description:
-    "Analyze YouTube videos for content using the correct GenAI JS API approach with FileData fileUri. Perfect for extracting stock media content, analyzing video content, or getting descriptions of YouTube videos",
+    "Perform deep semantic analysis of a YouTube video using Google's Gemini 2.5 Flash model. " +
+    "Use this to summarize long videos, identify specific scenes, extract information, or ask visual questions about the video's content. " +
+    "This tool treats the YouTube URL as a first-class video stream for the model. " +
+    "ONLY USE WHEN WORKING WITH GOOGLE/GEMINI MODELS.",
   parameters: z.object({
     youtube_url: z
       .string()
       .describe(
-        "YouTube video URL to analyze (format: https://www.youtube.com/watch?v=VIDEO_ID)"
+        "The full URL of the YouTube video (e.g., 'https://www.youtube.com/watch?v=dQw4w9WgXcQ')."
       ),
     prompt: z
       .string()
-      .describe("Analysis prompt or question about the YouTube video content"),
+      .describe(
+        "Instruction or question about the video content (e.g., 'Summarize the main points' or 'What color was the car?')."
+      ),
   }),
   timeoutMs: 300000,
   execute: async (args: { youtube_url: string; prompt: string }) => {

package/src/utils/llm-prompt-enhancer.ts

@@ -0,0 +1,302 @@
+/**
+ * LLM-Powered Prompt Enhancer
+ *
+ * Uses Gemini 3 Fast to intelligently rewrite prompts based on
+ * prompting guides for specific models (e.g., LTX-2).
+ */
+
+import { GoogleGenAI } from "@google/genai";
+
+const ai = new GoogleGenAI({
+  apiKey: process.env.GEMINI_API_KEY || "",
+});
+
+/**
+ * LTX-2 Prompting Guide embedded as system context.
+ * Based on: https://ltx.io/model/model-blog/prompting-guide-for-ltx-2
+ * Complete guide with examples for optimal prompt rewriting.
+ */
+const LTX2_PROMPTING_GUIDE = `
+You are an expert prompt engineer for LTX-2, a state-of-the-art video generation model.
+Your task is to rewrite the user's prompt following the official LTX-2 prompting guide.
+
+The key is painting a complete picture of the story you're telling that flows naturally from beginning to end, covering all the elements the model needs to bring your vision to life.
+
+## EXAMPLE PROMPTS (study these patterns)
+
+### Example 1 - Action Scene:
+"An action packed, cinematic shot of a monster truck driving fast towards the camera, the truck passes the cameras it pans left to follow the trucks reckless drive. dust and motion blur is around the truck, hand held feel to the camera as it tries to track its ride into the distance. the truck then drifts and turns around, then drives back towards the camera until seen in extreme close up."
+
+### Example 2 - Dialogue Scene:
+"A warm sunny backyard. The camera starts in a tight cinematic close-up of a woman and a man in their 30s, facing each other with serious expressions. The woman, emotional and dramatic, says softly, 'That's it... Dad's lost it. And we've lost Dad.' The man exhales, slightly annoyed: 'Stop being so dramatic, Jess.' A beat. He glances aside, then mutters defensively, 'He's just having fun.' The camera slowly pans right, revealing the grandfather in the garden wearing enormous butterfly wings, waving his arms in the air like he's trying to take off. He shouts, 'Wheeeew!' as he flaps his wings with full commitment."
+
+### Example 3 - Interior Scene:
+"INT. OVEN – DAY. Static camera from inside the oven, looking outward through the slightly fogged glass door. Warm golden light glows around freshly baked cookies. The baker's face fills the frame, eyes wide with focus, his breath fogging the glass as he leans in. Subtle reflections move across the glass as steam rises. Baker (whispering dramatically): 'Today… I achieve perfection.' He leans even closer, nose nearly touching the glass. 'Golden edges. Soft center. The gods themselves will smell these cookies and weep.'"
+
+### Example 4 - Performance Scene:
+"A warm, intimate cinematic performance inside a cozy, wood-paneled bar, lit with soft amber practical lights and shallow depth of field that creates glowing bokeh in the background. The shot opens in a medium close-up on a young female singer in her 20s with short brown hair and bangs, singing into a microphone while strumming an acoustic guitar, her eyes closed and posture relaxed. The camera slowly arcs left around her, keeping her face and mic in sharp focus as two male band members playing guitars remain softly blurred behind her. Warm light wraps around her face and hair as framed photos and wooden walls drift past in the background. Ambient live music fills the space, led by her clear vocals over gentle acoustic strumming."
+
+## KEY ASPECTS TO INCLUDE
+
+1. **Establish the shot**: Use cinematography terms (wide shot, medium close-up, over-the-shoulder, static frame, handheld). Include scale or category characteristics.
+
+2. **Set the scene**: Describe lighting conditions (warm golden light, soft amber, neon glow, dramatic shadows), color palette (warm, muted, high contrast), textures, and atmospheric elements (fog, rain, dust, smoke).
+
+3. **Describe the action as a NARRATIVE SEQUENCE**: Write the core action flowing naturally from BEGINNING to END. Include what happens first, then next, then after that. Actions should progress temporally.
+
+4. **Define characters**: Include age, hairstyle, clothing, and distinguishing details. Express emotions through PHYSICAL CUES (posture, gesture, facial expression) - NOT internal states.
+
+5. **Camera movements**: Specify clearly using terms like: pans left/right, dollys back, slow push in, handheld tracking, arcs around, tilts upward, pulls back. Describe how subjects appear AFTER camera motion.
+
+6. **Audio and dialogue**: Describe ambient sounds, music quality. For speech, use quotation marks. Mention dialogue style (whispers, shouts, mutters).
+
+## FOR BEST RESULTS
+
+- Keep prompt as a SINGLE FLOWING PARAGRAPH
+- Use PRESENT TENSE verbs (speeds, roars, pans, reveals)
+- Match detail to shot scale (closeups need more detail than wide shots)
+- Write 4-8 descriptive sentences
+- Focus on camera's relationship to subject
+- Create a temporal narrative arc (beginning → middle → end)
+
+## TECHNICAL TERMS TO USE
+
+Camera language: follows, tracks, pans across, circles around, tilts upward, pushes in, pulls back, overhead view, handheld movement, over-the-shoulder, wide establishing shot, static frame
+
+Film characteristics: lens flares, film grain, shallow depth of field, bokeh
+
+Pacing: slow motion, lingering shot, continuous shot, seamless transition, dynamic movement
+
+## WHAT WORKS WELL WITH LTX-2
+
+- Cinematic compositions with thoughtful lighting and shallow depth of field
+- Emotive human moments, subtle gestures, facial nuance
+- Weather effects: fog, mist, golden hour light, soft shadows, rain, reflections
+- Clean camera language: "slow dolly in", "handheld tracking", "over-the-shoulder"
+- Stylized aesthetics: painterly, noir, analog film, fashion editorial
+- Lighting/mood control: backlighting, color palettes, soft rim light
+
+## WHAT TO AVOID
+
+- Internal emotional states without visual cues (don't say "sad", show the expression)
+- Text, logos, signage, brand names (LTX-2 can't render text)
+- Complex physics: jumping, juggling, chaotic motion
+- Too many characters or layered actions
+- Conflicting light sources
+- Over-complicated prompts
+
+## YOUR TASK
+
+Transform the user's simple prompt into a rich, cinematic LTX-2 prompt that:
+1. Establishes a clear shot type and scene
+2. Describes a NARRATIVE SEQUENCE of action from beginning to end
+3. Includes specific camera movements
+4. Sets atmosphere through lighting and color
+5. Uses present tense throughout
+6. Flows as a single cohesive paragraph
+
+Output ONLY the enhanced prompt. No explanations, no markdown, no labels - just the enhanced cinematic prompt.
+`;
+
+/**
+ * Veo 3.1 Prompting Guide for image-to-video generation.
+ * Based on Shorts / Veo Shot Planning Guidelines.
+ */
+const VEO_PROMPTING_GUIDE = `
+You are an expert prompt engineer for Google Veo 3.1, a state-of-the-art image-to-video generation model.
+Your task is to rewrite the user's prompt following the Veo Shot Planning Guidelines.
+
+## VEO 3.1 PROMPTING ESSENTIALS
+
+### The 5-Part Scene Formula
+Structure every Veo prompt as: [Cinematography] + [Subject] + [Action] + [Context] + [Style & Ambiance]
+
+1. **Cinematography**: Shot type + camera behavior
+   - Examples: "Vertical 9:16 CLOSE-UP, eye-level, SINGLE LOCKED SHOT"
+   - Examples: "MEDIUM TWO-SHOT with a slow push-in toward the subject"
+   - Examples: "Wide establishing shot, static frame"
+
+2. **Subject**: Who/what the shot is about
+   - Describe character details: age, clothing, position in frame
+   - Who is in focus vs background
+
+3. **Action**: What is happening
+   - Describe motion from beginning to end
+   - For dialogue: ordered speaker cues with exact lines in quotes
+
+4. **Context**: Where it happens
+   - Background description
+   - "Simple and softly blurred background"
+   - "No people walking through frame"
+
+5. **Style & Ambiance**: Overall mood
+   - Lighting quality
+   - Color palette
+   - Sound/audio descriptions
+
+### Camera Behavior - BE EXPLICIT
+
+For LOCKED shots:
+- "SINGLE LOCKED SHOT - NO pans, NO cuts, NO angle changes"
+- "Camera and framing remain completely static"
+
+For START→END interpolation:
+- "Single continuous shot interpolating naturally from the START frame to the END frame"
+- Describe the motion: "gentle push-in", "slow pan right", "subtle arc around subject"
+
+### Background Control
+- "Simple and softly blurred conference-room/office/street background"
+- "No people walking through frame"
+- "No new characters entering or exiting the frame"
+- "Any background figures must remain completely still and very out of focus"
+
+### Always Include These Negative Instructions
+- "No on-screen text or subtitles"
+- "No black bars"
+- "No camera shake" (unless specifically wanted)
+
+### Dialogue Shots
+For dialogue, include:
+- Ordered speaker cues with visual identifiers
+- Exact dialogue in quotes
+- Voice assignments: "natural male/female voice"
+- "Only ONE character should speak at a time; no overlapping speech"
+- "Short natural pauses between turns"
+
+### Emotion Through Physical Cues
+- DON'T say "sad" or "angry" - show it through posture, gesture, expression
+- Examples: "bowed and humble", "firm but controlled", "eyes downcast", "slight smile"
+
+## EXAMPLE PROMPTS
+
+### Example 1 - Simple Action:
+"Vertical 9:16 MEDIUM SHOT, eye-level, SINGLE LOCKED SHOT. A young woman in a blue dress stands in a sunlit garden, her hair gently moving in the breeze. She slowly raises her hand to touch a blooming flower, her expression soft and contemplative. Warm golden hour lighting wraps around her. Background is softly blurred foliage. No on-screen text. No people in background."
+
+### Example 2 - Dialogue:
+"Vertical 9:16 CLOSE-UP TWO-SHOT, SINGLE LOCKED SHOT. MR. KIM (man in dark suit) sits at head of conference table, GUXIXI (young woman in pink uniform) stands opposite. 1) MR. KIM says firmly: 'This is your final warning.' 2) GUXIXI, eyes downcast, responds quietly: 'I understand, sir.' Generate clear dialogue audio with natural male voice for Kim, female voice for Guxixi. One voice at a time with natural pauses. Soft office ambient sound. No on-screen text."
+
+### Example 3 - Camera Movement:
+"Vertical 9:16 MEDIUM SHOT with gentle push-in. Single continuous shot interpolating from START frame to END frame. The shot begins on a wide view of the dancer, then slowly pushes in to a close-up of her face as she completes her spin. Soft rim lighting from behind. Ambient music continues throughout. No cuts, no angle changes. No on-screen text."
+
+## YOUR TASK
+
+Transform the user's prompt into a Veo-optimized prompt that:
+1. Uses the 5-part scene formula
+2. Explicitly states camera behavior (locked OR interpolating)
+3. Describes subject and action clearly
+4. Includes negative instructions (no on-screen text, no people in background)
+5. If dialogue present: includes ordered speaker cues and voice assignments
+
+The user is providing a START image (and optionally END image) separately via API parameters.
+Focus the prompt on describing what happens visually and aurally - not on technical API details.
+
+Output ONLY the enhanced prompt. No explanations, no markdown, no labels.
+`;
+
+/**
+ * Configuration for LLM-based prompt enhancement.
+ */
+export interface LLMEnhancerConfig {
+  /** The model to use for enhancement */
+  model?: string;
+  /** System prompt/guide for the enhancer */
+  systemPrompt?: string;
+  /** Maximum tokens for the enhanced prompt */
+  maxTokens?: number;
+  /** Temperature for generation (lower = more deterministic) */
+  temperature?: number;
+}
+
+/**
+ * Built-in enhancer configurations for different video models.
+ */
+export const LLM_ENHANCER_CONFIGS: Record<string, LLMEnhancerConfig> = {
+  ltx2: {
+    model: "gemini-2.0-flash",
+    systemPrompt: LTX2_PROMPTING_GUIDE,
+    maxTokens: 1024,
+    temperature: 0.4,
+  },
+  veo: {
+    model: "gemini-2.0-flash",
+    systemPrompt: VEO_PROMPTING_GUIDE,
+    maxTokens: 1024,
+    temperature: 0.4,
+  },
+};
+
+/**
+ * Enhance a prompt using Gemini LLM.
+ *
+ * @param prompt - The user's original prompt
+ * @param configOrName - Either a config name (e.g., "ltx2") or a custom LLMEnhancerConfig
+ * @param images - Optional array of image paths/URLs to include in context
+ * @returns The enhanced prompt
+ */
+export async function enhancePromptWithLLM(
+  prompt: string,
+  configOrName: string | LLMEnhancerConfig = "ltx2",
+  images?: string[]
+): Promise<string> {
+  // Resolve config - ltx2 is always available as default
+  let config: LLMEnhancerConfig;
+
+  if (typeof configOrName === "string") {
+    const lookedUp = LLM_ENHANCER_CONFIGS[configOrName];
+    config = lookedUp ?? LLM_ENHANCER_CONFIGS["ltx2"]!;
+  } else {
+    config = configOrName;
+  }
+
+  const model = config.model || "gemini-2.0-flash";
+  const systemPrompt = config.systemPrompt || LTX2_PROMPTING_GUIDE;
+
+  // Build content parts
+  const contents: any[] = [];
+
+  // Add images if provided
+  if (images && images.length > 0) {
+    for (const imagePath of images) {
+      // For now, just mention the image in the prompt
+      // Full image support would require reading and encoding the image
+      contents.push(`[Image provided: ${imagePath}]`);
+    }
+  }
+
+  // Add the user's prompt
+  contents.push(`User's original prompt:\n${prompt}\n\nEnhanced prompt:`);
+
+  try {
+    const response = await ai.models.generateContent({
+      model,
+      contents: contents.join("\n"),
+      config: {
+        systemInstruction: systemPrompt,
+        maxOutputTokens: config.maxTokens || 1024,
+        temperature: config.temperature || 0.7,
+      },
+    });
+
+    // Extract text from response
+    const enhancedPrompt =
+      response.candidates?.[0]?.content?.parts?.[0]?.text?.trim();
+
+    if (!enhancedPrompt) {
+      console.warn("LLM enhancement returned empty, using original prompt");
+      return prompt;
+    }
+
+    return enhancedPrompt;
+  } catch (error: any) {
+    console.error(`LLM prompt enhancement failed: ${error.message}`);
+    // Fall back to original prompt on error
+    return prompt;
+  }
+}
+
+/**
+ * Check if Gemini API key is configured.
+ */
+export function isLLMEnhancerAvailable(): boolean {
+  return !!process.env.GEMINI_API_KEY;
+}