beddel 0.2.2 → 0.3.0

package/src/agents/image/image.handler.ts

@@ -0,0 +1,86 @@
+import 'server-only';
+
+/**
+ * Image Agent Handler - Server-only execution logic
+ * Generates images using LLM providers (Google Gemini Imagen by default)
+ */
+
+import { experimental_generateImage } from 'ai';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import { extractProviderConfig } from '../../runtime/llmProviderFactory';
+import type { ExecutionContext } from '../../types/executionContext';
+import type { ImageHandlerParams, ImageHandlerResult } from './image.types';
+
+const GEMINI_IMAGE_MODEL = 'imagen-4.0-fast-generate-001';
+
+/**
+ * Execute image generation using configured provider
+ */
+export async function executeImageHandler(
+  params: ImageHandlerParams,
+  props: Record<string, string>,
+  context: ExecutionContext
+): Promise<ImageHandlerResult> {
+  const providerConfig = extractProviderConfig(props, 'google');
+  
+  // Currently only Google supports image generation via Vercel AI SDK
+  if (providerConfig.provider !== 'google') {
+    throw new Error(`Image generation is currently only supported with Google provider, got: ${providerConfig.provider}`);
+  }
+
+  const description = params.description?.trim();
+  const style = params.style?.trim();
+  const resolution = params.resolution?.trim();
+
+  if (!description) {
+    throw new Error('Missing required image input: description');
+  }
+  if (!style) {
+    throw new Error('Missing required image input: style');
+  }
+  if (!resolution || !/^\d+x\d+$/.test(resolution)) {
+    throw new Error('Missing required image input: resolution (format: WIDTHxHEIGHT)');
+  }
+
+  const promptTemplate = params.promptTemplate?.trim() ||
+    'Create a detailed image in {{style}} style focusing on: {{description}}';
+
+  const prompt = promptTemplate
+    .replace(/{{description}}/g, description)
+    .replace(/{{style}}/g, style)
+    .trim();
+
+  const google = createGoogleGenerativeAI({ apiKey: providerConfig.apiKey });
+  const model = google.image(GEMINI_IMAGE_MODEL);
+  const startTime = Date.now();
+
+  context.log(`[Image] Generating image with style=${style}, resolution=${resolution}`);
+
+  const result = await experimental_generateImage({
+    model,
+    prompt,
+    size: resolution as `${number}x${number}`,
+  });
+
+  const image = result.image;
+  if (!image?.base64 || !image.mediaType) {
+    throw new Error('Gemini Flash image helper returned an invalid file');
+  }
+
+  const normalizedBase64 = image.base64.replace(/\s+/g, '');
+  const imageUrl = `data:${image.mediaType};base64,${normalizedBase64}`;
+
+  return {
+    image_url: imageUrl,
+    image_base64: normalizedBase64,
+    media_type: image.mediaType,
+    prompt_used: prompt,
+    metadata: {
+      model_used: GEMINI_IMAGE_MODEL,
+      provider: providerConfig.provider,
+      processing_time: Date.now() - startTime,
+      style,
+      resolution,
+    },
+  };
+}

package/src/agents/image/image.schema.ts

@@ -0,0 +1,28 @@
+/**
+ * Image Agent Schema - Zod validation schemas
+ * Safe for both client and server
+ */
+
+import { z } from 'zod';
+
+export const ImageInputSchema = z.object({
+  description: z.string().min(5).max(500),
+  style: z.enum(['watercolor', 'neon', 'sketch']),
+  resolution: z.string().regex(/^[0-9]{3,4}x[0-9]{3,4}$/),
+});
+
+export const ImageOutputSchema = z.object({
+  image_url: z.string(),
+  image_base64: z.string().optional(),
+  media_type: z.string().optional(),
+  prompt_used: z.string(),
+  metadata: z.object({
+    model_used: z.string(),
+    processing_time: z.number(),
+    style: z.string(),
+    resolution: z.string(),
+  }),
+});
+
+export type ImageInput = z.infer<typeof ImageInputSchema>;
+export type ImageOutput = z.infer<typeof ImageOutputSchema>;

