agent-orcha 0.0.1

package/dist/templates/functions/README.md

@@ -0,0 +1,195 @@
+# Custom Functions
+
+This directory contains custom function tools that can be used by agents in the orchestrator.
+
+## Overview
+
+Functions are JavaScript files that export tools with metadata. They provide a way to extend agent capabilities with custom logic and operations.
+
+**No dependencies required!** Functions use a simple format that requires no npm packages or imports.
+
+## Creating a Function
+
+Functions must follow this structure:
+
+1. File name must end with `.function.js`
+2. Must export a default object with `name`, `description`, `parameters`, and `execute`
+3. Optionally export metadata for better documentation
+
+### Simple Format (Recommended)
+
+**No imports needed!** Just export a plain JavaScript object:
+
+```javascript
+/**
+ * Your function description
+ */
+export default {
+  name: 'your-function-name',
+  description: 'A clear description of what this function does',
+
+  parameters: {
+    param1: {
+      type: 'number',
+      description: 'Description of parameter 1',
+    },
+    param2: {
+      type: 'string',
+      description: 'Description of parameter 2',
+    },
+    optionalParam: {
+      type: 'boolean',
+      description: 'An optional parameter',
+      required: false,
+      default: true,
+    },
+  },
+
+  execute: async ({ param1, param2, optionalParam }) => {
+    // Your implementation here
+    return `Result: ${param1 + param2}`;
+  },
+};
+
+// Optional: Export metadata for discovery
+export const metadata = {
+  name: 'your-function-name',
+  description: 'Function description',
+  version: '1.0.0',
+  author: 'Your Name',
+  tags: ['category1', 'category2'],
+};
+```
+
+### Parameter Types
+
+Supported parameter types:
+
+- `'string'` - String value
+- `'number'` - Numeric value
+- `'boolean'` - Boolean true/false
+- `'array'` - Array of values
+- `'object'` - Object/JSON structure
+- `'enum'` - One of a fixed set of values (requires `values` array)
+
+### Enum Parameters
+
+For parameters with a fixed set of allowed values:
+
+```javascript
+parameters: {
+  operation: {
+    type: 'enum',
+    values: ['add', 'subtract', 'multiply', 'divide'],
+    description: 'The operation to perform',
+  },
+}
+```
+
+## Using Functions in Agents
+
+To use a function in an agent, add it to the agent's `tools` array using the `function:` prefix:
+
+```yaml
+name: my-agent
+description: An agent that uses custom functions
+
+tools:
+  - function:fibonacci  # References fibonacci.function.js
+  - function:your-function-name
+
+# ... rest of agent configuration
+```
+
+## Available Functions
+
+### fibonacci
+
+**File:** `fibonacci.function.js`
+
+**Description:** Returns the nth Fibonacci number
+
+**Parameters:**
+- `n` (number) - The index (0-based, max 100)
+
+**Examples:**
+- Fibonacci(0) returns: 0
+- Fibonacci(5) returns: 5
+- Fibonacci(10) returns: 55
+
+**Usage in agent:**
+```yaml
+tools:
+  - function:fibonacci
+```
+
+## Best Practices
+
+1. **Error Handling**: Always validate inputs and handle errors gracefully
+2. **Descriptive Names**: Use clear, descriptive names for functions and parameters
+3. **Documentation**: Include JSDoc comments explaining what the function does
+4. **Parameter Descriptions**: Provide clear descriptions for each parameter
+5. **Metadata**: Export metadata to make functions discoverable and well-documented
+6. **Async Operations**: Use async/await for operations that involve I/O or external calls
+7. **Return Values**: Return strings or serializable objects that agents can interpret
+
+## Development Tips
+
+- Functions are loaded automatically on orchestrator initialization
+- Function names must be unique across all loaded functions
+- The simple format requires no npm packages or dependencies
+- Test functions independently before integrating with agents
+- Use the simple format unless you need advanced LangChain features
+
+## Example Agent Using Fibonacci
+
+```yaml
+name: math-assistant
+description: A Fibonacci number assistant
+
+llm:
+  name: default
+  temperature: 0.3
+
+prompt:
+  system: |
+    You are a math assistant specialized in Fibonacci numbers.
+    Use the fibonacci tool to calculate Fibonacci numbers or sequences.
+  inputVariables:
+    - query
+
+tools:
+  - function:fibonacci
+
+output:
+  format: text
+```
+
+## Extending the System
+
+To add new function capabilities:
+
+1. Create a new `.function.js` file in this directory
+2. Export a default object with the simple format shown above
+3. Add it to your agent's tools array as `function:your-name`
+4. Restart the orchestrator to load the new function
+
+**Example new function:**
+
+```javascript
+// my-function.function.js
+export default {
+  name: 'my-function',
+  description: 'Does something useful',
+  parameters: {
+    input: {
+      type: 'string',
+      description: 'The input to process',
+    },
+  },
+  execute: async ({ input }) => {
+    // Your logic here
+    return `Processed: ${input}`;
+  },
+};
+```

