generated from coulomb/repo-seed
227 lines
9.2 KiB
Markdown
227 lines
9.2 KiB
Markdown
# 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
|
|
|
|
```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`
|
|
- `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 /api/v1/operations/metrics`
|
|
- `GET /api/v1/operations/jobs`
|
|
- `GET /api/v1/operations/events`
|
|
- `GET /api/v1/operations/recovery/actions`
|
|
- `POST /api/v1/operations/recovery/{action}`
|
|
- `POST /api/v1/exports`
|
|
- `POST /api/v1/exports/validate`
|
|
- `POST /api/v1/governance/report`
|
|
- `GET /api/v1/extensions/catalog`
|
|
- `POST /api/v1/extensions/events`
|
|
- `POST /api/v1/quality/signals`
|
|
- `GET /api/v1/quality/cost`
|
|
- `GET /api/v1/performance/smoke`
|
|
- `GET /api/v1/compliance/mvp`
|
|
- `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.
|
|
- observability, recovery, export, governance, extension, quality/cost, smoke,
|
|
and compliance report 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.
|
|
|
|
`KONT-WP-0010` added the MVP operator/readiness surface. Metrics, jobs, events,
|
|
recovery actions, export packages, governance reports, extension events,
|
|
quality/cost signals, performance smoke summaries, and compliance reports are
|
|
available through versioned service endpoints. See
|
|
`docs/observability-export-enterprise-readiness.md` and
|
|
`docs/mvp-compliance-report.md`.
|
|
|
|
## 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,
|
|
- 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,
|
|
- runtime operator metrics, recovery, export, governance, extension events,
|
|
quality/cost signals, smoke reports, and MVP compliance reports,
|
|
- `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`.
|