beddel 0.2.3 → 0.3.0

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[];
+}

package/src/agents/llm/llm.yaml

@@ -0,0 +1,87 @@
+# LLM Agent - Native Builtin Agent for Beddel Runtime
+# Route: /agents/llm
+# Method: llm.execute
+
+agent:
+  id: llm
+  version: 1.0.0
+  protocol: beddel-declarative-protocol/v2.0
+
+metadata:
+  name: "LLM Chat Agent"
+  description: "Direct LLM interaction with conversation history support (non-RAG)"
+  category: "intelligence"
+  route: "/agents/llm"
+  tags:
+    - "llm"
+    - "chat"
+    - "gemini"
+    - "conversation"
+
+schema:
+  input:
+    type: "object"
+    properties:
+      query:
+        type: "string"
+        description: "User message to respond to"
+      history:
+        type: "array"
+        items:
+          type: "object"
+          properties:
+            role:
+              type: "string"
+              enum: ["user", "assistant", "system"]
+            content:
+              type: "string"
+        description: "Conversation history for context continuity"
+      temperature:
+        type: "number"
+        minimum: 0
+        maximum: 2
+        default: 0.7
+        description: "LLM temperature for response generation"
+      systemPrompt:
+        type: "string"
+        description: "Custom system prompt for the LLM"
+    required: ["query"]
+
+  output:
+    type: "object"
+    properties:
+      response:
+        type: "string"
+        description: "Generated response"
+      timestamp:
+        type: "string"
+        description: "ISO timestamp of generation"
+      error:
+        type: "string"
+    required: ["response"]
+
+logic:
+  workflow:
+    - name: "generate-response"
+      type: "llm"
+      action:
+        query: "$input.query"
+        history: "$input.history"
+        temperature: "$input.temperature"
+        systemPrompt: "$input.systemPrompt"
+        result: "llmResult"
+
+    - name: "deliver-response"
+      type: "output-generator"
+      action:
+        type: "generate"
+        output:
+          response: "$llmResult.response"
+          timestamp: "$llmResult.timestamp"
+          error: "$llmResult.error"
+
+output:
+  schema:
+    response: "$llmResult.response"
+    timestamp: "$llmResult.timestamp"
+    error: "$llmResult.error"

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

@@ -2,42 +2,26 @@ 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)
+ * Generates natural language answers based on provided document context using LLM
+ *
+ * Note: RAG = Retrieval-Augmented Generation
+ * This agent ALWAYS requires document context. For direct LLM chat without
+ * documents, use the LLM agent instead.
  */
 
 import { generateText } from 'ai';
