vibefast-cli 0.2.3 → 0.2.4

package/recipes/chatbot/packages/backend/convex/tools/index.ts

@@ -0,0 +1,18 @@
+// Central export for all available AI tools
+// This file makes it easy to add more tools in the future
+
+import { knowledgeRetrievalTool } from './knowledgeRetrieval';
+import { tavilySearchTool } from './tavilySearch';
+import { userProfileTool } from './userProfile';
+
+// Export all tools in a single object for easy access
+export const allTools = {
+  knowledgeRetrieval: knowledgeRetrievalTool,
+  tavilySearch: tavilySearchTool,
+  userProfile: userProfileTool,
+} as const;
+
+// Export individual tools for specific use cases
+export { knowledgeRetrievalTool } from './knowledgeRetrieval';
+export { tavilySearchTool } from './tavilySearch';
+export { userProfileTool } from './userProfile';

package/recipes/chatbot/packages/backend/convex/tools/knowledgeRetrieval.ts

@@ -0,0 +1,92 @@
+import { createTool } from '@convex-dev/agent';
+import { z } from 'zod';
+
+import { api } from '../_generated/api';
+
+export const knowledgeRetrievalTool = createTool({
+  description:
+    'Search uploaded knowledge files and synthesize an answer with citations.',
+  args: z.object({
+    query: z.string().min(1).describe('Question or topic to search.'),
+    scope: z
+      .enum(['personal', 'global'])
+      .default('personal')
+      .describe(
+        'Whether to search personal uploads or the shared global knowledge base.',
+      ),
+    filter: z
+      .union([
+        z.object({
+          type: z.literal('filename'),
+          value: z.string(),
+        }),
+        z.object({
+          type: z.literal('category'),
+          value: z.union([z.string(), z.null()]),
+        }),
+      ])
+      .optional()
+      .describe('Optional filter to narrow search by filename or category.'),
+    limit: z
+      .number()
+      .min(1)
+      .max(20)
+      .default(10)
+      .describe('Maximum number of chunks to retrieve.'),
+    chunkContext: z
+      .object({
+        before: z.number().min(0).max(5).default(1),
+        after: z.number().min(0).max(5).default(1),
+      })
+      .default({ before: 1, after: 1 })
+      .describe('Number of neighboring chunks to include around matches.'),
+  }),
+  handler: async (ctx, args): Promise<string> => {
+    const prompt = args.query.trim();
+    if (!prompt) {
+      return 'Please provide a non-empty question for knowledge retrieval.';
+    }
+
+    const filter =
+      args.filter?.type === 'filename'
+        ? {
+            name: 'filename' as const,
+            value: args.filter.value,
+          }
+        : args.filter?.type === 'category'
+          ? {
+              name: 'category' as const,
+              value: args.filter.value,
+            }
+          : undefined;
+
+    const chunkContext = {
+      before: args.chunkContext?.before ?? 1,
+      after: args.chunkContext?.after ?? 1,
+    };
+
+    const result = (await ctx.runAction(api.ragKnowledge.askKnowledge, {
+      prompt,
+      globalNamespace: args.scope === 'global',
+      limit: args.limit,
+      chunkContext,
+      filter,
+    })) as {
+      answer: string;
+      files?: { filename: string; url: string | null }[];
+    };
+
+    if (!result.files || result.files.length === 0) {
+      return `${result.answer}\n\n_No supporting files were located._`;
+    }
+
+    const references = result.files
+      .map((file: { filename: string; url: string | null }, index: number) => {
+        const label = `[${index + 1}] ${file.filename}`;
+        return file.url ? `${label} — ${file.url}` : label;
+      })
+      .join('\n');
+
+    return `${result.answer}\n\n**References**\n${references}`;
+  },
+});

package/recipes/chatbot/packages/backend/convex/tools/tavilySearch.ts

