beddel 0.2.2 → 0.3.0

package/src/agents/chat/chat.handler.ts

@@ -0,0 +1,211 @@
+import 'server-only';
+
+/**
+ * Chat Agent Handler - Server-only execution logic
+ * Orchestrates RAG pipeline or simple LLM chat based on mode
+ */
+
+import type { ExecutionContext } from '../../types/executionContext';
+import type { ExecutionStep } from '../../shared/types/agent.types';
+import type { ChatHandlerParams, ChatHandlerResult, ChatMode } from './chat.types';
+import { executeVectorizeHandler } from '../gemini-vectorize/gemini-vectorize.handler';
+import { executeChromaDBHandler } from '../chromadb/chromadb.handler';
+import { executeRagHandler } from '../rag/rag.handler';
+import { executeLlmHandler } from '../llm/llm.handler';
+
+const KNOWLEDGE_COLLECTION = 'beddel_knowledge';
+
+/**
+ * Execute simple chat mode - direct LLM with conversation history (no documents)
+ */
+async function executeSimpleChat(
+  query: string,
+  messages: ChatHandlerParams['messages'],
+  props: Record<string, string>,
+  context: ExecutionContext,
+  executionSteps: ExecutionStep[]
+): Promise<ChatHandlerResult> {
+  const startTime = Date.now();
+
+  context.log(`[Chat:Simple] Processing query: "${query.substring(0, 50)}..."`);
+
+  const chatStep: ExecutionStep = {
+    agent: 'llm',
+    action: 'chat',
+    status: 'running',
+    startTime: Date.now(),
+    phase: 'generation',
+  };
+  executionSteps.push(chatStep);
+
+  const result = await executeLlmHandler(
+    { query, history: messages },
+    props,
+    context
+  );
+
+  chatStep.status = result.error ? 'error' : 'success';
+  chatStep.endTime = Date.now();
+  chatStep.duration = chatStep.endTime - chatStep.startTime;
+  if (result.error) chatStep.error = result.error;
+
+  return {
+    response: result.response,
+    timestamp: result.timestamp,
+    execution_steps: executionSteps,
+    total_duration: Date.now() - startTime,
+  };
+}
+
+/**
+ * Execute RAG chat mode - full pipeline with knowledge base
+ */
+async function executeRagChat(
+  query: string,
+  messages: ChatHandlerParams['messages'],
+  props: Record<string, string>,
+  context: ExecutionContext,
+  executionSteps: ExecutionStep[]
+): Promise<ChatHandlerResult> {
+  const startTime = Date.now();
+
+  context.log(`[Chat:RAG] Processing query: "${query.substring(0, 50)}..."`);
+
+  // Step 1: Vectorize user query
+  const vectorizeStep: ExecutionStep = {
+    agent: 'gemini-vectorize',
+    action: 'embedSingle',
+    status: 'running',
+    startTime: Date.now(),
+    phase: 'vectorization',
+  };
+  executionSteps.push(vectorizeStep);
+
+  const vectorResult = await executeVectorizeHandler(
+    { action: 'embedSingle', text: query },
+    props,
+    context
+  );
+
+  vectorizeStep.status = vectorResult.success ? 'success' : 'error';
+  vectorizeStep.endTime = Date.now();
+  vectorizeStep.duration = vectorizeStep.endTime - vectorizeStep.startTime;
+
+  if (!vectorResult.success || !vectorResult.vector) {
+    throw new Error(`Vectorization failed: ${vectorResult.error}`);
+  }
+
+  // Step 2: Check if knowledge base has data
+  const checkStep: ExecutionStep = {
+    agent: 'chromadb',
+    action: 'hasData',
+    status: 'running',
+    startTime: Date.now(),
+    phase: 'retrieval',
+  };
+  executionSteps.push(checkStep);
+
+  const hasDataResult = await executeChromaDBHandler(
+    { action: 'hasData', collection_name: KNOWLEDGE_COLLECTION, min_count: 5 },
+    props,
+    context
+  );
+
+  checkStep.status = hasDataResult.success ? 'success' : 'error';
+  checkStep.endTime = Date.now();
+  checkStep.duration = checkStep.endTime - checkStep.startTime;
+
+  // Step 3: Search knowledge base
+  const searchStep: ExecutionStep = {
+    agent: 'chromadb',
+    action: 'search',
+    status: 'running',
+    startTime: Date.now(),
+    phase: 'retrieval',
+  };
+  executionSteps.push(searchStep);
+
+  const searchResult = await executeChromaDBHandler(
+    {
+      action: 'search',
+      collection_name: KNOWLEDGE_COLLECTION,
+      query_vector: vectorResult.vector,
+      limit: 5,
+    },
+    props,
+    context
+  );
+
+  searchStep.status = searchResult.success ? 'success' : 'error';
+  searchStep.endTime = Date.now();
+  searchStep.duration = searchStep.endTime - searchStep.startTime;
+
+  // Step 4: Generate answer using RAG
+  const ragStep: ExecutionStep = {
+    agent: 'rag',
+    action: 'generate',
+    status: 'running',
+    startTime: Date.now(),
+    phase: 'generation',
+  };
+  executionSteps.push(ragStep);
+
+  const hasDocuments = searchResult.documents && searchResult.documents.trim().length > 0;
+  const documents = hasDocuments
+    ? searchResult.documents
+    : 'No specific documentation available. Answer based on general knowledge.';
+
+  const ragResult = await executeRagHandler(
+    { query, documents, history: messages },
+    props,
+    context
+  );
+
+  ragStep.status = ragResult.error ? 'error' : 'success';
+  ragStep.endTime = Date.now();
+  ragStep.duration = ragStep.endTime - ragStep.startTime;
+  if (ragResult.error) ragStep.error = ragResult.error;
+
+  return {
+    response: ragResult.response,
+    timestamp: ragResult.timestamp,
+    execution_steps: executionSteps,
+    total_duration: Date.now() - startTime,
+  };
+}
+
+/**
+ * Execute chat orchestration
+ */
+export async function executeChatHandler(
+  params: ChatHandlerParams,
+  props: Record<string, string>,
+  context: ExecutionContext
+): Promise<ChatHandlerResult> {
+  const executionSteps: ExecutionStep[] = [];
+  const messages = params.messages || [];
+  const lastUserMessage = [...messages].reverse().find((m) => m.role === 'user');
+  const query = params.query || lastUserMessage?.content || '';
+  const mode: ChatMode = params.mode || 'rag';
+
+  if (!query) {
+    throw new Error('No query found in messages or query parameter');
+  }
+
+  try {
+    return mode === 'simple'
+      ? await executeSimpleChat(query, messages, props, context, executionSteps)
+      : await executeRagChat(query, messages, props, context, executionSteps);
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    context.log(`[Chat] Error: ${message}`);
+    context.setError(message);
+
+    return {
+      response: `Error processing your request: ${message}`,
+      timestamp: new Date().toISOString(),
+      execution_steps: executionSteps,
+      total_duration: 0,
+    };
+  }
+}

