coulomb/kontextual-engine
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c2bc7071d74f40b8a52f6be0526a4fbe30543714
kontextual-engine/docs/service-api-boundary.md

6.5 KiB
Raw Blame History

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

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.

Implemented in KONT-WP-0010:

  • 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
  • Operator/readiness endpoints remain policy checked and audit backed.

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

Remaining planned endpoint groups:

  • POST /collections, GET /collections, GET /collections/{id}
  • POST /artifacts, GET /artifacts/{id}, GET /artifacts
  • POST /context/artifact/{id}

For the governed asset registry architecture, these planned groups should be translated to assets, metadata, context packages, and bounded agent operation 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

No MVP service API task remains deferred in this workplan.

  • Streaming run execution.
  • Provider-backed assisted steps.
Reference in New Issue View Git Blame Copy Permalink