beddel 0.2.1 → 0.2.3

package/src/agents/chromadb/chromadb.yaml

@@ -0,0 +1,128 @@
+# ChromaDB Agent - Native Builtin Agent for Beddel Runtime
+# Route: /agents/chromadb
+# Method: chromadb.execute
+
+agent:
+  id: chromadb
+  version: 1.0.0
+  protocol: beddel-declarative-protocol/v2.0
+
+metadata:
+  name: "ChromaDB Agent"
+  description: "Vector storage and retrieval using ChromaDB. Supports local and cloud deployments."
+  category: "database"
+  route: "/agents/chromadb"
+  tags:
+    - "chromadb"
+    - "storage"
+    - "vector-db"
+    - "rag"
+
+schema:
+  input:
+    type: "object"
+    properties:
+      action:
+        type: "string"
+        enum: ["hasData", "store", "search"]
+        description: "Action to perform"
+      collection_name:
+        type: "string"
+        description: "Name of the ChromaDB collection"
+      min_count:
+        type: "number"
+        description: "Minimum document count for hasData action (default: 1)"
+      ids:
+        type: "array"
+        items:
+          type: "string"
+        description: "Document IDs for store action"
+      vectors:
+        type: "array"
+        items:
+          type: "array"
+          items:
+            type: "number"
+        description: "Embedding vectors for store action"
+      documents:
+        type: "array"
+        items:
+          type: "string"
+        description: "Document texts for store action"
+      metadatas:
+        type: "array"
+        items:
+          type: "object"
+        description: "Metadata objects for store action"
+      query_vector:
+        type: "array"
+        items:
+          type: "number"
+        description: "Query embedding vector for search action"
+      limit:
+        type: "number"
+        description: "Maximum results for search action (default: 5)"
+    required: ["action", "collection_name"]
+
+  output:
+    type: "object"
+    properties:
+      success:
+        type: "boolean"
+      has_data:
+        type: "boolean"
+        description: "Whether collection has sufficient data (hasData action)"
+      count:
+        type: "number"
+        description: "Document count in collection (hasData action)"
+      stored_count:
+        type: "number"
+        description: "Number of documents stored (store action)"
+      results:
+        type: "array"
+        description: "Search results with text, metadata and distance (search action)"
+      documents:
+        type: "string"
+        description: "Concatenated document texts (search action)"
+      error:
+        type: "string"
+    required: ["success"]
+
+logic:
+  workflow:
+    - name: "chromadb-operation"
+      type: "chromadb"
+      action:
+        action: "$input.action"
+        collection_name: "$input.collection_name"
+        min_count: "$input.min_count"
+        ids: "$input.ids"
+        vectors: "$input.vectors"
+        documents: "$input.documents"
+        metadatas: "$input.metadatas"
+        query_vector: "$input.query_vector"
+        limit: "$input.limit"
+        result: "chromaResult"
+
+    - name: "deliver-response"
+      type: "output-generator"
+      action:
+        type: "generate"
+        output:
+          success: "$chromaResult.success"
+          has_data: "$chromaResult.has_data"
+          count: "$chromaResult.count"
+          stored_count: "$chromaResult.stored_count"
+          results: "$chromaResult.results"
+          documents: "$chromaResult.documents"
+          error: "$chromaResult.error"
+
+output:
+  schema:
+    success: "$chromaResult.success"
+    has_data: "$chromaResult.has_data"
+    count: "$chromaResult.count"
+    stored_count: "$chromaResult.stored_count"
+    results: "$chromaResult.results"
+    documents: "$chromaResult.documents"
+    error: "$chromaResult.error"

package/src/agents/chromadb/index.ts

@@ -0,0 +1,20 @@
+/**
+ * ChromaDB Agent - Public exports (client-safe)
+ */
+
+// Schema exports (client-safe)
+export { ChromaDBInputSchema, ChromaDBOutputSchema } from './chromadb.schema';
+export type { ChromaDBInput, ChromaDBOutput } from './chromadb.schema';
+
+// Type exports (client-safe)
+export type { ChromaDBHandlerParams, ChromaDBHandlerResult, ChromaDBSearchResult, ChromaDBMetadata } from './chromadb.types';
+
+// Metadata (client-safe)
+export const chromadbMetadata = {
+  id: 'chromadb',
+  name: 'ChromaDB Agent',
+  description: 'Vector storage and retrieval using ChromaDB. Supports local and cloud deployments.',
+  category: 'database',
+  route: '/agents/chromadb',
+  tags: ['chromadb', 'storage', 'vector-db', 'rag'],
+} as const;