package/src/agents/chat/chat.schema.ts

@@ -0,0 +1,33 @@
+/**
+ * Chat Agent Schema - Zod validation schemas
+ * Safe for both client and server
+ */
+
+import { z } from 'zod';
+
+export const ChatInputSchema = z.object({
+  messages: z.array(z.object({
+    role: z.enum(['user', 'assistant', 'system']),
+    content: z.string(),
+  })),
+  query: z.string().optional(),
+  knowledge_sources: z.array(z.string()).optional(),
+});
+
+export const ChatOutputSchema = z.object({
+  response: z.string(),
+  timestamp: z.string(),
+  execution_steps: z.array(z.object({
+    agent: z.string(),
+    action: z.string(),
+    status: z.enum(['running', 'success', 'error']),
+    startTime: z.number(),
+    endTime: z.number().optional(),
+    duration: z.number().optional(),
+    error: z.string().optional(),
+  })).optional(),
+  total_duration: z.number().optional(),
+});
+
+export type ChatInput = z.infer<typeof ChatInputSchema>;
+export type ChatOutput = z.infer<typeof ChatOutputSchema>;

package/src/agents/chat/chat.types.ts

@@ -0,0 +1,46 @@
+/**
+ * Chat Agent Types - Shared between client and server
+ */
+
+import type { ConversationMessage } from '../rag/rag.types';
+import type { ExecutionStep } from '../../shared/types/agent.types';
+
+/**
+ * Chat mode determines the execution flow
+ * - 'rag': Full RAG pipeline with knowledge base (default)
+ * - 'simple': Direct LLM chat maintaining conversation context only
+ */
+export type ChatMode = 'rag' | 'simple';
+
+/**
+ * Parameters for chat orchestration
+ */
+export interface ChatHandlerParams {
+  messages: ConversationMessage[];
+  query?: string;
+  mode?: ChatMode;
+  knowledge_sources?: string[];
+}
+
+/**
+ * Result from chat orchestration
+ */
+export interface ChatHandlerResult {
+  response: string;
+  timestamp: string;
+  execution_steps?: ExecutionStep[];
+  total_duration?: number;
+}
+
+/**
+ * Chat agent metadata
+ */
+export interface ChatMetadata {
+  id: 'chat';
+  name: string;
+  description: string;
+  category: 'chat';
+  route: '/agents/chat';
+  knowledge_sources: string[];
+  tags: string[];
+}

