beddel 0.2.3 → 1.0.0

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

@@ -1,209 +0,0 @@
-import 'server-only';
-
-/**
- * Chat Agent Handler - Server-only execution logic
- * Orchestrates RAG pipeline or simple 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';
-
-const KNOWLEDGE_COLLECTION = 'beddel_knowledge';
-
-/**
- * Execute simple chat mode - direct LLM with conversation history
- */
-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: 'rag',
-    action: 'chat',
-    status: 'running',
-    startTime: Date.now(),
-    phase: 'generation',
-  };
-  executionSteps.push(chatStep);
-
-  const result = await executeRagHandler(
-    { query, history: messages, mode: 'simple' },
-    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
-  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 ragResult = hasDocuments
-    ? await executeRagHandler({ query, documents: searchResult.documents, history: messages }, props, context)
-    : await executeRagHandler(
-        { query, documents: 'No specific documentation available. Answer based on general knowledge.', 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

@@ -1,33 +0,0 @@
-/**
- * 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

@@ -1,46 +0,0 @@
-/**
- * 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

@@ -1,150 +0,0 @@
-# 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 simple chat based on mode selection"
-  category: "chat"
-  route: "/agents/chat"
-  knowledge_sources:
-    - "gitmcp-agent"
-  tags:
-    - "chat"
-    - "orchestrator"
-    - "rag"
-    - "qa"
-    - "simple"
-
-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 chat or RAG pipeline
-    - name: "mode-check"
-      type: "conditional"
-      condition: "$input.mode == 'simple'"
-      then:
-        # Simple mode: Direct LLM chat with conversation history
-        - name: "simple-chat"
-          type: "rag"
-          action:
-            query: "$input.query"
-            history: "$input.messages"
-            mode: "simple"
-            result: "ragResult"
-      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"
-            mode: "rag"
-            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

@@ -1,21 +0,0 @@
-/**
- * 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

@@ -1,130 +0,0 @@
-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

@@ -1,35 +0,0 @@
-/**
- * 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

@@ -1,52 +0,0 @@
-/**
- * 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[];
-}