package/dist/templates/functions/fibonacci.function.js

@@ -0,0 +1,55 @@
+/**
+ * Fibonacci calculator function - Simple format example
+ *
+ * This demonstrates the simple function format that requires no imports.
+ * Just export a default object with name, description, parameters, and execute.
+ */
+
+export default {
+  name: 'fibonacci',
+  description: 'Returns the nth Fibonacci number (0-based indexing).',
+
+  parameters: {
+    n: {
+      type: 'number',
+      description: 'The index of the Fibonacci number (0-based). For example, n=0 returns 0, n=5 returns 5.',
+    },
+  },
+
+  execute: async ({ n }) => {
+    // Validate input
+    if (n < 0) {
+      throw new Error('Index must be non-negative');
+    }
+    if (!Number.isInteger(n)) {
+      throw new Error('Index must be an integer');
+    }
+    if (n > 100) {
+      throw new Error('Index too large (max 100 to prevent overflow)');
+    }
+
+    // Calculate Fibonacci number
+    if (n === 0) return `Fibonacci(${n}) = 0`;
+    if (n === 1) return `Fibonacci(${n}) = 1`;
+
+    let prev = 0;
+    let curr = 1;
+
+    for (let i = 2; i <= n; i++) {
+      const next = prev + curr;
+      prev = curr;
+      curr = next;
+    }
+
+    return `Fibonacci(${n}) = ${curr}`;
+  },
+};
+
+// Optional: Export metadata for discovery
+export const metadata = {
+  name: 'fibonacci',
+  description: 'Returns the nth Fibonacci number',
+  version: '1.0.0',
+  author: 'Agent Orchestrator',
+  tags: ['math', 'fibonacci'],
+};

package/dist/templates/llm.json

@@ -0,0 +1,44 @@
+{
+  "version": "1.0",
+  "models": {
+    "default": {
+      "provider": "openai",
+      "baseUrl": "http://localhost:1234/v1",
+      "apiKey": "not-needed",
+      "model": "your-model-name",
+      "temperature": 0.7
+    },
+    "openai": {
+      "provider": "openai",
+      "apiKey": "sk-your-openai-key-here",
+      "model": "gpt-4o",
+      "temperature": 0.7
+    },
+    "gemini": {
+      "provider": "gemini",
+      "apiKey": "your-gemini-api-key-here",
+      "model": "gemini-2.0-flash-exp",
+      "temperature": 0.7
+    }
+  },
+  "embeddings": {
+    "default": {
+      "provider": "openai",
+      "baseUrl": "http://localhost:1234/v1",
+      "apiKey": "not-needed",
+      "model": "text-embedding-nomic-embed-text-v1.5",
+      "eosToken": " "
+    },
+    "openai": {
+      "provider": "openai",
+      "apiKey": "sk-your-openai-key-here",
+      "model": "text-embedding-3-small",
+      "dimensions": 1536
+    },
+    "gemini": {
+      "provider": "gemini",
+      "apiKey": "your-gemini-api-key-here",
+      "model": "text-embedding-004"
+    }
+  }
+}

package/dist/templates/mcp.json

@@ -0,0 +1,18 @@
+{
+  "version": "1.0.0",
+  "servers": {
+    "fetch": {
+      "transport": "streamable-http",
+      "url": "https://remote.mcpservers.org/fetch/mcp",
+      "description": "Web fetch capabilities for retrieving URLs and returning markdown",
+      "timeout": 30000,
+      "enabled": true
+    }
+  },
+  "globalOptions": {
+    "throwOnLoadError": false,
+    "prefixToolNameWithServerName": true,
+    "additionalToolNamePrefix": "",
+    "defaultToolTimeout": 30000
+  }
+}

package/dist/templates/vectors/example-chroma.vector.yaml

@@ -0,0 +1,43 @@
+name: example-chroma
+description: Example vector store using Chroma for persistent storage
+
+source:
+  type: directory
+  path: vectors/sample-data
+  pattern: "*.txt"
+  recursive: false
+
+loader:
+  type: text
+
+splitter:
+  type: character
+  chunkSize: 1000
+  chunkOverlap: 200
+
+embedding: default  # References embedding config in llm.json
+
+store:
+  type: chroma
+  options:
+    # Path where Chroma will store data (relative to project root)
+    # Default: .chroma
+    path: .chroma
+
+    # Collection name for this vector store
+    # Default: uses the vector store name
+    collectionName: example-chroma
+
+    # Chroma server URL
+    # Default: http://localhost:8000
+    # Note: You need to run Chroma server separately
+    # Docker: docker run -p 8000:8000 chromadb/chroma
+    url: http://localhost:8000
+
+search:
+  defaultK: 4
+  scoreThreshold: 0.2
+
+metadata:
+  category: example
+  persistence: chroma

package/dist/templates/vectors/example.vector.yaml

