# Configuration Reference

Complete reference for configuring Embabel Agent Framework applications, covering all available properties, environment variables, and configuration patterns.

## Configuration Architecture

Embabel uses a layered configuration approach with clear separation between platform internals and application configuration:

- **Platform Properties** (`embabel.agent.platform.*`) - Internal framework behavior
- **Application Properties** (`embabel.agent.*`) - Business logic and deployment configuration
- **Module Properties** (`embabel.shell.*`, etc.) - Module-specific settings

## Platform Properties Reference

### Agent Platform Core
**Namespace**: `embabel.agent.platform.*`

```properties
# Agent scanning and discovery
embabel.agent.platform.scanning.annotation=true
embabel.agent.platform.scanning.packages=com.embabel.agent

# Agent ranking and selection
embabel.agent.platform.ranking.max-attempts=5
embabel.agent.platform.ranking.backoff-millis=100

# Autonomy and confidence thresholds
embabel.agent.platform.autonomy.agent-confidence-cut-off=0.6
embabel.agent.platform.autonomy.goal-confidence-cut-off=0.6

# Process ID generation
embabel.agent.platform.process-id-generation.include-version=false
embabel.agent.platform.process-id-generation.include-agent-name=false

# LLM operations and prompts
embabel.agent.platform.llm-operations.prompts.maybe-prompt-template=maybe_prompt_contribution
embabel.agent.platform.llm-operations.prompts.generate-examples-by-default=true
embabel.agent.platform.llm-operations.data-binding.max-attempts=10
embabel.agent.platform.llm-operations.data-binding.fixed-backoff-millis=10

# Server-sent events
embabel.agent.platform.sse.max-buffer-size=100
embabel.agent.platform.sse.max-process-buffers=1000

# Testing and development  
embabel.agent.platform.test.mock-mode=false
```

### Model Provider Platform Settings
**Namespace**: `embabel.agent.platform.models.*`

```properties
# Anthropic provider
embabel.agent.platform.models.anthropic.max-attempts=10
embabel.agent.platform.models.anthropic.backoff-millis=5000

# OpenAI provider
embabel.agent.platform.models.openai.max-attempts=10
embabel.agent.platform.models.openai.backoff-millis=5000
```

## Application Properties Reference

### Logging and Personality
**Namespace**: `embabel.agent.logging.*`

```properties
# Personality configuration
embabel.agent.logging.personality=default
embabel.agent.logging.verbosity=info
embabel.agent.logging.enable-runtime-switching=false
```

**Available personalities:**
- `default` - Standard Embabel logging
- `starwars` - Star Wars themed with ASCII art
- `severance` - Lumon Industries corporate style
- `hitchhiker` - Hitchhiker's Guide to the Galaxy references  
- `montypython` - Monty Python humor and quotes
- `colossus` - 1970s sci-fi computer aesthetic

### Infrastructure Configuration

#### Neo4j Integration
**Namespace**: `embabel.agent.infrastructure.neo4j.*`

```properties
embabel.agent.infrastructure.neo4j.enabled=false
embabel.agent.infrastructure.neo4j.uri=${NEO4J_URI:bolt://localhost:7687}
embabel.agent.infrastructure.neo4j.authentication.username=${NEO4J_USERNAME:}
embabel.agent.infrastructure.neo4j.authentication.password=${NEO4J_PASSWORD:}
```

#### MCP (Model Context Protocol) Integration
**Namespace**: `embabel.agent.infrastructure.mcp.*`

```properties
embabel.agent.infrastructure.mcp.enabled=false
embabel.agent.infrastructure.mcp.client.name=embabel
embabel.agent.infrastructure.mcp.client.version=1.0.0
embabel.agent.infrastructure.mcp.client.request-timeout=30s
embabel.agent.infrastructure.mcp.client.type=SYNC
```

#### Observability and Monitoring
**Namespace**: `embabel.agent.infrastructure.observability.*`