package/src/agents/gemini-vectorize/gemini-vectorize.handler.ts

@@ -0,0 +1,72 @@
+import 'server-only';
+
+/**
+ * Gemini Vectorize Agent Handler - Server-only execution logic
+ * Generates text embeddings using Google's Gemini text-embedding-004 model
+ */
+
+import { embed, embedMany } from 'ai';
+import { google } from '@ai-sdk/google';
+import type { ExecutionContext } from '../../types/executionContext';
+import type { VectorizeHandlerParams, VectorizeHandlerResult } from './gemini-vectorize.types';
+
+const GEMINI_EMBEDDING_MODEL = 'text-embedding-004';
+
+/**
+ * Execute vectorization using Gemini embeddings
+ */
+export async function executeVectorizeHandler(
+  params: VectorizeHandlerParams,
+  props: Record<string, string>,
+  context: ExecutionContext
+): Promise<VectorizeHandlerResult> {
+  const apiKey = props?.gemini_api_key?.trim();
+  if (!apiKey) {
+    throw new Error('Missing required prop: gemini_api_key');
+  }
+
+  // Set API key in environment for google provider
+  process.env.GOOGLE_GENERATIVE_AI_API_KEY = apiKey;
+
+  const action = params.action || 'embedSingle';
+
+  try {
+    if (action === 'embedSingle') {
+      const text = params.text;
+      if (!text) {
+        throw new Error('Text input is required for embedSingle');
+      }
+
+      context.log(`[Gemini Vectorize] Embedding single text (${text.length} chars)...`);
+
+      const { embedding } = await embed({
+        model: google.textEmbeddingModel(GEMINI_EMBEDDING_MODEL),
+        value: text,
+      });
+
+      return { success: true, vector: embedding };
+
+    } else if (action === 'embedBatch') {
+      const texts = params.texts;
+      if (!texts || !Array.isArray(texts)) {
+        throw new Error('Texts array input is required for embedBatch');
+      }
+
+      context.log(`[Gemini Vectorize] Embedding batch of ${texts.length} texts...`);
+
+      const { embeddings } = await embedMany({
+        model: google.textEmbeddingModel(GEMINI_EMBEDDING_MODEL),
+        values: texts,
+      });
+
+      return { success: true, vectors: embeddings };
+
+    } else {
+      throw new Error(`Unknown vectorize action: ${action}`);
+    }
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    context.log(`[Gemini Vectorize] Error: ${message}`);
+    return { success: false, error: message };
+  }
+}

package/src/agents/gemini-vectorize/gemini-vectorize.schema.ts

@@ -0,0 +1,22 @@
+/**
+ * Gemini Vectorize Agent Schema - Zod validation schemas
+ * Safe for both client and server
+ */
+
+import { z } from 'zod';
+
+export const GeminiVectorizeInputSchema = z.object({
+  action: z.enum(['embedSingle', 'embedBatch']),
+  text: z.string().optional(),
+  texts: z.array(z.string()).optional(),
+});
+
+export const GeminiVectorizeOutputSchema = z.object({
+  success: z.boolean(),
+  vector: z.array(z.number()).optional(),
+  vectors: z.array(z.array(z.number())).optional(),
+  error: z.string().optional(),
+});
+
+export type GeminiVectorizeInput = z.infer<typeof GeminiVectorizeInputSchema>;
+export type GeminiVectorizeOutput = z.infer<typeof GeminiVectorizeOutputSchema>;

package/src/agents/gemini-vectorize/gemini-vectorize.types.ts

