# Contract: HTTP Serve Mode

**layer:** Functional  
**maturity:** Beta  
**module:** `llm_connect.server`  
**since:** WP-0003

## Purpose

Expose any `LLMAdapter` as a lightweight HTTP service.  Intended for
local/inter-process use; not hardened for public internet exposure.

## API endpoints

### `GET /health`

Liveness probe.

**Response 200**

```json
{"status": "ok"}
```

---

### `POST /execute`

Execute a prompt through the configured adapter.

**Request body** (JSON)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `prompt` | string | yes | Prompt text |
| `config` | object | no | `RunConfig` overrides (see below) |

`config` sub-fields (all optional, defaults match `RunConfig` defaults):

| Field | Type | Default |
|-------|------|---------|
| `model_name` | string | `"gpt-4"` |
| `temperature` | float | `0.7` |
| `max_tokens` | int | `2000` |
| `timeout_seconds` | int | `300` |

**Response 200** — `LLMResponse.to_dict()` shape

```json
{
  "content": "...",
  "model": "...",
  "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0},
  "finish_reason": "stop",
  "metadata": {}
}
```

**Error responses**

| HTTP | Condition |
|------|-----------|
| 400 | Missing `prompt` field or invalid JSON body |
| 404 | Unknown path |
| 500 | Adapter raised an exception |

## Implementation notes

- Uses Python stdlib `http.server` — **no additional runtime dependency**.
- The `[server]` optional-dependency group is reserved for future migration
  to `aiohttp`/`starlette` if native async serving is required.
- `LLMServer(adapter, port=0)` binds to an OS-assigned free port; read back
  via `server.port` after `start()`.

## CLI

```
python -m llm_connect.server [--host HOST] [--port PORT] [--provider PROVIDER] [--model MODEL]
```

Default provider: `mock`.  All registered providers from `create_adapter` are valid.

## Known consumers

- `inter-hub` (IHUB-WP-0012 Phase 11): drives federation calls over HTTP from non-Python services.