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, API version metadata, and the first governed asset-resource surface while leaving domain behavior in the application services.

Implemented Package Shape

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
POST /api/v1/assets
GET /api/v1/assets
GET /api/v1/assets/{asset_id}
POST /api/v1/assets/{asset_id}/metadata
GET /api/v1/assets/{asset_id}/metadata
POST /api/v1/assets/{asset_id}/lifecycle
POST /api/v1/relationships
GET /api/v1/relationships
GET /api/v1/audit/events
POST /api/v1/policy/evaluate
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,
asset service construction,
basic actor/correlation context construction,
asset, metadata, lifecycle, relationship, audit, and policy operation translation.

Readiness currently checks that the configured asset registry repository can list assets. It does not mutate state.

Asset, metadata, relationship, lifecycle, audit, and policy operations delegate to AssetRegistryService, the configured repository, and the configured PolicyGateway. Protected mutations therefore keep the existing policy and audit semantics. The current header-to-actor translation is deliberately simple and will be expanded in KONT-WP-0009-T004.

Dependency Boundary

The service extra now includes FastAPI, Uvicorn, and HTTPX for test-client execution:

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,
runtime asset create/list/get operations,
runtime metadata add/list operations,
runtime lifecycle transition operations,
runtime relationship create/list operations,
runtime audit query and policy evaluation,
runtime policy denial blocking a protected operation,
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

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.

3.4 KiB Raw Blame History