package/src/agents/image/image.types.ts

@@ -0,0 +1,46 @@
+/**
+ * Image Agent Types - Shared between client and server
+ */
+
+/**
+ * Supported image styles
+ */
+export type ImageStyle = 'watercolor' | 'neon' | 'sketch' | string;
+
+/**
+ * Parameters for image generation
+ */
+export interface ImageHandlerParams {
+  description: string;
+  style: ImageStyle;
+  resolution: string;
+  promptTemplate?: string;
+}
+
+/**
+ * Result from image generation
+ */
+export interface ImageHandlerResult {
+  image_url: string;
+  image_base64: string;
+  media_type: string;
+  prompt_used: string;
+  metadata: {
+    model_used: string;
+    provider: string;
+    processing_time: number;
+    style: string;
+    resolution: string;
+  };
+}
+
+/**
+ * Image agent metadata
+ */
+export interface ImageMetadata {
+  id: 'image';
+  name: string;
+  description: string;
+  category: 'creative';
+  route: '/agents/image';
+}

package/src/agents/image/image.yaml

@@ -0,0 +1,86 @@
+# Image Generator Agent - Declarative Genkit workflow
+# Route: /agents/image
+# Method: image.generate
+
+agent:
+  id: image
+  version: 1.0.0
+  protocol: beddel-declarative-protocol/v2.0
+
+metadata:
+  name: "Image Generator Agent"
+  description: "Generates images using Gemini Flash with curated styles"
+  category: "creative"
+  route: "/agents/image"
+
+schema:
+  input:
+    type: "object"
+    properties:
+      description:
+        type: "string"
+        minLength: 5
+        maxLength: 500
+        description: "Detailed textual description of the scene"
+      style:
+        type: "string"
+        enum: ["watercolor", "neon", "sketch"]
+        description: "Desired visual style"
+      resolution:
+        type: "string"
+        pattern: "^[0-9]{3,4}x[0-9]{3,4}$"
+        description: "Resolution in WIDTHxHEIGHT format (e.g., 1024x1024)"
+    required: ["description", "style", "resolution"]
+
+  output:
+    type: "object"
+    properties:
+      image_url:
+        type: "string"
+      image_base64:
+        type: "string"
+      media_type:
+        type: "string"
+      prompt_used:
+        type: "string"
+      metadata:
+        type: "object"
+        properties:
+          model_used:
+            type: "string"
+          processing_time:
+            type: "number"
+          style:
+            type: "string"
+          resolution:
+            type: "string"
+        required: ["model_used", "processing_time", "style", "resolution"]
+    required: ["image_url", "prompt_used", "metadata"]
+
+logic:
+  workflow:
+    - name: "generate-image"
+      type: "genkit-image"
+      action:
+        type: "image"
+        result: "imageResult"
+        promptTemplate: "Create an image in {{style}} style focusing on: {{description}}"
+
+    - name: "deliver-image"
+      type: "output-generator"
+      action:
+        type: "generate"
+        output:
+          image_url: "$imageResult.image_url"
+          image_base64: "$imageResult.image_base64"
+          media_type: "$imageResult.media_type"
+          prompt_used: "$imageResult.prompt_used"
+          metadata: "$imageResult.metadata"
+
+output:
+  schema:
+    image_url: "$imageResult.image_url"
+    image_base64: "$imageResult.image_base64"
+    media_type: "$imageResult.media_type"
+    prompt_used: "$imageResult.prompt_used"
+    metadata: "$imageResult.metadata"

