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 governed asset-resource, job, retrieval, transformation, and workflow 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
GET /api/v1/context
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 /api/v1/ingestion/capabilities
POST /api/v1/ingestion/jobs
GET /api/v1/ingestion/jobs
GET /api/v1/ingestion/jobs/{job_id}
POST /api/v1/retrieval/index/refresh
POST /api/v1/retrieval/assets
POST /api/v1/retrieval/context-entities
POST /api/v1/retrieval/relationships
POST /api/v1/retrieval/feedback
GET /api/v1/retrieval/feedback
GET /api/v1/retrieval/quality
GET /api/v1/transformations/operations
POST /api/v1/transformations/runs
GET /api/v1/transformations/runs
GET /api/v1/transformations/runs/{run_id}
POST /api/v1/transformations/runs/{run_id}/retry
POST /api/v1/transformations/runs/{run_id}/cancel
POST /api/v1/workflows/templates
GET /api/v1/workflows/templates
GET /api/v1/workflows/templates/{template_id}
POST /api/v1/workflows/runs
POST /api/v1/workflows/runs/queue
GET /api/v1/workflows/runs
GET /api/v1/workflows/runs/{run_id}
POST /api/v1/workflows/runs/{run_id}/resume
POST /api/v1/workflows/runs/{run_id}/retry
POST /api/v1/workflows/runs/{run_id}/cancel
GET /api/v1/workflows/runs/{run_id}/reconstruction
GET /api/v1/workflows/reviews
GET /api/v1/workflows/exceptions
POST /api/v1/workflows/runs/{run_id}/reviews/{review_id}/decision
GET /api/v1/agents/operations
GET /api/v1/agents/operations/{operation_id}
POST /api/v1/agents/operations/{operation_id}
GET /api/v1/context-packages/schema
POST /api/v1/context-packages
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,
actor/correlation/delegation context construction,
asset, metadata, lifecycle, relationship, audit, and policy operation translation,
ingestion job start/list/get translation,
governed retrieval query translation for assets, context entities, and relationships,
transformation operation/run/retry/cancel translation,
workflow template/run/review/exception/reconstruction translation,
bounded agent operation catalog and dispatch translation,
governed context-package assembly translation.

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

Asset, metadata, relationship, lifecycle, audit, policy, ingestion, retrieval, transformation, and workflow operations delegate to existing application services, the configured repository, and the configured PolicyGateway. Protected mutations and retrieval operations therefore keep the existing policy and audit semantics.

KONT-WP-0009-T004 expanded request context parsing. The FastAPI adapter now accepts explicit actor, delegated actor, group, agent, request-scope, and policy-scope headers, and exposes the resulting operation context at GET /api/v1/context. Authorization errors are redacted at the HTTP boundary so denied responses keep action, resource, correlation, and public policy decision fields while omitting protected resource metadata from policy context.

Job and run responses include correlation IDs, state, output references, failures or diagnostics, and compact retry/cancel hints where the runtime can derive them. Retrieval responses remain permission-filtered and source-grounded through source references, representations, snippets, relationships, and retrieval audit events. Transformation and workflow responses expose lineage, audit events, run reconstruction, review tasks, and exception queues from the underlying core services.

KONT-WP-0009-T005 added a bounded agent operation catalog. Agents can list documented operations and execute only those operation IDs. Each catalog entry declares required permissions, input/output shape notes, audit operation, failure modes, and dry-run support. Execution first authorizes and audits agent.operation.*, then dispatches through existing runtime operations such as retrieval, metadata enrichment, transformation, workflow invocation, review submission, or result reporting.

KONT-WP-0009-T006 added a governed context-package assembly API. Packages are assembled from permission-filtered retrieval results rather than unrestricted repository reads. The payload carries selected assets, snippets, metadata, relationships, representations, source references, policy constraints, opaque external memory refs, and an audit event. The markitect format adds a Markitect-compatible payload envelope while keeping markdown rendering, selector semantics, and contract checks delegated to markitect-tool.

KONT-WP-0009-T007 added explicit review/dry-run response envelopes for agent operation policy decisions. require_review decisions now return review_required envelopes with review obligations and review_required audit outcomes. dry_run_only decisions return dry_run_required envelopes unless the request is already a dry run. Partial-failure contracts are covered through directory ingestion with mixed supported and unsupported inputs.

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,
runtime actor context with delegated actors and AI-agent identity,
redacted API authorization error payloads,
runtime ingestion jobs with completed and failed job envelopes,
runtime source-grounded retrieval with snippets,
runtime transformation runs with lineage and audit references,
runtime workflow template/run/reconstruction contracts,
runtime bounded agent operation catalog, dry-run behavior, dispatch, and separate agent audit events,
runtime context-package assembly with source-grounded results, opaque memory references, and Markitect-compatible payload shape,
runtime review-required and dry-run-only agent operation envelopes,
runtime partial-failure ingestion job envelopes,
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

No MVP service API tasks remain open in KONT-WP-0009.

8.1 KiB Raw Blame History