package/src/agents/chat/chat.yaml

@@ -0,0 +1,148 @@
+# Chat Agent - Native Builtin Orchestrator Agent for Beddel Runtime
+# Route: /agents/chat
+# Method: chat.execute
+
+agent:
+  id: chat
+  version: 1.0.0
+  protocol: beddel-declarative-protocol/v2.0
+
+metadata:
+  name: "Q&A Context Chat Agent"
+  description: "Orchestrates RAG pipeline or direct LLM chat based on mode selection"
+  category: "chat"
+  route: "/agents/chat"
+  knowledge_sources:
+    - "gitmcp-agent"
+  tags:
+    - "chat"
+    - "orchestrator"
+    - "rag"
+    - "llm"
+    - "qa"
+
+schema:
+  input:
+    type: "object"
+    properties:
+      messages:
+        type: "array"
+        items:
+          type: "object"
+          properties:
+            role:
+              type: "string"
+              enum: ["user", "assistant", "system"]
+            content:
+              type: "string"
+          required: ["role", "content"]
+        description: "Conversation messages"
+      query:
+        type: "string"
+        description: "Direct query (alternative to messages)"
+      mode:
+        type: "string"
+        enum: ["rag", "simple"]
+        default: "rag"
+        description: "Chat mode: 'rag' for knowledge-based answers, 'simple' for direct LLM chat"
+      knowledge_sources:
+        type: "array"
+        items:
+          type: "string"
+        description: "GitMCP URLs to use as knowledge sources"
+    required: ["messages"]
+
+  output:
+    type: "object"
+    properties:
+      response:
+        type: "string"
+        description: "Generated answer"
+      timestamp:
+        type: "string"
+        description: "ISO timestamp"
+      execution_steps:
+        type: "array"
+        description: "Detailed execution steps for observability"
+      total_duration:
+        type: "number"
+        description: "Total execution time in milliseconds"
+    required: ["response", "timestamp"]
+
+logic:
+  variables:
+    - name: "userQuery"
+      type: "string"
+      init: '""'
+    - name: "allDocuments"
+      type: "string"
+      init: '""'
+
+  workflow:
+    # Step 1: Extract user query from messages
+    - name: "extract-query"
+      type: "output-generator"
+      action:
+        type: "generate"
+        output:
+          _extracted: true
+
+    # Step 2: Mode branch - Simple LLM chat or RAG pipeline
+    - name: "mode-check"
+      type: "conditional"
+      condition: "$input.mode == 'simple'"
+      then:
+        # Simple mode: Direct LLM chat with conversation history (no documents)
+        - name: "simple-chat"
+          type: "llm"
+          action:
+            query: "$input.query"
+            history: "$input.messages"
+            result: "llmResult"
+      else:
+        # RAG mode: Full pipeline with knowledge base
+        - name: "vectorize-query"
+          type: "gemini-vectorize"
+          action:
+            action: "embedSingle"
+            text: "$input.query"
+            result: "queryVector"
+
+        - name: "check-knowledge"
+          type: "chromadb"
+          action:
+            action: "hasData"
+            collection_name: "beddel_knowledge"
+            min_count: 5
+            result: "hasDataResult"
+
+        - name: "search-knowledge"
+          type: "chromadb"
+          action:
+            action: "search"
+            collection_name: "beddel_knowledge"
+            query_vector: "$queryVector.vector"
+            limit: 5
+            result: "searchResult"
+
+        - name: "generate-answer"
+          type: "rag"
+          action:
+            query: "$input.query"
+            documents: "$searchResult.documents"
+            history: "$input.messages"
+            result: "ragResult"
+
+    # Step 3: Deliver final response
+    - name: "deliver-response"
+      type: "output-generator"
+      action:
+        type: "generate"
+        output:
+          response: "$ragResult.response"
+          timestamp: "$ragResult.timestamp"
+
+output:
+  schema:
+    response: "$ragResult.response"
+    timestamp: "$ragResult.timestamp"

