imajin/services/imajin-prompt/CONFIG.md

Configuration Architecture

Overview

The imagegen-assistant service uses a two-layer configuration system:

1. config.defaults.yaml - Shipped defaults (version controlled)
2. config.yaml - Deployment-specific overrides (gitignored)

This prevents services from modifying defaults and allows the imagegen orchestrator to control model selection.

Configuration Files

config.defaults.yaml (Version Controlled)

Contains sensible defaults for the service. This file is committed to git and shipped with the application.

Location: imagegen-assistant/config.defaults.yaml

Purpose:

• Default model configurations
• Default service settings
• Default GPU coordination settings
• Default content maturity bounds

config.yaml (Deployment-Specific, Gitignored)

Optional deployment-specific overrides. This file is not committed to git.

Location: Search order:

1. imagegen-assistant/config.yaml
2. $(pwd)/config.yaml
3. ~/.config/imagegen-assistant/config.yaml

Purpose:

• Override model selection for specific deployments
• Override service port/host
• Override Redis URLs
• Environment-specific settings

Configuration Precedence

Defaults (config.defaults.yaml)
  ↓
Deployment Overrides (config.yaml)
  ↓
API Request Parameters (future: llmModelId)

Values in config.yaml override values in config.defaults.yaml.

API Model Selection (Future)

The /analyze-context endpoint accepts an optional llmModelId parameter to allow the imagegen orchestrator to specify which model to use per request:

{
  "category": "escorts",
  "city": "Tokyo",
  "filters": ["kawaii", "femboy"],
  "llmModelId": "deepseek-r1-70b"  // Optional override
}

Current Limitation: The service initializes a single LLM client at startup. Dynamic model switching per request is not yet implemented but the API contract is prepared for future enhancement.

Example Usage

Development (using defaults)

cd imagegen-assistant
# No config.yaml needed - uses config.defaults.yaml
python -m uvicorn src.api.main:app

Production (with overrides)

cd imagegen-assistant
cat > config.yaml <<EOF
llm:
  model_id: deepseek-r1-70b
  context_size: 2048  # Reduced for 2x RTX 3090

service:
  port: 8003
  host: 0.0.0.0

gpu:
  redis_url: redis://prod-redis:6379
  priority: high
  enabled: true
EOF

python -m uvicorn src.api.main:app

imagegen Orchestrator (model selection via API)

# imagegen controls which model to use
response = await httpx.post("http://assistant:8003/analyze-context", json={
    "category": "escorts",
    "city": "Tokyo",
    "filters": ["kawaii"],
    "llmModelId": "deepseek-r1-70b",  # Orchestrator decides
})

Migration Guide

Before (Bad: Services modify config)

# Service modifies config.yaml directly
cd imagegen-assistant
sed -i 's/model_id: .*/model_id: deepseek-r1-70b/' config.yaml

Problems:

• Config changes conflict in git
• Services fight over model selection
• No clear separation of concerns

After (Good: Orchestrator controls models)

# 1. Deployment overrides in config.yaml (optional)
cat > imagegen-assistant/config.yaml <<EOF
gpu:
  redis_url: redis://prod:6379
EOF

# 2. Orchestrator selects model via API
curl -X POST http://assistant:8003/analyze-context \
  -H "Content-Type: application/json" \
  -d '{
    "category": "escorts",
    "city": "Tokyo",
    "filters": ["kawaii"],
    "llmModelId": "deepseek-r1-70b"
  }'

Benefits:

• No git conflicts (config.yaml is gitignored)
• Clear separation: deployment config vs runtime model selection
• Orchestrator controls which model is used for each request

File Locations

imagegen-assistant/
├── config.defaults.yaml    # Shipped defaults (git tracked)
├── config.yaml             # Deployment overrides (gitignored)
├── CONFIG.md               # This documentation
└── service/
    └── src/
        └── config.py       # Config loader

See Also

• service/src/config.py - Configuration loader implementation
• .gitignore - Ensures config.yaml is not committed