```properties
embabel.agent.infrastructure.observability.enabled=false

# AI observations
embabel.agent.infrastructure.observability.ai.chat.observations.enabled=true
embabel.agent.infrastructure.observability.ai.chat.observations.log-prompt=true
embabel.agent.infrastructure.observability.ai.chat.observations.log-completion=true
embabel.agent.infrastructure.observability.ai.chat.observations.include-completion=true
embabel.agent.infrastructure.observability.ai.chat.observations.include-prompt=true
embabel.agent.infrastructure.observability.ai.chat.observations.include-error-logging=true

# Tracing configuration
embabel.agent.infrastructure.observability.tracing.enabled=true
embabel.agent.infrastructure.observability.tracing.sampling-probability=1.0
embabel.agent.infrastructure.observability.tracing.zipkin-endpoint=${ZIPKIN_ENDPOINT:http://localhost:9411/api/v2/spans}

# Management endpoints
embabel.agent.infrastructure.observability.management.endpoints.web-exposure-include=*
embabel.agent.infrastructure.observability.management.endpoint.env.show-values=always
embabel.agent.infrastructure.observability.management.endpoint.env.show-details=always
embabel.agent.infrastructure.observability.management.endpoint.health.show-details=always
embabel.agent.infrastructure.observability.management.observations.enabled=true
embabel.agent.infrastructure.observability.management.observations.web-response-enabled=true
```

## Module-Specific Properties

### Shell Configuration
**Namespace**: `embabel.shell.*`

```properties
embabel.shell.enabled=false
embabel.shell.line-length=140
embabel.shell.chat.confirm-goals=true
embabel.shell.chat.bind-conversation=false
```

## Migration Properties

### Migration Detection System
**Namespace**: `embabel.agent.platform.migration.*`

```properties
# Enable migration detection (disabled by default for zero production overhead)
embabel.agent.platform.migration.scanning.enabled=false

# Packages to scan for deprecated property usage
embabel.agent.platform.migration.scanning.include-packages=com.embabel.agent,com.embabel.agent.shell

# Additional packages to exclude from scanning
embabel.agent.platform.migration.scanning.additional-excludes=

# Enable automatic JAR package exclusion for performance
embabel.agent.platform.migration.scanning.auto-exclude-jar-packages=true

# Warning configuration
embabel.agent.platform.migration.warnings.enabled=true
embabel.agent.platform.migration.warnings.individual-logging=true
```

## OpenAI-Compatible Providers

Embabel supports any OpenAI-compatible API provider by configuring the base URL and API key:

### **Azure OpenAI Service**
```properties
OPENAI_BASE_URL=https://your-resource.openai.azure.com/openai/deployments/your-deployment
OPENAI_API_KEY=your-azure-api-key
```

### **Groq**
```properties
OPENAI_BASE_URL=https://api.groq.com/openai/v1
OPENAI_API_KEY=your-groq-api-key
```

### **DeepSeek**
```properties
OPENAI_BASE_URL=https://api.deepseek.com/v1
OPENAI_API_KEY=your-deepseek-api-key
```

### **Together AI**
```properties
OPENAI_BASE_URL=https://api.together.xyz/v1
OPENAI_API_KEY=your-together-api-key
```

### **Custom OpenAI-Compatible Server**
```properties
OPENAI_BASE_URL=http://your-server:8080/v1
OPENAI_API_KEY=your-custom-api-key
OPENAI_COMPLETIONS_PATH=/custom/chat/completions  # If different from default
```

### Optional Cloud Provider API Keys

**Note:** These are completely optional. Embabel works great with local models!

```bash
# Optional - enables OpenAI cloud models (GPT-4, etc.)
export OPENAI_API_KEY=your_openai_api_key

# Optional - enables Anthropic cloud models (Claude, etc.)
export ANTHROPIC_API_KEY=your_anthropic_api_key

# Optional - enables AWS Bedrock models (requires AWS credentials)
export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=your_aws_access_key
export AWS_SECRET_ACCESS_KEY=your_aws_secret_key

# Optional - for examples that demonstrate cloud features
export EMBABEL_API_KEY=brahmsian
```