package/src/agents/image/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Image Agent - Public exports (client-safe)
+ */
+
+// Schema exports (client-safe)
+export { ImageInputSchema, ImageOutputSchema } from './image.schema';
+export type { ImageInput, ImageOutput } from './image.schema';
+
+// Type exports (client-safe)
+export type { ImageStyle, ImageHandlerParams, ImageHandlerResult, ImageMetadata } from './image.types';
+
+// Metadata (client-safe)
+export const imageMetadata = {
+  id: 'image',
+  name: 'Image Generator Agent',
+  description: 'Generates images using Gemini Flash with curated styles',
+  category: 'creative',
+  route: '/agents/image',
+} as const;

package/src/agents/index.ts

@@ -0,0 +1,63 @@
+/**
+ * Agents Module - Public exports
+ *
+ * This module provides the agent registry and agent metadata.
+ * Handler implementations are server-only and should be imported directly
+ * from their respective agent folders when needed.
+ */
+
+// Registry exports
+export { AgentRegistry, agentRegistry } from './registry';
+export type { AgentRegistration } from './registry';
+
+// Agent metadata exports (client-safe)
+export { jokerMetadata } from './joker';
+export { translatorMetadata } from './translator';
+export { imageMetadata } from './image';
+export { mcpToolMetadata } from './mcp-tool';
+export { geminiVectorizeMetadata } from './gemini-vectorize';
+export { chromadbMetadata } from './chromadb';
+export { gitmcpMetadata } from './gitmcp';
+export { ragMetadata } from './rag';
+export { llmMetadata } from './llm';
+export { chatMetadata } from './chat';
+
+// Schema exports (client-safe)
+export { JokerInputSchema, JokerOutputSchema } from './joker';
+export { TranslatorInputSchema, TranslatorOutputSchema } from './translator';
+export { ImageInputSchema, ImageOutputSchema } from './image';
+export { McpToolInputSchema, McpToolOutputSchema } from './mcp-tool';
+export { GeminiVectorizeInputSchema, GeminiVectorizeOutputSchema } from './gemini-vectorize';
+export { ChromaDBInputSchema, ChromaDBOutputSchema } from './chromadb';
+export { GitMcpInputSchema, GitMcpOutputSchema } from './gitmcp';
+export { RagInputSchema, RagOutputSchema } from './rag';
+export { LlmInputSchema, LlmOutputSchema } from './llm';
+export { ChatInputSchema, ChatOutputSchema } from './chat';
+
+// Type exports (client-safe)
+export type { JokerInput, JokerOutput, JokeHandlerParams, JokeHandlerResult } from './joker';
+export type { TranslatorInput, TranslatorOutput, TranslationHandlerParams, TranslationHandlerResult } from './translator';
+export type { ImageInput, ImageOutput, ImageStyle, ImageHandlerParams, ImageHandlerResult } from './image';
+export type { McpToolInput, McpToolOutput, McpToolHandlerParams, McpToolHandlerResult } from './mcp-tool';
+export type { GeminiVectorizeInput, GeminiVectorizeOutput, VectorizeHandlerParams, VectorizeHandlerResult } from './gemini-vectorize';
+export type { ChromaDBInput, ChromaDBOutput, ChromaDBHandlerParams, ChromaDBHandlerResult, ChromaDBSearchResult } from './chromadb';
+export type { GitMcpInput, GitMcpOutput, GitMcpHandlerParams, GitMcpHandlerResult } from './gitmcp';
+export type { RagInput, RagOutput, RagHandlerParams, RagHandlerResult, ConversationMessage } from './rag';
+export type { LlmInput, LlmOutput, LlmHandlerParams, LlmHandlerResult } from './llm';
+export type { ChatInput, ChatOutput, ChatHandlerParams, ChatHandlerResult } from './chat';
+
+/**
+ * All agent metadata for UI display
+ */
+export const allAgentMetadata = [
+  { id: 'joker', name: 'Joker Agent', description: 'Tells jokes using Gemini Flash', category: 'utility', route: '/agents/joker' },
+  { id: 'translator', name: 'Translator Agent', description: 'Translates text between languages using Gemini Flash via Genkit', category: 'translation', route: '/agents/translator' },
+  { id: 'image', name: 'Image Generator Agent', description: 'Generates images using Gemini Flash with curated styles', category: 'creative', route: '/agents/image' },
+  { id: 'mcp-tool', name: 'MCP Tool Agent', description: 'Generic agent for calling MCP server tools via SSE transport', category: 'integration', route: '/agents/mcp-tool' },
+  { id: 'gemini-vectorize', name: 'Gemini Vectorize Agent', description: "Generates text embeddings using Google's Gemini text-embedding-004 model", category: 'ai-service', route: '/agents/gemini-vectorize' },
+  { id: 'chromadb', name: 'ChromaDB Agent', description: 'Vector storage and retrieval using ChromaDB. Supports local and cloud deployments.', category: 'database', route: '/agents/chromadb' },
+  { id: 'gitmcp', name: 'GitMCP Documentation Agent', description: 'Fetches and chunks GitHub repository documentation via gitmcp.io MCP servers', category: 'integration', route: '/agents/gitmcp' },
+  { id: 'rag', name: 'RAG Intelligence Agent', description: 'Generates natural language answers based on provided document context using Gemini', category: 'intelligence', route: '/agents/rag' },
+  { id: 'llm', name: 'LLM Chat Agent', description: 'Direct LLM interaction with conversation history support (non-RAG)', category: 'intelligence', route: '/agents/llm' },
+  { id: 'chat', name: 'Q&A Context Chat Agent', description: 'Orchestrates RAG pipeline or direct LLM chat based on mode selection', category: 'chat', route: '/agents/chat' },
+] as const;

