beddel 0.2.2 → 0.3.0

package/src/runtime/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Runtime Module - Server-only exports
+ *
+ * This module provides the declarative agent runtime and workflow execution.
+ * All exports in this module are server-only.
+ */
+
+// Main runtime exports
+export { DeclarativeAgentInterpreter, declarativeInterpreter } from './declarativeAgentRuntime';
+export type { YamlAgentDefinition, YamlAgentInterpreterOptions, YamlExecutionResult } from './declarativeAgentRuntime';
+
+// Workflow executor exports
+export {
+  executeWorkflowStep,
+  getAvailableStepTypes,
+  isStepTypeSupported,
+  // Individual handlers for direct use
+  executeJokeHandler,
+  executeTranslationHandler,
+  executeImageHandler,
+  executeMcpToolHandler,
+  executeVectorizeHandler,
+  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,
+  };
+}

package/src/runtime/workflowExecutor.ts

@@ -0,0 +1,107 @@
+import 'server-only';
+
+/**
+ * Workflow Executor - Server-only workflow step execution
+ * Delegates to individual agent handlers based on step type
+ */
+
+import type { ExecutionContext } from '../types/executionContext';
+import type { WorkflowStepType } from '../shared/types/agent.types';
+import { LEGACY_STEP_TYPE_MAP } from '../shared/types/agent.types';
+
+// Import handlers from each agent
+import { executeJokeHandler } from '../agents/joker/joker.handler';
+import { executeTranslationHandler } from '../agents/translator/translator.handler';
+import { executeImageHandler } from '../agents/image/image.handler';
+import { executeMcpToolHandler } from '../agents/mcp-tool/mcp-tool.handler';
+import { executeVectorizeHandler } from '../agents/gemini-vectorize/gemini-vectorize.handler';
+import { executeChromaDBHandler } from '../agents/chromadb/chromadb.handler';
+import { executeGitMcpHandler } from '../agents/gitmcp/gitmcp.handler';
+import { executeRagHandler } from '../agents/rag/rag.handler';
+import { executeLlmHandler } from '../agents/llm/llm.handler';
+import { executeChatHandler } from '../agents/chat/chat.handler';
+
+/**
+ * Handler function type - uses any for params to allow flexible handler signatures
+ */
+type HandlerFunction = (
+  params: any,
+  props: Record<string, string>,
+  context: ExecutionContext
+) => Promise<unknown>;
+
+/**
+ * Map of workflow step types to their handlers
+ * Preferred step type names only - legacy names resolved via LEGACY_STEP_TYPE_MAP
+ */
+const handlerMap: Record<string, HandlerFunction> = {
+  'joke': executeJokeHandler,
+  'translation': executeTranslationHandler,
+  'image': executeImageHandler,
+  'mcp-tool': executeMcpToolHandler,
+  'vectorize': executeVectorizeHandler,
+  'chromadb': executeChromaDBHandler,
+  'gitmcp': executeGitMcpHandler,
+  'rag': executeRagHandler,
+  'llm': executeLlmHandler,
+  'chat': executeChatHandler,
+};
+
+/**
+ * Resolve step type, handling legacy names with deprecation warning
+ */
+function resolveStepType(stepType: string, context: ExecutionContext): string {
+  if (stepType in LEGACY_STEP_TYPE_MAP) {
+    const preferred = LEGACY_STEP_TYPE_MAP[stepType];
+    context.log(
+      `[DEPRECATION WARNING] Step type '${stepType}' is deprecated. Use '${preferred}' instead.`
+    );
+    return preferred;
+  }
+  return stepType;
+}
+
+/**
+ * Execute a workflow step by delegating to the appropriate handler
+ */
+export async function executeWorkflowStep(
+  stepType: WorkflowStepType | string,
+  params: Record<string, unknown>,
+  props: Record<string, string>,
+  context: ExecutionContext
+): Promise<unknown> {
+  const resolvedType = resolveStepType(stepType, context);
+  const handler = handlerMap[resolvedType];
+  if (!handler) {
+    throw new Error(`Unknown workflow step type: ${stepType}`);
+  }
+  return handler(params, props, context);
+}
+
+/**
+ * Get all available workflow step types
+ */
+export function getAvailableStepTypes(): string[] {
+  return Object.keys(handlerMap);
+}
+
+/**
+ * Check if a step type is supported (including legacy names)
+ */
+export function isStepTypeSupported(stepType: string): boolean {
+  return stepType in handlerMap || stepType in LEGACY_STEP_TYPE_MAP;
+}
+
+// Export individual handlers for direct use
+export {
+  executeJokeHandler,
+  executeTranslationHandler,
+  executeImageHandler,
+  executeMcpToolHandler,
+  executeVectorizeHandler,
+  executeChromaDBHandler,
+  executeGitMcpHandler,
+  executeRagHandler,
+  executeLlmHandler,
+  executeChatHandler,
+};