### Infrastructure Credentials (when enabled)

```bash
# Neo4j Integration (when embabel.agent.infrastructure.neo4j.enabled=true)
export NEO4J_URI=bolt://your-neo4j-server:7687
export NEO4J_USERNAME=your_neo4j_username
export NEO4J_PASSWORD=your_neo4j_password

# MCP Server API Keys (for specific tools when enabled)
export BRAVE_API_KEY=your_brave_search_api_key              # Brave search MCP
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_github_token    # GitHub MCP
export GOOGLE_MAPS_API_KEY=your_google_maps_key             # Google Maps MCP

# Observability (when embabel.agent.infrastructure.observability.enabled=true)
export ZIPKIN_ENDPOINT=http://your-zipkin:9411/api/v2/spans  # Tracing endpoint
```

### Optional Environment Variables

```bash
# Agent behavior
export EMBABEL_AGENT_LOGGING_PERSONALITY=starwars
export EMBABEL_AGENT_LOGGING_VERBOSITY=debug

# Platform tuning
export EMBABEL_AGENT_PLATFORM_AUTONOMY_AGENT_CONFIDENCE_CUT_OFF=0.8
export EMBABEL_AGENT_PLATFORM_RANKING_MAX_ATTEMPTS=10

# Infrastructure toggles
export EMBABEL_AGENT_INFRASTRUCTURE_NEO4J_ENABLED=true
export EMBABEL_AGENT_INFRASTRUCTURE_MCP_ENABLED=true
export EMBABEL_AGENT_INFRASTRUCTURE_OBSERVABILITY_ENABLED=true

# Shell configuration
export EMBABEL_SHELL_ENABLED=true
export EMBABEL_SHELL_LINELENGTH=120

# Migration detection (disabled by default)
export EMBABEL_AGENT_PLATFORM_MIGRATION_SCANNING_ENABLED=true
```

## Configuration by Environment

### Development Environment

```yaml
# application-development.yml
embabel:
  agent:
    platform:
      test:
        mock-mode: true              # Use mock services
    logging:
      personality: starwars          # Fun logging for development
      verbosity: debug               # Detailed logging
    infrastructure:
      neo4j:
        enabled: true
        uri: bolt://localhost:7687
        authentication:
          username: ${NEO4J_USERNAME:neo4j}
          password: ${NEO4J_PASSWORD:dev}
      observability:
        enabled: true
        tracing:
          sampling-probability: 1.0   # Full sampling in dev
          zipkin-endpoint: http://localhost:9411/api/v2/spans
  shell:
    enabled: true                    # Interactive development

spring:
  profiles:
    active: development
```

### Testing Environment

```yaml
# application-test.yml  
embabel:
  agent:
    platform:
      test:
        mock-mode: true              # Always mock in tests
    logging:
      personality: default           # Clean test output
      verbosity: warn                # Minimal logging
    infrastructure:
      neo4j:
        enabled: false               # Disable external dependencies
      mcp:
        enabled: false
      observability:
        enabled: false
  shell:
    enabled: false                   # No interactive shell in tests
```

### Production Environment

```yaml
# application-production.yml
embabel:
  agent:
    platform:
      test:
        mock-mode: false             # Real services only
    logging:
      personality: default           # Professional logging
      verbosity: info                # Balanced logging
    infrastructure:
      neo4j:
        enabled: true
        uri: ${NEO4J_URI:}           # Required from environment
        authentication:
          username: ${NEO4J_USERNAME:}
          password: ${NEO4J_PASSWORD:}
      mcp:
        enabled: true
        servers:
          github:
            command: docker
            args: ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "mcp/github"]
            env:
              GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_PERSONAL_ACCESS_TOKEN:}
      observability:
        enabled: true
        tracing:
          sampling-probability: 0.1   # Reduced sampling in prod
          zipkin-endpoint: ${ZIPKIN_ENDPOINT:}
  shell:
    enabled: false                   # No interactive shell in production

spring:
  profiles:
    active: production

logging:
  level:
    com.embabel: INFO
    org.springframework: WARN
```