@@ -0,0 +1,28 @@
+name: example
+description: Example vector store for semantic search
+
+source:
+  type: directory
+  path: vectors/sample-data
+  pattern: "*.txt"
+  recursive: false
+
+loader:
+  type: text
+
+splitter:
+  type: character
+  chunkSize: 1000
+  chunkOverlap: 200
+
+embedding: default  # References embedding config in llm.json
+
+store:
+  type: memory  # Use 'chroma' for production with persistent storage
+
+search:
+  defaultK: 4
+  scoreThreshold: 0.2
+
+metadata:
+  category: example

package/dist/templates/vectors/sample-data/example-document.txt

@@ -0,0 +1,15 @@
+Welcome to Agent Orchestrator
+
+This is an example document for the vector store.
+
+Agent Orchestrator is a TypeScript framework for building and orchestrating multi-agent AI systems with LangChain, Model Context Protocol (MCP), and vector store integration.
+
+Key Features:
+- Define agents using YAML configuration files
+- Create workflows that coordinate multiple agents
+- Integrate vector stores for RAG capabilities
+- Connect MCP servers for extended functionality
+- REST API for programmatic access
+
+You can add more documents to this directory to build your knowledge base.
+Each document will be chunked and embedded for semantic search.

package/dist/templates/workflows/example.workflow.yaml

@@ -0,0 +1,79 @@
+name: example-workflow
+description: A workflow demonstrating multi-agent orchestration with MCP, function, and vector tools
+version: "1.0.0"
+
+input:
+  schema:
+    topic:
+      type: string
+      required: true
+      description: The topic or question to process
+
+steps:
+  # Step 1: Get current East Coast time
+  - id: get-time
+    agent: time
+    input:
+      timezone: "America/New_York"
+    output:
+      key: current_time
+
+  # Step 2: Search the knowledge base for relevant information
+  - id: search-knowledge
+    agent: knowledge
+    input:
+      query: "{{input.topic}}"
+    output:
+      key: knowledge_result
+
+  # Step 3: Calculate the 10th Fibonacci number
+  - id: perform-calculation
+    agent: math
+    input:
+      query: "Calculate the 10th Fibonacci number"
+    output:
+      key: calculation_result
+
+  # Step 4: Summarize results with the example agent
+  - id: summarize
+    agent: example
+    input:
+      query: |
+        Summarize the following information:
+
+        Current East Coast USA Time:
+        {{steps.get-time.output}}
+
+        Topic: {{input.topic}}
+
+        Knowledge Base Results:
+        {{steps.search-knowledge.output}}
+
+        Fibonacci Calculation Results:
+        {{steps.perform-calculation.output}}
+
+        Provide a coherent summary combining these results, and make sure to include the current time.
+    output:
+      key: final_summary
+
+config:
+  timeout: 300000
+  onError: stop
+
+output:
+  timestamp: "{{steps.get-time.output}}"
+  knowledge: "{{steps.search-knowledge.output}}"
+  calculation: "{{steps.perform-calculation.output}}"
+  summary: "{{steps.summarize.output}}"
+
+metadata:
+  category: example
+  tags:
+    - demo
+    - workflow
+    - multi-agent
+    - function-tools
+    - vector-search
+    - mcp-tools
+    - time-api
+    - fibonacci

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "agent-orcha",
+  "version": "0.0.1",
+  "description": "TypeScript Agentic Orchestration http server and framework for building multi-agent workflows with MCP tools and vector stores",
+  "keywords": [
+    "ai",
+    "agents",
+    "llm",
+    "langchain",
+    "mcp",
+    "vector-store",
+    "rag",
+    "orchestrator",
+    "workflow",
+    "typescript",
+    "orca"
+  ],
+  "author": "David Dalcu <david.dalcu@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ddalcu/agent-orcha.git"
+  },
+  "type": "module",
+  "main": "dist/lib/index.js",
+  "types": "dist/lib/index.d.ts",
+  "bin": {
+    "agent-orcha": "./bin/cli.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc && npm run copy-assets",
+    "copy-assets": "mkdir -p dist && cp -r public dist/ && cp -r templates dist/",
+    "start": "node dist/src/index.js",
+    "prepublishOnly": "npm run build",
+    "lint": "eslint src lib --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx/esm --test test/**/*.test.ts"
+  },
+  "dependencies": {
+    "@fastify/cors": "^10.0.1",
+    "@fastify/static": "^8.0.4",
+    "@langchain/anthropic": "^1.3.10",
+    "@langchain/community": "^1.1.4",
+    "@langchain/core": "^1.1.15",
+    "@langchain/google-genai": "^2.1.10",
+    "@langchain/langgraph": "^1.1.0",
+    "@langchain/openai": "^1.2.2",
+    "@langchain/textsplitters": "^1.0.1",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "chromadb": "^1.9.2",
+    "dotenv": "^16.4.7",
+    "fastify": "^5.2.0",
+    "glob": "^11.0.0",
+    "langchain": "^1.2.10",
+    "openai": "^4.104.0",
+    "pino": "^10.2.1",
+    "pino-pretty": "^13.1.3",
+    "yaml": "^2.6.1",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "eslint": "^9.17.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}