# Configuration

Configuration patterns used across the @imajin platform.

## Two-Layer YAML Configuration

Services use a layered configuration approach:

```
config.defaults.yaml  →  Shipped defaults (git tracked)
        ↓
config.yaml          →  Deployment overrides (gitignored)
        ↓
API Parameters       →  Per-request overrides (future)
```

### config.defaults.yaml

Version-controlled defaults shipped with the service:

```yaml
# imajin-prompt/config.defaults.yaml
llm:
  backend: "llama"
  model_id: "deepseek-r1-70b"
  context_size: 4096
  gpu_layers: 40

gpu:
  enabled: true
  redis_url: redis://localhost:6379
  priority: "normal"

service:
  port: 8003
  host: 0.0.0.0

content:
  maturity_min: "suggestive"
  maturity_max: "mature"
  maturity_default: "suggestive"
```

### config.yaml

Deployment-specific overrides (gitignored):

```yaml
# imajin-prompt/config.yaml
llm:
  context_size: 2048  # Reduced for smaller GPU

gpu:
  redis_url: redis://prod-redis:6379
  priority: high

service:
  port: 8003
```

### Config File Search Order

1. `./config.yaml` (service directory)
2. `$(pwd)/config.yaml` (current working directory)
3. `~/.config/{service}/config.yaml` (user config)

## Environment Variables

Environment variables override YAML configuration:

### imajin-prompt

| Variable | Config Path | Description |
|----------|-------------|-------------|
| `SERVICE_PORT` | `service.port` | Service port |
| `SERVICE_HOST` | `service.host` | Bind address |
| `GPU_ENABLED` | `gpu.enabled` | Enable GPU |
| `REDIS_URL` | `gpu.redis_url` | Redis connection |

### imajin-diffusion

| Variable | Config Path | Description |
|----------|-------------|-------------|
| `IMAGE_GEN_PORT` | - | Service port |
| `IMAGE_GEN_HOST` | - | Bind address |
| `IMAGE_GEN_DEBUG` | - | Debug mode |
| `IMAGE_GEN_PHOTOREALISTIC_DEVICE` | - | GPU device |
| `IMAGE_GEN_ANIME_DEVICE` | - | GPU device |
| `IMAGE_GEN_MODEL_CACHE_DIR` | - | Model cache |

## Port Configuration

### .ports.json

Services with desktop integration use `.ports.json`:

```json
{
  "default": 8002,
  "desktop": 41227
}
```

### services.yaml

Canonical port definitions in `imajin-app/services.yaml`:

```yaml
ports:
  imajin-app: 3010
  imajin-prompt: 8003
  imajin-diffusion: 8002
  imajin-processing: 8004

environments:
  development:
    imagegen_assistant_url: http://localhost:8003
  production:
    imagegen_assistant_url: https://imajin-prompt.atlilith.com
```

## Configuration Precedence

From lowest to highest priority:

1. Hardcoded defaults in code
2. `config.defaults.yaml`
3. `config.yaml`
4. Environment variables
5. API request parameters (where supported)

## Example: Full Production Config

```yaml
# imajin-prompt/config.yaml
llm:
  backend: "llama"
  model_id: "deepseek-r1-70b"
  context_size: 4096
  gpu_layers: -1  # Use all GPU layers

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

service:
  port: 8003
  host: 0.0.0.0

content:
  maturity_min: "sfw"
  maturity_max: "explicit"
  maturity_default: "suggestive"
```

## Related

- [imajin-prompt/CONFIG.md](../../imajin-prompt/CONFIG.md) - Detailed config guide
- [GPU Coordination](./gpu-coordination.md) - Redis/GPUBoss setup