## Configuration Precedence (Highest to Lowest)

1. **Environment Variables** - `EMBABEL_AGENT_LOGGING_PERSONALITY=starwars`
2. **System Properties** - `-Dembabel.agent.logging.personality=starwars`
3. **Application Properties** - `application.yml` values
4. **Platform Defaults** - `agent-platform.properties` defaults
5. **Framework Defaults** - Hardcoded fallbacks

## Security Best Practices

### Never Hardcode Secrets

```yaml
# ❌ NEVER DO THIS
embabel:
  agent:
    infrastructure:
      neo4j:
        authentication:
          password: "hardcoded-password"  # Security vulnerability!

# ✅ SECURE APPROACH
embabel:
  agent:
    infrastructure:
      neo4j:
        authentication:
          password: ${NEO4J_PASSWORD:}    # Must be provided via environment
```

### Use Secrets Management in Production

```bash
# Development (local environment)
export NEO4J_PASSWORD=dev_password

# Production (from AWS Secrets Manager)
export NEO4J_PASSWORD=$(aws secretsmanager get-secret-value \
  --secret-id prod/neo4j/password \
  --query SecretString --output text)

# Production (from Kubernetes secret)
# NEO4J_PASSWORD is mounted from secret volume
```

### Environment-Specific Credentials

```yaml
# application-development.yml
embabel:
  agent:
    infrastructure:
      neo4j:
        uri: bolt://localhost:7687
        authentication:
          username: ${NEO4J_USERNAME:dev_user}
          password: ${NEO4J_PASSWORD:dev_password}

# application-production.yml  
embabel:
  agent:
    infrastructure:
      neo4j:
        uri: ${NEO4J_URI:}                    # Required
        authentication:
          username: ${NEO4J_USERNAME:}        # Required  
          password: ${NEO4J_PASSWORD:}        # Required
```

## Property Validation

### Built-in Validation

```kotlin
@ConfigurationProperties("embabel.agent.infrastructure.neo4j")
@Validated
data class Neo4jConfiguration(
    var enabled: Boolean = false,
    
    @field:NotBlank(message = "Neo4j URI must be provided when enabled")
    var uri: String = "",
    
    @field:Valid
    var authentication: AuthConfig = AuthConfig()
) {
    data class AuthConfig(
        @field:NotBlank(message = "Neo4j username must be provided")
        var username: String = "",
        
        @field:NotBlank(message = "Neo4j password must be provided") 
        var password: String = ""
    )
}
```

### Custom Validation

```kotlin
@Component
class ConfigurationValidator {
    
    @PostConstruct
    fun validateConfiguration() {
        validateApiKeys()
        validateEndpoints()
        validateBusinessRules()
    }
    
    private fun validateApiKeys() {
        if (System.getenv("OPENAI_API_KEY").isNullOrBlank()) {
            throw IllegalStateException("OPENAI_API_KEY environment variable is required")
        }
    }
}
```

## IDE Support

### Auto-completion Configuration

Add to your `src/main/resources/META-INF/spring-configuration-metadata.json`:

```json
{
  "properties": [
    {
      "name": "embabel.agent.logging.personality",
      "type": "java.lang.String",
      "description": "The personality theme for agent logging output",
      "defaultValue": "default",
      "hints": {
        "values": [
          {"value": "default", "description": "Standard Embabel logging"},
          {"value": "starwars", "description": "Star Wars themed logging"},
          {"value": "severance", "description": "Lumon Industries themed logging"},
          {"value": "hitchhiker", "description": "Hitchhiker's Guide themed logging"},
          {"value": "montypython", "description": "Monty Python themed logging"},
          {"value": "colossus", "description": "1970s sci-fi themed logging"}
        ]
      }
    },
    {
      "name": "embabel.agent.infrastructure.neo4j.enabled",
      "type": "java.lang.Boolean",
      "description": "Enable Neo4j integration for graph database functionality",
      "defaultValue": false
    }
  ]
}
```