@@ -0,0 +1,34 @@
+/**
+ * Gemini Vectorize Agent Types - Shared between client and server
+ */
+
+/**
+ * Parameters for vectorization
+ */
+export interface VectorizeHandlerParams {
+  action: 'embedSingle' | 'embedBatch';
+  text?: string;
+  texts?: string[];
+}
+
+/**
+ * Result from vectorization
+ */
+export interface VectorizeHandlerResult {
+  success: boolean;
+  vector?: number[];
+  vectors?: number[][];
+  error?: string;
+}
+
+/**
+ * Gemini Vectorize agent metadata
+ */
+export interface GeminiVectorizeMetadata {
+  id: 'gemini-vectorize';
+  name: string;
+  description: string;
+  category: 'ai-service';
+  route: '/agents/gemini-vectorize';
+  tags: string[];
+}

package/src/agents/gemini-vectorize/gemini-vectorize.yaml

@@ -0,0 +1,84 @@
+# Gemini Vectorize Agent - Native Builtin Agent for Beddel Runtime
+# Route: /agents/gemini-vectorize
+# Method: gemini-vectorize.execute
+
+agent:
+  id: gemini-vectorize
+  version: 1.0.0
+  protocol: beddel-declarative-protocol/v2.0
+
+metadata:
+  name: "Gemini Vectorize Agent"
+  description: "Generates text embeddings using Google's Gemini text-embedding-004 model"
+  category: "ai-service"
+  route: "/agents/gemini-vectorize"
+  tags:
+    - "embeddings"
+    - "gemini"
+    - "ai"
+    - "vectorization"
+
+schema:
+  input:
+    type: "object"
+    properties:
+      action:
+        type: "string"
+        enum: ["embedSingle", "embedBatch"]
+        description: "Action to perform: embedSingle for one text, embedBatch for multiple"
+      text:
+        type: "string"
+        description: "Single text to embed (for embedSingle action)"
+      texts:
+        type: "array"
+        items:
+          type: "string"
+        description: "Array of texts to embed (for embedBatch action)"
+
+  output:
+    type: "object"
+    properties:
+      success:
+        type: "boolean"
+      vector:
+        type: "array"
+        items:
+          type: "number"
+        description: "Single embedding vector (for embedSingle)"
+      vectors:
+        type: "array"
+        items:
+          type: "array"
+          items:
+            type: "number"
+        description: "Array of embedding vectors (for embedBatch)"
+      error:
+        type: "string"
+    required: ["success"]
+
+logic:
+  workflow:
+    - name: "vectorize"
+      type: "gemini-vectorize"
+      action:
+        action: "$input.action"
+        text: "$input.text"
+        texts: "$input.texts"
+        result: "vectorizeResult"
+
+    - name: "deliver-response"
+      type: "output-generator"
+      action:
+        type: "generate"
+        output:
+          success: "$vectorizeResult.success"
+          vector: "$vectorizeResult.vector"
+          vectors: "$vectorizeResult.vectors"
+          error: "$vectorizeResult.error"
+
+output:
+  schema:
+    success: "$vectorizeResult.success"
+    vector: "$vectorizeResult.vector"
+    vectors: "$vectorizeResult.vectors"
+    error: "$vectorizeResult.error"

package/src/agents/gemini-vectorize/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Gemini Vectorize Agent - Public exports (client-safe)
+ */
+
+// Schema exports (client-safe)
+export { GeminiVectorizeInputSchema, GeminiVectorizeOutputSchema } from './gemini-vectorize.schema';
+export type { GeminiVectorizeInput, GeminiVectorizeOutput } from './gemini-vectorize.schema';
+
+// Type exports (client-safe)
+export type { VectorizeHandlerParams, VectorizeHandlerResult, GeminiVectorizeMetadata } from './gemini-vectorize.types';
+
+// Metadata (client-safe)
+export const geminiVectorizeMetadata = {
+  id: 'gemini-vectorize',
+  name: 'Gemini Vectorize Agent',
+  description: "Generates text embeddings using Google's Gemini text-embedding-004 model",
+  category: 'ai-service',
+  route: '/agents/gemini-vectorize',
+  tags: ['embeddings', 'gemini', 'ai', 'vectorization'],
+} as const;

package/src/agents/gitmcp/gitmcp.handler.ts