package/src/agents/chat/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Chat Agent - Public exports (client-safe)
+ */
+
+// Schema exports (client-safe)
+export { ChatInputSchema, ChatOutputSchema } from './chat.schema';
+export type { ChatInput, ChatOutput } from './chat.schema';
+
+// Type exports (client-safe)
+export type { ChatHandlerParams, ChatHandlerResult, ChatMetadata } from './chat.types';
+
+// Metadata (client-safe)
+export const chatMetadata = {
+  id: 'chat',
+  name: 'Q&A Context Chat Agent',
+  description: 'Orchestrates RAG pipeline: vectorization, storage, retrieval and answer generation',
+  category: 'chat',
+  route: '/agents/chat',
+  knowledge_sources: ['gitmcp-agent'],
+  tags: ['chat', 'orchestrator', 'rag', 'qa'],
+} as const;

package/src/agents/chromadb/chromadb.handler.ts

@@ -0,0 +1,130 @@
+import 'server-only';
+
+/**
+ * ChromaDB Agent Handler - Server-only execution logic
+ * Vector storage and retrieval using ChromaDB
+ */
+
+import type { ExecutionContext } from '../../types/executionContext';
+import type { ChromaDBHandlerParams, ChromaDBHandlerResult, ChromaDBSearchResult } from './chromadb.types';
+
+// ChromaDB imports (lazy loaded)
+let chromaClient: any = null;
+
+/**
+ * Execute ChromaDB operations
+ */
+export async function executeChromaDBHandler(
+  params: ChromaDBHandlerParams,
+  _props: Record<string, string>,
+  context: ExecutionContext
+): Promise<ChromaDBHandlerResult> {
+  const action = params.action;
+  const collectionName = params.collection_name;
+
+  if (!collectionName) {
+    throw new Error('Missing required ChromaDB input: collection_name');
+  }
+
+  try {
+    // Lazy load ChromaDB
+    if (!chromaClient) {
+      const chromaModule = await import('chromadb');
+
+      if (process.env.CHROMADB_API_KEY) {
+        context.log('[ChromaDB] Initializing CloudClient...');
+        chromaClient = new chromaModule.CloudClient({
+          apiKey: process.env.CHROMADB_API_KEY,
+          tenant: process.env.CHROMADB_TENANT || 'default_tenant',
+          database: process.env.CHROMADB_DATABASE || 'dev',
+        });
+      } else {
+        context.log('[ChromaDB] Initializing Local ChromaClient...');
+        chromaClient = new chromaModule.ChromaClient({
+          path: process.env.CHROMADB_URL || 'http://localhost:8000',
+        });
+      }
+    }
+
+    if (action === 'hasData') {
+      const minCount = params.min_count || 1;
+      context.log(`[ChromaDB] Checking data for collection: ${collectionName}`);
+
+      try {
+        const collection = await chromaClient.getCollection({
+          name: collectionName,
+          embeddingFunction: undefined,
+        });
+        const count = await collection.count();
+        const hasEnoughData = count >= minCount;
+
+        return { success: true, has_data: hasEnoughData, count };
+      } catch {
+        return { success: true, has_data: false, count: 0 };
+      }
+
+    } else if (action === 'store') {
+      const ids = params.ids;
+      const vectors = params.vectors;
+      const documents = params.documents;
+      const metadatas = params.metadatas;
+
+      context.log(`[ChromaDB] Storing ${ids?.length || 0} items in ${collectionName}...`);
+
+      const collection = await chromaClient.getOrCreateCollection({
+        name: collectionName,
+        embeddingFunction: undefined,
+      });
+
+      await collection.add({
+        ids,
+        embeddings: vectors,
+        documents,
+        metadatas,
+      });
+
+      return { success: true, stored_count: ids?.length || 0 };
+
+    } else if (action === 'search') {
+      const queryVector = params.query_vector;
+      const limit = params.limit || 5;
+
+      context.log(`[ChromaDB] Searching ${collectionName}...`);
+
+      try {
+        const collection = await chromaClient.getCollection({
+          name: collectionName,
+          embeddingFunction: undefined,
+        });
+
+        const results = await collection.query({
+          queryEmbeddings: [queryVector],
+          nResults: limit,
+        });
+
+        const flatResults: ChromaDBSearchResult[] = (results.documents[0] || []).map(
+          (doc: string | null, idx: number) => ({
+            text: doc,
+            metadata: results.metadatas[0]?.[idx] || null,
+            distance: results.distances?.[0]?.[idx] || null,
+          })
+        );
+
+        const documentsString = flatResults.map((r) => r.text).join('\n\n---\n\n');
+
+        return { success: true, results: flatResults, documents: documentsString };
+      } catch {
+        // Collection doesn't exist - return empty results
+        context.log(`[ChromaDB] Collection ${collectionName} not found, returning empty results`);
+        return { success: true, results: [], documents: '' };
+      }
+
+    } else {
+      throw new Error(`Unknown ChromaDB action: ${action}`);
+    }
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    context.log(`[ChromaDB] Error: ${message}`);
+    return { success: false, error: message };
+  }
+}

