Skip to content

configuration-guide.md

Latest commit

 

History

History
221 lines (180 loc) · 5.43 KB

configuration-guide.md

File metadata and controls

221 lines (180 loc) · 5.43 KB

Configuration Guide

Configuration File Locations

saigen searches for configuration files in the following order:

  1. ~/.saigen/config.yaml or ~/.saigen/config.json
  2. .saigen.yaml or .saigen.json (in current directory)
  3. saigen.yaml or saigen.json (in current directory)

Configuration Format

Configuration files can be in YAML or JSON format. YAML is recommended for readability.

Complete Configuration Example

# Configuration version
config_version: "0.1.0"

# Logging configuration
log_level: info  # debug, info, warning, error
log_file: ~/.saigen/logs/saigen.log  # Optional log file

# LLM Provider Configuration
llm_providers:
  openai:
    provider: openai
    model: gpt-4o-mini
    max_tokens: 4000
    temperature: 0.1
    timeout: 30
    max_retries: 3
    enabled: true
    # api_key: set via OPENAI_API_KEY environment variable
  
  anthropic:
    provider: anthropic
    model: claude-3-sonnet-20240229
    max_tokens: 4000
    temperature: 0.1
    timeout: 30
    max_retries: 3
    enabled: false
    # api_key: set via ANTHROPIC_API_KEY environment variable
  
  ollama:
    provider: ollama
    api_base: http://localhost:11434
    model: llama2
    enabled: false

# Repository Configuration
repositories:
  ubuntu-main:
    name: ubuntu-main
    type: apt
    platform: linux
    url: http://archive.ubuntu.com/ubuntu/dists/jammy/main/binary-amd64/Packages.gz
    enabled: true
    priority: 10
    cache_ttl_hours: 24
    timeout: 300
    architecture: [amd64]
    parsing:
      format: text
      line_pattern: '^Package:\s*(.+)$'
      name_group: 1
      version_pattern: '^Version:\s*(.+)$'
      description_pattern: '^Description:\s*(.+)$'
    metadata:
      description: Ubuntu Main Repository
      maintainer: Ubuntu
  
  homebrew-core:
    name: homebrew-core
    type: brew
    platform: macos
    url: https://formulae.brew.sh/api/formula.json
    enabled: true
    priority: 10
    cache_ttl_hours: 12
    parsing:
      format: json
      field_mapping:
        name: name
        version: versions.stable
        description: desc
        homepage: homepage
    metadata:
      description: Homebrew Core Formulae
      maintainer: Homebrew
  
  custom-generic:
    name: custom-json-repo
    type: generic
    platform: linux
    url: https://api.example.com/packages.json
    enabled: true
    priority: 5
    cache_ttl_hours: 6
    parsing:
      format: json
      package_path: [packages]
      field_mapping:
        name: package_name
        version: latest_version
        description: summary
    metadata:
      description: Custom JSON Package Repository

# Cache Configuration
cache:
  directory: ~/.saigen/cache
  max_size_mb: 1000
  default_ttl: 3600  # 1 hour
  cleanup_interval: 86400  # 24 hours

# RAG (Retrieval-Augmented Generation) Configuration
rag:
  enabled: true
  index_directory: ~/.saigen/rag_index
  embedding_model: sentence-transformers/all-MiniLM-L6-v2
  max_context_items: 5
  similarity_threshold: 0.7
  rebuild_on_startup: false

# Validation Configuration
validation:
  schema_path: null  # Use built-in schema or path to custom schema
  strict_mode: true  # Enable strict validation rules
  auto_fix_common_issues: true  # Automatically fix minor issues
  validate_repository_accuracy: true  # Check against repository data
  show_suggestions: true  # Include helpful suggestions in error reports
  max_errors: 50  # Maximum number of errors to report

# Generation Configuration
generation:
  default_providers: [apt, brew, winget]
  output_directory: ./saidata
  backup_existing: true
  parallel_requests: 3
  request_timeout: 120

# Advanced Settings
user_agent: "saigen/0.1.0"
max_concurrent_requests: 5
request_timeout: 30

Environment Variables

Environment variables override configuration file settings:

Required for LLM Providers

  • OPENAI_API_KEY - OpenAI API key
  • ANTHROPIC_API_KEY - Anthropic API key

Optional Overrides

  • SAIGEN_LOG_LEVEL - Override log level
  • SAIGEN_CACHE_DIR - Override cache directory
  • SAIGEN_OUTPUT_DIR - Override output directory

Example

export OPENAI_API_KEY="sk-..."
export SAIGEN_LOG_LEVEL="debug"
export SAIGEN_CACHE_DIR="/tmp/saigen-cache"

saigen generate nginx

Configuration Management Commands

View Current Configuration

saigen config --show

Validate Configuration

saigen config --validate

Security Best Practices

  1. API Keys: Never store API keys in configuration files. Use environment variables.

  2. File Permissions: Configuration files are automatically saved with secure permissions (0o600).

  3. Cache Directory: Ensure cache directory has appropriate permissions.

  4. Log Files: Be careful with log file locations and permissions if logging sensitive data.

Troubleshooting

Configuration Not Found

If saigen can't find a configuration file, it will create a default configuration. Check the search paths above.

Invalid Configuration

Use saigen config --validate to check for configuration errors.

API Key Issues

Ensure environment variables are set correctly:

echo $OPENAI_API_KEY  # Should show your API key

Permission Errors

Ensure saigen can write to cache and output directories:

ls -la ~/.saigen/

Migration from Previous Versions

When upgrading saigen, configuration files are automatically migrated to the latest format. Backup your configuration before upgrading:

cp ~/.saigen/config.yaml ~/.saigen/config.yaml.backup