@@ -0,0 +1,83 @@
+import { createTool } from '@convex-dev/agent';
+import { z } from 'zod';
+
+import { internal } from '../_generated/api';
+import type { Id } from '../_generated/dataModel';
+
+/**
+ * Tavily search tool exposed to the Convex agent runtime.
+ * Uses the direct HTTP API to stay compatible with the Convex execution environment.
+ */
+export const tavilySearchTool = createTool({
+  description:
+    'Search the web with Tavily to retrieve up-to-date information. Best for news, recent events, or factual lookups.',
+  args: z.object({
+    query: z.string().describe('The query to send to Tavily.'),
+  }),
+  handler: async (ctx, { query }) => {
+    const userId = ctx.userId as Id<'users'> | undefined;
+    if (userId) {
+      await ctx.runMutation(internal.rateLimit.enforceTool, { userId });
+    }
+
+    const apiKey = process.env.TAVILY_API_KEY;
+    if (!apiKey) {
+      return 'Tavily search is unavailable because TAVILY_API_KEY is not configured.';
+    }
+
+    try {
+      const response = await fetch('https://api.tavily.com/search', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          query,
+          max_results: 5,
+          search_depth: 'basic',
+          include_answer: false,
+          include_images: false,
+        }),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(
+          `Tavily API error: ${response.status} ${response.statusText} - ${errorText}`,
+        );
+      }
+
+      const searchResult = await response.json();
+
+      if (!searchResult.results || searchResult.results.length === 0) {
+        return `No Tavily results found for “${query}”.`;
+      }
+
+      const formattedResults = searchResult.results
+        .map(
+          (
+            result: {
+              title?: string;
+              url?: string;
+              content?: string;
+            },
+            index: number,
+          ) => {
+            const title = result.title ?? 'Untitled';
+            const url = result.url ?? 'No URL';
+            const content = result.content?.trim() || 'No summary available.';
+            return `${index + 1}. **${title}**\n   URL: ${url}\n   Summary: ${content}`;
+          },
+        )
+        .join('\n\n');
+
+      return `🌐 **Tavily Search Results for “${query}”**\n\n${formattedResults}`;
+    } catch (error) {
+      console.error('[Tavily Search Tool] Error performing search:', error);
+      return `Tavily search failed: ${
+        error instanceof Error ? error.message : 'Unknown error'
+      }`;
+    }
+  },
+});

package/recipes/chatbot/packages/backend/convex/tools/userProfile.ts

@@ -0,0 +1,72 @@
+import { createTool } from '@convex-dev/agent';
+import { z } from 'zod';
+
+import { internal } from '../_generated/api';
+import type { Id } from '../_generated/dataModel';
+
+type PublicUserFields = {
+  name: string | null;
+  email: string | null;
+  credits: number;
+  joinedAt: string | null;
+  emailVerified: boolean;
+};
+
+type UserProfileToolResult =
+  | {
+      found: false;
+      reason: string;
+    }
+  | {
+      found: true;
+      profile: PublicUserFields;
+      guidance: string;
+    };
+
+/**
+ * Tool that surfaces the signed-in user's profile information so the agent can
+ * answer personalized questions (e.g. “How many credits do I have?”).
+ *
+ * The handler returns a sanitized payload – no phone numbers or internal IDs –
+ * and gracefully handles anonymous or missing profiles.
+ */
+export const userProfileTool = createTool({
+  description:
+    'Fetch the current signed-in user profile (name, email, credits, join date). Use when the user asks about their account details.',
+  args: z
+    .object({})
+    .describe('No input is required; the tool looks up the current user.'),
+  handler: async (ctx, _args): Promise<UserProfileToolResult> => {
+    const userId = ctx.userId as Id<'users'> | undefined;
+
+    if (!userId) {
+      return {
+        found: false,
+        reason:
+          'There is no signed-in user associated with this conversation, so profile data is unavailable.',
+      };
+    }
+
+    await ctx.runMutation(internal.rateLimit.enforceTool, {
+      userId,
+    });
+
+    const profile = await ctx.runQuery(internal.sharedUsers.getPublicProfile, {
+      userId,
+    });
+
+    if (!profile) {
+      return {
+        found: false,
+        reason: 'Could not locate the user record linked to this conversation.',
+      };
+    }
+
+    return {
+      found: true,
+      profile,
+      guidance:
+        'Summarize the profile in natural language. If fields are null, mention they are not provided. Use credits to answer balance questions.',
+    };
+  },
+});

package/recipes/chatbot/recipe.json

