beddel 0.2.1 → 0.2.3

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

@@ -0,0 +1,82 @@
+import 'server-only';
+
+/**
+ * Image Agent Handler - Server-only execution logic
+ * Generates images using Gemini Flash with curated styles
+ */
+
+import { experimental_generateImage } from 'ai';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+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 Gemini
+ */
+export async function executeImageHandler(
+  params: ImageHandlerParams,
+  props: Record<string, string>,
+  context: ExecutionContext
+): Promise<ImageHandlerResult> {
+  const apiKey = props?.gemini_api_key?.trim();
+  if (!apiKey) {
+    throw new Error('Missing required prop: gemini_api_key');
+  }
+
+  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 });
+  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,
+      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,45 @@
+/**
+ * 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;
+    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,59 @@
+/**
+ * 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 { 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 { 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 { 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 context using Gemini', category: 'intelligence', route: '/agents/rag' },
+  { id: 'chat', name: 'Q&A Context Chat Agent', description: 'Orchestrates RAG pipeline: vectorization, storage, retrieval and answer generation', 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,60 @@
+import 'server-only';
+
+/**
+ * Joker Agent Handler - Server-only execution logic
+ * Generates jokes using Gemini Flash
+ */
+
+import { generateText } from 'ai';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import type { ExecutionContext } from '../../types/executionContext';
+import type { JokeHandlerParams, JokeHandlerResult } from './joker.types';
+
+const GEMINI_MODEL = 'models/gemini-2.5-flash';
+
+/**
+ * Execute joke generation using Gemini Flash
+ */
+export async function executeJokeHandler(
+  params: JokeHandlerParams,
+  props: Record<string, string>,
+  context: ExecutionContext
+): Promise<JokeHandlerResult> {
+  const apiKey = props?.gemini_api_key?.trim();
+  if (!apiKey) {
+    throw new Error('Missing required prop: gemini_api_key');
+  }
+
+  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 google = createGoogleGenerativeAI({ apiKey });
+  const model = google(GEMINI_MODEL);
+  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: GEMINI_MODEL,
+      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,37 @@
+/**
+ * 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;
+    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/mcp-tool/index.ts

@@ -0,0 +1,19 @@
+/**
+ * MCP Tool Agent - Public exports (client-safe)
+ */
+
+// Schema exports (client-safe)
+export { McpToolInputSchema, McpToolOutputSchema } from './mcp-tool.schema';
+export type { McpToolInput, McpToolOutput } from './mcp-tool.schema';
+
+// Type exports (client-safe)
+export type { McpToolHandlerParams, McpToolHandlerResult, McpToolMetadata } from './mcp-tool.types';
+
+// Metadata (client-safe)
+export const mcpToolMetadata = {
+  id: 'mcp-tool',
+  name: 'MCP Tool Agent',
+  description: 'Generic agent for calling MCP server tools via SSE transport',
+  category: 'integration',
+  route: '/agents/mcp-tool',
+} as const;

package/src/agents/mcp-tool/mcp-tool.handler.ts

@@ -0,0 +1,112 @@
+import 'server-only';
+
+/**
+ * MCP Tool Agent Handler - Server-only execution logic
+ * Generic agent for calling MCP server tools via SSE transport
+ */
+
+import type { ExecutionContext } from '../../types/executionContext';
+import type { McpToolHandlerParams, McpToolHandlerResult } from './mcp-tool.types';
+
+// MCP imports (lazy loaded to avoid issues if not installed)
+let mcpClient: any = null;
+let mcpSSETransport: any = null;
+
+/**
+ * Execute MCP tool invocation
+ */
+export async function executeMcpToolHandler(
+  params: McpToolHandlerParams,
+  _props: Record<string, string>,
+  context: ExecutionContext
+): Promise<McpToolHandlerResult> {
+  const serverUrl = params.server_url;
+  const toolName = params.tool_name;
+  const toolArguments = params.tool_arguments || {};
+
+  if (!serverUrl) {
+    throw new Error('Missing required MCP input: server_url');
+  }
+  if (!toolName) {
+    throw new Error('Missing required MCP input: tool_name');
+  }
+
+  context.log(`[MCP Tool] Connecting to ${serverUrl}...`);
+  context.log(`[MCP Tool] Tool: ${toolName}`);
+
+  try {
+    // Lazy load MCP SDK
+    if (!mcpClient) {
+      const { Client } = await import('@modelcontextprotocol/sdk/client/index.js');
+      const { SSEClientTransport } = await import('@modelcontextprotocol/sdk/client/sse.js');
+      mcpClient = Client;
+      mcpSSETransport = SSEClientTransport;
+
+      // Setup EventSource for Node.js
+      const eventsourceModule = await import('eventsource');
+      const EventSourceClass = eventsourceModule.default || eventsourceModule;
+      if (!(global as any).EventSource) {
+        (global as any).EventSource = EventSourceClass;
+      }
+    }
+
+    const transport = new mcpSSETransport(new URL(serverUrl));
+    const client = new mcpClient(
+      { name: 'beddel-mcp-client', version: '1.0.0' },
+      { capabilities: {} }
+    );
+
+    await client.connect(transport);
+    context.log('[MCP Tool] Connected!');
+
+    // List available tools
+    const tools = await client.listTools();
+    const availableToolNames = tools.tools.map((t: any) => t.name);
+    context.log(`[MCP Tool] Available tools: ${availableToolNames.join(', ')}`);
+
+    // Handle list_tools special case
+    if (toolName === 'list_tools') {
+      await client.close();
+      return {
+        success: true,
+        data: JSON.stringify(tools.tools),
+        tool_names: availableToolNames,
+      };
+    }
+
+    // Validate tool exists
+    if (!availableToolNames.includes(toolName)) {
+      await client.close();
+      return {
+        success: false,
+        error: `Tool '${toolName}' not found. Available tools: ${availableToolNames.join(', ')}`,
+      };
+    }
+
+    // Call the tool with timeout
+    const timeoutPromise = new Promise((_, reject) =>
+      setTimeout(() => reject(new Error('MCP Tool Timeout (30s)')), 30000)
+    );
+
+    const callPromise = client.callTool({
+      name: toolName,
+      arguments: toolArguments,
+    });
+
+    const callResult: any = await Promise.race([callPromise, timeoutPromise]);
+    await client.close();
+
+    // Parse result content
+    const textContent = callResult.content
+      .filter((c: any) => c.type === 'text')
+      .map((c: any) => c.text)
+      .join('\n') || 'No text content returned';
+
+    return { success: true, data: textContent };
+
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    context.log(`[MCP Tool] Error: ${message}`);
+    return { success: false, error: message };
+  }
+}

package/src/agents/mcp-tool/mcp-tool.schema.ts

@@ -0,0 +1,22 @@
+/**
+ * MCP Tool Agent Schema - Zod validation schemas
+ * Safe for both client and server
+ */
+
+import { z } from 'zod';
+
+export const McpToolInputSchema = z.object({
+  server_url: z.string().url(),
+  tool_name: z.string().min(1),
+  tool_arguments: z.record(z.string(), z.unknown()).optional(),
+});
+
+export const McpToolOutputSchema = z.object({
+  success: z.boolean(),
+  data: z.string().optional(),
+  tool_names: z.array(z.string()).optional(),
+  error: z.string().optional(),
+});
+
+export type McpToolInput = z.infer<typeof McpToolInputSchema>;
+export type McpToolOutput = z.infer<typeof McpToolOutputSchema>;