@@ -0,0 +1,122 @@
+import 'server-only';
+
+/**
+ * GitMCP Agent Handler - Server-only execution logic
+ * Fetches and chunks GitHub repository documentation via gitmcp.io MCP servers
+ */
+
+import type { ExecutionContext } from '../../types/executionContext';
+import type { GitMcpHandlerParams, GitMcpHandlerResult } from './gitmcp.types';
+import { executeMcpToolHandler } from '../mcp-tool/mcp-tool.handler';
+
+/**
+ * Split text into chunks preserving paragraphs
+ */
+function splitIntoChunks(text: string, chunkSize: number): string[] {
+  const paragraphs = text.split(/\n\s*\n/);
+  const chunks: string[] = [];
+  let currentChunk = '';
+
+  for (const para of paragraphs) {
+    if (currentChunk.length + para.length > chunkSize && currentChunk) {
+      chunks.push(currentChunk.trim());
+      currentChunk = para;
+    } else {
+      currentChunk += (currentChunk ? '\n\n' : '') + para;
+    }
+  }
+
+  if (currentChunk) chunks.push(currentChunk.trim());
+  return chunks;
+}
+
+/**
+ * Execute GitMCP documentation fetching
+ */
+export async function executeGitMcpHandler(
+  params: GitMcpHandlerParams,
+  props: Record<string, string>,
+  context: ExecutionContext
+): Promise<GitMcpHandlerResult> {
+  const gitmcpUrl = params.gitmcp_url;
+
+  if (!gitmcpUrl) {
+    throw new Error('Missing required GitMCP input: gitmcp_url');
+  }
+
+  context.log(`[GitMCP] Fetching content from ${gitmcpUrl}...`);
+
+  try {
+    const sseUrl = `${gitmcpUrl}/sse`;
+
+    // Use MCP tool to list available tools
+    const toolListResult = await executeMcpToolHandler(
+      {
+        server_url: sseUrl,
+        tool_name: 'list_tools',
+        tool_arguments: {},
+      },
+      props,
+      context
+    );
+
+    let selectedToolName = '';
+    let selectedToolArgs: Record<string, unknown> = {};
+
+    if (toolListResult?.success && toolListResult?.tool_names) {
+      const availableTools = toolListResult.tool_names;
+      context.log(`[GitMCP] Discovered tools: ${availableTools.join(', ')}`);
+
+      // Heuristic tool selection
+      if (availableTools.includes('fetch_beddel_alpha_documentation')) {
+        selectedToolName = 'fetch_beddel_alpha_documentation';
+        selectedToolArgs = { path: '/' };
+      } else if (availableTools.includes('read_file')) {
+        selectedToolName = 'read_file';
+        selectedToolArgs = { path: 'README.md' };
+      } else if (availableTools.includes('fetch_generic_url_content')) {
+        selectedToolName = 'fetch_generic_url_content';
+        selectedToolArgs = { url: gitmcpUrl };
+      } else {
+        selectedToolName = availableTools.find((t) => t !== 'list_tools' && !t.includes('search')) || availableTools[0];
+        selectedToolArgs = { path: '/' };
+      }
+    } else {
+      selectedToolName = 'fetch_beddel_alpha_documentation';
+      selectedToolArgs = { path: '/' };
+    }
+
+    context.log(`[GitMCP] Selected tool: ${selectedToolName}`);
+
+    // Fetch content
+    const mcpResult = await executeMcpToolHandler(
+      {
+        server_url: sseUrl,
+        tool_name: selectedToolName,
+        tool_arguments: selectedToolArgs,
+      },
+      props,
+      context
+    );
+
+    if (!mcpResult?.success) {
+      throw new Error(`Failed to fetch docs via MCP: ${mcpResult?.error}`);
+    }
+
+    const textContent = mcpResult.data;
+    if (!textContent) {
+      throw new Error('No content returned from MCP tool');
+    }
+
+    // Chunking
+    const chunks = splitIntoChunks(textContent, 800);
+    context.log(`[GitMCP] Content split into ${chunks.length} chunks`);
+
+    return { success: true, chunks, source: gitmcpUrl };
+
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    context.log(`[GitMCP] Error: ${message}`);
+    return { success: false, chunks: [], error: message };
+  }
+}

package/src/agents/gitmcp/gitmcp.schema.ts