@@ -14,6 +14,46 @@
     {
       "from": "packages/backend/convex/chatbot",
       "to": "packages/backend/convex/chatbot"
+    },
+    {
+      "from": "packages/backend/convex/chatbotAgent.ts",
+      "to": "packages/backend/convex/chatbotAgent.ts"
+    },
+    {
+      "from": "packages/backend/convex/chatbotHistory.ts",
+      "to": "packages/backend/convex/chatbotHistory.ts"
+    },
+    {
+      "from": "packages/backend/convex/agents.ts",
+      "to": "packages/backend/convex/agents.ts"
+    },
+    {
+      "from": "packages/backend/convex/lib/rateLimit.ts",
+      "to": "packages/backend/convex/lib/rateLimit.ts"
+    },
+    {
+      "from": "packages/backend/convex/lib/telemetry.ts",
+      "to": "packages/backend/convex/lib/telemetry.ts"
+    },
+    {
+      "from": "packages/backend/convex/ragKnowledge.ts",
+      "to": "packages/backend/convex/ragKnowledge.ts"
+    },
+    {
+      "from": "packages/backend/convex/tools/index.ts",
+      "to": "packages/backend/convex/tools/index.ts"
+    },
+    {
+      "from": "packages/backend/convex/tools/knowledgeRetrieval.ts",
+      "to": "packages/backend/convex/tools/knowledgeRetrieval.ts"
+    },
+    {
+      "from": "packages/backend/convex/tools/tavilySearch.ts",
+      "to": "packages/backend/convex/tools/tavilySearch.ts"
+    },
+    {
+      "from": "packages/backend/convex/tools/userProfile.ts",
+      "to": "packages/backend/convex/tools/userProfile.ts"
     }
   ],
   "nav": {
@@ -33,5 +73,53 @@
       "react-native-reanimated",
       "react-native-safe-area-context"
     ]
-  }
+  },
+  "env": [
+    {
+      "key": "OPENAI_API_KEY",
+      "description": "OpenAI API key used by the backend agent and knowledge tools.",
+      "example": "sk-abc123def456",
+      "link": "https://platform.openai.com/account/api-keys"
+    },
+    {
+      "key": "GOOGLE_GENERATIVE_AI_API_KEY",
+      "description": "Google Generative AI key that unlocks the Gemini-backed assistant.",
+      "example": "AIzaSyExampleGeneratedKey",
+      "link": "https://console.cloud.google.com/apis/credentials"
+    },
+    {
+      "key": "TAVILY_API_KEY",
+      "description": "API key for Tavily web search results used by the agent tools.",
+      "example": "tavily_abc123",
+      "link": "https://app.tavily.com/"
+    },
+    {
+      "key": "CHAT_LATENCY_TELEMETRY_MODE",
+      "description": "Optional telemetry mode to sample chat latency (off | sample | debug).",
+      "example": "sample"
+    }
+  ],
+  "manualSteps": [
+    {
+      "title": "Create an OpenAI API key",
+      "description": "Sign into https://platform.openai.com and create/copy a server API key for the chat agent.",
+      "link": "https://platform.openai.com/account/api-keys"
+    },
+    {
+      "title": "Create a Google Generative AI key",
+      "description": "Enable the Generative AI APIs in the Google Cloud Console and issue a new API key.",
+      "link": "https://console.cloud.google.com/apis/credentials"
+    },
+    {
+      "title": "Create a Tavily search key",
+      "description": "Register at Tavily and grab an API key so the chatbot can query the web.",
+      "link": "https://app.tavily.com/"
+    },
+    {
+      "title": "Store the keys in your .env",
+      "description": "Add the required AI/search env variables so Convex can call OpenAI, Google, and Tavily.",
+      "file": ".env",
+      "content": "OPENAI_API_KEY=sk-...\nGOOGLE_GENERATIVE_AI_API_KEY=...\nTAVILY_API_KEY=...\nCHAT_LATENCY_TELEMETRY_MODE=sample"
+    }
+  ]
 }

package/recipes/image-generator/packages/backend/convex/imageGeneration/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Image Generation Domain Aggregator
+ *
+ * Single entry point for all image generation Convex functions.
+ * Re-exports functions from imageGeneratorFunctions.ts to decouple
+ * frontend from internal file structure.
+ */
+
+export {
+  generateImageAction,
+  saveImageRecord,
+} from '../imageGeneratorFunctions';

package/recipes/image-generator/packages/backend/convex/imageGeneratorFunctions.ts

