beddel 0.2.1 → 0.2.3

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

@@ -0,0 +1,33 @@
+/**
+ * MCP Tool Agent Types - Shared between client and server
+ */
+
+/**
+ * Parameters for MCP tool invocation
+ */
+export interface McpToolHandlerParams {
+  server_url: string;
+  tool_name: string;
+  tool_arguments?: Record<string, unknown>;
+}
+
+/**
+ * Result from MCP tool invocation
+ */
+export interface McpToolHandlerResult {
+  success: boolean;
+  data?: string;
+  tool_names?: string[];
+  error?: string;
+}
+
+/**
+ * MCP Tool agent metadata
+ */
+export interface McpToolMetadata {
+  id: 'mcp-tool';
+  name: string;
+  description: string;
+  category: 'integration';
+  route: '/agents/mcp-tool';
+}

package/src/agents/mcp-tool/mcp-tool.yaml

@@ -0,0 +1,71 @@
+# MCP Tool Agent - Native Builtin Agent for Beddel Runtime
+# Route: /agents/mcp-tool
+# Method: mcp-tool.execute
+
+agent:
+  id: mcp-tool
+  version: 1.0.0
+  protocol: beddel-declarative-protocol/v2.0
+
+metadata:
+  name: "MCP Tool Agent"
+  description: "Generic agent for calling MCP server tools via SSE transport"
+  category: "integration"
+  route: "/agents/mcp-tool"
+
+schema:
+  input:
+    type: "object"
+    properties:
+      server_url:
+        type: "string"
+        description: "MCP server SSE endpoint URL"
+      tool_name:
+        type: "string"
+        description: "Name of the MCP tool to invoke (use 'list_tools' to discover available tools)"
+      tool_arguments:
+        type: "object"
+        description: "Arguments to pass to the tool"
+    required: ["server_url", "tool_name"]
+
+  output:
+    type: "object"
+    properties:
+      success:
+        type: "boolean"
+      data:
+        type: "string"
+      tool_names:
+        type: "array"
+        items:
+          type: "string"
+      error:
+        type: "string"
+    required: ["success"]
+
+logic:
+  workflow:
+    - name: "call-mcp-tool"
+      type: "mcp-tool"
+      action:
+        server_url: "$input.server_url"
+        tool_name: "$input.tool_name"
+        tool_arguments: "$input.tool_arguments"
+        result: "mcpResult"
+
+    - name: "deliver-response"
+      type: "output-generator"
+      action:
+        type: "generate"
+        output:
+          success: "$mcpResult.success"
+          data: "$mcpResult.data"
+          tool_names: "$mcpResult.toolNames"
+          error: "$mcpResult.error"
+
+output:
+  schema:
+    success: "$mcpResult.success"
+    data: "$mcpResult.data"
+    tool_names: "$mcpResult.toolNames"
+    error: "$mcpResult.error"

package/src/agents/rag/index.ts

@@ -0,0 +1,20 @@
+/**
+ * RAG Agent - Public exports (client-safe)
+ */
+
+// Schema exports (client-safe)
+export { RagInputSchema, RagOutputSchema } from './rag.schema';
+export type { RagInput, RagOutput } from './rag.schema';
+
+// Type exports (client-safe)
+export type { RagHandlerParams, RagHandlerResult, ConversationMessage, RagMetadata } from './rag.types';
+
+// Metadata (client-safe)
+export const ragMetadata = {
+  id: 'rag',
+  name: 'RAG Intelligence Agent',
+  description: 'Generates natural language answers based on provided context using Gemini',
+  category: 'intelligence',
+  route: '/agents/rag',
+  tags: ['rag', 'gemini', 'qa', 'generation'],
+} as const;

package/src/agents/rag/rag.handler.ts