## IDE Auto-Completion Support

Enable IntelliJ IDEA and VS Code auto-completion for Embabel properties:

### **Add Configuration Processor**
```xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>
```

### **Rebuild and Restart IDE**
1. **Clean and rebuild** your project: `mvn clean compile`
2. **Restart your IDE** to pick up the new configuration metadata
3. **Auto-completion works** in `application.yml` and `application.properties`

### **Available Auto-Completions**
- **`embabel.agent.logging.personality`** - Dropdown with valid values (starwars, severance, etc.)
- **`embabel.agent.infrastructure.neo4j.*`** - All Neo4j configuration options
- **`embabel.agent.infrastructure.mcp.*`** - MCP server configuration
- **`embabel.shell.*`** - Shell configuration options

### **Custom Configuration Metadata**
Add your own auto-completion hints:

```json
// src/main/resources/META-INF/additional-spring-configuration-metadata.json
{
  "properties": [
    {
      "name": "myapp.agent.timeout",
      "type": "java.time.Duration",
      "description": "Timeout for agent operations",
      "defaultValue": "30s"
    }
  ]
}
```

## Troubleshooting Configuration

### Common Issues

#### Property Not Being Applied
```bash
# Check property resolution
java -jar app.jar --debug

# Verify environment variables
env | grep EMBABEL

# Check Spring Boot configuration properties report
java -jar app.jar --spring.config.location=classpath:application.yml
```

#### Missing Required Properties
```
Error: Neo4j username must be provided when enabled
```
**Solution:**
```bash
export NEO4J_USERNAME=your_username
export NEO4J_PASSWORD=your_password
```

#### Profile Configuration Conflicts
```
WARN: DEPRECATED: Profile 'neo' is deprecated
```
**Solution:** Remove profile usage and migrate to property-based config:
```yaml
# Remove:
spring:
  profiles:
    active: neo

# Replace with:
embabel:
  agent:
    infrastructure:
      neo4j:
        enabled: true
```

### Configuration Debugging

#### Enable Configuration Logging
```yaml
logging:
  level:
    org.springframework.boot.context.config: DEBUG
    org.springframework.core.env: DEBUG
```

#### Dump All Properties
```bash
# Add actuator dependency
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

# Enable configprops endpoint
management:
  endpoints:
    web:
      exposure:
        include: configprops

# View at: http://localhost:8080/actuator/configprops
```

## Migration from Profile-Based Configuration

See **[PROFILES_MIGRATION_GUIDE.md](PROFILES_MIGRATION_GUIDE.md)** for detailed migration instructions.

### Quick Migration Summary

| Old Profile | New Property | Description |
|-------------|--------------|-------------|
| `spring.profiles.active=starwars` | `embabel.agent.logging.personality=starwars` | Personality selection |
| `spring.profiles.active=shell` | `embabel.shell.enabled=true` | Shell activation |
| `spring.profiles.active=neo` | `embabel.agent.infrastructure.neo4j.enabled=true` | Neo4j integration |
| `spring.profiles.active=docker-desktop` | `embabel.agent.infrastructure.mcp.enabled=true` | MCP integration |

### Enable Migration Detection

```bash
# Enable comprehensive migration detection
export EMBABEL_AGENT_PLATFORM_MIGRATION_SCANNING_ENABLED=true

# Restart application to see migration warnings
java -jar app.jar
```

This will show warnings for any deprecated profile or property usage in your configuration.

---

For more configuration examples and patterns, see:
- **[Development Guide](Development-Guide.md)** - Environment-specific configurations
- **[Testing Cookbook](Testing-Cookbook.md)** - Test configuration patterns
- **[Production Deployment](Production-Deployment.md)** - Production configuration strategies