package/src/agents/joker/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Joker Agent - Public exports (client-safe)
+ */
+
+// Schema exports (client-safe)
+export { JokerInputSchema, JokerOutputSchema } from './joker.schema';
+export type { JokerInput, JokerOutput } from './joker.schema';
+
+// Type exports (client-safe)
+export type { JokeHandlerParams, JokeHandlerResult, JokerMetadata } from './joker.types';
+
+// Metadata (client-safe)
+export const jokerMetadata = {
+  id: 'joker',
+  name: 'Joker Agent',
+  description: 'Tells jokes using Gemini Flash',
+  category: 'utility',
+  route: '/agents/joker',
+} as const;

package/src/agents/joker/joker.handler.ts

@@ -0,0 +1,55 @@
+import 'server-only';
+
+/**
+ * Joker Agent Handler - Server-only execution logic
+ * Generates jokes using LLM providers (Google Gemini by default)
+ */
+
+import { generateText } from 'ai';
+import { LLMProviderFactory, extractProviderConfig } from '../../runtime/llmProviderFactory';
+import type { ExecutionContext } from '../../types/executionContext';
+import type { JokeHandlerParams, JokeHandlerResult } from './joker.types';
+
+/**
+ * Execute joke generation using configured LLM provider
+ */
+export async function executeJokeHandler(
+  params: JokeHandlerParams,
+  props: Record<string, string>,
+  context: ExecutionContext
+): Promise<JokeHandlerResult> {
+  const providerConfig = extractProviderConfig(props, 'google');
+  const model = LLMProviderFactory.createLanguageModel(providerConfig);
+
+  const prompt = params.prompt?.trim() || 'Tell a short and original joke that works for any audience.';
+  const temperature = params.temperature ?? 0.8;
+  const maxTokens = params.maxTokens;
+
+  const startTime = Date.now();
+
+  context.log(`[Joker] Generating joke with temperature=${temperature}`);
+
+  const { text } = await generateText({
+    model,
+    prompt,
+    temperature,
+    ...(maxTokens && { maxOutputTokens: maxTokens }),
+  });
+
+  const finalText = text?.trim() || '';
+  if (!finalText) {
+    throw new Error('Gemini returned empty response');
+  }
+
+  return {
+    text: finalText,
+    metadata: {
+      model_used: providerConfig.model || LLMProviderFactory.getDefaultModel(providerConfig.provider),
+      provider: providerConfig.provider,
+      processing_time: Date.now() - startTime,
+      temperature,
+      max_tokens: maxTokens ?? null,
+      prompt_used: prompt,
+    },
+  };
+}

