docs/reference/environment.md

# Environment Variables

Configuration for the AI Imaging Agent is managed via environment variables, typically defined in a `.env` file.

## Required Variables

### OPENAI_API_KEY

OpenAI API key for vision-language model calls.

```dotenv
OPENAI_API_KEY=sk-xxxx
```

**Where to get it**: [OpenAI API Keys](https://platform.openai.com/api-keys)

**Required**: Yes (unless using alternative model provider)

**Used by**: Agent VLM calls, tool selection

## Optional Variables

### SOFTWARE_CATALOG

Path to the software catalog JSONL file.

```dotenv
SOFTWARE_CATALOG=dataset/catalog.jsonl
```

**Default**: `dataset/catalog.jsonl`

**Required**: No (uses default)

### TOP_K

Number of candidate tools to retrieve from FAISS search.

```dotenv
TOP_K=8
```

**Default**: `8`

**Range**: 1-50 (recommended: 5-10)

**Impact**: More candidates = better recall but slower VLM calls

### NUM_CHOICES

Number of final tool recommendations to return to user.

```dotenv
NUM_CHOICES=3
```

**Default**: `3`

**Range**: 1-10 (recommended: 3-5)

**Impact**: Too many recommendations can overwhelm users

### GITHUB_TOKEN

GitHub personal access token for repository info tool.

```dotenv
GITHUB_TOKEN=ghp_xxxx
```

**Where to get it**: [GitHub Tokens](https://github.com/settings/tokens)

**Permissions needed**: `public_repo` (read access)

**Required**: No (tool gracefully degrades without it)

**Benefits**: Higher API rate limits, access to private repos

### SYNC_EVERY_HOURS

Auto-refresh catalog interval in hours.

```dotenv
SYNC_EVERY_HOURS=24
```

**Default**: `0` (disabled)

**Range**: 0 (disabled) or ≥1

**Behavior**: Background thread checks catalog every N hours and rebuilds index if changed

## Logging Configuration

### LOGLEVEL_CONSOLE

Console logging level.

```dotenv
LOGLEVEL_CONSOLE=WARNING
```

**Options**: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`

**Default**: `WARNING`

**Recommendation**: 
- Development: `DEBUG` or `INFO`
- Production: `WARNING`

### LOGLEVEL_FILE

File logging level.

```dotenv
LOGLEVEL_FILE=INFO
```

**Options**: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`

**Default**: `INFO`

**Files written to**: `logs/app_YYYYMMDD.log`

### FILE_LOG

Enable file logging.

```dotenv
FILE_LOG=1
```

**Options**: `0` (disabled), `1` (enabled)

**Default**: `1`

### LOG_DIR

Directory for log files.

```dotenv
LOG_DIR=logs
```

**Default**: `logs`

**Created automatically** if it doesn't exist

### LOG_PROMPTS

Save VLM prompts and images for debugging.

```dotenv
LOG_PROMPTS=1
```

**Options**: `0` (disabled), `1` (enabled)

**Default**: `0`

**Writes to**: `logs/prompts/YYYYMMDD_HHMMSS/`

**Contents**:
- `prompt.txt`: Text prompt sent to VLM
- `image_*.png`: Images included in prompt
- `response.json`: VLM response
- `metadata.json`: Request metadata

**Warning**: Can consume significant disk space over time

## Model Configuration

### CONFIG_PATH

Path to YAML model configuration file.

```dotenv
CONFIG_PATH=config.yaml
```

**Default**: `config.yaml`

**See**: `config.yaml` for model configuration details

### Alternative Model Providers

For custom OpenAI-compatible endpoints, configure in `config.yaml`:

```yaml
agent_model:
  name: "model-name"
  base_url: "https://api.example.com/v1"
  api_key_env: "CUSTOM_API_KEY"
```

Then in `.env`:

```dotenv
CUSTOM_API_KEY=your-key-here
```

<!-- ## Advanced Configuration

### RERANK_TOP_N

Number of candidates to retrieve before reranking.

```dotenv
RERANK_TOP_N=20
```

**Default**: `20`

**Interaction with TOP_K**:
- FAISS retrieves `RERANK_TOP_N` candidates (e.g., 20)
- CrossEncoder reranks them
- Top `TOP_K` (e.g., 8) passed to VLM

**Recommendation**: 2-3x `TOP_K` value

-->

## .env File Example

Complete example `.env` file:

```dotenv
# Required
OPENAI_API_KEY=sk-xxxx

# Optional: Alternative providers
EPFL_API_KEY=sk-xxxx
GITHUB_TOKEN=ghp_xxxx

# Catalog
SOFTWARE_CATALOG=dataset/catalog.jsonl
SYNC_EVERY_HOURS=24

# Pipeline
TOP_K=8
NUM_CHOICES=3

# Logging
LOGLEVEL_CONSOLE=WARNING
LOGLEVEL_FILE=INFO
FILE_LOG=1
LOG_DIR=logs
LOG_PROMPTS=0  # Set to 1 for debugging

# Model configuration
CONFIG_PATH=config.yaml
```

## Loading Environment Variables

### Automatic Loading

The application automatically loads `.env` from the repository root:

```python
from dotenv import load_dotenv
load_dotenv()  # Loads .env automatically
```

### Manual Loading

```bash
# Export manually
export OPENAI_API_KEY=sk-xxxx
export TOP_K=8

# Or source .env
set -a
source .env
set +a
```

### Docker

Pass environment variables to Docker:

```bash
docker run --env-file .env ai-agent
```

## Security Best Practices

!!! warning "Never commit .env files"
    Add `.env` to `.gitignore` to prevent accidental commits

!!! warning "Protect API keys"
    Treat API keys as sensitive credentials:
    - Never share in public repositories
    - Rotate keys if exposed
    - Use environment-specific keys (dev/prod)

!!! tip "Use .env.example"
    Create `.env.example` with dummy values for documentation:
    
    ```dotenv
    OPENAI_API_KEY=sk-your-key-here
    GITHUB_TOKEN=ghp-your-token-here
    ```

## Next Steps

- Review [CLI Commands](cli.md)
- Check [Configuration Guide](../getting-started/configuration.md)
- See [Changelog](changelog.md)