86 lines
2 KiB
Markdown
86 lines
2 KiB
Markdown
|
# 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.
|