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.

OPENAI_API_KEY=sk-xxxx

Where to get it: OpenAI 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.

SOFTWARE_CATALOG=dataset/catalog.jsonl

Default: dataset/catalog.jsonl

Required: No (uses default)

TOP_K

Number of candidate tools to retrieve from FAISS search.

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.

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.

GITHUB_TOKEN=ghp_xxxx

Where to get it: GitHub 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.

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.

LOGLEVEL_CONSOLE=WARNING

Options: DEBUG, INFO, WARNING, ERROR, CRITICAL

Default: WARNING

Recommendation:

• Development: DEBUG or INFO
• Production: WARNING

LOGLEVEL_FILE

File logging level.

LOGLEVEL_FILE=INFO

Options: DEBUG, INFO, WARNING, ERROR, CRITICAL

Default: INFO

Files written to: logs/app_YYYYMMDD.log

FILE_LOG

Enable file logging.

FILE_LOG=1

Options: 0 (disabled), 1 (enabled)

Default: 1

LOG_DIR

Directory for log files.

LOG_DIR=logs

Default: logs

Created automatically if it doesn't exist

LOG_PROMPTS

Save VLM prompts and images for debugging.

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.

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:

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

Then in .env:

CUSTOM_API_KEY=your-key-here

.env File Example

Complete example .env file:

# 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:

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

Manual Loading

# 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:

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
• Check Configuration Guide
• See Changelog