# Documentation for Kamiwaza 1.0.0

This is documentation for Kamiwaza **1.0.0**, which is no longer actively maintained. For the current GA release, see [**1.0.1**](https://docs.kamiwaza.ai/).

## Overview

Kamiwaza can register any external endpoint that speaks the OpenAI `/v1/chat/completions` wire format and proxy it through the same deployment, audit, and access-control surfaces as locally hosted models. This includes OpenAI directly, Microsoft Azure's OpenAI Service and AI Foundry, customer-hosted LiteLLM proxies, self-hosted vLLM or Ollama, and any other provider whose chat API matches the OpenAI shape.

Once registered, the endpoint deploys through the normal model lifecycle and exposes a Kamiwaza `/v1/chat/completions` route that applications can call without knowing which provider sits behind it.

## Prerequisites

Before registering an OpenAI-compatible endpoint, make sure:

- You have a provider API key (OpenAI key, Azure resource key, Azure AI Foundry project key, LiteLLM master key, etc.).
- The model you intend to register is enabled on the account the API key belongs to. For Azure, the deployment exists in the project the URL points at.
- Outbound HTTPS from the Kamiwaza control plane to the provider hostname is permitted.

## Quick Start (UI)

Registration is a three-step wizard: pick the provider, configure the endpoint, then pick which discovered models to register.

1. In Kamiwaza, go to **Models**, click **Add Model**, then click **Add external inference endpoint** in the dialog header.

2. **Source** — under **Where is your model hosted?**, choose one of:
   - **OpenAI** — for OpenAI directly.
   - **Azure** — for Azure OpenAI Service or Azure AI Foundry.
   - **Other (OpenAI-compatible)** — for LiteLLM proxies, vLLM, Ollama, or any other host whose chat API matches the OpenAI shape.

Click **Next**.

3. **Setup** — configure the endpoint:
   - **Inference endpoint URL**— The provider's API root.
   - **Credentials** — If a credential is already stored for this endpoint, Kamiwaza offers **Use existing credential** with a **Use a different credential** link to override. Otherwise paste the provider API key.

Click **Connect**. Kamiwaza validates the URL, authenticates with the credential, and discovers the models the endpoint exposes.

4. **Review** — Kamiwaza shows the list of models discovered on the endpoint. Tick the checkbox for each model you want to register. Expand a row to customize the display name, default parameters, or other per-model settings. Click **Register N models** when done.

5. From the Models list, deploy each newly registered model.

> Test each deployment from the Models list to confirm Kamiwaza can reach the provider with the credentials you supplied before applications start calling it.

## Provider examples

The wizard is the same for every provider; only the values change.

### OpenAI directly

| Field | Value |
| --- | --- |
| Source | **OpenAI** |
| Inference endpoint URL | `https://api.openai.com/v1` |
| Credential | OpenAI API key (`sk-…`) |
| Underlying model (Review step) | `gpt-5`, `gpt-4o`, `gpt-5-chat-latest`, etc. |

> Restricted OpenAI keys default to chat-only. If you also intend to register a transcription endpoint with the same key, widen the key's scope to include `Audio` first.

### Azure OpenAI Service

| Field | Value |
| --- | --- |
| Source | **Azure** |
| Inference endpoint URL | `https://<your-resource>.openai.azure.com` |
| Credential | Azure OpenAI resource key |
| Underlying model (Review step) | The Azure deployment name (e.g. `gpt-4o`) |

Kamiwaza auto-detects the `*.openai.azure.com` host.

### Azure AI Foundry

| Field | Value |
| --- | --- |
| Source | **Azure** |
| Inference endpoint URL | `https://<your-project>.services.ai.azure.com/models` |
| Credential | Azure AI Foundry project key |
| Underlying model (Review step) | The Foundry deployment name (e.g. `Mistral-Large-3`) |

### Customer-hosted LiteLLM proxy

| Field | Value |
| --- | --- |
| Source | **Other (OpenAI-compatible)** |
| Inference endpoint URL | Your published proxy URL (e.g. `https://litellm.example.com`) |
| Credential | The proxy's master key (or a virtual key) |
| Underlying model (Review step) | The model alias as configured in your LiteLLM config |

### Self-hosted vLLM, Ollama, or other OpenAI-compatible service

Use **Other (OpenAI-compatible)**, paste your internal hostname, and supply whatever bearer token the service requires (or any non-empty placeholder if it's open).

## Credentials

Credentials registered through the OpenAI-compatible form are encrypted on save and stored in the Kamiwaza secret catalog, keyed by base URL. For most providers the credential is a single API key string. Kamiwaza handles wrapping it in the right header based on the detected provider.

## API Usage

Once deployed, the endpoint is callable via the standard Kamiwaza runtime route:

```bash
curl -X POST "https://<your-domain>/runtime/models/<deployment-id>/v1/chat/completions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 50
  }'
```

## Operational notes

- Inference errors from the upstream provider are surfaced through the Kamiwaza response body.
- Multiple registered models that share a base URL share one credential in the catalog.

## Next steps

- Register a transcription endpoint against the same provider.