generated from coulomb/repo-seed
Service-API completion: ingestion, retrieval, transformations, workflows, actor/delegation context, bounded agent operations, context packages, and dry-run/review-gate contracts
This commit is contained in:
@@ -35,6 +35,84 @@ Implemented in `KONT-WP-0009-T002`:
|
||||
- `GET /api/v1/audit/events`
|
||||
- `POST /api/v1/policy/evaluate`
|
||||
|
||||
Implemented in `KONT-WP-0009-T003`:
|
||||
|
||||
- `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`
|
||||
|
||||
Implemented in `KONT-WP-0009-T004`:
|
||||
|
||||
- `GET /api/v1/context`
|
||||
- Actor headers: `X-Actor-Id`, `X-Actor-Type`, `X-Actor-Display-Name`,
|
||||
`X-Actor-External-Ref`, `X-Actor-Groups`.
|
||||
- Delegation headers: `X-Delegated-Actor-Id`, `X-Delegated-Actor-Type`,
|
||||
`X-Delegated-Actor-Display-Name`, `X-Delegated-Actor-External-Ref`,
|
||||
`X-Delegated-Actor-Groups`.
|
||||
- Agent headers: `X-Agent-Id`, `X-Agent-Name`, `X-Agent-Run-Id`,
|
||||
`X-Agent-Tool`.
|
||||
- Scope headers: `X-Request-Scope` and `X-Policy-Scope` as JSON objects.
|
||||
- Redacted HTTP authorization error payloads.
|
||||
|
||||
Implemented in `KONT-WP-0009-T005`:
|
||||
|
||||
- `GET /api/v1/agents/operations`
|
||||
- `GET /api/v1/agents/operations/{operation_id}`
|
||||
- `POST /api/v1/agents/operations/{operation_id}`
|
||||
- Catalog entries declare input/output shape notes, permissions, audit
|
||||
operation, failure modes, and dry-run support.
|
||||
- Execution is limited to documented operation IDs and emits separate
|
||||
`agent.operation.*` audit events before dispatching through existing service
|
||||
contracts.
|
||||
|
||||
Implemented in `KONT-WP-0009-T006`:
|
||||
|
||||
- `GET /api/v1/context-packages/schema`
|
||||
- `POST /api/v1/context-packages`
|
||||
- Context packages are assembled from governed retrieval results.
|
||||
- Payloads carry source refs, snippets, metadata, relationships, policy
|
||||
constraints, opaque external memory refs, and audit/policy references.
|
||||
- The `markitect` format emits a Markitect-compatible envelope while keeping
|
||||
markdown rendering and selector semantics delegated to `markitect-tool`.
|
||||
|
||||
Implemented in `KONT-WP-0009-T007`:
|
||||
|
||||
- Agent operation policies can return `require_review` and receive structured
|
||||
`review_required` envelopes with review obligations.
|
||||
- Agent operation policies can return `dry_run_only` and receive
|
||||
`dry_run_required` envelopes unless the request is already a dry run.
|
||||
- Review and dry-run outcomes are audited with explicit `review_required` and
|
||||
`dry_run` audit outcomes.
|
||||
- Partial-failure job envelopes are covered by contract tests.
|
||||
|
||||
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`.
|
||||
@@ -49,19 +127,14 @@ python3 -m pip install -e '.[service]'
|
||||
|
||||
## Planned Resource Shape
|
||||
|
||||
Planned endpoint groups:
|
||||
Remaining 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
|
||||
translated to assets, metadata, context packages, and bounded agent operation
|
||||
resources.
|
||||
|
||||
## MVP API Versioning Policy
|
||||
@@ -85,10 +158,6 @@ resources.
|
||||
|
||||
## 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.
|
||||
No MVP service API task remains deferred in this workplan.
|
||||
- Streaming run execution.
|
||||
- Provider-backed assisted steps.
|
||||
|
||||
@@ -8,8 +8,8 @@ Status: active implementation note for `KONT-WP-0009`.
|
||||
|
||||
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.
|
||||
the governed asset-resource, job, retrieval, transformation, and workflow
|
||||
surface while leaving domain behavior in the application services.
|
||||
|
||||
## Implemented Package Shape
|
||||
|
||||
@@ -31,6 +31,7 @@ src/kontextual_engine/
|
||||
- `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}`
|
||||
@@ -41,6 +42,42 @@ src/kontextual_engine/
|
||||
- `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
|
||||
@@ -59,18 +96,63 @@ the `/api/v1` namespace for future domain resources.
|
||||
- readiness checks,
|
||||
- version payload,
|
||||
- asset service construction,
|
||||
- basic actor/correlation context construction,
|
||||
- actor/correlation/delegation context construction,
|
||||
- asset, metadata, lifecycle, relationship, audit, and policy operation
|
||||
translation.
|
||||
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, 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`.
|
||||
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
|
||||
|
||||
@@ -96,6 +178,18 @@ missing-dependency behavior are tested without FastAPI.
|
||||
- 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,
|
||||
@@ -104,9 +198,4 @@ missing-dependency behavior are tested without FastAPI.
|
||||
|
||||
## 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.
|
||||
No MVP service API tasks remain open in `KONT-WP-0009`.
|
||||
|
||||
Reference in New Issue
Block a user