# Model Configuration

This SDK builds on pydantic-ai. There are two ways to configure models:

1. **Native pydantic-ai model strings** - Direct connection to provider APIs
2. **Gateway mode** - Route requests through a unified gateway

## Quick Start

```python
from ya_agent_sdk.agents.models import infer_model

# Option 1: Native pydantic-ai format (direct provider connection)
model = infer_model("openai-chat:gpt-4o")
model = infer_model("anthropic:claude-3-5-sonnet-20241022")

# Option 2: Gateway format (via gateway proxy)
model = infer_model("mygateway@openai-chat:gpt-4o")
model = infer_model("mygateway@anthropic:claude-3-5-sonnet-20241022")
```

## Native pydantic-ai Models

Model strings without `@` are passed directly to pydantic-ai, supporting all built-in providers.

See official docs: [pydantic-ai Models](https://ai.pydantic.dev/models/)

**Common formats:**

| Provider     | Format                                             | Example                                |
| ------------ | -------------------------------------------------- | -------------------------------------- |
| OpenAI       | `openai-chat:<model>` / `openai-responses:<model>` | `openai-chat:gpt-4o`                   |
| Anthropic    | `anthropic:<model>`                                | `anthropic:claude-3-5-sonnet-20241022` |
| Google       | `google:<model>`                                   | `google:gemini-2.5-pro`                |
| Google Cloud | `google-cloud:<model>`                             | `google-cloud:gemini-2.5-pro`          |
| Groq         | `groq:<model>`                                     | `groq:llama-3.1-70b-versatile`         |

## Google Vertex AI Configuration

Google Cloud Vertex AI requires additional configuration via environment variables. pydantic-ai automatically reads these variables when using the `google-cloud:` prefix.

### Environment Variables

| Variable                         | Description                          | Required                  |
| -------------------------------- | ------------------------------------ | ------------------------- |
| `GOOGLE_API_KEY`                 | API key for Vertex AI authentication | One of API key or ADC     |
| `GOOGLE_APPLICATION_CREDENTIALS` | Path to service account JSON file    | For service account auth  |
| `GOOGLE_CLOUD_PROJECT`           | GCP project ID                       | Recommended for Vertex AI |
| `GOOGLE_CLOUD_LOCATION`          | GCP region (default: `us-central1`)  | Optional                  |

### Authentication Methods

**Method 1: API Key**

```bash
export GOOGLE_API_KEY=your-api-key
```

```python
model = infer_model("google-cloud:gemini-2.5-pro")
```

**Method 2: Application Default Credentials (ADC)**

```bash
# Login with gcloud CLI
gcloud auth application-default login

# Set project and location
export GOOGLE_CLOUD_PROJECT=my-project-id
export GOOGLE_CLOUD_LOCATION=us-central1
```

```python
model = infer_model("google-cloud:gemini-2.5-pro")
```

**Method 3: Service Account**

```bash
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
export GOOGLE_CLOUD_PROJECT=my-project-id
export GOOGLE_CLOUD_LOCATION=us-central1
```

```python
model = infer_model("google-cloud:gemini-2.5-pro")
```

### Available Regions

Common regions for Vertex AI:

- `us-central1` (default, most model support)
- `us-east1`, `us-east4`, `us-east5`, `us-west1`, `us-west4`
- `europe-west1`, `europe-west2`, `europe-west3`, `europe-west4`
- `asia-east1`, `asia-northeast1`, `asia-southeast1`
- `global` (higher availability, fewer models)

For full list, see [Vertex AI Locations](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations).

### References

- [pydantic-ai Google Models](https://ai.pydantic.dev/models/google/)
- [Vertex AI Authentication](https://cloud.google.com/vertex-ai/docs/authentication)

## Gateway Mode

Use `gateway_name@provider:model` format to route requests through a unified gateway. Useful for:

- Centralized API key management across multiple providers
- Internal proxy/load balancing scenarios
- Sticky routing requirements

### Environment Variables

Gateway mode requires two environment variables (using `mygateway` as example):

```bash
# API Key (required)
MYGATEWAY_API_KEY=your-api-key

# Gateway Base URL (required)
MYGATEWAY_BASE_URL=https://your-gateway.example.com/v1
```

Naming convention: `{GATEWAY_NAME}_API_KEY` and `{GATEWAY_NAME}_BASE_URL`

### Supported Providers

| Provider Name                                 | Model String Format                            |
| --------------------------------------------- | ---------------------------------------------- |
| `openai` / `openai-chat` / `openai-responses` | `gateway@openai-chat:gpt-4o`                   |
| `anthropic`                                   | `gateway@anthropic:claude-3-5-sonnet-20241022` |
| `gemini` / `google-vertex`                    | `gateway@gemini:gemini-1.5-pro`                |
| `groq`                                        | `gateway@groq:llama-3.1-70b-versatile`         |
| `bedrock` / `converse`                        | `gateway@bedrock:anthropic.claude-3-sonnet`    |

### Sticky Routing

For session affinity scenarios, pass `extra_headers`:

```python
model = infer_model(
    "mygateway@gemini:gemini-1.5-pro",
    extra_headers={"x-session-id": "unique-session-id"}
)
```

**Note**: `extra_headers` only applies to Gateway mode, primarily for providers like `gemini` and `bedrock` that require header injection via http_client.

## Anthropic Adaptive Thinking Presets

When configuring Anthropic models through ya-agent-sdk presets:

- `anthropic` resolves to adaptive thinking by default.
- `anthropic_adaptive_xhigh` is available for Claude Opus 4.7.
- `anthropic_adaptive_high`, `anthropic_adaptive_medium`, and `anthropic_adaptive_low` remain the general-purpose effort presets.
- `anthropic_off` disables thinking.

Claude Opus 4.7 uses adaptive thinking as the primary thinking mode. The `xhigh` effort level is intended for long-horizon coding and agentic workloads.

## Integration with pydantic-ai Agent

```python
from pydantic_ai import Agent
from ya_agent_sdk.agents.models import infer_model

agent = Agent(
    model=infer_model("mygateway@openai-chat:gpt-4o"),
    system_prompt="You are a helpful assistant."
)
```

## References

- [pydantic-ai Models Documentation](https://ai.pydantic.dev/models/)
- [pydantic-ai Provider Configuration](https://ai.pydantic.dev/models/#model-configuration)
