Metadata-Version: 2.4
Name: helix-nox
Version: 1.0.4
Summary: Helix AI Agent — Self-hosted, provider-agnostic AI agent with memory, plugins, and CLI
Author-email: Nabil Karem <nabilkarem911@example.com>
License: MIT
Project-URL: Homepage, https://github.com/Nabilkarem911/Helix
Project-URL: Repository, https://github.com/Nabilkarem911/Helix.git
Project-URL: Issues, https://github.com/Nabilkarem911/Helix/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: aiofiles>=23.0
Requires-Dist: openai>=1.0
Requires-Dist: anthropic>=0.20
Requires-Dist: litellm>=1.0
Requires-Dist: chromadb>=0.4
Requires-Dist: python-telegram-bot>=20.0
Requires-Dist: gtts>=2.3.0
Requires-Dist: pydub>=0.25
Requires-Dist: paramiko>=3.0
Requires-Dist: aiohttp>=3.9
Requires-Dist: pillow>=10.0
Requires-Dist: pytesseract>=0.3
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: google-api-python-client>=2.100.0
Requires-Dist: google-auth-httplib2>=0.2.0
Requires-Dist: google-auth-oauthlib>=1.1.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn>=0.29.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: cryptography>=41.0
Requires-Dist: rich>=13.0
Requires-Dist: pyreadline3>=3.4

# Helix AI Agent 🌊

A self-hosted, provider-agnostic AI Agent Framework that learns, remembers, and adapts to each user.

## Phase 1: Core Foundation ✅

### Features
- ✅ **Provider-Agnostic**: Works with OpenAI, Anthropic, Ollama, or any OpenAI-compatible API
- ✅ **Self-Hosted**: User owns all data (local ChromaDB)
- ✅ **Memory**: Conversation history with ChromaDB vector storage
- ✅ **Onboarding**: Personality formation through first conversation
- ✅ **Telegram**: Full Telegram bot interface

## Phase 2: Smart Memory ✅

### Features
- ✅ **Memory Compression**: Summarizes long conversations to reduce token usage
- ✅ **Smart Context Retrieval**: Semantic search for relevant facts
- ✅ **Token Tracking**: Cost monitoring and budget alerts
- ✅ **Error Learning**: Tracks mistakes and learns to avoid them
- ✅ **Auto Fact Extraction**: Automatically extracts user facts from conversations

## Phase 3: Tools & Safety ✅

### Features
- ✅ **Safe SSH Client**: Remote server management with approval system
- ✅ **File Operations**: Read/write with sandbox and backup
- ✅ **API Caller**: Generic HTTP client for external APIs
- ✅ **Obedience Engine**: Safety layer for dangerous operations
- ✅ **Docker Support**: Production-ready containerization

## Phase 4: Voice & Production Polish ✅

### Features
- ✅ **Voice Input**: Whisper API (cloud-based) + Nemotron ASR (local fallback)
- ✅ **Health Monitoring**: System health checks for all components
- ✅ **Production Logging**: Advanced logging with rotation
- ✅ **Rate Limiting**: Request throttling protection
- ✅ **Complete Documentation**: Full deployment guides

## Phase 5: Vision & OCR ✅

### Features
- ✅ **Image OCR**: Extract text from images using EasyOCR (Arabic + English)
- ✅ **Image Processing**: Automatic resize, format conversion
- ✅ **Async Processing**: Non-blocking with timeout protection
- ✅ **Memory Persistence**: Fixed CHROMA_PATH environment variable

## Phase 6: Plugin Architecture ✅ (Complete)

### Features
- ✅ **Dynamic Plugins**: Load features without restart
- ✅ **Plugin Registry**: Easy install/uninstall
- ✅ **Hot Reload**: Enable/disable on the fly
- ✅ **Safe Mode**: Plugins can't break core
- ✅ **5 Active Plugins**: OCR, Voice, SSH, Web Search, File Ops

### Available Plugins

| Plugin | Status | Description |
|--------|--------|-------------|
| **ocr** | ✅ Ready | Extract text from images |
| **voice** | ✅ Ready | Speech-to-text with Whisper |
| **ssh** | 🔄 Ready | Remote server management |
| **memory** | ✅ Ready | ChromaDB conversation storage |
| **file_ops** | ✅ Ready | Safe file read/write |
| **web_search** | ✅ Ready | Search the web |
| **code_exec** | 🔴 Planned | Safe code execution |

### Quick Start

#### 1. Clone and Setup
```bash
cd helix
pip install -r requirements.txt
```

#### 2. Configure
```bash
# Copy example files
cp .env.example .env
cp config/config.example.yaml config/config.yaml

# Edit .env with your API keys
nano .env
```

#### 3. Run
```bash
python run.py
```

### Configuration