package/src/agents/joker/joker.schema.ts

@@ -0,0 +1,15 @@
+/**
+ * Joker Agent Schema - Zod validation schemas
+ * Safe for both client and server
+ */
+
+import { z } from 'zod';
+
+export const JokerInputSchema = z.object({}).optional();
+
+export const JokerOutputSchema = z.object({
+  response: z.string(),
+});
+
+export type JokerInput = z.infer<typeof JokerInputSchema>;
+export type JokerOutput = z.infer<typeof JokerOutputSchema>;

package/src/agents/joker/joker.types.ts

@@ -0,0 +1,38 @@
+/**
+ * Joker Agent Types - Shared between client and server
+ */
+
+/**
+ * Parameters for joke generation
+ */
+export interface JokeHandlerParams {
+  prompt?: string;
+  temperature?: number;
+  maxTokens?: number;
+}
+
+/**
+ * Result from joke generation
+ */
+export interface JokeHandlerResult {
+  text: string;
+  metadata: {
+    model_used: string;
+    provider: string;
+    processing_time: number;
+    temperature: number;
+    max_tokens: number | null;
+    prompt_used: string;
+  };
+}
+
+/**
+ * Joker agent metadata
+ */
+export interface JokerMetadata {
+  id: 'joker';
+  name: string;
+  description: string;
+  category: 'utility';
+  route: '/agents/joker';
+}

package/src/agents/joker/joker.yaml

@@ -0,0 +1,47 @@
+# Joker Agent - Simple Response Agent for Beddel Runtime
+# Route: /agents/joker
+# Method: joker.execute
+
+agent:
+  id: joker
+  version: 1.0.0
+  protocol: beddel-declarative-protocol/v2.0
+
+metadata:
+  name: "Joker Agent"
+  description: "Tells jokes using Gemini Flash"
+  category: "utility"
+  route: "/agents/joker"
+
+schema:
+  input:
+    type: "object"
+    properties: {}
+    required: []
+
+  output:
+    type: "object"
+    properties:
+      response:
+        type: "string"
+    required: ["response"]
+
+logic:
+  workflow:
+    - name: "generate-joke"
+      type: "genkit-joke"
+      action:
+        type: "joke"
+        prompt: "Tell a short and original joke that works for any audience."
+        result: "jokerResult"
+
+    - name: "deliver-response"
+      type: "output-generator"
+      action:
+        type: "generate"
+        output:
+          response: "$jokerResult.text"
+
+output:
+  schema:
+    response: "$jokerResult.text"

package/src/agents/llm/index.ts

@@ -0,0 +1,20 @@
+/**
+ * LLM Agent - Public exports (client-safe)
+ */
+
+// Schema exports (client-safe)
+export { LlmInputSchema, LlmOutputSchema } from './llm.schema';
+export type { LlmInput, LlmOutput } from './llm.schema';
+
+// Type exports (client-safe)
+export type { LlmHandlerParams, LlmHandlerResult, LlmMetadata } from './llm.types';
+
+// Metadata (client-safe)
+export const llmMetadata = {
+  id: 'llm',
+  name: 'LLM Chat Agent',
+  description: 'Direct LLM interaction with conversation history support (non-RAG)',
+  category: 'intelligence',
+  route: '/agents/llm',
+  tags: ['llm', 'chat', 'gemini', 'conversation'],
+} as const;

package/src/agents/llm/llm.handler.ts

