docs: add comprehensive user manual with practical usage examples
This commit is contained in:
364
USER_MANUAL.md
Normal file
364
USER_MANUAL.md
Normal file
@@ -0,0 +1,364 @@
|
||||
# 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!
|
||||
Reference in New Issue
Block a user