Settings Management

Manage Thoth configuration including API credentials, file paths, search parameters, and system behavior. Settings are stored in thoth.settings.json and persist across sessions.

Overview

The settings system provides:

•Centralized Configuration - All settings in one place
•Validation - Schema-based validation prevents errors
•Sections - Organized by feature area
•Persistence - Changes saved to file automatically

Core Tools

Tool	Purpose	When to Use
`view_settings`	Display current configuration	Check current values
`update_settings`	Modify settings	Change configuration
`validate_settings`	Check settings validity	After changes or troubleshooting
`reset_settings`	Restore defaults	Fix broken configuration
`migrate_settings`	Import from environment	First-time setup

Settings Sections

API Configuration (`api`)

json

{
  "api": {
    "openai_api_key": "sk-...",
    "anthropic_api_key": "sk-ant-...",
    "semantic_scholar_api_key": "...",
    "openalex_email": "user@example.com"
  }
}

File Paths (`paths`)

json

{
  "paths": {
    "vault_path": "/path/to/obsidian/vault",
    "pdf_directory": "thoth/papers/pdfs",
    "data_directory": "thoth/data",
    "backup_directory": "thoth/backups"
  }
}

RAG Settings (`rag`)

json

{
  "rag": {
    "embedding_model": "text-embedding-3-small",
    "chunk_size": 1000,
    "chunk_overlap": 200,
    "collection_name": "thoth_articles"
  }
}

Search Settings (`search`)

json

{
  "search": {
    "default_limit": 10,
    "min_relevance": 0.7,
    "hybrid_search": true,
    "sources": ["semantic_scholar", "openalex", "arxiv"]
  }
}

Discovery Settings (`discovery`)

json

{
  "discovery": {
    "default_max_papers": 50,
    "default_relevance_threshold": 0.7,
    "auto_discovery_enabled": false,
    "discovery_interval_hours": 24
  }
}

Database Settings (`database`)

json

{
  "database": {
    "connection_string": "postgresql://...",
    "pool_size": 5
  }
}

Viewing Settings

View All Settings

code

view_settings()
→ Returns complete settings object

View Specific Section

code

view_settings(section="api")
→ Returns only API configuration

view_settings(section="paths")
→ Returns only path configuration

View Single Setting

code

view_settings(section="rag", key="embedding_model")
→ Returns: "text-embedding-3-small"

Updating Settings

Update Single Value

code

update_settings(
  section="search",
  updates={"default_limit": 20}
)

Update Multiple Values

code

update_settings(
  section="rag",
  updates={
    "chunk_size": 1200,
    "chunk_overlap": 300
  }
)

Important Notes

•Changes are validated before saving
•Some changes require service restart
•Some changes require reindexing (see RAG Administration skill)

Validation

Check Settings Validity

code

validate_settings()
→ Returns validation results

Example output:
{
  "valid": true,
  "warnings": [
    "semantic_scholar_api_key not set - rate limits will apply"
  ],
  "errors": []
}

Common Validation Issues

Issue	Solution
Missing required field	Set the field with update_settings
Invalid path	Check path exists and is accessible
Invalid API key format	Verify key is correctly copied
Invalid value type	Check expected type in schema

Resetting Settings

Reset Single Section

code

reset_settings(section="search")
→ Restores search settings to defaults

Reset All Settings

code

reset_settings(all=true)
→ Restores entire configuration to defaults

Warning: Reset will overwrite current values. Consider backup first.

Migration from Environment Variables

For first-time setup or transitioning from .env files:

code

migrate_settings()
→ Imports settings from environment variables

Migrated:
- OPENAI_API_KEY → api.openai_api_key
- VAULT_PATH → paths.vault_path
- POSTGRES_URL → database.connection_string
...

Workflow Examples

Example 1: Change Vault Path

User: "I moved my Obsidian vault to a new location"

code

1. View current path
   view_settings(section="paths", key="vault_path")
   → /old/path/to/vault

2. Update path
   update_settings(
     section="paths",
     updates={"vault_path": "/new/path/to/vault"}
   )

3. Validate
   validate_settings()
   → valid: true

4. Response:
   "Updated your vault path to /new/path/to/vault.
   Changes are saved and will take effect immediately."

Example 2: Configure API Keys

User: "I need to set up my Semantic Scholar API key"

code

1. Get current state
   view_settings(section="api")
   → Shows current API keys (masked)

