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

cd helix
pip install -r requirements.txt

2. Configure

# 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

python run.py

Configuration

Environment Variables (.env)

OPENAI_API_KEY=sk-your-key-here
TELEGRAM_BOT_TOKEN=your-telegram-token

Config File (config/config.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

# Install Docker & Docker Compose
curl -fsSL https://get.docker.com | sh

Step 2: Download Helix

# 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

# Copy environment template
cp .env.example .env

# Edit with your values
nano .env

.env file:

# 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:

# 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!

# 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 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 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

# 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)

# Create service file
sudo nano /etc/systemd/system/helix.service

Service file content:

[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

# 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:

TELEGRAM_BOT_TOKEN=your-telegram-token
OPENAI_API_KEY=your-api-key-here

config/config.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:

# 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

# 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

# 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

# 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:

# 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)

# 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):

# 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.