@@ -0,0 +1,119 @@
+import 'server-only';
+
+/**
+ * RAG Agent Handler - Server-only execution logic
+ * Generates natural language answers based on provided context using Gemini
+ * Supports both RAG mode (with documents) and simple chat mode (conversation only)
+ */
+
+import { generateText } from 'ai';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import type { ExecutionContext } from '../../types/executionContext';
+import type { RagHandlerParams, RagHandlerResult, ConversationMessage } from './rag.types';
+
+const GEMINI_RAG_MODEL = 'models/gemini-2.0-flash-exp';
+
+/**
+ * Build prompt for simple chat mode (no documents)
+ */
+function buildSimpleChatPrompt(query: string, history?: ConversationMessage[]): string {
+  const conversationContext = history?.length
+    ? `CONVERSATION HISTORY:\n${history.map((m) => `${m.role.toUpperCase()}: ${m.content}`).join('\n')}\n\n`
+    : '';
+
+  return `You are a helpful, friendly assistant.
+
+${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:`;
+}
+
+/**
+ * Build prompt for RAG mode (with documents)
+ */
+function buildRagPrompt(query: string, ragContext: string, history?: ConversationMessage[]): string {
+  const conversationContext = history?.length
+    ? `CONVERSATION HISTORY:\n${history.map((m) => `${m.role.toUpperCase()}: ${m.content}`).join('\n')}\n\n`
+    : '';
+
+  return `You are a helpful and expert assistant for the Beddel Protocol.
+
+${conversationContext}CONTEXT INFORMATION:
+${ragContext}
+
+USER QUESTION:
+${query}
+
+INSTRUCTIONS:
+1. Answer the user's question based on the CONTEXT INFORMATION provided above.
+2. Consider the CONVERSATION HISTORY for context continuity if available.
+3. If the context does not contain the answer, politely state that you don't have enough information in the documentation to answer.
+4. Be concise but comprehensive.
+
+ANSWER:`;
+}
+
+/**
+ * Execute RAG answer generation
+ */
+export async function executeRagHandler(
+  params: RagHandlerParams,
+  props: Record<string, string>,
+  context: ExecutionContext
+): Promise<RagHandlerResult> {
+  const apiKey = props?.gemini_api_key?.trim();
+  if (!apiKey) {
+    throw new Error('Missing required prop: gemini_api_key');
+  }
+
+  const { query, history, mode = 'rag' } = params;
+  const ragContext = params.context || params.documents;
+
+  if (!query) {
+    throw new Error('Missing required RAG input: query');
+  }
+
+  // Simple mode doesn't require documents
+  if (mode === 'rag' && !ragContext) {
+    throw new Error('Missing required RAG input: context or documents');
+  }
+
+  const google = createGoogleGenerativeAI({ apiKey });
+  const model = google(GEMINI_RAG_MODEL);
+
+  const prompt = mode === 'simple'
+    ? buildSimpleChatPrompt(query, history)
+    : buildRagPrompt(query, ragContext!, history);
+
+  try {
+    context.log(`[RAG:${mode}] Generating answer for: "${query.substring(0, 50)}..."`);
+
+    const { text } = await generateText({
+      model,
+      prompt,
+      temperature: mode === 'simple' ? 0.7 : 0.3,
+    });
+
+    return {
+      response: text,
+      answer: text,
+      timestamp: new Date().toISOString(),
+    };
+
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    context.log(`[RAG] Error: ${message}`);
+    return {
+      response: '',
+      answer: '',
+      timestamp: new Date().toISOString(),
+      error: message,
+    };
+  }
+}

package/src/agents/rag/rag.schema.ts

@@ -0,0 +1,26 @@
+/**
+ * RAG Agent Schema - Zod validation schemas
+ * Safe for both client and server
+ */
+
+import { z } from 'zod';
+
+export const RagInputSchema = z.object({
+  query: z.string().min(1),
+  context: z.string().optional(),
+  documents: z.string().optional(),
+  history: z.array(z.object({
+    role: z.enum(['user', 'assistant', 'system']),
+    content: z.string(),
+  })).optional(),
+});
+
+export const RagOutputSchema = z.object({
+  response: z.string(),
+  answer: z.string().optional(),
+  timestamp: z.string().optional(),
+  error: z.string().optional(),
+});
+
+export type RagInput = z.infer<typeof RagInputSchema>;
+export type RagOutput = z.infer<typeof RagOutputSchema>;

