# 🧠 Cortex Pack — Documentation

## What It Is

Cortex Pack wraps any small local LLM (3B–8B parameters) with a pipeline that makes it perform like a much larger model. It connects to any OpenAI-compatible API (LM Studio, Ollama, vLLM, llama.cpp) and adds:

- **Tool-Use** — code interpreter, web search, calculator
- **Self-Critique** — 2-pass generate → review → rewrite
- **JSON Mode** — structured output enforcement
- **RAG** — query your own documents
- **Anti-Loop** — 5-layer loop detection and break
- **Memory** — persistent facts across sessions
- **HTTP API** — REST endpoint for any agent framework

## Quick Install

```bash
# From downloaded pack:
bash quickstart.sh

# Or manually:
tar xzf cortex-pack-v1.0.0.tar.gz
cd cortex-pack-v1.0.0
bash install.sh
```

## Usage

### CLI Mode (any terminal)

```bash
# Check setup
cortex --info

# Basic chat
cortex "What is the capital of France?"

# Tool use (code interpreter for math)
cortex --tools "Calculate 583 * 947"

# Self-critique (2-pass accuracy)
cortex --critique "Explain TCP vs UDP"

# JSON mode (structured output)
cortex --json 'Extract name and age from "John Smith, 34"'

# RAG mode (query your documents)
cortex --rag --rag-dir ./my-docs "What does the contract say?"

# Everything at once
cortex --tools --critique --rag "Based on my docs, calculate the total"

# Interactive chat
cortex --tools --critique --interactive
```

### HTTP API Mode (for any agent framework)

```bash
# Start the API server
cortex --serve --port 9090

# Then from any agent or script:
curl -X POST http://localhost:9090/v1/chat \
  -H 'Content-Type: application/json' \
  -d '{"message": "Calculate 583 * 947"}'

# Response:
# {"response": "552101", "model": "qwen3-4b"}
```

**Available endpoints:**

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/chat` | POST | Send a message, get a response |
| `/v1/health` | GET | Health check + model info |
| `/v1/info` | GET | Full pipeline status as JSON |
| `/v1/reset` | POST | Reset conversation history |
| `/v1/ingest` | POST | Ingest files into RAG |

### Python Module (import in your own code)

```python
from cortex_chat import CortexPipeline

# Create a pipeline
p = CortexPipeline(
    api_url="http://localhost:1234/v1",
    model="qwen3-4b",
    use_tools=True,
    use_critique=True
)

# Chat
response = p.chat("Calculate 583 * 947")
print(response)
# → "The result is 552101"

# Use individual components
from cortex_chat import CodeInterpreter, AntiLoop

interp = CodeInterpreter()
result = interp.run_and_format("print('hello world')")
print(result)  # → "hello world"
```

### Hermes Agent Integration

The pack includes 7 Hermes Agent skills. If you used `install.sh`, they're already in your profile:

```
~/.hermes/profiles/<profile>/skills/
├── cortex-tool-use/
├── cortex-self-critique/
├── cortex-code-interp/
├── cortex-json-mode/
├── cortex-rag/
├── cortex-memory/
└── cortex-anti-loop/
```

Load a skill:
```python
skill_view("cortex-tool-use")
```

Or use the HTTP API:
```python
# Start server: cortex --serve --port 9090
# Hermes can now call:
termainal("curl -X POST http://localhost:9090/v1/chat -d '{\"message\": \"...\"}'")
```

## Configuration

Set environment variables or create `~/.cortex/config.json`:

```bash
export CORTEX_API_URL="http://localhost:1234/v1"
export CORTEX_MODEL="qwen_qwen3-4b-thinking-2507"
export CORTEX_DIR="$HOME/.cortex"
```

## Requirements

- **Python 3.10+**
- **Any LLM** with an OpenAI-compatible API:
  - LM Studio → `http://localhost:1234/v1`
  - Ollama → `http://localhost:11434/v1`
  - vLLM → `http://localhost:8000/v1`
  - llama.cpp → `http://localhost:8080/v1`
- **pip install requests** (optional: `duckduckgo-search` for web search)

## What's Included

```
cortex-pack-v1.0.0/
├── install.sh                  # One-command install
├── quickstart.sh               # Quick install script
├── package.json                # Machine-readable manifest
├── README.md                   # This file
├── scripts/
│   ├── cortex_chat.py          # Core engine (importable module)
│   └── cortex-chat.py          # CLI wrapper
├── skills/                     # 7 Hermes Agent skills
├── prompts/                    # Battle-tested prompt templates
├── configs/                    # Pre-baked backend configs
└── examples/                   # Runnable demo scripts
```

## Support

- GitHub Issues: https://github.com/aireck/cortex-pack/issues
- Discord: [link]
- Email: [email]