generated from coulomb/repo-seed
87 lines
2.3 KiB
Markdown
87 lines
2.3 KiB
Markdown
# Service API Implementation Note
|
|
|
|
Date: 2026-05-06
|
|
|
|
Status: active implementation note for `KONT-WP-0009`.
|
|
|
|
## Purpose
|
|
|
|
This note records the first optional FastAPI service adapter. The service layer
|
|
is intentionally thin: it exposes operational probes and API version metadata
|
|
while leaving domain behavior in the application services.
|
|
|
|
## Implemented Package Shape
|
|
|
|
```text
|
|
src/kontextual_engine/
|
|
api/
|
|
__init__.py
|
|
app.py
|
|
```
|
|
|
|
`kontextual_engine.api.create_app()` builds the FastAPI app when the optional
|
|
`service` extra is installed. Importing the package does not require FastAPI.
|
|
|
|
## Implemented Endpoints
|
|
|
|
- `GET /health`
|
|
- `GET /ready`
|
|
- `GET /version`
|
|
- `GET /api/v1/health`
|
|
- `GET /api/v1/ready`
|
|
- `GET /api/v1/version`
|
|
- `GET /openapi.json`
|
|
|
|
Unversioned endpoints are operational probes. Versioned endpoints establish
|
|
the `/api/v1` namespace for future domain resources.
|
|
|
|
## Runtime Contract
|
|
|
|
`ServiceRuntime` owns the adapter runtime state:
|
|
|
|
- repository reference,
|
|
- API version,
|
|
- service name,
|
|
- startup timestamp,
|
|
- package version discovery,
|
|
- health payload,
|
|
- readiness checks,
|
|
- version payload.
|
|
|
|
Readiness currently checks that the configured asset registry repository can
|
|
list assets. It does not mutate state.
|
|
|
|
## Dependency Boundary
|
|
|
|
The `service` extra now includes FastAPI, Uvicorn, and HTTPX for test-client
|
|
execution:
|
|
|
|
```text
|
|
kontextual-engine[service]
|
|
```
|
|
|
|
The current workspace does not have FastAPI installed, so HTTP adapter tests
|
|
are skipped locally until the extra is installed. The pure runtime contract and
|
|
missing-dependency behavior are tested without FastAPI.
|
|
|
|
## Test Coverage
|
|
|
|
`tests/test_service_api.py` covers:
|
|
|
|
- service runtime health/readiness/version without FastAPI installed,
|
|
- `create_app()` missing-dependency behavior when the optional extra is absent,
|
|
- health/readiness/version/OpenAPI endpoint contracts when FastAPI and HTTPX
|
|
are installed,
|
|
- runtime attachment to FastAPI application state when the service extra is
|
|
installed.
|
|
|
|
## Not Yet Implemented
|
|
|
|
- Asset, metadata, relationship, audit, and policy endpoints.
|
|
- Ingestion, retrieval, transformation, workflow, review, and reconstruction
|
|
endpoints.
|
|
- Request actor context and delegation middleware.
|
|
- Bounded agent operation catalog.
|
|
- Context package API.
|
|
- Dry-run and review-gate response envelopes.
|