@@ -0,0 +1,290 @@
+import { getAuthUserId } from '@convex-dev/auth/server';
+import { experimental_generateImage as generateImage } from 'ai';
+import { createOpenAI } from '@ai-sdk/openai';
+import { GoogleGenAI } from '@google/genai';
+import { v } from 'convex/values';
+
+import { internal } from './_generated/api';
+import type { Id } from './_generated/dataModel';
+import { action, internalMutation } from './_generated/server';
+
+const DEFAULT_OPENAI_MODEL = 'dall-e-3';
+const DEFAULT_GEMINI_MODEL = 'gemini-2.5-flash-image';
+
+const SUPPORTED_OPENAI_MODELS = new Set<string>(['dall-e-3', 'gpt-image-1']);
+const SUPPORTED_GEMINI_MODELS = new Set<string>([
+  'gemini-2.5-flash-image',
+  'gemini-2.0-flash-image',
+]);
+
+type SupportedProvider = 'openai' | 'gemini';
+
+const isSupportedProvider = (value: string): value is SupportedProvider =>
+  value === 'openai' || value === 'gemini';
+
+const resolveProvider = (
+  provider: string | null | undefined,
+): SupportedProvider => {
+  if (provider && isSupportedProvider(provider)) {
+    return provider;
+  }
+  return 'gemini';
+};
+
+const resolveModel = (
+  provider: SupportedProvider,
+  model: string | null | undefined,
+): string => {
+  if (provider === 'openai') {
+    return model && SUPPORTED_OPENAI_MODELS.has(model)
+      ? model
+      : DEFAULT_OPENAI_MODEL;
+  }
+  return model && SUPPORTED_GEMINI_MODELS.has(model)
+    ? model
+    : DEFAULT_GEMINI_MODEL;
+};
+
+const generateWithOpenAI = async (prompt: string, model: string) => {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) {
+    throw new Error('OPENAI_API_KEY environment variable is required');
+  }
+
+  const openai = createOpenAI({ apiKey });
+  const result = await generateImage({
+    model: openai.image(model),
+    prompt,
+    size: '1024x1024',
+  });
+
+  const imageResult = result.image ?? result.images?.[0];
+  if (!imageResult) {
+    throw new Error('OpenAI image generation did not return any image data.');
+  }
+
+  const mimeType = imageResult.mimeType ?? 'image/png';
+  const base64Data =
+    imageResult.base64 ??
+    (imageResult.uint8Array
+      ? Buffer.from(imageResult.uint8Array).toString('base64')
+      : null);
+
+  if (!base64Data) {
+    throw new Error('OpenAI image generation returned no image payload.');
+  }
+
+  return {
+    imageDataUri: `data:${mimeType};base64,${base64Data}`,
+    mimeType,
+  };
+};
+
+const generateWithGemini = async (prompt: string, model: string) => {
+  const apiKey = process.env.GEMINI_API_KEY;
+  if (!apiKey) {
+    throw new Error('GEMINI_API_KEY environment variable is required');
+  }
+
+  const ai = new GoogleGenAI({ apiKey });
+  const response = await ai.models.generateContentStream({
+    model,
+    config: {
+      responseModalities: ['IMAGE', 'TEXT'],
+      //   imageConfig: {
+      //     imageSize: "1K",
+      //   },
+    },
+    contents: [
+      {
+        role: 'user',
+        parts: [
+          {
+            text: prompt,
+          },
+        ],
+      },
+    ],
+  });
+
+  let imageInlineData: {
+    data?: string;
+    mimeType?: string;
+  } | null = null;
+  const textChunks: string[] = [];
+
+  for await (const chunk of response) {
+    const parts = chunk.candidates?.[0]?.content?.parts ?? [];
+    for (const part of parts) {
+      if (part.inlineData) {
+        imageInlineData = part.inlineData;
+        break;
+      }
+      if (part.text) {
+        textChunks.push(part.text);
+      }
+    }
+    if (imageInlineData) {
+      break;
+    }
+  }
+
+  if (!imageInlineData?.data) {
+    const textSummary = textChunks.join(' ').trim();
+    throw new Error(
+      textSummary
+        ? `Gemini image generation did not return any image data. Response: ${textSummary}`
+        : 'Gemini image generation did not return any image data.',
+    );
+  }
+
+  const mimeType = imageInlineData.mimeType ?? 'image/png';
+  const base64Data = imageInlineData.data;
+
+  return {
+    imageDataUri: `data:${mimeType};base64,${base64Data}`,
+    mimeType,
+  };
+};
+
+export const saveImageRecord = internalMutation({
+  args: v.object({
+    userId: v.id('users'),
+    prompt: v.string(),
+    storageId: v.id('_storage'),
+    provider: v.string(),
+    model: v.string(),
+    mimeType: v.optional(v.string()),
+  }),
+  returns: v.id('generatedImages'),
+  handler: async (
+    ctx,
+    { userId, prompt, storageId, provider, model, mimeType },
+  ) => {
+    console.log(`[saveImageRecord] Saving image record for user: ${userId}`);
+
+    const imageRecordId = await ctx.db.insert('generatedImages', {
+      userId,
+      prompt,
+      storageId,
+      provider,
+      model,
+      mimeType,
+    });
+
+    console.log(
+      `[saveImageRecord] Image record created with ID: ${imageRecordId}`,
+    );
+    return imageRecordId;
+  },
+});
+
+/**
+ * Generate an image based on user prompt and provider selection
+ */
+export const generateImageAction = action({
+  args: v.object({
+    prompt: v.string(),
+    provider: v.string(), // supports 'openai' and 'gemini'
+    model: v.string(),
+  }),
+  returns: v.object({
+    imageDataUri: v.string(),
+    mimeType: v.string(),
+    prompt: v.string(),
+    provider: v.string(),
+    model: v.string(),
+    storageId: v.optional(v.id('_storage')),
+    imageId: v.optional(v.id('generatedImages')),
+  }),
+  handler: async (ctx, { prompt, provider, model }) => {
+    // Verify user authentication
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) {
+      throw new Error(
+        'Unauthenticated: User must be logged in to generate images',
+      );
+    }
+
+    const userId = await getAuthUserId(ctx);
+    if (!userId) {
+      throw new Error('User record not found for authenticated identity');
+    }
+    console.log(`[generateImageAction] Provider: ${provider}, Model: ${model}`);
+    const resolvedProvider = resolveProvider(provider);
+    const resolvedModel = resolveModel(resolvedProvider, model);
+
+    console.log(
+      `[generateImageAction] Starting image generation | provider=${resolvedProvider}, model=${resolvedModel}`,
+    );
+
+    try {
+      const result =
+        resolvedProvider === 'openai'
+          ? await generateWithOpenAI(prompt, resolvedModel)
+          : await generateWithGemini(prompt, resolvedModel);
+
+      console.log(
+        `[generateImageAction] Image generated successfully. provider=${resolvedProvider}, model=${resolvedModel}, mimeType=${result.mimeType}, dataUri length=${result.imageDataUri.length}`,
+      );
+
+      let storageId: Id<'_storage'> | null = null;
+      try {
+        const base64Match = result.imageDataUri.match(
+          /^data:(?<mime>[^;]+);base64,(?<payload>.+)$/,
+        );
+        if (!base64Match?.groups?.payload) {
+          throw new Error('Invalid image data URI returned by provider');
+        }
+        const buffer = Buffer.from(base64Match.groups.payload, 'base64');
+        const uint8Array = new Uint8Array(buffer);
+        const blob = new Blob([uint8Array], { type: result.mimeType });
+        storageId = await ctx.storage.store(blob);
+      } catch (storageError) {
+        console.error(
+          '[generateImageAction] Failed to persist generated image to storage',
+          storageError,
+        );
+      }
+
+      let imageRecordId: Id<'generatedImages'> | null = null;
+      if (storageId) {
+        try {
+          imageRecordId = await ctx.runMutation(
+            internal.imageGeneration.index.saveImageRecord,
+            {
+              userId,
+              prompt,
+              storageId,
+              provider: resolvedProvider,
+              model: resolvedModel,
+              mimeType: result.mimeType,
+            },
+          );
+        } catch (recordError) {
+          console.error(
+            '[generateImageAction] Failed to save generated image metadata',
+            recordError,
+          );
+        }
+      }
+
+      return {
+        imageDataUri: result.imageDataUri,
+        mimeType: result.mimeType,
+        prompt,
+        provider: resolvedProvider,
+        model: resolvedModel,
+        storageId: storageId ?? undefined,
+        imageId: imageRecordId ?? undefined,
+      };
+    } catch (error) {
+      console.error('[generateImageAction] Error generating image:', error);
+      throw new Error(
+        `Image generation failed: ${
+          error instanceof Error ? error.message : 'Unknown error'
+        }`,
+      );
+    }
+  },
+});