kv-ai/USER_MANUAL.md

# Companion AI - User Manual

A practical guide to running and using your personal AI companion.

---

## Quick Start (5 minutes)

### Option 1: Docker (Recommended)

```bash
# 1. Clone and enter directory
git clone https://github.com/santhoshjan/companion.git
cd companion

# 2. Edit config.json - set your vault path
nano config.json
# Change: "path": "/home/yourname/KnowledgeVault/Default"

# 3. Start everything
docker-compose up -d

# 4. Open the UI
open http://localhost:5173
```

### Option 2: Manual Install

```bash
# Install dependencies
pip install -e ".[dev]"

# Run the API
python -m uvicorn companion.api:app --host 0.0.0.0 --port 7373
```

---

## Configuration

Before first use, edit `config.json`:

```json
{
  "vault": {
    "path": "/path/to/your/obsidian/vault"
  }
}
```

**Required paths to set:**
- `vault.path` - Your Obsidian vault directory
- `rag.vector_store.path` - Where to store embeddings (default: `~/.companion/vectors`)
- `companion.memory.persistent_store` - Conversation history (default: `~/.companion/memory.db`)

---

## Indexing Your Vault

The system needs to index your vault before it can answer questions.

### One-time Full Index

```bash
# Using Python module
python -m companion.indexer_daemon.cli index

# Or with Docker
docker-compose exec companion-api python -m companion.indexer_daemon.cli index
```

**Output:**
```
Running full index...
Done. Total chunks: 12,847
```

### Continuous File Watching

```bash
# Auto-sync when files change
python -m companion.indexer_daemon.watcher
```

**What it does:**
- Monitors your vault for changes
- Automatically re-indexes modified files
- Debounced (5-second delay to batch rapid changes)

### Check Index Status

```bash
python -m companion.indexer_daemon.cli status
```

**Output:**
```
Total chunks: 12,847
Indexed files: 847
Unindexed files: 3
```

### Incremental Sync

```bash
# Sync only changed files
python -m companion.indexer_daemon.cli sync
```

**When to use:**
- After editing a few notes
- Faster than full re-index
- Keeps vector store updated

---

## Using the Chat Interface

### Web UI

1. Start the backend: `python -m uvicorn companion.api:app --port 7373`
2. In another terminal: `cd ui && npm run dev`
3. Open http://localhost:5173

**Interface:**
- Type messages in the bottom textarea
- Press Enter to send
- Citations appear in a side panel when RAG retrieves context
- Conversation history persists per session

### API Directly

```bash
# Start a conversation
curl -X POST http://localhost:7373/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What did I write about my trip to Japan?",
    "stream": true
  }'
```

**Parameters:**
- `message` (required): Your question
- `session_id` (optional): Continue existing conversation
- `stream` (optional): Stream response (default: true)
- `use_rag` (optional): Enable vault search (default: true)

### Get Session History

```bash
curl http://localhost:7373/sessions/{session_id}/history
```

---

## Fine-Tuning (Optional)

### Extract Training Data

```bash
# Extract reflection examples from your vault
python -m companion.forge.extract \
  --output training_data.jsonl \
  --min-length 100
```

### Train Model

```bash
# Start training (takes hours, needs GPU)
python -m companion.forge.train \
  --data training_data.jsonl \
  --output-dir ./models
```

### Export to GGUF

```bash
# Convert for llama.cpp inference
python -m companion.forge.export \
  --model ./models/checkpoint \
  --output companion-7b.gguf
```

### Reload Model (Hot Swap)

```bash
# Admin endpoint - reload without restarting API
curl -X POST http://localhost:7373/admin/reload-model \
  -H "Content-Type: application/json" \
  -d '{"model_path": "/path/to/companion-7b.gguf"}'
```

---

## Command Reference

### Indexer Commands

| Command | Description | Example |
|---------|-------------|---------|
| `index` | Full re-index of vault | `cli index` |
| `sync` | Incremental sync | `cli sync` |
| `reindex` | Force full reindex | `cli reindex` |
| `status` | Show index statistics | `cli status` |

### Common Options

All indexer commands support:
- `--config PATH` : Use alternative config file
- `--verbose` : Detailed logging

### Environment Variables

| Variable | Purpose | Example |
|----------|---------|---------|
| `COMPANION_CONFIG` | Config file path | `/etc/companion/config.json` |
| `COMPANION_DATA_DIR` | Data storage root | `/var/lib/companion` |
| `VAULT_PATH` | Override vault location | `/home/user/vault` |

---

## Troubleshooting

### "No module named 'companion'"

```bash
# Install in editable mode
pip install -e "."

# Or set PYTHONPATH
export PYTHONPATH=/path/to/companion:$PYTHONPATH
```

### "Failed to generate embedding"

- Check Ollama is running: `curl http://localhost:11434/api/tags`
- Verify embedding model is pulled: `ollama pull mxbai-embed-large`
- Check `config.json` has correct `rag.embedding.base_url`

### "No results from search"

1. Check index status: `cli status`
2. Verify vault path is correct in config
3. Run full index: `cli index`
4. Check file patterns match your notes (default: `*.md`)

### "Port 7373 already in use"

```bash
# Find and kill process
lsof -i :7373
kill <PID>

# Or use different port
python -m uvicorn companion.api:app --port 7374
```

### Windows: Scripts won't run

```powershell
# Set execution policy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Or run with explicit bypass
powershell -ExecutionPolicy Bypass -File scripts/install.ps1
```

---

## Systemd Commands (Linux)

If installed as a service:

```bash
# Start/stop/restart
sudo systemctl start companion-api
sudo systemctl stop companion-api
sudo systemctl restart companion-api

# Check status
sudo systemctl status companion-api

# View logs
sudo journalctl -u companion-api -f

# Enable auto-start
sudo systemctl enable companion-api
```

---

## Docker Commands

```bash
# Start all services
docker-compose up -d

# View logs
docker-compose logs -f companion-api

# Run indexer command
docker-compose exec companion-api python -m companion.indexer_daemon.cli index

# Rebuild after code changes
docker-compose up -d --build

# Stop everything
docker-compose down
```

---

## Performance Tips

### Indexing Large Vaults

- First index takes time (1-5 hours for 1000+ notes)
- Subsequent syncs are fast (seconds to minutes)
- Use `sync` instead of `reindex` for updates

### Memory Usage

- API server: ~500MB-1GB RAM
- Indexer: ~200MB while watching
- LanceDB is disk-based, scales to 100K+ chunks

### GPU Acceleration

For fine-tuning (not required for RAG):
- Requires CUDA-capable GPU
- Install `unsloth` and `torch` with CUDA support
- Training uses ~10GB VRAM for 7B models

---

## Best Practices

1. **Index regularly**: Run `sync` daily or use the file watcher
2. **Back up vectors**: Copy `~/.companion/vectors.lance` periodically
3. **Use session IDs**: Pass `session_id` to maintain conversation context
4. **Monitor citations**: Check the sources panel to verify RAG is working
5. **Keep Ollama running**: The embedding service must be available

---

## Getting Help

- Check logs: `journalctl -u companion-api` or `docker-compose logs`
- Verify config: `python -c "from companion.config import load_config; print(load_config())"`
- Test search directly: `python -m companion.indexer_daemon.cli search "test query"`

---

## Next Steps

1. Index your vault
2. Start the API server
3. Open the web UI
4. Ask your first question
5. Explore the citations

Enjoy your personal AI companion!