Relevant source files

The following files were used as context for generating this wiki page: - [README.md](https://github.com/Trancendos/cornelius-ai/blob/main/README.md) - [package.json](https://github.com/Trancendos/cornelius-ai/blob/main/package.json) - [tsconfig.json](https://github.com/Trancendos/cornelius-ai/blob/main/tsconfig.json) - [src/index.ts](https://github.com/Trancendos/cornelius-ai/blob/main/src/index.ts) - [src/config/env.ts](https://github.com/Trancendos/cornelius-ai/blob/main/src/config/env.ts) - [src/api/server.ts](https://github.com/Trancendos/cornelius-ai/blob/main/src/api/server.ts) - [src/orchestration/orchestrator.ts](https://github.com/Trancendos/cornelius-ai/blob/main/src/orchestration/orchestrator.ts) - [src/routing/nexus-router.ts](https://github.com/Trancendos/cornelius-ai/blob/main/src/routing/nexus-router.ts)

# Quick Start & Setup Cornelius-AI serves as the Master AI Orchestrator within the Trancendos Industry 6.0 platform. Its primary purpose is to manage a 24-agent mesh by analyzing user intent, delegating tasks to specialized agents, and managing inter-agent consensus. The system exposes these capabilities through REST, WebSocket, and the Model Context Protocol (MCP). The setup process involves configuring environment variables for server operations, security (IAM), and LLM integration, followed by a standard Node.js build and execution cycle. Once running, the system initializes an agent registry and starts the Nexus Ant Colony Optimization (ACO) routing engine to manage communication across the mesh. Sources: [README.md:1-12](), [src/index.ts:1-14]() ## Installation and Commands The project requires Node.js (version 20 or higher) and uses `npm` for dependency management. | Command | Description | |---------|-------------| | `npm install` | Installs project dependencies defined in `package.json`. | | `npm run dev` | Starts the development server with hot-reload via `tsx`. | | `npm run build` | Compiles TypeScript source code to the `dist` directory. | | `npm start` | Executes the compiled production build from `dist/index.js`. | | `npm run typecheck` | Runs the TypeScript compiler without emitting files to verify types. | | `npm test` | Runs the test suite using `vitest`. | Sources: [package.json:7-14](), [package.json:44-46](), [README.md:143-158]() ## Configuration (Environment Variables) Cornelius uses a centralized configuration system validated with Zod. Settings are typically loaded from a `.env` file. ### Core Server Settings | Variable | Type | Default | Description | |----------|------|---------|-------------| | `PORT` | Number | `4000` | The port the HTTP/WS server listens on. | | `HOST` | String | `0.0.0.0` | The host address for the server. | | `NODE_ENV` | Enum | `development` | Options: `development`, `production`, `test`. | | `ALLOWED_ORIGINS`| String | `http://localhost:3000...` | CORS allowed origins. | Sources: [src/config/env.ts:13-18](), [src/config/env.ts:46-47]() ### AI & Orchestration Settings | Variable | Type | Default | Description | |----------|------|---------|-------------| | `LLM_PROVIDER` | Enum | `none` | Options: `openai`, `anthropic`, `local`, `none`. | | `LLM_MODEL` | String | `gpt-4o-mini` | The model used for intent classification. | | `MCP_ENABLED` | Boolean | `true` | Enables/disables the Model Context Protocol server. | | `INFINITY_PORTAL_URL`| URL | `http://localhost:8000` | Backend URL for Infinity Portal integration. | Sources: [src/config/env.ts:25-29](), [src/config/env.ts:42-43](), [README.md:167-171]() ### Routing & Mesh Settings | Variable | Type | Default | Description | |----------|------|---------|-------------| | `ACO_EVAPORATION_RATE`| Number | `0.1` | Pheromone decay rate for Nexus ACO routing. | | `ACO_REINFORCEMENT_FACTOR`| Number | `0.3` | Success reinforcement factor for routing. | | `MESH_ROUTING_PROTOCOL`| Enum | `static_port` | Options: `static_port`, `mdns`, `consul`, `semantic_mesh`. | Sources: [src/config/env.ts:37-39](), [src/routing/nexus-router.ts:246-258]() ## System Bootstrap Process The bootstrap sequence initializes the core modules in a specific order to ensure agent availability before the API becomes accessible. ```mermaid flowchart TD Start([Bootstrap Start]) --> Registry[Load Agent Registry] Registry --> Nexus[Register Agents with Nexus Router] Nexus --> ACO[Start Pheromone Evaporation Cycle] ACO --> MCP{MCP Enabled?} MCP -- Yes --> MCP_Init[Initialize MCP Server] MCP -- No --> Server[Initialize HTTP + WS Server] MCP_Init --> Server Server --> Listen[Listen on PORT:HOST] Listen --> Ready([System Ready]) ``` The bootstrap logic (found in `src/index.ts`) ensures that the 24-agent mesh is active and registered with the Nexus Router before the server begins accepting requests. It also sets up interval timers (every 60 seconds) for ACO pheromone evaporation. Sources: [src/index.ts:30-67](), [src/routing/nexus-router.ts:121-131]() ## Connectivity & Endpoints Once setup is complete, the following interfaces are available: ### Service URLs - **REST API:** `http://:/api/v1` - **WebSocket:** `ws://:/ws` - **Health Check:** `http://:/health` - **MCP Info:** `http://:/api/v1/mcp/info` Sources: [src/index.ts:70-75]() ### WebSocket Interaction Flow The WebSocket server facilitates real-time orchestration and mesh heartbeat updates. ```mermaid sequenceDiagram participant Client participant WS as "WebSocket Server" participant Orch as "Orchestrator" Client->>WS: Connect to /ws WS-->>Client: Send initial mesh_status Note over Client, WS: Subscription Client->>WS: Send { "type": "subscribe_mesh" } WS-->>Client: Send { "type": "subscribed" } Note over Client, WS: Execution Client->>WS: Send { "type": "orchestrate", "prompt": "..." } WS->>Orch: orchestrate(prompt) Orch-->>WS: Return result WS-->>Client: Send { "type": "orchestration_result" } loop Every 30 seconds WS-->>Client: Broadcast mesh_heartbeat end ``` Sources: [src/api/server.ts:340-388]() ## Security Setup (IAM) The system implements the Trancendos 2060 Security Standard. Setup requires a `JWT_SECRET` for HS512 token verification. Access is controlled via Role-Based Access Control (RBAC) and privilege levels. - **Integrity:** Uses SHA-512 hashes for audit trails. - **Middleware:** The `requireIAMLevel(maxLevel)` middleware protects sensitive endpoints. - **Headers:** All responses include `X-Service-Id` and `X-Mesh-Address`. Sources: [src/api/server.ts:25-89](), [SECURITY.md:10-18]() ## Summary Setting up Cornelius-AI requires a Node.js 20+ environment and proper configuration of the `.env` file to define LLM providers and routing parameters. The system automatically initializes the agent registry and Nexus routing engine during the bootstrap phase. Developers can interact with the orchestrator through the REST API, persistent WebSocket connections for real-time updates, or the Model Context Protocol for tool-based LLM integration. Sources: [src/index.ts:30-67](), [README.md:143-158](), [src/config/env.ts:1-10]()