docs: add comprehensive README and module documentation
This commit is contained in:
278
docs/config.md
Normal file
278
docs/config.md
Normal file
@@ -0,0 +1,278 @@
|
||||
# Configuration Reference
|
||||
|
||||
Complete reference for `config.json` configuration options.
|
||||
|
||||
## Overview
|
||||
|
||||
The configuration file uses JSON format with support for:
|
||||
- Path expansion (`~` expands to home directory)
|
||||
- Type validation via Pydantic models
|
||||
- Environment-specific overrides
|
||||
|
||||
## Schema Validation
|
||||
|
||||
Validate your config against the schema:
|
||||
|
||||
```bash
|
||||
python -c "from companion.config import load_config; load_config('config.json')"
|
||||
```
|
||||
|
||||
Or use the JSON Schema directly: [config-schema.json](../config-schema.json)
|
||||
|
||||
## Configuration Sections
|
||||
|
||||
### companion
|
||||
|
||||
Core companion personality and behavior settings.
|
||||
|
||||
```json
|
||||
{
|
||||
"companion": {
|
||||
"name": "SAN",
|
||||
"persona": {
|
||||
"role": "companion",
|
||||
"tone": "reflective",
|
||||
"style": "questioning",
|
||||
"boundaries": [
|
||||
"does_not_impersonate_user",
|
||||
"no_future_predictions",
|
||||
"no_medical_or_legal_advice"
|
||||
]
|
||||
},
|
||||
"memory": {
|
||||
"session_turns": 20,
|
||||
"persistent_store": "~/.companion/memory.db",
|
||||
"summarize_after": 10
|
||||
},
|
||||
"chat": {
|
||||
"streaming": true,
|
||||
"max_response_tokens": 2048,
|
||||
"default_temperature": 0.7,
|
||||
"allow_temperature_override": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Fields
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|-------|------|---------|-------------|
|
||||
| `name` | string | "SAN" | Display name for the companion |
|
||||
| `persona.role` | string | "companion" | Role description (companion/advisor/reflector) |
|
||||
| `persona.tone` | string | "reflective" | Communication tone (reflective/supportive/analytical) |
|
||||
| `persona.style` | string | "questioning" | Interaction style (questioning/supportive/direct) |
|
||||
| `persona.boundaries` | string[] | [...] | Behavioral guardrails |
|
||||
| `memory.session_turns` | int | 20 | Messages to keep in context |
|
||||
| `memory.persistent_store` | string | "~/.companion/memory.db" | SQLite database path |
|
||||
| `memory.summarize_after` | int | 10 | Summarize history after N turns |
|
||||
| `chat.streaming` | bool | true | Stream responses in real-time |
|
||||
| `chat.max_response_tokens` | int | 2048 | Max tokens per response |
|
||||
| `chat.default_temperature` | float | 0.7 | Creativity (0.0=deterministic, 2.0=creative) |
|
||||
| `chat.allow_temperature_override` | bool | true | Let users adjust temperature |
|
||||
|
||||
---
|
||||
|
||||
### vault
|
||||
|
||||
Obsidian vault indexing configuration.
|
||||
|
||||
```json
|
||||
{
|
||||
"vault": {
|
||||
"path": "~/KnowledgeVault/Default",
|
||||
"indexing": {
|
||||
"auto_sync": true,
|
||||
"auto_sync_interval_minutes": 1440,
|
||||
"watch_fs_events": true,
|
||||
"file_patterns": ["*.md"],
|
||||
"deny_dirs": [".obsidian", ".trash", "zzz-Archive", ".git"],
|
||||
"deny_patterns": ["*.tmp", "*.bak", "*conflict*"]
|
||||
},
|
||||
"chunking_rules": {
|
||||
"default": {
|
||||
"strategy": "sliding_window",
|
||||
"chunk_size": 500,
|
||||
"chunk_overlap": 100
|
||||
},
|
||||
"Journal/**": {
|
||||
"strategy": "section",
|
||||
"section_tags": ["#DayInShort", "#mentalhealth", "#work"],
|
||||
"chunk_size": 300,
|
||||
"chunk_overlap": 50
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### rag
|
||||
|
||||
RAG (Retrieval-Augmented Generation) engine configuration.
|
||||
|
||||
```json
|
||||
{
|
||||
"rag": {
|
||||
"embedding": {
|
||||
"provider": "ollama",
|
||||
"model": "mxbai-embed-large",
|
||||
"base_url": "http://localhost:11434",
|
||||
"dimensions": 1024,
|
||||
"batch_size": 32
|
||||
},
|
||||
"vector_store": {
|
||||
"type": "lancedb",
|
||||
"path": "~/.companion/vectors.lance"
|
||||
},
|
||||
"search": {
|
||||
"default_top_k": 8,
|
||||
"max_top_k": 20,
|
||||
"similarity_threshold": 0.75,
|
||||
"hybrid_search": {
|
||||
"enabled": true,
|
||||
"keyword_weight": 0.3,
|
||||
"semantic_weight": 0.7
|
||||
},
|
||||
"filters": {
|
||||
"date_range_enabled": true,
|
||||
"tag_filter_enabled": true,
|
||||
"directory_filter_enabled": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### model
|
||||
|
||||
LLM configuration for inference and fine-tuning.
|
||||
|
||||
```json
|
||||
{
|
||||
"model": {
|
||||
"inference": {
|
||||
"backend": "llama.cpp",
|
||||
"model_path": "~/.companion/models/companion-7b-q4.gguf",
|
||||
"context_length": 8192,
|
||||
"gpu_layers": 35,
|
||||
"batch_size": 512,
|
||||
"threads": 8
|
||||
},
|
||||
"fine_tuning": {
|
||||
"base_model": "unsloth/Meta-Llama-3.1-8B-Instruct-bnb-4bit",
|
||||
"output_dir": "~/.companion/training",
|
||||
"lora_rank": 16,
|
||||
"lora_alpha": 32,
|
||||
"learning_rate": 0.0002,
|
||||
"batch_size": 4,
|
||||
"gradient_accumulation_steps": 4,
|
||||
"num_epochs": 3,
|
||||
"warmup_steps": 100,
|
||||
"save_steps": 500,
|
||||
"eval_steps": 250,
|
||||
"training_data_path": "~/.companion/training_data/",
|
||||
"validation_split": 0.1
|
||||
},
|
||||
"retrain_schedule": {
|
||||
"auto_reminder": true,
|
||||
"default_interval_days": 90,
|
||||
"reminder_channels": ["chat_stream", "log"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### api
|
||||
|
||||
FastAPI backend configuration.
|
||||
|
||||
```json
|
||||
{
|
||||
"api": {
|
||||
"host": "127.0.0.1",
|
||||
"port": 7373,
|
||||
"cors_origins": ["http://localhost:5173"],
|
||||
"auth": {
|
||||
"enabled": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ui
|
||||
|
||||
Web UI configuration.
|
||||
|
||||
```json
|
||||
{
|
||||
"ui": {
|
||||
"web": {
|
||||
"enabled": true,
|
||||
"theme": "obsidian",
|
||||
"features": {
|
||||
"streaming": true,
|
||||
"citations": true,
|
||||
"source_preview": true
|
||||
}
|
||||
},
|
||||
"cli": {
|
||||
"enabled": true,
|
||||
"rich_output": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### logging
|
||||
|
||||
Logging configuration.
|
||||
|
||||
```json
|
||||
{
|
||||
"logging": {
|
||||
"level": "INFO",
|
||||
"file": "~/.companion/logs/companion.log",
|
||||
"max_size_mb": 100,
|
||||
"backup_count": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### security
|
||||
|
||||
Security and privacy settings.
|
||||
|
||||
```json
|
||||
{
|
||||
"security": {
|
||||
"local_only": true,
|
||||
"vault_path_traversal_check": true,
|
||||
"sensitive_content_detection": true,
|
||||
"sensitive_patterns": [
|
||||
"#mentalhealth",
|
||||
"#physicalhealth",
|
||||
"#finance",
|
||||
"#Relations"
|
||||
],
|
||||
"require_confirmation_for_external_apis": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Full Example
|
||||
|
||||
See [config.json](../config.json) for a complete working configuration.
|
||||
Reference in New Issue
Block a user