# Azure OpenAI setup

This project requires Azure OpenAI for **embeddings only**:

- **Embeddings** (`text-embedding-3-large`, **3072 dims**):
  - role inference (against Data Lake role vocabulary)
  - competence inference (against Data Lake competence vocabulary)
  - similarity scoring for matching

There are **no chat/LLM features** anymore.

## 1) Create an embedding deployment in Azure

In your Azure OpenAI resource, create an embedding deployment for:

- `text-embedding-3-large`

Notes:

- The deployment **name** must match what you set in `config.toml`.
- This project uses 3072 embedding dimensions.

## 2) Configure `config.toml`

Copy the template:

- `cp config.toml.example config.toml`

Set the Azure section:

```toml
[azure_openai]
endpoint = "https://<your-resource>.openai.azure.com"
api_version = "2024-02-15-preview"
embedding_deployment = "text-embedding-3-large"

# Embeddings batching (number of inputs per embeddings API request)
embedding_batch_size = 128

# Optional
show_costs_in_output = false
```

Notes:

- Embeddings requests may be batched (`input=[...]`) and chunked sequentially.
  Increase `embedding_batch_size` to reduce round-trips, or decrease it if you
  suspect request-size related failures.

## 3) Configure credentials via environment variables

The server reads the API key from:

- `AZURE_OPENAI_EMBEDDING_API_KEY`

Recommended: keep secrets in a local `.env` file (do not commit):

```bash
AZURE_OPENAI_EMBEDDING_API_KEY="..."
```

The server also needs database credentials:

- `DATA_LAKE_USERNAME`
- `DATA_LAKE_PASSWORD`

## 4) Verify your setup

### 4.1 Quick import/run smoke check

Start the server with debug logs and confirm it loads your config:

- `uv run teamlandkarte-mcp --config config.toml --log-level DEBUG`

### 4.2 Typical Azure errors

- HTTP 401/403: wrong key or wrong resource
- HTTP 404: deployment name mismatch
- HTTP 429: throttling; warm the embedding cache and/or reduce concurrency
- network/TLS: verify corporate proxy/TLS setup

See `docs/troubleshooting.md` for additional details.