docs/getting-started/configuration.md

Configuration

Before running the AI Imaging Agent, you need to configure it with your API keys and preferences.

Environment Variables

Create a .env file in the repository root with the following configuration:

# Required: OpenAI API key
OPENAI_API_KEY=sk-xxxx

# Optional: GitHub token for repository info tool
GITHUB_TOKEN=ghp_xxxx

# Optional: Alternative model providers
EPFL_API_KEY=sk-xxxx

# Software catalog path
SOFTWARE_CATALOG=dataset/catalog.jsonl

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

# Custom config path
CONFIG_PATH=config.yaml

Required Configuration

OpenAI API Key

The AI Imaging Agent requires an OpenAI API key for the vision-language model:

1. Sign up for an account at OpenAI
2. Navigate to API Keys
3. Create a new API key
4. Add it to your .env file:

OPENAI_API_KEY=sk-your-actual-key-here

Model Configuration

The agent model can be configured via config.yaml:

# AI Agent Model Configuration

# Default/fallback model (used for CLI and initial startup)
agent_model:
  name: "gpt-4o-mini"
  base_url: null                        # null for default OpenAI endpoint
  api_key_env: "OPENAI_API_KEY"

# Available models for UI dropdown
available_models:
  - display_name: "gpt-4o-mini"
    name: "gpt-4o-mini"
    base_url: null
    provider: "OpenAI"
    api_key_env: "OPENAI_API_KEY"
  
  - display_name: "gpt-4o"
    name: "gpt-4o"
    base_url: null
    provider: "OpenAI"
    api_key_env: "OPENAI_API_KEY"
  
  - display_name: "gpt-5.1"
    name: "gpt-5.1"
    base_url: null
    provider: "OpenAI"
    api_key_env: "OPENAI_API_KEY"

Using Alternative Model Providers

You can configure custom OpenAI-compatible endpoints:

available_models:
  - display_name: "EPFL Inference"
    name: "gpt-4o-mini"
    base_url: "https://inference.epfl.ch/v1"
    provider: "EPFL"
    api_key_env: "EPFL_API_KEY"

Then add the corresponding API key to your .env:

EPFL_API_KEY=your-epfl-key

Optional Configuration

GitHub Token

For the repository info tool (optional):

GITHUB_TOKEN=ghp_your_github_personal_access_token

This enables the agent to fetch detailed information about GitHub repositories.

Pipeline Parameters

Adjust retrieval and recommendation settings directly in the app setting. You can change the TOP_K and NUM_CHOICES parameters.

Logging

Configure logging behavior:

# Console log level (DEBUG, INFO, WARNING, ERROR)
LOGLEVEL_CONSOLE=WARNING

# File log level
LOGLEVEL_FILE=INFO

# Enable file logging (0 or 1)
FILE_LOG=1

# Log directory
LOG_DIR=logs

# Save VLM prompts and images for debugging (0 or 1)
LOG_PROMPTS=0

!!! tip "Debug Mode" Set LOG_PROMPTS=1 to save VLM prompts and images to the logs/ directory. This is useful for debugging but will increase disk usage.

Software Catalog

Specify the path to your software catalog:

SOFTWARE_CATALOG=dataset/catalog.jsonl

The catalog should be in JSONL format following the schema.org SoftwareSourceCode structure.

Configured Gradio Tools

Supported runnable Gradio tools are defined in one JSON file. The packaged default is:

src/ai_agent/config/gradio_tools.json

At runtime, override it with:

AI_AGENT_GRADIO_TOOLS_CONFIG=/absolute/path/to/gradio_tools.json

Use the override for editable deployments where the Custom Tools UI should save changes. The JSON file stores metadata and environment-variable names only; do not put API keys, tokens, passwords, or secret values in it.

A Gradio tool represents one logical Gradio application. Each tool has one or more endpoints. A single-endpoint tool still uses an endpoints list with one entry. Tool-level aliases resolve through default_endpoint; endpoint-level aliases resolve directly to that endpoint and are preferred for multi-operation Gradio apps.

Common tool fields:

• id, display_name, description, icon, enabled
• gradio_url
• auth.token_env or auth.token_envs
• catalog_aliases
• default_endpoint
• timeout_seconds, max_download_bytes
• notes, metadata
• endpoints

Common endpoint fields:

• id, display_name, description, enabled
• api_name
• catalog_aliases
• supported_input_types
• input_mapping.parameters
• output_mapping.original, output_mapping.preview
• approval.required, approval.title, approval.message
• demo.available
• endpoint-specific timeout_seconds and max_download_bytes

Supported input parameter sources are session_file, image_path, description, literal, and param. File inputs can be wrapped with gradio_client.handle_file by setting as_gradio_file to true.

Output selectors support first, root, dotted dictionary paths such as result.file, and numeric list indexes such as 0.path. Materialized outputs are downloaded safely with the configured size limit. Preview generation failures do not fail the whole tool execution.

The React app exposes a Custom Tools page at /tools. It lets authenticated users add a Hugging Face Space link such as user-tool.hf.space, huggingface.co/user/tool, or huggingface.co/spaces/user/tool. The backend fetches /gradio_api/info and /gradio_api/mcp/schema, converts the discovered description, endpoints, endpoint descriptions, and parameters into the registry format, saves the config atomically, and reloads the active registry. The page lists configured tools and endpoints but does not expose JSON editing controls.

When a configured endpoint needs runtime values, the Run Tool approval panel shows simple parameter fields for those values before execution.

Verification

After configuring, verify your setup:

# Check that environment variables are loaded
python -c "from dotenv import load_dotenv; import os; load_dotenv(); print('API Key:', 'SET' if os.getenv('OPENAI_API_KEY') else 'NOT SET')"

Next Steps

With configuration complete, you're ready to:

• Run the Quick Start
• Learn about Using the Chat Interface