# Custom Fields

Add extra fields to `model_data_logs` for custom tracking and monitoring needs.

## Overview

The `custom_fields` parameter allows you to include additional fields in the encrypted `model_data_logs` sent to the RAIT API. These fields are merged with standard fields like `prompt_id`, `ethical_dimensions`, and telemetry data.

## Single Evaluation

Use `custom_fields` to pass a dictionary of additional values:

```python
from rait_connector import RAITClient

client = RAITClient()

result = client.evaluate(
    prompt_id="123",
    prompt_url="https://example.com/123",
    timestamp="2025-12-11T10:00:00Z",
    model_name="gpt-4",
    model_version="1.0",
    query="What is AI?",
    response="AI is artificial intelligence...",
    environment="production",
    purpose="monitoring",
    custom_fields={
        "user_id": "user_123",
        "session_id": "session_abc",
        "custom_metric": 0.95,
        "api_version": "v2.1",
        "region": "us-east-1"
    }
)
```

## Batch Evaluation

For batch evaluation, `custom_fields` is specified per prompt:

```python
from rait_connector import RAITClient

client = RAITClient()

prompts = [
    {
        "prompt_id": "batch-001",
        "prompt_url": "https://example.com/prompt/001",
        "timestamp": "2025-12-11T10:00:00Z",
        "model_name": "gpt-4",
        "model_version": "1.0",
        "query": "What is AI?",
        "response": "AI is...",
        "environment": "production",
        "purpose": "monitoring",
        "custom_fields": {
            "user_id": "user_123",
            "session_id": "session_abc",
        },
    },
    {
        "prompt_id": "batch-002",
        "prompt_url": "https://example.com/prompt/002",
        "timestamp": "2025-12-11T10:01:00Z",
        "model_name": "gpt-4",
        "model_version": "1.0",
        "query": "What is ML?",
        "response": "ML is...",
        "environment": "production",
        "purpose": "monitoring",
        "custom_fields": {
            "user_id": "user_456",
            "session_id": "session_def",
        },
    },
]

summary = client.evaluate_batch(prompts=prompts)
```

## Use Cases

### User Context Tracking

```python
custom_fields = {
    "user_id": current_user.id,
    "organization_id": current_user.org_id,
    "subscription_tier": current_user.subscription
}
```

### Performance Monitoring

```python
custom_fields = {
    "response_time_ms": response_timer.elapsed(),
    "tokens_used": token_counter.count,
    "cache_hit": cache.was_hit()
}
```

### A/B Testing

```python
custom_fields = {
    "experiment_id": "exp_123",
    "variant": "variant_b",
    "feature_flags": ["new_ui", "enhanced_search"]
}
```

### Custom Business Metrics

```python
custom_fields = {
    "customer_segment": "enterprise",
    "request_priority": "high",
    "sla_tier": "gold",
    "cost_center": "engineering"
}
```

## Data Flow

1. Base `model_data_logs` is constructed with standard fields
2. `custom_fields` dict is merged (if provided)
3. Complete `model_data_logs` is encrypted
4. Encrypted data is sent to RAIT API

## Best Practices

1. **Keep it simple**: Only add fields you actually need
2. **Avoid PII**: Don't include sensitive personal information
3. **Use meaningful names**: Make field names descriptive and consistent
4. **Document custom fields**: Keep track of what each field means