package/src/server/api/graphql.ts

@@ -4,7 +4,7 @@
 
 import { GraphQLError, GraphQLScalarType, Kind, type ValueNode } from "graphql";
 import { createSchema, createYoga } from "graphql-yoga";
-import { agentRegistry } from "../../agents/agentRegistry";
+import { agentRegistry } from "../../agents/registry";
 import {
   getClientByApiKey,
   getEndpointByName,

package/src/server/index.ts

@@ -2,5 +2,5 @@ export * from "./types";
 export * from "./errors";
 export * from "./kvStore";
 export * from "./runtimeSecurity";
-export { agentRegistry } from "../agents/agentRegistry";
-export type { AgentRegistration } from "../agents/agentRegistry";
+export { agentRegistry } from "../agents/registry";
+export type { AgentRegistration } from "../agents/registry";

package/src/shared/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared Module - Client-safe types and utilities
+ * This module can be safely imported in both client and server environments
+ */
+
+export * from './types';
+export * from './utils';

package/src/shared/types/agent.types.ts

@@ -0,0 +1,100 @@
+/**
+ * Shared Agent Types - Safe for client and server
+ * These types contain no sensitive data and can be used in both environments
+ */
+
+/**
+ * Agent metadata - safe for client display
+ */
+export interface AgentMetadata {
+  id: string;
+  name: string;
+  description: string;
+  category: string;
+  route: string;
+  tags?: string[];
+}
+
+/**
+ * Generic agent response wrapper
+ */
+export interface AgentResponse<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  timestamp?: string;
+}
+
+/**
+ * Execution step tracking for workflow visualization
+ */
+export interface ExecutionStep {
+  agent: string;
+  action: string;
+  status: 'running' | 'success' | 'error';
+  startTime: number;
+  endTime?: number;
+  duration?: number;
+  input?: Record<string, unknown>;
+  output?: Record<string, unknown>;
+  error?: string;
+  description?: string;
+  phase?: 'orchestration' | 'vectorization' | 'storage' | 'retrieval' | 'ingestion' | 'generation';
+}
+
+/**
+ * Workflow step types supported by the runtime
+ *
+ * PREFERRED: Use the English step type names (joke, translation, image, vectorize)
+ *
+ * DEPRECATED: The following legacy names are supported for backward compatibility
+ * but will be removed in a future major version:
+ * - genkit-joke → use 'joke'
+ * - genkit-translation → use 'translation'
+ * - genkit-image → use 'image'
+ * - gemini-vectorize → use 'vectorize'
+ */
+export type WorkflowStepType =
+  // Preferred step types (use these)
+  | 'joke'
+  | 'translation'
+  | 'image'
+  | 'vectorize'
+  | 'mcp-tool'
+  | 'chromadb'
+  | 'gitmcp'
+  | 'rag'
+  | 'llm'
+  | 'chat'
+  | 'output-generator'
+  | 'builtin-agent'
+  | 'custom-action'
+  // Legacy step types (deprecated - will be removed in v1.0)
+  | 'genkit-joke'
+  | 'genkit-translation'
+  | 'genkit-image'
+  | 'gemini-vectorize';
+
+/**
+ * Maps legacy step type names to their preferred equivalents
+ * @deprecated Use preferred step type names directly
+ */
+export const LEGACY_STEP_TYPE_MAP: Record<string, WorkflowStepType> = {
+  'genkit-joke': 'joke',
+  'genkit-translation': 'translation',
+  'genkit-image': 'image',
+  'gemini-vectorize': 'vectorize',
+};
+
+/**
+ * Agent categories for organization
+ */
+export type AgentCategory =
+  | 'utility'
+  | 'translation'
+  | 'image'
+  | 'mcp'
+  | 'vectorization'
+  | 'storage'
+  | 'retrieval'
+  | 'orchestration';

package/src/shared/types/execution.types.ts

