generated from coulomb/repo-seed
43 lines
1.3 KiB
Markdown
43 lines
1.3 KiB
Markdown
# Service API Boundary
|
|
|
|
Date: 2026-05-05
|
|
|
|
## 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.
|
|
|
|
## First Resource Shape
|
|
|
|
Planned endpoint groups:
|
|
|
|
- `GET /health`
|
|
- `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}`
|
|
|
|
## 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
|
|
|
|
- Authentication and authorization.
|
|
- Durable database backend.
|
|
- OpenAPI model polishing.
|
|
- Streaming run execution.
|
|
- Provider-backed assisted steps.
|
|
|