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¶

Never commit .env files

Add .env to .gitignore to prevent accidental commits

Protect API keys

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

Use .env.example

Create .env.example with dummy values for documentation:

OPENAI_API_KEY=sk-your-key-here
GITHUB_TOKEN=ghp-your-token-here