#### Environment Variables (.env)
```bash
OPENAI_API_KEY=sk-your-key-here
TELEGRAM_BOT_TOKEN=your-telegram-token
```

#### Config File (config/config.yaml)
```yaml
providers:
  default: "openai"  # or "anthropic", "ollama"
  
agent:
  language: "ar"     # or "en"
```

---

## 🚀 Deployment Guide

### Method 1: Docker Compose (Recommended for Beginners)

The easiest way to deploy Helix on any server with Docker support.

#### Step 1: Prepare Your Server
```bash
# Install Docker & Docker Compose
curl -fsSL https://get.docker.com | sh
```

#### Step 2: Download Helix
```bash
# Clone the repository
git clone https://github.com/Nabilkarem911/Helix.git
cd Helix

# Or just download the files you need:
# - docker-compose.yml
# - docker/Dockerfile
# - .env.example
```

#### Step 3: Configure Environment
```bash
# Copy environment template
cp .env.example .env

# Edit with your values
nano .env
```

**.env file:**
```bash
# Required: Telegram Bot Token (get from @BotFather)
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxyz

# Required: At least one LLM provider
OPENAI_API_KEY=sk-your-openai-key-here
# Or: ANTHROPIC_API_KEY=sk-ant-your-key-here

# Optional: Settings
DEFAULT_PROVIDER=openai
ENABLE_COMPRESSION=false

# Phase 4: Enable Voice (optional)
ENABLE_VOICE=false
ASR_MODEL_PATH=./models/nemotron-3.5-asr-q4_0.gguf
```

#### Optional: Voice Setup (Phase 4)

To enable voice message support:

```bash
# 1. Download Nemotron ASR model
mkdir -p models
cd models
wget https://huggingface.co/mudler/parakeet-cpp-gguf/resolve/main/nemotron-3.5-asr-q4_0.gguf

# 2. Enable in config
echo 'ENABLE_VOICE=true' >> .env

# 3. Restart Helix
docker-compose restart
```

**Features:**
- 🎤 40+ languages supported
- 🧠 0.6B parameters (lightweight)
- 💻 CPU-only (no GPU needed)
- ⚡ 2.5x faster than NVIDIA NeMo

#### Step 4: Deploy!
```bash
# Start Helix
docker-compose up -d

# Check logs
docker-compose logs -f helix

# Stop Helix
docker-compose down

# Update to new version
git pull
docker-compose down
docker-compose up -d --build
```

---

### Method 2: Dokploy (One-Click Deployment)