@@ -0,0 +1,45 @@
+/**
+ * Execution Types - Shared between client and server
+ * Used for tracking and displaying execution progress
+ */
+
+/**
+ * Execution result from a workflow step
+ */
+export interface ExecutionResult<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  duration?: number;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Workflow execution status
+ */
+export type ExecutionStatus = 'pending' | 'running' | 'success' | 'error' | 'cancelled';
+
+/**
+ * Workflow execution summary
+ */
+export interface ExecutionSummary {
+  agentId: string;
+  status: ExecutionStatus;
+  startTime: number;
+  endTime?: number;
+  totalDuration?: number;
+  stepsCompleted: number;
+  totalSteps: number;
+  error?: string;
+}
+
+/**
+ * Execution log entry
+ */
+export interface ExecutionLogEntry {
+  timestamp: number;
+  level: 'info' | 'warn' | 'error' | 'debug';
+  message: string;
+  step?: string;
+  metadata?: Record<string, unknown>;
+}

package/src/shared/types/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared Types - Re-exports for client and server
+ */
+
+export * from './agent.types';
+export * from './execution.types';
+export * from './schema.types';

package/src/shared/types/schema.types.ts

@@ -0,0 +1,55 @@
+/**
+ * Schema Types - Shared type definitions for agent schemas
+ * Used for input/output validation on both client and server
+ */
+
+/**
+ * JSON Schema-like type definition
+ */
+export interface SchemaProperty {
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  description?: string;
+  enum?: string[];
+  items?: SchemaProperty;
+  properties?: Record<string, SchemaProperty>;
+  required?: string[];
+  default?: unknown;
+  minLength?: number;
+  maxLength?: number;
+  minimum?: number;
+  maximum?: number;
+  pattern?: string;
+}
+
+/**
+ * Agent schema definition
+ */
+export interface AgentSchemaDefinition {
+  input: {
+    type: 'object';
+    properties: Record<string, SchemaProperty>;
+    required?: string[];
+  };
+  output: {
+    type: 'object';
+    properties: Record<string, SchemaProperty>;
+    required?: string[];
+  };
+}
+
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+  valid: boolean;
+  errors?: ValidationError[];
+}
+
+/**
+ * Validation error detail
+ */
+export interface ValidationError {
+  path: string;
+  message: string;
+  code: string;
+}

package/src/shared/utils/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Shared Utilities - Re-exports
+ */
+
+export * from './validation';

package/src/shared/utils/validation.ts

@@ -0,0 +1,100 @@
+/**
+ * Validation Utilities - Shared validation helpers
+ * Safe for use in both client and server environments
+ */
+
+import type { ValidationResult, ValidationError } from '../types/schema.types';
+
+/**
+ * Validate that a value is a non-empty string
+ */
+export function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+/**
+ * Validate that a value is a positive number
+ */
+export function isPositiveNumber(value: unknown): value is number {
+  return typeof value === 'number' && value > 0 && !isNaN(value);
+}
+
+/**
+ * Validate that a value is a valid URL
+ */
+export function isValidUrl(value: unknown): value is string {
+  if (typeof value !== 'string') return false;
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate resolution format (e.g., "1024x1024")
+ */
+export function isValidResolution(value: unknown): value is string {
+  if (typeof value !== 'string') return false;
+  return /^\d+x\d+$/.test(value);
+}
+
+/**
+ * Validate language code (e.g., "en", "pt", "es")
+ */
+export function isValidLanguageCode(value: unknown): value is string {
+  if (typeof value !== 'string') return false;
+  return /^[a-z]{2}(-[A-Z]{2})?$/.test(value);
+}
+
+/**
+ * Create a validation result with errors
+ */
+export function createValidationResult(errors: ValidationError[]): ValidationResult {
+  return {
+    valid: errors.length === 0,
+    errors: errors.length > 0 ? errors : undefined,
+  };
+}
+
+/**
+ * Create a validation error
+ */
+export function createValidationError(
+  path: string,
+  message: string,
+  code: string
+): ValidationError {
+  return { path, message, code };
+}
+
+/**
+ * Sanitize string input by trimming whitespace
+ */
+export function sanitizeString(value: unknown): string {
+  if (typeof value !== 'string') return '';
+  return value.trim();
+}
+
+/**
+ * Validate required fields in an object
+ */
+export function validateRequiredFields(
+  obj: Record<string, unknown>,
+  requiredFields: string[]
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+  
+  for (const field of requiredFields) {
+    if (obj[field] === undefined || obj[field] === null) {
+      errors.push(createValidationError(
+        field,
+        `Missing required field: ${field}`,
+        'REQUIRED_FIELD_MISSING'
+      ));
+    }
+  }
+  
+  return errors;
+}