package/src/agents/rag/rag.types.ts

@@ -0,0 +1,51 @@
+/**
+ * RAG Agent Types - Shared between client and server
+ */
+
+/**
+ * Conversation message
+ */
+export interface ConversationMessage {
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+}
+
+/**
+ * RAG execution mode
+ * - 'rag': Uses provided documents/context for answer generation
+ * - 'simple': Direct LLM chat without document context
+ */
+export type RagMode = 'rag' | 'simple';
+
+/**
+ * Parameters for RAG answer generation
+ */
+export interface RagHandlerParams {
+  query: string;
+  context?: string;
+  documents?: string;
+  history?: ConversationMessage[];
+  mode?: RagMode;
+}
+
+/**
+ * Result from RAG answer generation
+ */
+export interface RagHandlerResult {
+  response: string;
+  answer: string;
+  timestamp: string;
+  error?: string;
+}
+
+/**
+ * RAG agent metadata
+ */
+export interface RagMetadata {
+  id: 'rag';
+  name: string;
+  description: string;
+  category: 'intelligence';
+  route: '/agents/rag';
+  tags: string[];
+}

package/src/agents/rag/rag.yaml

@@ -0,0 +1,89 @@
+# RAG Agent - Native Builtin Agent for Beddel Runtime
+# Route: /agents/rag
+# Method: rag.execute
+
+agent:
+  id: rag
+  version: 1.0.0
+  protocol: beddel-declarative-protocol/v2.0
+
+metadata:
+  name: "RAG Intelligence Agent"
+  description: "Generates natural language answers based on provided context using Gemini"
+  category: "intelligence"
+  route: "/agents/rag"
+  tags:
+    - "rag"
+    - "gemini"
+    - "qa"
+    - "generation"
+
+schema:
+  input:
+    type: "object"
+    properties:
+      query:
+        type: "string"
+        description: "User question to answer"
+      context:
+        type: "string"
+        description: "Retrieved documentation or context for answering"
+      documents:
+        type: "string"
+        description: "Alternative to context - retrieved documents"
+      history:
+        type: "array"
+        items:
+          type: "object"
+          properties:
+            role:
+              type: "string"
+              enum: ["user", "assistant", "system"]
+            content:
+              type: "string"
+        description: "Conversation history for context continuity"
+    required: ["query"]
+
+  output:
+    type: "object"
+    properties:
+      response:
+        type: "string"
+        description: "Generated answer"
+      answer:
+        type: "string"
+        description: "Alias for response"
+      timestamp:
+        type: "string"
+        description: "ISO timestamp of generation"
+      error:
+        type: "string"
+    required: ["response"]
+
+logic:
+  workflow:
+    - name: "generate-answer"
+      type: "rag"
+      action:
+        query: "$input.query"
+        context: "$input.context"
+        documents: "$input.documents"
+        history: "$input.history"
+        result: "ragResult"
+
+    - name: "deliver-response"
+      type: "output-generator"
+      action:
+        type: "generate"
+        output:
+          response: "$ragResult.response"
+          answer: "$ragResult.answer"
+          timestamp: "$ragResult.timestamp"
+          error: "$ragResult.error"
+
+output:
+  schema:
+    response: "$ragResult.response"
+    answer: "$ragResult.answer"
+    timestamp: "$ragResult.timestamp"
+    error: "$ragResult.error"

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,18 @@ 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 Chat Agent (Orchestrator)
+      this.registerChatAgent();
     } catch (error) {
       console.error("Failed to register built-in agents:", error);
     }
@@ -221,7 +233,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 +259,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 +283,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 +302,150 @@ 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 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
    */

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;