Metadata-Version: 2.4
Name: chandan-cortex
Version: 0.1.0
Summary: Your personal AI assistant gateway. Simple. Powerful. Local-first. 🧠
Author: Cortex Contributors
License: MIT
Project-URL: Homepage, https://github.com/chandanhastantram/cortex
Project-URL: Documentation, https://github.com/chandanhastantram/cortex#readme
Project-URL: Repository, https://github.com/chandanhastantram/cortex
Project-URL: Issues, https://github.com/chandanhastantram/cortex/issues
Keywords: ai,assistant,gateway,chatbot,personal-ai,multi-channel
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
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.104.0
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: websockets>=12.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: click>=8.1
Requires-Dist: openai>=1.10.0
Requires-Dist: anthropic>=0.18.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: apscheduler>=3.10.0
Requires-Dist: prompt-toolkit>=3.0.0
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=20.7; extra == "telegram"
Provides-Extra: discord
Requires-Dist: discord.py>=2.3.0; extra == "discord"
Provides-Extra: slack
Requires-Dist: slack-bolt>=1.18.0; extra == "slack"
Provides-Extra: groq
Requires-Dist: groq>=0.4.0; extra == "groq"
Provides-Extra: all
Requires-Dist: python-telegram-bot>=20.7; extra == "all"
Requires-Dist: discord.py>=2.3.0; extra == "all"
Requires-Dist: slack-bolt>=1.18.0; extra == "all"
Requires-Dist: groq>=0.4.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <h1 align="center">🧠 Cortex</h1>
  <p align="center">
    <strong>Your personal AI assistant gateway. Simple. Powerful. Local-first.</strong>
  </p>
  <p align="center">
    <a href="#install">Install</a> ·
    <a href="#quick-start">Quick Start</a> ·
    <a href="#features">Features</a> ·
    <a href="#configuration">Configuration</a> ·
    <a href="#channels">Channels</a> ·
    <a href="#contributing">Contributing</a>
  </p>
</p>

---

Cortex is a personal AI assistant you run on your own machine. It comes with a beautiful web dashboard, connects to your messaging channels (Telegram, Discord, Slack), remembers your conversations, and tracks your tasks — all in one `pip install`.

> **Why Cortex?**  
> Existing open-source AI assistants are either too complex (24+ channels, 50+ config files, Docker/Tailscale required) or too simple (no memory, no dashboard, no channels). Cortex sits in the sweet spot: **powerful enough for real use, simple enough to set up in 60 seconds.**

## Install

```bash
pip install cortex-ai
```

Or install from source:

```bash
git clone https://github.com/chandanhastantram/cortex.git
cd cortex
pip install -e ".[all]"
```

## Quick Start

```bash
# 1. Create config (optional — works with env vars too)
cortex init

# 2. Set your API key
export OPENAI_API_KEY="sk-..."
# or: export ANTHROPIC_API_KEY="sk-ant-..."

# 3. Launch
cortex start
```

Open **http://localhost:3100** — that's it! 🚀

## Features

### 🎨 Beautiful Web Dashboard
Premium dark-mode chat UI with glassmorphism design, real-time streaming, conversation management, and markdown rendering.

### 🧠 Conversation Memory (RAG)
Every conversation is persisted in SQLite. Cortex uses TF-IDF search to recall relevant past conversations when answering new questions — your assistant actually **remembers**.

### 🤖 Multi-Model Support
Use any major AI provider with automatic failover:

| Provider | Models | How to use |
|----------|--------|------------|
| **OpenAI** | GPT-4o, GPT-4o-mini, GPT-4.5 | `OPENAI_API_KEY` |
| **Anthropic** | Claude Opus, Sonnet, Haiku | `ANTHROPIC_API_KEY` |
| **Ollama** | Llama, Mistral, Phi (local) | Set provider to `ollama` |

### 📬 Messaging Channels
Connect Cortex to your existing chat platforms:

- **Telegram** — `pip install cortex-ai[telegram]`
- **Discord** — `pip install cortex-ai[discord]`
- **Slack** — `pip install cortex-ai[slack]`
- **WebChat** — Built-in, always available

### ✅ Task Manager
Built-in task tracking with priorities, tags, and status tracking. Accessible from the dashboard sidebar and the REST API.

### 📊 Usage Analytics
Track token consumption, API costs, requests per model, and conversation statistics — all in the dashboard.

### 🔒 Security
- DM pairing policy (like OpenClaw) — unknown senders must be approved
- Auth token support for remote access
- Local-first — all data stays on your machine

### 🔍 Memory Search

```bash
# Search past conversations from CLI
cortex search "python async patterns"
```

### 🩺 Health Checks

```bash
cortex doctor
```

Validates your config, dependencies, API keys, and more.

## Architecture

