# Actor Configuration API Reference

## Overview

CleverAgents uses an actor-first architecture where all AI interactions are performed through actors. Actors encapsulate provider, model, and configuration details into a single reusable entity.

## Actor Configuration Format

Actor configurations use YAML or JSON format and must conform to the v2 schema. No alternative schemas or extensions are supported.

### Basic Structure

```yaml
# Minimal actor configuration
provider: openai
model: gpt-4

# Extended configuration with options
provider: anthropic
model: claude-3-opus
options:
  temperature: 0.7
  max_tokens: 4000
  
# Graph-based actor with tools
graph: ToolAgentGraph
provider: openai
model: gpt-4
tools:
  - name: code_search
    description: Search codebase for patterns
  - name: file_reader
    description: Read file contents
options:
  temperature: 0.5
```

## Configuration Fields

### Core Fields

#### `provider` (required)
- **Type**: `string`
- **Description**: The AI provider to use
- **Valid Values**: `openai`, `anthropic`, `google`, `azure`, `groq`, `cohere`, `together`, `gemini`, `openrouter`, `mock`
- **Example**: `provider: openai`

#### `model` (required)
- **Type**: `string`
- **Description**: The specific model from the provider
- **Examples**:
  - OpenAI: `gpt-4`, `gpt-3.5-turbo`
  - Anthropic: `claude-3-opus`, `claude-3-sonnet`
  - Google: `gemini-pro`, `gemini-pro-vision`

#### `graph` (optional)
- **Type**: `string`
- **Description**: The LangGraph workflow to use
- **Default**: `BasicChatGraph`
- **Available Graphs**:
  - `BasicChatGraph` - Simple chat completion
  - `PlanGenerationGraph` - Multi-step plan generation
  - `ContextAnalysisAgent` - Code analysis workflow
  - `AutoDebugGraph` - Error detection and fixing
  - `ToolAgentGraph` - Tool-calling agent

#### `options` (optional)
- **Type**: `object`
- **Description**: Provider-specific configuration options
- **Common Options**:
  ```yaml
  options:
    temperature: 0.7          # Creativity (0.0-1.0)
    max_tokens: 4000         # Maximum response length
    top_p: 0.9              # Nucleus sampling
    frequency_penalty: 0.0   # Reduce repetition
    presence_penalty: 0.0    # Encourage new topics
    stop: ["```", "\n\n"]   # Stop sequences
  ```

### Advanced Fields

#### `tools` (optional)
- **Type**: `array`
- **Description**: Tools available to the actor (requires compatible graph)
- **Structure**:
  ```yaml
  tools:
    - name: tool_name
      description: What the tool does
      parameters:
        param1: string
        param2: number
  ```

#### `context` (optional)
- **Type**: `object`
- **Description**: Initial context variables injected at runtime
- **Example**:
  ```yaml
  context:
    project_type: web_app
    language: python
    framework: fastapi
  ```

#### `unsafe` (optional)
- **Type**: `boolean`
- **Description**: Explicitly mark configuration as unsafe
- **Default**: Auto-detected based on content
- **Note**: Unsafe actors require `--unsafe` flag when adding

## Graph Descriptors

Graph descriptors are automatically generated from the configuration and describe the actor's capabilities:

```json
{
  "type": "PlanGenerationGraph",
  "capabilities": ["streaming", "retry", "validation"],
  "nodes": ["analyze", "generate", "validate"],
  "edges": ["conditional", "retry"],
  "requires_context": true
}
```

### Capability Flags

- `streaming` - Supports real-time output streaming
- `retry` - Has built-in retry logic
- `validation` - Validates outputs before returning
- `tools` - Can use external tools
- `memory` - Maintains conversation history
- `context` - Requires or uses context

## Unsafe Detection Rules

Configurations are analyzed for potentially unsafe operations:

### Automatically Detected as Unsafe

1. **Shell/System Access**
   ```yaml
   tools:
     - name: shell_execute
       description: Execute shell commands
   ```

2. **File System Writes**
   ```yaml
   tools:
     - name: file_write
       description: Write to filesystem
       parameters:
         path: string
         content: string
   ```

3. **Network Access**
   ```yaml
   tools:
     - name: http_request
       description: Make HTTP requests
   ```

4. **Code Execution**
   ```yaml
   graph: CodeExecutionGraph
   options:
     allow_exec: true
   ```

### Marking as Safe

If auto-detection incorrectly flags a configuration:

```yaml
# Override auto-detection
unsafe: false
provider: openai
model: gpt-4
# ... rest of config
```

## Environment Variable Interpolation

Actor configurations support environment variable interpolation:

```yaml
provider: openai
model: ${MODEL_NAME:-gpt-4}
options:
  api_key: ${OPENAI_API_KEY}
  temperature: ${TEMPERATURE:-0.7}
  max_tokens: ${MAX_TOKENS:-4000}
```

### Interpolation Syntax

- `${VAR}` - Use environment variable VAR
- `${VAR:-default}` - Use VAR or default value if not set
- `${VAR:?error message}` - Error if VAR not set

## Provider/Model Mapping

Actor configurations map to provider implementations:

### OpenAI Example
```yaml
provider: openai
model: gpt-4
```

Maps to:
- Provider class: `OpenAIProvider`
- Model identifier: `gpt-4`
- API endpoint: `https://api.openai.com/v1`

### Custom Endpoints
```yaml
provider: openai
model: gpt-4
options:
  base_url: http://localhost:8080/v1
  api_key: local-key
```

## Configuration Hash Calculation

The configuration hash is a SHA-256 digest of the canonical JSON representation:

1. Parse YAML/JSON to object
2. Remove comments and formatting
3. Sort keys alphabetically
4. Serialize to canonical JSON
5. Calculate SHA-256 hash

Example:
```python
config_hash = hashlib.sha256(
    json.dumps(config, sort_keys=True).encode()
).hexdigest()
```

## Usage in Commands

### Creating Custom Actors

```bash
# From configuration file
agents actor add --name assistant --config ./assistant.yaml

# Results in actor: local/assistant
```

### Using Actors

```bash
# Use specific actor
agents tell "refactor this function" --actor local/assistant

# Use with options override
agents build --actor openai/gpt-4 --option temperature=0.2
```

### Built-in Actor Names

Built-in actors follow the pattern `<provider>/<model>`:
- `openai/gpt-4`
- `openai/gpt-3.5-turbo`
- `anthropic/claude-3-opus`
- `google/gemini-pro`
- `mock/test-model`

## Error Handling

### Common Configuration Errors

1. **Missing Required Fields**
   ```
   ERROR: Configuration missing required field 'provider'
   ```

2. **Invalid Provider/Model**
   ```
   ERROR: Unknown provider 'invalid'
   ```

3. **Unsafe Without Flag**
   ```
   ERROR: Configuration appears unsafe. Add --unsafe flag to confirm.
   ```

4. **Invalid YAML/JSON**
   ```
   ERROR: Failed to parse configuration: expected ':', got '}'
   ```

## Best Practices

1. **Use Descriptive Names**
   ```bash
   agents actor add --name code-reviewer --config ./reviewer.yaml
   ```

2. **Set Appropriate Options**
   ```yaml
   # For code generation
   options:
     temperature: 0.2  # Lower for consistency
     max_tokens: 8000  # Higher for complete code
   ```

3. **Document Custom Actors**
   ```yaml
   # Code review assistant optimized for Python
   provider: openai
   model: gpt-4
   context:
     purpose: code_review
     language: python
   ```

4. **Version Control Configurations**
   - Store actor configs in `./actors/` directory
   - Track changes in git
   - Use meaningful commit messages