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:

```dotenv
# 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](https://platform.openai.com/)
2. Navigate to [API Keys](https://platform.openai.com/api-keys)
3. Create a new API key
4. Add it to your `.env` file:

```dotenv
OPENAI_API_KEY=sk-your-actual-key-here
```

## Model Configuration

The agent model can be configured via `config.yaml`:

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

```yaml
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`:

```dotenv
EPFL_API_KEY=your-epfl-key
```

## Optional Configuration

### GitHub Token

For the repository info tool (optional):

```dotenv
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:

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

```dotenv
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:

```text
src/ai_agent/config/gradio_tools.json
```

At runtime, override it with:

```dotenv
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:

```bash
# 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](quickstart.md)
- Learn about [Using the Chat Interface](../user-guide/chat-interface.md)