-import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import { LLMProviderFactory, extractProviderConfig } from '../../runtime/llmProviderFactory';
 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 {
+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`
     : '';
@@ -61,43 +45,36 @@ ANSWER:`;
 
 /**
  * Execute RAG answer generation
+ * Requires document context - for direct LLM chat, use the LLM agent
  */
 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 providerConfig = extractProviderConfig(props, 'google');
+  const model = LLMProviderFactory.createLanguageModel(providerConfig);
 
-  const { query, history, mode = 'rag' } = params;
+  const { query, history } = 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');
+  if (!ragContext) {
+    throw new Error('Missing required RAG input: context or documents. For direct LLM chat without documents, use the LLM agent instead.');
   }
 
-  const google = createGoogleGenerativeAI({ apiKey });
-  const model = google(GEMINI_RAG_MODEL);
-
-  const prompt = mode === 'simple'
-    ? buildSimpleChatPrompt(query, history)
-    : buildRagPrompt(query, ragContext!, history);
+  const prompt = buildRagPrompt(query, ragContext, history);
 
   try {
-    context.log(`[RAG:${mode}] Generating answer for: "${query.substring(0, 50)}..."`);
+    context.log(`[RAG] Generating answer for: "${query.substring(0, 50)}..."`);
 
     const { text } = await generateText({
       model,
       prompt,
-      temperature: mode === 'simple' ? 0.7 : 0.3,
+      temperature: 0.3,
     });
 
     return {
@@ -105,7 +82,6 @@ export async function executeRagHandler(
       answer: text,
       timestamp: new Date().toISOString(),
     };
-
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);
     context.log(`[RAG] Error: ${message}`);

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

@@ -1,5 +1,6 @@
 /**
  * RAG Agent Types - Shared between client and server
+ * RAG = Retrieval-Augmented Generation (always requires document context)
  */
 
 /**
@@ -10,22 +11,15 @@ export interface ConversationMessage {
   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
+ * Note: context or documents is REQUIRED - RAG always needs document context
  */
 export interface RagHandlerParams {
   query: string;
   context?: string;
   documents?: string;
   history?: ConversationMessage[];
-  mode?: RagMode;
 }
 
 /**

package/src/agents/registry/agentRegistry.ts

@@ -220,6 +220,8 @@ export class AgentRegistry {
       this.registerGitMcpAgent();
       // Register RAG Agent
       this.registerRagAgent();
+      // Register LLM Agent
+      this.registerLlmAgent();
       // Register Chat Agent (Orchestrator)
       this.registerChatAgent();
     } catch (error) {
@@ -422,6 +424,30 @@ export class AgentRegistry {
     }
   }
 
+  /**
+   * 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)
    */
@@ -519,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/translator/translator.handler.ts

@@ -2,29 +2,27 @@ import 'server-only';
 
 /**
  * Translator Agent Handler - Server-only execution logic
- * Translates text between languages using Gemini Flash
+ * Translates text between languages using LLM providers
  */
 
 import { generateText } from 'ai';
-import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import { LLMProviderFactory, extractProviderConfig } from '../../runtime/llmProviderFactory';
 import type { ExecutionContext } from '../../types/executionContext';
 import type { TranslationHandlerParams, TranslationHandlerResult } from './translator.types';
 
-const GEMINI_MODEL = 'models/gemini-2.5-flash';
 const SUPPORTED_LANGUAGES = ['pt', 'en', 'es', 'fr'];
 
 /**
- * Execute translation using Gemini Flash
+ * Execute translation using configured LLM provider
  */
 export async function executeTranslationHandler(
   params: TranslationHandlerParams,
   props: Record<string, string>,
   context: ExecutionContext
 ): Promise<TranslationHandlerResult> {
-  const apiKey = props?.gemini_api_key?.trim();
-  if (!apiKey) {
-    throw new Error('Missing required prop: gemini_api_key');
-  }
+  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();
@@ -39,7 +37,8 @@ export async function executeTranslationHandler(
     return {
       translated_text: text,
       metadata: {
-        model_used: GEMINI_MODEL,
+        model_used: modelName,
+        provider: providerConfig.provider,
         processing_time: 0,
         confidence: 1,
         supported_languages: SUPPORTED_LANGUAGES,
@@ -65,8 +64,6 @@ Text:
     .replace(/{{target_language}}/g, targetLanguage)
     .trim();
 
-  const google = createGoogleGenerativeAI({ apiKey });
-  const model = google(GEMINI_MODEL);
   const startTime = Date.now();
 
   context.log(`[Translator] Translating from ${sourceLanguage} to ${targetLanguage}`);
@@ -79,13 +76,14 @@ Text:
 
   const finalText = translatedText?.trim() || '';
   if (!finalText) {
-    throw new Error('Gemini Flash translation returned empty response');
+    throw new Error('LLM translation returned empty response');
   }
 
   return {
     translated_text: finalText,
     metadata: {
-      model_used: GEMINI_MODEL,
+      model_used: modelName,
+      provider: providerConfig.provider,
       processing_time: Date.now() - startTime,
       confidence: 0.85,
       supported_languages: SUPPORTED_LANGUAGES,

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

@@ -19,6 +19,7 @@ export interface TranslationHandlerResult {
   translated_text: string;
   metadata: {
     model_used: string;
+    provider: string;
     processing_time: number;
     confidence: number;
     supported_languages: string[];

package/src/index.ts

@@ -164,5 +164,13 @@ export { chatMetadata } from "./agents/chat";
 // RAG types (client-safe)
 export type { ConversationMessage } from "./agents/rag/rag.types";
 
+// LLM agent exports (client-safe)
+export type {
+  LlmHandlerParams,
+  LlmHandlerResult,
+  LlmMetadata,
+} from "./agents/llm/llm.types";
+export { llmMetadata } from "./agents/llm";
+
 // Server/runtime exports
 export * as Server from "./server";

package/src/runtime/declarativeAgentRuntime.ts

@@ -239,18 +239,23 @@ export class DeclarativeAgentInterpreter {
     switch (step.type) {
       case 'output-generator':
         return this.executeOutputGenerator(step, variables, options);
+      // Preferred step types
+      case 'joke':
       case 'genkit-joke':
-        return this.executeGenkitJoke(step, variables, options);
+        return this.executeJoke(step, variables, options);
+      case 'translation':
       case 'genkit-translation':
-        return this.executeGenkitTranslation(step, variables, options);
+        return this.executeTranslation(step, variables, options);
+      case 'image':
       case 'genkit-image':
-        return this.executeGenkitImage(step, variables, options);
+        return this.executeImage(step, variables, options);
+      case 'vectorize':
+      case 'gemini-vectorize':
+        return this.executeVectorize(step, variables, options);
       case 'custom-action':
         return this.executeCustomAction(step, variables, options);
       case 'mcp-tool':
         return this.executeMcpTool(step, variables, options);
-      case 'gemini-vectorize':
-        return this.executeGeminiVectorize(step, variables, options);
       case 'chromadb':
         return this.executeChromaDB(step, variables, options);
       case 'gitmcp':
@@ -309,7 +314,7 @@ export class DeclarativeAgentInterpreter {
   // Delegated Handlers - Using extracted agent handlers
   // ============================================================================
 
-  private async executeGenkitJoke(
+  private async executeJoke(
     step: any,
     variables: Map<string, any>,
     options: YamlAgentInterpreterOptions
@@ -337,7 +342,7 @@ export class DeclarativeAgentInterpreter {
     return result;
   }
 
-  private async executeGenkitTranslation(
+  private async executeTranslation(
     step: any,
     variables: Map<string, any>,
     options: YamlAgentInterpreterOptions
@@ -369,7 +374,7 @@ export class DeclarativeAgentInterpreter {
     return result;
   }
 
-  private async executeGenkitImage(
+  private async executeImage(
     step: any,
     variables: Map<string, any>,
     options: YamlAgentInterpreterOptions
@@ -454,7 +459,7 @@ export class DeclarativeAgentInterpreter {
     return result;
   }
 
-  private async executeGeminiVectorize(
+  private async executeVectorize(
     step: any,
     variables: Map<string, any>,
     options: YamlAgentInterpreterOptions

package/src/runtime/index.ts

@@ -23,9 +23,14 @@ export {
   executeChromaDBHandler,
   executeGitMcpHandler,
   executeRagHandler,
+  executeLlmHandler,
   executeChatHandler,
 } from './workflowExecutor';
 
+// LLM Provider Factory exports
+export { LLMProviderFactory, extractProviderConfig } from './llmProviderFactory';
+export type { LLMProviderType, LLMProviderConfig } from './llmProviderFactory';
+
 // Schema compiler exports
 export { DeclarativeSchemaCompiler, DeclarativeSchemaValidationError } from './schemaCompiler';
 export type { DeclarativeSchemaPhase } from './schemaCompiler';

package/src/runtime/llmProviderFactory.ts

@@ -0,0 +1,145 @@
+import 'server-only';
+
+/**
+ * LLM Provider Factory - Centralized provider creation and configuration
+ * 
+ * Provides a single point of configuration for LLM providers, enabling:
+ * - Centralized API key validation
+ * - Easy provider switching (Google, OpenAI, Anthropic, etc.)
+ * - Retry/fallback logic between providers
+ * - Consistent error handling
+ */
+
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import type { LanguageModel } from 'ai';
+
+/**
+ * Supported LLM provider types
+ */
+export type LLMProviderType = 'google' | 'openai' | 'anthropic';
+
+/**
+ * Provider configuration
+ */
+export interface LLMProviderConfig {
+  provider: LLMProviderType;
+  apiKey: string;
+  model?: string;
+  baseURL?: string;
+}
+
+/**
+ * Default models for each provider
+ */
+const DEFAULT_MODELS: Record<LLMProviderType, string> = {
+  google: 'models/gemini-2.5-flash',
+  openai: 'gpt-4-turbo',
+  anthropic: 'claude-3-5-sonnet-20241022',
+};
+
+/**
+ * LLM Provider Factory
+ * 
+ * Centralizes provider creation and configuration across all agents
+ */
+export class LLMProviderFactory {
+  /**
+   * Create a language model instance
+   */
+  static createLanguageModel(config: LLMProviderConfig): LanguageModel {
+    this.validateConfig(config);
+
+    switch (config.provider) {
+      case 'google':
+        return this.createGoogleProvider(config);
+      case 'openai':
+        throw new Error('OpenAI provider not yet implemented');
+      case 'anthropic':
+        throw new Error('Anthropic provider not yet implemented');
+      default:
+        throw new Error(`Unsupported provider: ${config.provider}`);
+    }
+  }
+
+  /**
+   * Create Google Generative AI provider
+   */
+  private static createGoogleProvider(config: LLMProviderConfig): LanguageModel {
+    const google = createGoogleGenerativeAI({ 
+      apiKey: config.apiKey,
+      ...(config.baseURL && { baseURL: config.baseURL }),
+    });
+    
+    const model = config.model || DEFAULT_MODELS.google;
+    return google(model);
+  }
+
+  /**
+   * Validate provider configuration
+   */
+  private static validateConfig(config: LLMProviderConfig): void {
+    if (!config.apiKey?.trim()) {
+      throw new Error(`Missing API key for provider: ${config.provider}`);
+    }
+
+    if (!config.provider) {
+      throw new Error('Provider type is required');
+    }
+  }
+
+  /**
+   * Get default model for a provider
+   */
+  static getDefaultModel(provider: LLMProviderType): string {
+    return DEFAULT_MODELS[provider];
+  }
+
+  /**
+   * Validate API key format (basic check)
+   */
+  static validateApiKey(apiKey: string, provider: LLMProviderType): boolean {
+    if (!apiKey?.trim()) {
+      return false;
+    }
+
+    // Provider-specific validation can be added here
+    switch (provider) {
+      case 'google':
+        // Google API keys typically start with 'AIza'
+        return apiKey.startsWith('AIza') || apiKey.length > 20;
+      case 'openai':
+        return apiKey.startsWith('sk-');
+      case 'anthropic':
+        return apiKey.startsWith('sk-ant-');
+      default:
+        return true;
+    }
+  }
+}
+
+/**
+ * Helper function to extract provider config from props
+ */
+export function extractProviderConfig(
+  props: Record<string, string>,
+  defaultProvider: LLMProviderType = 'google'
+): LLMProviderConfig {
+  const apiKey = props.gemini_api_key || props.openai_api_key || props.anthropic_api_key;
+  
+  if (!apiKey) {
+    throw new Error('Missing required prop: API key (gemini_api_key, openai_api_key, or anthropic_api_key)');
+  }
+
+  // Determine provider from key name
+  let provider: LLMProviderType = defaultProvider;
+  if (props.openai_api_key) provider = 'openai';
+  if (props.anthropic_api_key) provider = 'anthropic';
+  if (props.gemini_api_key) provider = 'google';
+
+  return {
+    provider,
+    apiKey: apiKey.trim(),
+    model: props.model,
+    baseURL: props.base_url,
+  };
+}