package/src/agents/chromadb/chromadb.schema.ts

@@ -0,0 +1,35 @@
+/**
+ * ChromaDB Agent Schema - Zod validation schemas
+ * Safe for both client and server
+ */
+
+import { z } from 'zod';
+
+export const ChromaDBInputSchema = z.object({
+  action: z.enum(['hasData', 'store', 'search']),
+  collection_name: z.string().min(1),
+  min_count: z.number().optional(),
+  ids: z.array(z.string()).optional(),
+  vectors: z.array(z.array(z.number())).optional(),
+  documents: z.array(z.string()).optional(),
+  metadatas: z.array(z.record(z.string(), z.unknown())).optional(),
+  query_vector: z.array(z.number()).optional(),
+  limit: z.number().optional(),
+});
+
+export const ChromaDBOutputSchema = z.object({
+  success: z.boolean(),
+  has_data: z.boolean().optional(),
+  count: z.number().optional(),
+  stored_count: z.number().optional(),
+  results: z.array(z.object({
+    text: z.string().nullable(),
+    metadata: z.record(z.string(), z.unknown()).nullable(),
+    distance: z.number().nullable(),
+  })).optional(),
+  documents: z.string().optional(),
+  error: z.string().optional(),
+});
+
+export type ChromaDBInput = z.infer<typeof ChromaDBInputSchema>;
+export type ChromaDBOutput = z.infer<typeof ChromaDBOutputSchema>;

package/src/agents/chromadb/chromadb.types.ts

@@ -0,0 +1,52 @@
+/**
+ * ChromaDB Agent Types - Shared between client and server
+ */
+
+/**
+ * Parameters for ChromaDB operations
+ */
+export interface ChromaDBHandlerParams {
+  action: 'hasData' | 'store' | 'search';
+  collection_name: string;
+  min_count?: number;
+  ids?: string[];
+  vectors?: number[][];
+  documents?: string[];
+  metadatas?: Record<string, unknown>[];
+  query_vector?: number[];
+  limit?: number;
+}
+
+/**
+ * Search result item
+ */
+export interface ChromaDBSearchResult {
+  text: string | null;
+  metadata: Record<string, unknown> | null;
+  distance: number | null;
+}
+
+/**
+ * Result from ChromaDB operations
+ */
+export interface ChromaDBHandlerResult {
+  success: boolean;
+  has_data?: boolean;
+  count?: number;
+  stored_count?: number;
+  results?: ChromaDBSearchResult[];
+  documents?: string;
+  error?: string;
+}
+
+/**
+ * ChromaDB agent metadata
+ */
+export interface ChromaDBMetadata {
+  id: 'chromadb';
+  name: string;
+  description: string;
+  category: 'database';
+  route: '/agents/chromadb';
+  tags: string[];
+}