@@ -0,0 +1,82 @@
+import 'server-only';
+
+/**
+ * LLM Agent Handler - Server-only execution logic
+ * Direct LLM interaction with conversation history support (non-RAG)
+ */
+
+import { generateText } from 'ai';
+import { LLMProviderFactory, extractProviderConfig } from '../../runtime/llmProviderFactory';
+import type { ExecutionContext } from '../../types/executionContext';
+import type { LlmHandlerParams, LlmHandlerResult } from './llm.types';
+import type { ConversationMessage } from '../rag/rag.types';
+
+/**
+ * Build prompt for direct LLM chat (no document context)
+ */
+function buildChatPrompt(
+  query: string,
+  history?: ConversationMessage[],
+  systemPrompt?: string
+): string {
+  const system = systemPrompt || 'You are a helpful, friendly assistant.';
+
+  const conversationContext = history?.length
+    ? `CONVERSATION HISTORY:\n${history.map((m) => `${m.role.toUpperCase()}: ${m.content}`).join('\n')}\n\n`
+    : '';
+
+  return `${system}
+
+${conversationContext}USER MESSAGE:
+${query}
+
+INSTRUCTIONS:
+1. Respond naturally to the user's message.
+2. Consider the conversation history for context continuity if available.
+3. Be concise but helpful.
+
+RESPONSE:`;
+}
+
+/**
+ * Execute direct LLM chat
+ */
+export async function executeLlmHandler(
+  params: LlmHandlerParams,
+  props: Record<string, string>,
+  context: ExecutionContext
+): Promise<LlmHandlerResult> {
+  const providerConfig = extractProviderConfig(props, 'google');
+  const model = LLMProviderFactory.createLanguageModel(providerConfig);
+
+  const { query, history, temperature = 0.7, systemPrompt } = params;
+
+  if (!query) {
+    throw new Error('Missing required LLM input: query');
+  }
+
+  const prompt = buildChatPrompt(query, history, systemPrompt);
+
+  try {
+    context.log(`[LLM] Generating response for: "${query.substring(0, 50)}..."`);
+
+    const { text } = await generateText({
+      model,
+      prompt,
+      temperature,
+    });
+
+    return {
+      response: text,
+      timestamp: new Date().toISOString(),
+    };
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    context.log(`[LLM] Error: ${message}`);
+    return {
+      response: '',
+      timestamp: new Date().toISOString(),
+      error: message,
+    };
+  }
+}

package/src/agents/llm/llm.schema.ts

@@ -0,0 +1,25 @@
+/**
+ * LLM Agent Schema - Zod validation schemas
+ * Safe for both client and server
+ */
+
+import { z } from 'zod';
+
+export const LlmInputSchema = z.object({
+  query: z.string().min(1),
+  history: z.array(z.object({
+    role: z.enum(['user', 'assistant', 'system']),
+    content: z.string(),
+  })).optional(),
+  temperature: z.number().min(0).max(2).optional(),
+  systemPrompt: z.string().optional(),
+});
+
+export const LlmOutputSchema = z.object({
+  response: z.string(),
+  timestamp: z.string().optional(),
+  error: z.string().optional(),
+});
+
+export type LlmInput = z.infer<typeof LlmInputSchema>;
+export type LlmOutput = z.infer<typeof LlmOutputSchema>;

package/src/agents/llm/llm.types.ts

@@ -0,0 +1,37 @@
+/**
+ * LLM Agent Types - Shared between client and server
+ * Direct LLM interaction without document context (non-RAG)
+ */
+
+import type { ConversationMessage } from '../rag/rag.types';
+
+/**
+ * Parameters for direct LLM chat
+ */
+export interface LlmHandlerParams {
+  query: string;
+  history?: ConversationMessage[];
+  temperature?: number;
+  systemPrompt?: string;
+}
+
+/**
+ * Result from LLM chat
+ */
+export interface LlmHandlerResult {
+  response: string;
+  timestamp: string;
+  error?: string;
+}
+
+/**
+ * LLM agent metadata
+ */
+export interface LlmMetadata {
+  id: 'llm';
+  name: string;
+  description: string;
+  category: 'intelligence';
+  route: '/agents/llm';
+  tags: string[];
+}