Service API Boundary

Date: 2026-05-06

Decision

The first service boundary will be an optional FastAPI layer over the programmatic contracts implemented in kontextual_engine. The service must not define separate business behavior; it should expose the same artifact, collection, relationship, ingestion, query, workflow, and context operations as HTTP resources.

Implemented MVP Resource Shape

Implemented in KONT-WP-0009-T001:

GET /health
GET /ready
GET /version
GET /api/v1/health
GET /api/v1/ready
GET /api/v1/version
GET /openapi.json

Implemented in KONT-WP-0009-T002:

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

The unversioned health/readiness/version endpoints are operational probes. The versioned /api/v1/* endpoints establish the MVP API namespace. Future domain-resource endpoints should live under /api/v1.

The service dependency is optional. Importing kontextual_engine and kontextual_engine.api does not require FastAPI; calling create_app() does. Install the service extra to run the HTTP adapter:

python3 -m pip install -e '.[service]'

Planned Resource Shape

Planned endpoint groups:

POST /collections, GET /collections, GET /collections/{id}
POST /artifacts, GET /artifacts/{id}, GET /artifacts
POST /relationships, GET /relationships
POST /ingest
POST /query/artifacts, POST /query/relationships
POST /runs, GET /runs/{id}, GET /runs/{id}/manifest
POST /context/artifact/{id}

For the governed asset registry architecture, these planned groups should be translated to assets, metadata, relationships, ingestion jobs, retrieval, transformations, workflow templates/runs, review queues, and reconstruction resources.

MVP API Versioning Policy

/api/v1 is the first stable namespace for implemented service resources.
Backward-incompatible changes require a new namespace such as /api/v2.
Additive response fields are allowed inside a version.
Structured diagnostics and error codes are part of the contract and should remain stable inside a version.
Unversioned operational probes may remain as aliases for the active API generation, but domain-resource endpoints must be versioned.

Rules

The Python API is canonical until contracts stabilize.
HTTP handlers must translate request/response envelopes only.
Markdown parsing, document transforms, selectors, contracts, and local indexes must remain adapter calls to markitect-tool.
Provider calls must remain adapter calls to llm-connect.
Structured diagnostics and errors must be preserved in responses.

Deferred

Ingestion, retrieval, transformation, and workflow endpoints.
Actor context, delegation, and authorization middleware.
Agent-safe operation catalog.
Context package API.
Dry-run and review-gate response envelopes for high-impact operations.
Streaming run execution.
Provider-backed assisted steps.

3.2 KiB Raw Blame History