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

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:

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.

2.3 KiB Raw Blame History