```
Telegram / Discord / Slack / WebChat
        │
        ▼
┌─────────────────────────┐
│       Gateway            │
│   http://127.0.0.1:3100  │
│                          │
│  ┌─────────┐ ┌────────┐ │
│  │ Agent   │ │ Memory │ │
│  │ Runtime │ │ (RAG)  │ │
│  └────┬────┘ └────┬───┘ │
│       │           │      │
│  ┌────▼────┐ ┌────▼───┐ │
│  │ Models  │ │ Tasks  │ │
│  │ OpenAI  │ │ SQLite │ │
│  │ Claude  │ └────────┘ │
│  │ Ollama  │            │
│  └─────────┘            │
└─────────────────────────┘
```

## Configuration

Cortex uses YAML config with sensible defaults. Create one with:

```bash
cortex init
```

Minimal config (`~/.cortex/cortex.yaml`):

```yaml
model:
  provider: openai
  model: gpt-4o

memory:
  enabled: true

tasks:
  enabled: true
```

All settings can be overridden with environment variables:

| Env Variable | Config Path |
|-------------|-------------|
| `OPENAI_API_KEY` | `model.api_key` |
| `ANTHROPIC_API_KEY` | `model.api_key` |
| `CORTEX_PORT` | `gateway.port` |
| `TELEGRAM_BOT_TOKEN` | `channels.telegram.token` |
| `DISCORD_BOT_TOKEN` | `channels.discord.token` |

## Channels

### Telegram

```yaml
channels:
  telegram:
    enabled: true
    token: "123456:ABCDEF"  # Or set TELEGRAM_BOT_TOKEN
    dm_policy: pairing
```

### Discord

```yaml
channels:
  discord:
    enabled: true
    token: "your-bot-token"  # Or set DISCORD_BOT_TOKEN
    dm_policy: pairing
```

### WebChat

Always available at the gateway URL. No additional configuration needed.

## CLI Reference

| Command | Description |
|---------|-------------|
| `cortex start` | Start the gateway server |
| `cortex init` | Create example config file |
| `cortex doctor` | Run health checks |
| `cortex search "query"` | Search conversation memory |
| `cortex stats` | Show memory/usage statistics |
| `cortex --version` | Show version |

## API Reference

### REST API

| Endpoint | Method | Description |
|----------|--------|-------------|
| `GET /api/health` | GET | Health check + stats |
| `POST /api/chat` | POST | Send a chat message |
| `GET /api/conversations` | GET | List conversations |
| `GET /api/conversations/:id/messages` | GET | Get messages |
| `DELETE /api/conversations/:id` | DELETE | Delete conversation |
| `GET /api/tasks` | GET | List tasks |
| `POST /api/tasks` | POST | Create task |
| `PATCH /api/tasks/:id` | PATCH | Update task |
| `DELETE /api/tasks/:id` | DELETE | Delete task |
| `GET /api/memory/search?q=` | GET | Search memory |
| `GET /api/usage` | GET | Usage statistics |

### WebSocket

Connect to `ws://localhost:3100/ws/chat` for real-time streaming chat.

```json
// Send
{"action": "chat", "message": "Hello!", "conversation_id": null}

// Receive (streaming)
{"type": "token", "content": "Hello", "conversation_id": "abc123"}
{"type": "token", "content": "!", "conversation_id": "abc123"}
{"type": "done", "content": "Hello!", "model": "openai/gpt-4o", "latency_ms": 342}
```

## Comparison with OpenClaw

| Feature | OpenClaw | Cortex |
|---------|----------|--------|
| **Install** | `npm install -g openclaw` + onboarding wizard | `pip install cortex-ai` |
| **Language** | TypeScript (monorepo) | Python (single package) |
| **Channels** | 24+ | 5 (focused, plugin-based) |
| **Memory/RAG** | ❌ Session-only | ✅ Persistent with RAG search |
| **Web Dashboard** | WebChat only | Full dashboard + analytics |
| **Task Manager** | ❌ | ✅ Built-in |
| **Usage Analytics** | ❌ | ✅ Token costs + model stats |
| **Config** | JSON5 (complex) | YAML (simple) |
| **Dependencies** | Node 24+, pnpm, Docker | Python 3.10+ |
| **Lines of Code** | ~100K+ | ~2K |

## Roadmap

- [ ] Slack channel plugin
- [ ] WhatsApp (via Baileys bridge)
- [ ] Voice input/output (TTS/STT)
- [ ] Plugin/skill system
- [ ] Scheduled tasks (cron)
- [ ] Browser automation tool
- [ ] Mobile companion app
- [ ] OpenAPI spec generation

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

AI/vibe-coded PRs welcome! 🤖

## License

[MIT](LICENSE) — free for personal and commercial use.

---

<p align="center">
  Built with 🧠 by <a href="https://github.com/chandanhastantram">Chandan</a> and the community.
</p>
