beddel 0.2.2 → 0.3.0

package/src/agents/{agentRegistry.ts → registry/agentRegistry.ts}

@@ -5,8 +5,8 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from "fs";
 import { join } from "path";
-import { declarativeInterpreter } from "../runtime/declarativeAgentRuntime";
-import { ExecutionContext } from "../types/executionContext";
+import { declarativeInterpreter } from "../../runtime/declarativeAgentRuntime";
+import { ExecutionContext } from "../../types/executionContext";
 
 export interface AgentRegistration {
   id: string;
@@ -210,6 +210,20 @@ export class AgentRegistry {
       this.registerTranslatorAgent();
       // Register Image Generator Agent
       this.registerImageAgent();
+      // Register MCP Tool Agent
+      this.registerMcpToolAgent();
+      // Register Gemini Vectorize Agent
+      this.registerGeminiVectorizeAgent();
+      // Register ChromaDB Agent
+      this.registerChromaDBAgent();
+      // Register GitMCP Agent
+      this.registerGitMcpAgent();
+      // Register RAG Agent
+      this.registerRagAgent();
+      // Register LLM Agent
+      this.registerLlmAgent();
+      // Register Chat Agent (Orchestrator)
+      this.registerChatAgent();
     } catch (error) {
       console.error("Failed to register built-in agents:", error);
     }
@@ -221,7 +235,7 @@ export class AgentRegistry {
   private registerJokerAgent(): void {
     try {
       // Get the Joker Agent YAML content
-      const jokerYamlPath = this.resolveAgentPath("joker-agent.yaml");
+      const jokerYamlPath = this.resolveAgentPath("joker/joker.yaml");
       const yamlContent = readFileSync(jokerYamlPath, "utf-8");
 
       // Parse YAML to extract metadata
@@ -247,7 +261,7 @@ export class AgentRegistry {
    */
   private registerTranslatorAgent(): void {
     try {
-      const translatorYamlPath = this.resolveAgentPath("translator-agent.yaml");
+      const translatorYamlPath = this.resolveAgentPath("translator/translator.yaml");
       const yamlContent = readFileSync(translatorYamlPath, "utf-8");
       const agent = this.parseAgentYaml(yamlContent);
 
@@ -271,7 +285,7 @@ export class AgentRegistry {
    */
   private registerImageAgent(): void {
     try {
-      const imageYamlPath = this.resolveAgentPath("image-agent.yaml");
+      const imageYamlPath = this.resolveAgentPath("image/image.yaml");
       const yamlContent = readFileSync(imageYamlPath, "utf-8");
       const agent = this.parseAgentYaml(yamlContent);
 
@@ -290,6 +304,174 @@ export class AgentRegistry {
     }
   }
 
+  /**
+   * Register MCP Tool Agent
+   */
+  private registerMcpToolAgent(): void {
+    try {
+      const yamlPath = this.resolveAgentPath("mcp-tool/mcp-tool.yaml");
+      const yamlContent = readFileSync(yamlPath, "utf-8");
+      const agent = this.parseAgentYaml(yamlContent);
+
+      this.registerAgent({
+        id: agent.agent.id,
+        name: "mcp-tool.execute",
+        description: agent.metadata.description,
+        protocol: agent.agent.protocol,
+        route: agent.metadata.route || "/agents/mcp-tool",
+        requiredProps: [],
+        yamlContent,
+      });
+    } catch (error) {
+      console.error("Failed to register MCP Tool Agent:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Register Gemini Vectorize Agent
+   */
+  private registerGeminiVectorizeAgent(): void {
+    try {
+      const yamlPath = this.resolveAgentPath("gemini-vectorize/gemini-vectorize.yaml");
+      const yamlContent = readFileSync(yamlPath, "utf-8");
+      const agent = this.parseAgentYaml(yamlContent);
+
+      this.registerAgent({
+        id: agent.agent.id,
+        name: "gemini-vectorize.execute",
+        description: agent.metadata.description,
+        protocol: agent.agent.protocol,
+        route: agent.metadata.route || "/agents/gemini-vectorize",
+        requiredProps: ["gemini_api_key"],
+        yamlContent,
+      });
+    } catch (error) {
+      console.error("Failed to register Gemini Vectorize Agent:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Register ChromaDB Agent
+   */
+  private registerChromaDBAgent(): void {
+    try {
+      const yamlPath = this.resolveAgentPath("chromadb/chromadb.yaml");
+      const yamlContent = readFileSync(yamlPath, "utf-8");
+      const agent = this.parseAgentYaml(yamlContent);
+
+      this.registerAgent({
+        id: agent.agent.id,
+        name: "chromadb.execute",
+        description: agent.metadata.description,
+        protocol: agent.agent.protocol,
+        route: agent.metadata.route || "/agents/chromadb",
+        requiredProps: [],
+        yamlContent,
+      });
+    } catch (error) {
+      console.error("Failed to register ChromaDB Agent:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Register GitMCP Agent
+   */
+  private registerGitMcpAgent(): void {
+    try {
+      const yamlPath = this.resolveAgentPath("gitmcp/gitmcp.yaml");
+      const yamlContent = readFileSync(yamlPath, "utf-8");
+      const agent = this.parseAgentYaml(yamlContent);
+
+      this.registerAgent({
+        id: agent.agent.id,
+        name: "gitmcp.execute",
+        description: agent.metadata.description,
+        protocol: agent.agent.protocol,
+        route: agent.metadata.route || "/agents/gitmcp",
+        requiredProps: [],
+        yamlContent,
+      });
+    } catch (error) {
+      console.error("Failed to register GitMCP Agent:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Register RAG Agent
+   */
+  private registerRagAgent(): void {
+    try {
+      const yamlPath = this.resolveAgentPath("rag/rag.yaml");
+      const yamlContent = readFileSync(yamlPath, "utf-8");
+      const agent = this.parseAgentYaml(yamlContent);
+
+      this.registerAgent({
+        id: agent.agent.id,
+        name: "rag.execute",
+        description: agent.metadata.description,
+        protocol: agent.agent.protocol,
+        route: agent.metadata.route || "/agents/rag",
+        requiredProps: ["gemini_api_key"],
+        yamlContent,
+      });
+    } catch (error) {
+      console.error("Failed to register RAG Agent:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Register LLM Agent
+   */
+  private registerLlmAgent(): void {
+    try {
+      const yamlPath = this.resolveAgentPath("llm/llm.yaml");
+      const yamlContent = readFileSync(yamlPath, "utf-8");
+      const agent = this.parseAgentYaml(yamlContent);
+
+      this.registerAgent({
+        id: agent.agent.id,
+        name: "llm.execute",
+        description: agent.metadata.description,
+        protocol: agent.agent.protocol,
+        route: agent.metadata.route || "/agents/llm",
+        requiredProps: ["gemini_api_key"],
+        yamlContent,
+      });
+    } catch (error) {
+      console.error("Failed to register LLM Agent:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Register Chat Agent (Orchestrator)
+   */
+  private registerChatAgent(): void {
+    try {
+      const yamlPath = this.resolveAgentPath("chat/chat.yaml");
+      const yamlContent = readFileSync(yamlPath, "utf-8");
+      const agent = this.parseAgentYaml(yamlContent);
+
+      this.registerAgent({
+        id: agent.agent.id,
+        name: "chat.execute",
+        description: agent.metadata.description,
+        protocol: agent.agent.protocol,
+        route: agent.metadata.route || "/agents/chat",
+        requiredProps: ["gemini_api_key"],
+        yamlContent,
+      });
+    } catch (error) {
+      console.error("Failed to register Chat Agent:", error);
+      throw error;
+    }
+  }
+
   /**
    * Parse agent YAML content
    */
@@ -363,11 +545,18 @@ export class AgentRegistry {
 
   /**
    * Resolve agent asset path when running in bundled runtimes
+   * Handles both source (src/agents/) and dist (dist/agents/) paths
    */
   private resolveAgentPath(filename: string): string {
     const candidatePaths = [
-      join(__dirname, filename),
+      // From registry folder, go up one level to agents folder
+      join(__dirname, "..", filename),
+      // Direct path from src/agents
       join(process.cwd(), "packages", "beddel", "src", "agents", filename),
+      // Direct path from dist/agents (for built package)
+      join(process.cwd(), "packages", "beddel", "dist", "agents", filename),
+      // When running from node_modules
+      join(__dirname, "..", "..", "agents", filename),
     ];
 
     for (const path of candidatePaths) {

package/src/agents/registry/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Agent Registry - Re-exports
+ */
+
+export { AgentRegistry, agentRegistry } from './agentRegistry';
+export type { AgentRegistration } from './agentRegistry';

package/src/agents/translator/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Translator Agent - Public exports (client-safe)
+ */
+
+// Schema exports (client-safe)
+export { TranslatorInputSchema, TranslatorOutputSchema } from './translator.schema';
+export type { TranslatorInput, TranslatorOutput } from './translator.schema';
+
+// Type exports (client-safe)
+export type { TranslationHandlerParams, TranslationHandlerResult, TranslatorMetadata } from './translator.types';
+
+// Metadata (client-safe)
+export const translatorMetadata = {
+  id: 'translator',
+  name: 'Translator Agent',
+  description: 'Translates text between languages using Gemini Flash via Genkit',
+  category: 'translation',
+  route: '/agents/translator',
+} as const;

package/src/agents/translator/translator.handler.ts

@@ -0,0 +1,97 @@
+import 'server-only';
+
+/**
+ * Translator Agent Handler - Server-only execution logic
+ * Translates text between languages using LLM providers
+ */
+
+import { generateText } from 'ai';
+import { LLMProviderFactory, extractProviderConfig } from '../../runtime/llmProviderFactory';
+import type { ExecutionContext } from '../../types/executionContext';
+import type { TranslationHandlerParams, TranslationHandlerResult } from './translator.types';
+
+const SUPPORTED_LANGUAGES = ['pt', 'en', 'es', 'fr'];
+
+/**
+ * Execute translation using configured LLM provider
+ */
+export async function executeTranslationHandler(
+  params: TranslationHandlerParams,
+  props: Record<string, string>,
+  context: ExecutionContext
+): Promise<TranslationHandlerResult> {
+  const providerConfig = extractProviderConfig(props, 'google');
+  const model = LLMProviderFactory.createLanguageModel(providerConfig);
+  const modelName = providerConfig.model || LLMProviderFactory.getDefaultModel(providerConfig.provider);
+
+  const text = params.text?.trim();
+  const sourceLanguage = params.source_language?.trim().toLowerCase();
+  const targetLanguage = params.target_language?.trim().toLowerCase();
+
+  if (!text || !sourceLanguage || !targetLanguage) {
+    throw new Error('Missing required translation parameters: text, source_language, target_language');
+  }
+
+  // Same language bypass
+  if (sourceLanguage === targetLanguage) {
+    return {
+      translated_text: text,
+      metadata: {
+        model_used: modelName,
+        provider: providerConfig.provider,
+        processing_time: 0,
+        confidence: 1,
+        supported_languages: SUPPORTED_LANGUAGES,
+        requested_languages: {
+          source: sourceLanguage,
+          target: targetLanguage,
+        },
+        prompt_used: 'Bypass: source and target languages are the same',
+      },
+    };
+  }
+
+  const template = params.promptTemplate?.trim() ||
+    `Translate the text below from {{source_language}} to {{target_language}}.
+Reply only with the translated text without additional comments.
+
+Text:
+{{text}}`;
+
+  const prompt = template
+    .replace(/{{text}}/g, text)
+    .replace(/{{source_language}}/g, sourceLanguage)
+    .replace(/{{target_language}}/g, targetLanguage)
+    .trim();
+
+  const startTime = Date.now();
+
+  context.log(`[Translator] Translating from ${sourceLanguage} to ${targetLanguage}`);
+
+  const { text: translatedText } = await generateText({
+    model,
+    prompt,
+    temperature: 0.2,
+  });
+
+  const finalText = translatedText?.trim() || '';
+  if (!finalText) {
+    throw new Error('LLM translation returned empty response');
+  }
+
+  return {
+    translated_text: finalText,
+    metadata: {
+      model_used: modelName,
+      provider: providerConfig.provider,
+      processing_time: Date.now() - startTime,
+      confidence: 0.85,
+      supported_languages: SUPPORTED_LANGUAGES,
+      requested_languages: {
+        source: sourceLanguage,
+        target: targetLanguage,
+      },
+      prompt_used: prompt,
+    },
+  };
+}

package/src/agents/translator/translator.schema.ts

@@ -0,0 +1,30 @@
+/**
+ * Translator Agent Schema - Zod validation schemas
+ * Safe for both client and server
+ */
+
+import { z } from 'zod';
+
+export const TranslatorInputSchema = z.object({
+  text: z.string().min(1).max(10000),
+  source_language: z.string().regex(/^[a-z]{2}$/),
+  target_language: z.string().regex(/^[a-z]{2}$/),
+});
+
+export const TranslatorOutputSchema = z.object({
+  translated_text: z.string(),
+  metadata: z.object({
+    model_used: z.string(),
+    processing_time: z.number(),
+    confidence: z.number(),
+    supported_languages: z.array(z.string()),
+    requested_languages: z.object({
+      source: z.string(),
+      target: z.string(),
+    }),
+    prompt_used: z.string(),
+  }),
+});
+
+export type TranslatorInput = z.infer<typeof TranslatorInputSchema>;
+export type TranslatorOutput = z.infer<typeof TranslatorOutputSchema>;

package/src/agents/translator/translator.types.ts

@@ -0,0 +1,43 @@
+/**
+ * Translator Agent Types - Shared between client and server
+ */
+
+/**
+ * Parameters for translation
+ */
+export interface TranslationHandlerParams {
+  text: string;
+  source_language: string;
+  target_language: string;
+  promptTemplate?: string;
+}
+
+/**
+ * Result from translation
+ */
+export interface TranslationHandlerResult {
+  translated_text: string;
+  metadata: {
+    model_used: string;
+    provider: string;
+    processing_time: number;
+    confidence: number;
+    supported_languages: string[];
+    requested_languages: {
+      source: string;
+      target: string;
+    };
+    prompt_used: string;
+  };
+}
+
+/**
+ * Translator agent metadata
+ */
+export interface TranslatorMetadata {
+  id: 'translator';
+  name: string;
+  description: string;
+  category: 'translation';
+  route: '/agents/translator';
+}

package/src/agents/translator/translator.yaml

@@ -0,0 +1,80 @@
+# Translator Agent - Declarative Genkit-powered translation workflow
+# Route: /agents/translator
+# Method: translator.execute
+
+agent:
+  id: translator
+  version: 1.0.0
+  protocol: beddel-declarative-protocol/v2.0
+
+metadata:
+  name: "Translator Agent"
+  description: "Translates text between languages using Gemini Flash via Genkit"
+  category: "translation"
+  route: "/agents/translator"
+
+schema:
+  input:
+    type: "object"
+    properties:
+      text:
+        type: "string"
+        minLength: 1
+        maxLength: 10000
+        description: "Original text to be translated"
+      source_language:
+        type: "string"
+        pattern: "^[a-z]{2}$"
+        description: "Source language (ISO-639-1, e.g., pt, en)"
+      target_language:
+        type: "string"
+        pattern: "^[a-z]{2}$"
+        description: "Target language (ISO-639-1, e.g., en, es)"
+    required: ["text", "source_language", "target_language"]
+
+  output:
+    type: "object"
+    properties:
+      translated_text:
+        type: "string"
+      metadata:
+        type: "object"
+        properties:
+          model_used:
+            type: "string"
+          processing_time:
+            type: "number"
+          confidence:
+            type: "number"
+          supported_languages:
+            type: "array"
+            items:
+              type: "string"
+          requested_languages:
+            type: "object"
+            properties:
+              source:
+                type: "string"
+              target:
+                type: "string"
+            required: ["source", "target"]
+          prompt_used:
+            type: "string"
+        required:
+          [
+            "model_used",
+            "processing_time",
+            "confidence",
+            "supported_languages",
+            "requested_languages",
+            "prompt_used",
+          ]
+    required: ["translated_text", "metadata"]
+
+logic:
+  workflow:
+    - name: "translate"
+      type: "genkit-translation"
+      action:
+        type: "translate"
+        result: "translationResult"

package/src/client/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Client Module - Safe exports for client-side usage
+ *
+ * This module exports only types and metadata that are safe for client-side usage.
+ * It does NOT export any handlers, runtime logic, or server-only code.
+ *
+ * IMPORTANT: Never import from '../agents' index as it includes server-only registry!
+ * Import directly from individual agent folders instead.
+ */
+
+// Re-export all shared types and utilities
+export * from '../shared';
+
+// Re-export client-specific types
+export * from './types';
+
+// Agent metadata exports (client-safe) - import directly from agent folders
+export { jokerMetadata } from '../agents/joker';
+export { translatorMetadata } from '../agents/translator';
+export { imageMetadata } from '../agents/image';
+export { mcpToolMetadata } from '../agents/mcp-tool';
+export { geminiVectorizeMetadata } from '../agents/gemini-vectorize';
+export { chromadbMetadata } from '../agents/chromadb';
+export { gitmcpMetadata } from '../agents/gitmcp';
+export { ragMetadata } from '../agents/rag';
+export { chatMetadata } from '../agents/chat';
+
+// Schema exports (client-safe - for validation)
+export { JokerInputSchema, JokerOutputSchema } from '../agents/joker';
+export { TranslatorInputSchema, TranslatorOutputSchema } from '../agents/translator';
+export { ImageInputSchema, ImageOutputSchema } from '../agents/image';
+export { McpToolInputSchema, McpToolOutputSchema } from '../agents/mcp-tool';
+export { GeminiVectorizeInputSchema, GeminiVectorizeOutputSchema } from '../agents/gemini-vectorize';
+export { ChromaDBInputSchema, ChromaDBOutputSchema } from '../agents/chromadb';
+export { GitMcpInputSchema, GitMcpOutputSchema } from '../agents/gitmcp';
+export { RagInputSchema, RagOutputSchema } from '../agents/rag';
+export { ChatInputSchema, ChatOutputSchema } from '../agents/chat';
+
+/**
+ * All agent metadata for UI display
+ * Defined here to avoid importing from agents/index.ts which includes server-only registry
+ */
+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/client/types.ts

@@ -0,0 +1,38 @@
+/**
+ * Client Types - Safe type re-exports for client-side usage
+ * These types contain no sensitive data or server-only logic
+ */
+
+// Re-export all shared types
+export type {
+  AgentMetadata,
+  AgentResponse,
+  ExecutionStep,
+  WorkflowStepType,
+  AgentCategory,
+} from '../shared/types/agent.types';
+
+export type {
+  ExecutionResult,
+  ExecutionStatus,
+  ExecutionSummary,
+  ExecutionLogEntry,
+} from '../shared/types/execution.types';
+
+export type {
+  SchemaProperty,
+  AgentSchemaDefinition,
+  ValidationResult,
+  ValidationError,
+} from '../shared/types/schema.types';
+
+// Agent-specific type exports (client-safe)
+export type { JokerInput, JokerOutput, JokeHandlerParams, JokeHandlerResult } from '../agents/joker';
+export type { TranslatorInput, TranslatorOutput, TranslationHandlerParams, TranslationHandlerResult } from '../agents/translator';
+export type { ImageInput, ImageOutput, ImageStyle, ImageHandlerParams, ImageHandlerResult } from '../agents/image';
+export type { McpToolInput, McpToolOutput, McpToolHandlerParams, McpToolHandlerResult } from '../agents/mcp-tool';
+export type { GeminiVectorizeInput, GeminiVectorizeOutput, VectorizeHandlerParams, VectorizeHandlerResult } from '../agents/gemini-vectorize';
+export type { ChromaDBInput, ChromaDBOutput, ChromaDBHandlerParams, ChromaDBHandlerResult, ChromaDBSearchResult } from '../agents/chromadb';
+export type { GitMcpInput, GitMcpOutput, GitMcpHandlerParams, GitMcpHandlerResult } from '../agents/gitmcp';
+export type { RagInput, RagOutput, RagHandlerParams, RagHandlerResult, ConversationMessage } from '../agents/rag';
+export type { ChatInput, ChatOutput, ChatHandlerParams, ChatHandlerResult } from '../agents/chat';