@@ -0,0 +1,20 @@
+/**
+ * GitMCP Agent Schema - Zod validation schemas
+ * Safe for both client and server
+ */
+
+import { z } from 'zod';
+
+export const GitMcpInputSchema = z.object({
+  gitmcp_url: z.string().url(),
+});
+
+export const GitMcpOutputSchema = z.object({
+  success: z.boolean(),
+  chunks: z.array(z.string()).optional(),
+  source: z.string().optional(),
+  error: z.string().optional(),
+});
+
+export type GitMcpInput = z.infer<typeof GitMcpInputSchema>;
+export type GitMcpOutput = z.infer<typeof GitMcpOutputSchema>;

package/src/agents/gitmcp/gitmcp.types.ts

@@ -0,0 +1,33 @@
+/**
+ * GitMCP Agent Types - Shared between client and server
+ */
+
+/**
+ * Parameters for GitMCP documentation fetching
+ */
+export interface GitMcpHandlerParams {
+  gitmcp_url: string;
+}
+
+/**
+ * Result from GitMCP documentation fetching
+ */
+export interface GitMcpHandlerResult {
+  success: boolean;
+  chunks?: string[];
+  source?: string;
+  error?: string;
+}
+
+/**
+ * GitMCP agent metadata
+ */
+export interface GitMcpMetadata {
+  id: 'gitmcp';
+  name: string;
+  description: string;
+  category: 'integration';
+  route: '/agents/gitmcp';
+  provides_knowledge: boolean;
+  tags: string[];
+}

package/src/agents/gitmcp/gitmcp.yaml

@@ -0,0 +1,71 @@
+# GitMCP Agent - Native Builtin Agent for Beddel Runtime
+# Route: /agents/gitmcp
+# Method: gitmcp.execute
+
+agent:
+  id: gitmcp
+  version: 1.0.0
+  protocol: beddel-declarative-protocol/v2.0
+
+metadata:
+  name: "GitMCP Documentation Agent"
+  description: "Fetches and chunks GitHub repository documentation via gitmcp.io MCP servers"
+  category: "integration"
+  route: "/agents/gitmcp"
+  provides_knowledge: true
+  tags:
+    - "gitmcp"
+    - "documentation"
+    - "github"
+    - "mcp"
+
+schema:
+  input:
+    type: "object"
+    properties:
+      gitmcp_url:
+        type: "string"
+        description: "GitMCP repository URL (e.g., https://gitmcp.io/owner/repo)"
+    required: ["gitmcp_url"]
+
+  output:
+    type: "object"
+    properties:
+      success:
+        type: "boolean"
+      chunks:
+        type: "array"
+        items:
+          type: "string"
+        description: "Content split into chunks for vectorization"
+      source:
+        type: "string"
+        description: "Source URL of the fetched content"
+      error:
+        type: "string"
+    required: ["success"]
+
+logic:
+  workflow:
+    - name: "fetch-content"
+      type: "gitmcp"
+      action:
+        gitmcp_url: "$input.gitmcp_url"
+        result: "gitmcpResult"
+
+    - name: "deliver-response"
+      type: "output-generator"
+      action:
+        type: "generate"
+        output:
+          success: "$gitmcpResult.success"
+          chunks: "$gitmcpResult.chunks"
+          source: "$gitmcpResult.source"
+          error: "$gitmcpResult.error"
+
+output:
+  schema:
+    success: "$gitmcpResult.success"
+    chunks: "$gitmcpResult.chunks"
+    source: "$gitmcpResult.source"
+    error: "$gitmcpResult.error"

package/src/agents/gitmcp/index.ts

@@ -0,0 +1,21 @@
+/**
+ * GitMCP Agent - Public exports (client-safe)
+ */
+
+// Schema exports (client-safe)
+export { GitMcpInputSchema, GitMcpOutputSchema } from './gitmcp.schema';
+export type { GitMcpInput, GitMcpOutput } from './gitmcp.schema';
+
+// Type exports (client-safe)
+export type { GitMcpHandlerParams, GitMcpHandlerResult, GitMcpMetadata } from './gitmcp.types';
+
+// Metadata (client-safe)
+export const gitmcpMetadata = {
+  id: 'gitmcp',
+  name: 'GitMCP Documentation Agent',
+  description: 'Fetches and chunks GitHub repository documentation via gitmcp.io MCP servers',
+  category: 'integration',
+  route: '/agents/gitmcp',
+  provides_knowledge: true,
+  tags: ['gitmcp', 'documentation', 'github', 'mcp'],
+} as const;