kontextual-engine/docs/service-api-implementation.md

# 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

```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`
- `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:

```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,
- 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.