Deploy on [Dokploy](https://dokploy.com) or similar platforms (Railway, Coolify, etc.)

#### Step 1: Fork/Clone Repository
Fork this repo to your GitHub account.

#### Step 2: Connect to Dokploy
1. Log in to Dokploy dashboard
2. Click "Create Service" → "Template"
3. Select "Docker Compose"
4. Connect your GitHub account
5. Choose the forked Helix repository

#### Step 3: Add Environment Variables
In Dokploy dashboard, add these environment variables:

| Variable | Value | Required |
|----------|-------|----------|
| `TELEGRAM_BOT_TOKEN` | Your bot token | ✅ Yes |
| `OPENAI_API_KEY` | Your OpenAI key | ✅* |
| `ANTHROPIC_API_KEY` | Your Anthropic key | ✅* |
| `DEFAULT_PROVIDER` | `openai` or `anthropic` | No (default: openai) |

\* At least one provider key required

#### Step 4: Deploy
Click "Deploy" and wait for build to complete.

Helix will start automatically and connect to Telegram.

📖 **Detailed Guide:** See [DOKPLOY_DEPLOY.md](DOKPLOY_DEPLOY.md) for complete step-by-step instructions with troubleshooting.

---

### Method 3: Manual Installation (Advanced)

For servers without Docker or custom setups.

#### Requirements
- Python 3.11+
- pip
- git

#### Installation Steps
```bash
# 1. Clone repository
git clone https://github.com/Nabilkarem911/Helix.git
cd Helix

# 2. Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or: venv\Scripts\activate  # Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Install as command (optional, for CLI mode)
pip install -e .

# 5. Configure
cp .env.example .env
# Edit .env and add your API keys

# 6. Run — choose your mode:
python run.py                           # Telegram mode (default)
python run.py --interface api           # HTTP API only
python run.py --interface both          # Telegram + API
python run.py --cli                     # Interactive CLI mode

# Or if you installed with pip install -e .:
helix --cli                             # CLI in any directory
helix --interface telegram              # Telegram bot
helix --interface api                   # API server
helix --interface both                  # Both Telegram + API
```

#### Using Systemd (Linux Servers)
```bash
# Create service file
sudo nano /etc/systemd/system/helix.service
```

**Service file content:**
```ini
[Unit]
Description=Helix AI Agent
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/Helix
Environment=PYTHONUNBUFFERED=1
ExecStart=/path/to/Helix/venv/bin/python run.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

```bash
# Enable and start service
sudo systemctl enable helix
sudo systemctl start helix

# Check status
sudo systemctl status helix
sudo journalctl -u helix -f
```

---

### Method 4: Custom API Proxy (Orcanox, etc.)

Use a unified API proxy that combines multiple providers.

**.env:**
```bash
TELEGRAM_BOT_TOKEN=your-telegram-token
OPENAI_API_KEY=your-api-key-here
```

**config/config.yaml:**
```yaml
providers:
  default: "openai"
  openai:
    api_key: "${OPENAI_API_KEY}"
    base_url: "https://api.orcanox.xyz/v1"  # Custom proxy URL
    model: "gpt-4o"
    temperature: 0.7
```

---

### Post-Deployment: Verify Installation

After deployment, verify everything works:

```bash
# Check container is running
docker ps | grep helix

# Check logs
docker-compose logs helix

# Test Telegram bot
# 1. Open Telegram
# 2. Find your bot (by username you created with @BotFather)
# 3. Send /start
# 4. You should receive welcome message
```

### Updating Helix

```bash
# Using Docker Compose
cd /path/to/Helix
git pull                    # Get latest code
docker-compose down        # Stop old version
docker-compose up -d --build  # Build and start new version

# Using manual installation
git pull
source venv/bin/activate
pip install -r requirements.txt  # In case deps changed
python run.py
```

---

### Troubleshooting

#### Container keeps restarting
```bash
# Check logs for errors
docker-compose logs helix

# Common issues:
# 1. Missing TELEGRAM_BOT_TOKEN
# 2. Invalid API key
# 3. Network issues
```

#### Bot not responding in Telegram
1. Check bot token is correct in .env
2. Verify bot is started with @BotFather
3. Check logs: `docker-compose logs -f helix`
4. Try sending /start again

#### Permission denied errors
```bash
# Fix data directory permissions
sudo chown -R $USER:$USER ./data
# Or for Docker:
sudo chown -R 1000:1000 ./data
```

---

### Architecture

```
helix/
├── helix_core/              # Core system (lightweight)
│   ├── config_loader.py     # Pydantic config
│   ├── core.py               # Main orchestrator
│   ├── providers/            # LLM providers
│   │   ├── openai_provider.py
│   │   ├── anthropic_provider.py
│   │   └── router.py
│   ├── memory/               # ChromaDB storage
│   │   └── chroma_store.py
│   ├── plugins/              # ✅ Plugin system (Phase 6)
│   │   ├── manager.py
│   │   └── base.py
│   └── safety/               # Security layer
│       └── obedience.py
├── plugins/                  # 🔄 Dynamic plugins
│   ├── ocr/                  # ✅ Phase 5
│   ├── voice/                # ✅ Phase 4
│   └── web_search/           # 🔴 Planned
├── interfaces/
│   └── telegram_bot.py       # Telegram interface
├── docker/
│   └── Dockerfile
├── docker-compose.yml
├── config/
│   └── config.example.yaml
├── README.md
└── requirements.txt
```

### Usage

#### First Conversation (Onboarding)
When user first messages the bot:
```
User: Hello!
Helix: Hello! I'm Helix, your AI companion. 🌟

To get started, I'd love to know:
1. What would you like to name me?
2. How would you describe my role?

Just reply with something like: "Name me Sara, you're my assistant"

User: Name me Luna, you're my friend
Helix: Perfect! I'm now Luna, your friend. How can I help you?
```

#### Commands

| Command | Description |
|---------|-------------|
| `/start` | Start conversation |
| `/help` | Show help |
| `/stats` | Memory, learning & tools statistics |
| `/tokens` | Detailed token usage & cost report |
| `/lessons` | Learned lessons from past errors |
| `/clear` | Clear conversation history |
| `/memory` | Show stored user facts |
| `/remind` | Set a reminder |
| `/monitor` | Server health monitoring |
| `/plugins` | Manage plugins (list, enable, disable) |
| `/connect` | Connect to SSH server |
| `/exec` | Execute SSH command |
| `/servers` | List connected servers |
| `/search` | Web search |
| `/read` | Read a file from server |
| `/write` | Write a file to server |
| `/ls` | List files on server |
| `/skills` | Manage knowledge base skills |
| `/alert` | Smart monitoring alerts |
| `/approve` | Approve a dangerous command |
| `/reject` | Reject a dangerous command |
| `/pending` | List pending approvals |
| `/stop` | Cancel current operation |

**CLI Mode (`helix --cli`):**
| Command | Description |
|---------|-------------|
| `/tree [depth]` | Show project file tree |
| `/read <file>` | Read file with syntax highlight |
| `/ls [dir]` | List files |
| `/undo` | Undo last file edit |
| `/history` | Show edit history |
| `/diff` | Show pending edits |
| `/approve [id]` | Approve file edit |
| `/reject [id]` | Reject file edit |

#### CLI Mode (Phase 7)

Run Helix directly in your terminal with project awareness:

```bash
# 1. Clone the repo
git clone https://github.com/Nabilkarem911/Helix.git
cd Helix

# 2. Install dependencies
pip install -r requirements.txt

# 3. Install as command (one-time)
pip install -e .

# 4. Configure your API key
cp .env.example .env
# Edit .env and add your keys

# 5. Start CLI in any project directory
cd /path/to/your-project
helix --cli
# or without installing: python run.py --cli
```

**Interactive terminal features:**
- 🗂️ Project scanner — auto-detects type (Python, Node, etc.)
- 📁 File tree — `/tree` shows project structure
- 📖 Syntax-highlighted file reading — `/read src/app.py`
- 📝 Safe editing — diff preview + approval gate before any file change
- ↩️ Undo stack — `/undo` reverts last edit
- 🧠 Shared memory — same profile from Telegram

```
$ helix --cli
╔═══════════════════════════════════════╗
║     🌊 H E L I X  C L I               ║
╚═══════════════════════════════════════╝

🌀 Helix — your developer
Project: my-project (python)
✓ Found 42 files

> /read main.py
📄 main.py
  1 | import os
  2 | def main():
  ...

> add logging to main.py
🌀 Helix: I'll add logging. Here's the diff:
--- a/main.py
+++ b/main.py
+ import logging
...

Approve this edit? [y/n]: y
✓ Edited main.py

> /exit
🌀 Goodbye!
```

#### Natural Language Triggers
- **Learn skills**: "اتعلمي [URL]" or "learn [URL]"
- **Set alerts**: "نبهيني لو CPU وصل 90%" or "alert me if..."
- **Ask for commands**: "ايه الاوامر" or "what commands" → shows full list
- **Voice**: Send voice message for transcription
- **Photos**: Send image for GPT-4o vision analysis

### Providers Supported

| Provider | Status | Notes |
|----------|--------|-------|
| OpenAI | ✅ Ready | GPT-4, GPT-4o-mini, etc. |
| Anthropic | ✅ Ready | Claude 3 Haiku, Sonnet, etc. |
| Ollama | ✅ Ready | Local models (Llama, etc.) |

### Roadmap

- **Phase 1** ✅: Core Foundation (Provider-agnostic, Memory, Telegram)
- **Phase 2** ✅: Smart Memory (Compression, Token tracking, Error learning)
- **Phase 3** ✅: Tools (SSH, files), Safety layer, Docker
- **Phase 4** ✅: Voice (Whisper API + Nemotron), Health monitoring
- **Phase 5** ✅: Vision OCR (EasyOCR), Memory persistence fix
- **Phase 6** ✅: Plugin Architecture (dynamic loading, hot reload, dependency management)
- **Phase 7** ✅: CLI Mode (interactive terminal, project awareness, diff preview, undo)

## Project Status

Helix is a **production-ready AI Agent Framework** with:
- 🤖 Multi-provider LLM support
- 🧠 Persistent memory with ChromaDB
- 🛠️ Safe tool execution
- 🎤 Voice input capability
- 👁️ OCR for images
- 🐳 Docker deployment
- 📊 Health monitoring
- 💻 Interactive CLI with project awareness & diff preview

### Quick Feature Toggle (via Environment Variables)

```bash
# Core (Required)
TELEGRAM_BOT_TOKEN=your-token
OPENAI_API_KEY=your-key

# Features (Optional)
ENABLE_VOICE=true          # Voice messages
ENABLE_OCR=true            # Image text extraction
ENABLE_SSH=false           # Remote server access
ENABLE_FILE_OPS=false      # File management
```

---

## ⚠️ Security Notice

**Helix can execute system commands when enabled.**

### Safety Features:
- ✅ **Approval System**: Destructive actions require manual approval
- ✅ **Sandbox**: File operations restricted to allowed paths
- ✅ **Dry-run Mode**: Preview SSH commands before execution
- ✅ **Audit Log**: All actions are logged

### Enable Tools (Optional):
```yaml
# config/config.yaml
tools:
  ssh:
    enabled: true
    require_approval: true
    allowed_hosts: ["trusted-server.com"]
  
  file_ops:
    enabled: true
    allowed_paths: ["./data/"]
```

**Warning**: Only enable tools if you trust the LLM and understand the risks. SSH/file operations can damage your system.

## License
MIT License - Self-hosted for everyone.
