# 🧠 Cortex Hub: Autonomous AI Agent Mesh & Orchestrator

Cortex Hub is a state-of-the-art, modular AI orchestration platform that bridges the gap between Large Language Models (LLMs) and local execution via a distributed **Agent Node Mesh**. It features a modern React-based workspace, a powerful **Skill System**, and advanced **RAG** (Retrieval-Augmented Generation) capabilities.

## ✨ Key Features

*   **🌐 Distributed Agent Mesh**: Connect multiple local or remote nodes (Linux, macOS, Windows) to your Hub. Each node can execute tasks, manage files, and provide terminal access.
*   **🌍 Dedicated Browser Service**: High-performance browser automation (Playwright) running as a dedicated system service. Centralized execution for reduced latency and reduced node footprint.
*   **🛠️ Extensible Skill System**: Orchestrate AI capabilities via "Skills" (Terminal Control, File Management, System Analysis). Dynamic permissioning allows granular control over which users or groups can access specific nodes and skills.
*   **📂 Private RAG Pipeline**: Securely ingest documents into a FAISS vector store to ground AI responses in factual, local data.
*   **🔐 Industrial-Grade Security**: Integrated with OIDC (OpenID Connect) for secure user authentication and Role-Based Access Control (RBAC). 
*   **🖥️ Unified Command Center**: A sleek, premium React frontend for managing sessions, configuring nodes, and monitoring the swarm in real-time.

---

## 💬 How to Use

### 1. Connecting Nodes
Download the **Agent Node Bundle** from the "Nodes" page in the dashboard. Unzip and run `./run.sh` (Linux/macOS) or `run.bat` (Windows). The node will automatically connect to your Hub using the pre-configured security token.

### 2. Using Skills
Skills like **Browser Automation** and **Terminal Control** are available directly in your chat sessions. You can attach specific nodes to a session to give the AI hands-on access to those environments.

---

## 🚀 Quick Start (Local Development)

The easiest way to get started is using the pre-configured **Dev Container** or local Docker Compose.

### Prerequisites
*   **Docker** & **Docker Compose**
*   **Python 3.11+** (if running without Docker)
*   **Node.js 18+** (for frontend development)

### 1. Configure Secrets
Copy the example environment file and add your API keys (Gemini, OpenAI, etc.):
```bash
cp .env.example .env
```

### 2. Launch the Stack
Initialize the Hub (Backend, Frontend, and Database) in one command:
```bash
docker compose up -d --build
```
*   **Frontend**: [http://localhost:8002](http://localhost:8002)
*   **API Docs**: [http://localhost:8000/docs](http://localhost:8000/docs)

---

## 🏗️ Deployment Architecture

Cortex Hub uses a layered deployment strategy to keep the core codebase clean while supporting specific production environments.

### 📂 Folder Structure
*   **`ai-hub/`**: The Core Python (FastAPI) backend.
*   **`frontend/`**: The React-based unified dashboard.
*   **`agent-node/`**: The lightweight client software for distributed nodes.
*   **`skills/`**: Source for AI capabilities (Shell, Browser, etc.).
*   **`deployment/`**: Environment-specific overrides (e.g., `jerxie-prod` with NFS support).
*   **`scripts/`**: Centralized automation for sync, rebuilding, and maintenance.

### 🚢 Production Deployment
For Jerxie AI production instances, we use the centralized remote deployer:
```bash
# Sync local changes and rebuild on the production server
REMOTE_PASS='<PASSWORD>' bash scripts/remote_deploy.sh
```

---

## 🏛️ Project Layout

```text
.
├── ai-hub/             # Backend API & Orchestrator
├── ui/                 # Frontend Workspace (React)
├── agent-node/         # Distributed Node Client (Lightweight)
├── browser-service/    # Dedicated Browser Automation Service (Playwright)
├── skills/             # AI Skill Definitions
├── deployment/         # Env Overrides (NFS, SSL, OIDC)
├── scripts/            # CI/CD & Maintenance Scripts
├── cortex.db           # Local SQLite Cache
└── docker-compose.yml  # Generic Development Entrypoint
```

## 🧪 Testing

*   **Backend**: `pytest ai-hub/tests/`
*   **Frontend Health**: `scripts/frontend_tester`
*   **Connectivity**: `scripts/test_ws.js`

---

## ⚖️ License
Distributed under the MIT License. See `LICENSE` for more information.