2. Update key
   update_settings(
     section="api",
     updates={"semantic_scholar_api_key": "user-provided-key"}
   )

3. Validate
   validate_settings()
   → Check for warnings/errors

4. Response:
   "Semantic Scholar API key configured.
   You'll now have higher rate limits for paper discovery."

Example 3: Optimize Search Configuration

User: "My searches are returning too few results"

code

1. Check current search settings
   view_settings(section="search")
   → default_limit: 10, min_relevance: 0.8

2. Adjust settings
   update_settings(
     section="search",
     updates={
       "default_limit": 25,
       "min_relevance": 0.6,
       "hybrid_search": true
     }
   )

3. Response:
   "Search settings updated:
   - Results limit: 10 → 25
   - Relevance threshold: 0.8 → 0.6 (more inclusive)
   - Hybrid search: enabled (combines semantic + keyword)
   
   Try your search again - you should see more results."

Example 4: First-Time Setup

User: "I just installed Thoth, help me configure it"

code

1. Try migration from environment
   migrate_settings()
   → Imported 5 settings from environment

2. Check for missing required settings
   validate_settings()
   → warnings: ["vault_path not set"]

3. Set required paths
   update_settings(
     section="paths",
     updates={
       "vault_path": "/path/to/obsidian/vault",
       "pdf_directory": "thoth/papers/pdfs"
     }
   )

4. Verify API keys
   view_settings(section="api")
   → Check which keys are configured

5. Response:
   "Initial configuration complete!
   
   Configured:
   ✓ OpenAI API key
   ✓ Vault path
   ✓ PDF directory
   
   Optional (not configured):
   - Semantic Scholar API key (higher rate limits)
   - Anthropic API key (alternative LLM)
   
   You can now start using Thoth. Would you like me to:
   - Run a test search to verify everything works?
   - Help you import existing PDFs?"

Settings Reference

Required Settings

Setting	Section	Purpose
`openai_api_key`	api	LLM and embeddings
`vault_path`	paths	Obsidian vault location

Recommended Settings

Setting	Section	Default	Purpose
`pdf_directory`	paths	thoth/papers/pdfs	PDF storage
`chunk_size`	rag	1000	RAG chunk size
`min_relevance`	search	0.7	Search threshold

Optional Settings

Setting	Section	Purpose
`semantic_scholar_api_key`	api	Higher rate limits
`anthropic_api_key`	api	Alternative LLM
`auto_discovery_enabled`	discovery	Background searches

Best Practices

Security

•Never share API keys in chat
•Use environment variables for sensitive values in shared configs
•API keys are masked in view_settings output

Configuration Changes

•Always validate after making changes
•Some RAG changes require reindexing (use RAG Administration skill)
•Test after major configuration changes

Backup

•Settings are in thoth.settings.json
•Back up before major changes
•Use reset_settings cautiously

Troubleshooting

Settings Not Taking Effect

code

1. Validate settings: validate_settings()
2. Check for errors in validation output
3. Restart services if required
4. For RAG changes, run reindex

Invalid Settings File

code

1. Try validate_settings() for specific errors
2. Reset specific section: reset_settings(section="broken_section")
3. As last resort: reset_settings(all=true)

Missing Settings After Update

code

1. Check if migration was run: migrate_settings()
2. Verify file permissions on settings file
3. Check for typos in section/key names

Settings Management

Overview

Core Tools

Settings Sections

API Configuration (api)

File Paths (paths)

RAG Settings (rag)

Search Settings (search)

Discovery Settings (discovery)

Database Settings (database)

Viewing Settings

View All Settings

View Specific Section

View Single Setting

Updating Settings

Update Single Value

Update Multiple Values

Important Notes

Validation

Check Settings Validity

Common Validation Issues

Resetting Settings

Reset Single Section

Reset All Settings

Migration from Environment Variables

Workflow Examples

Example 1: Change Vault Path

Example 2: Configure API Keys

Example 3: Optimize Search Configuration

Example 4: First-Time Setup

Settings Reference

Required Settings

Recommended Settings

Optional Settings

Best Practices

Security

Configuration Changes

Backup

Troubleshooting

Settings Not Taking Effect

Invalid Settings File

Missing Settings After Update

API Configuration (`api`)

File Paths (`paths`)

RAG Settings (`rag`)

Search Settings (`search`)

Discovery Settings (`discovery`)

Database Settings (`database`)