CompTech AIOps - service contract baseline
Public-safe summary of the Phase 1 service contracts for the comptech-aiops platform.
The canonical service contract decision is comptech-aiops ADR 0020.
The current RAG ingestion baseline is comptech-aiops ADR 0023.
The durable RAG storage baseline is comptech-aiops ADR 0024.
The operator portal MVP decision is comptech-aiops ADR 0025.
The trusted-LAN portal ingress decision is comptech-aiops ADR 0026.
The RAG embedding and Qdrant indexing baseline is comptech-aiops ADR 0027.
The reviewed knowledge pack and retrieval evaluation baseline is comptech-aiops ADR 0028.
The operator chat console decision is comptech-aiops ADR 0029.
This page is the public-safe summary. It describes boundaries and API shapes, but does not publish credentials, private infrastructure evidence, or sensitive runtime details.
Contract Principles
- The portal frontend talks only to the Go/Gin portal API.
- Operator-facing APIs use
/api/v1. - Internal first-party services use
/internal/v1. - Tool execution goes through the MCP gateway and policy path.
- RAG retrieval informs plans and answers; it does not override source systems, approvals, policy, or operator decisions.
- Mutating operations must be auditable.
- Evidence references must not expose secret values.
- Every first-party service needs liveness and readiness checks.
Implementation Status
Canonical issue #26 implemented the first contract-shaped service stubs and tests. Canonical issue #27 implemented shared service contract helpers for those stubs. Canonical issue #28 implemented the first Postgres-backed operational store for portal-owned task state and task audit events. Canonical issue #29 wired the portal API to the internal orchestrator, MCP gateway, and RAG service stubs. Canonical issue #30 implemented the first approval decision and evidence metadata API behavior. Canonical issue #31 implemented the first orchestrator approval-wait workflow. Canonical issue #32 implemented the first RAG ingestion pipeline skeleton. Canonical issue #33 implemented durable RAG metadata and source object storage. Canonical issue #34 implemented the first operator portal MVP against the portal API boundary. Canonical issue #35 exposes only the portal ingress gateway on the trusted LAN path. Canonical issue #36 adds deterministic RAG embeddings and Qdrant indexing. Canonical issue #37 adds the first reviewed RAG knowledge pack and retrieval evaluation fixture. Canonical issue #38 adds the first operator chat console.
Public-safe status:
| Service | Status |
|---|---|
| Portal API | Exposes /api/v1 stubs, /healthz, /readyz, /metrics, and a container healthcheck mode. |
| Agent orchestrator | Exposes /internal/v1/orchestrator stubs, /healthz, /readyz, and /metrics. |
| MCP gateway | Exposes /internal/v1/mcp stubs, /healthz, /readyz, and /metrics. |
| RAG ingestion | Exposes reviewed source ingestion, durable source/job/chunk reads, deterministic embeddings, Qdrant indexing, vector-first query with keyword fallback, /healthz, /readyz, and /metrics. |
| Compose | Adds first-party service health checks and force-recreates the ingress gateway when the Caddyfile changes. |
| Shared helpers | Standardizes request IDs, task IDs, error envelopes, list envelopes, and health/readiness response shapes. |
| Operational store | Adds durable Postgres tables for tasks, approvals, evidence metadata, and audit events. |
| Internal client wiring | Portal API readiness, task enqueue/cancel, inventory targets, and knowledge query now call internal service stubs. |
| Approval and evidence API | Portal API lists/reads approvals, records approval decisions as audit events, and reads evidence metadata. |
| Approval-wait workflow | Execution-seeking tasks can enter awaiting_approval, create durable approval requests, resume when approved, and block when denied. |
| RAG ingestion skeleton | Reviewed markdown/plain-text source content can be ingested into in-process source, job, and chunk records; query returns public-safe citations. |
| Durable RAG storage | RAG source, job, and chunk metadata is stored in Postgres, with reviewed source object copies in MinIO when configured. |
| Operator portal MVP | Browser UI exposes readiness, tasks, approvals, knowledge citations, inventory targets, evidence lookup, and task events through the portal API only; deployed smoke checks passed on ze-tower. |
| Operator chat console | Browser UI and portal API endpoint for chat-driven task creation, RAG citations, planning envelopes, task state, and approval/risk state. |
| LAN portal ingress | The existing portal ingress is reachable from trusted LAN clients; internal services remain Docker-internal. |
| RAG semantic indexing | Reviewed chunks receive deterministic local embeddings and are indexed into Qdrant when available; Qdrant remains rebuildable from durable metadata. |
| RAG retrieval evaluation | Public-safe reviewed source pack and fixture check that representative operator questions return expected citations before deployment. |
The stubs prove route shape, status codes, and deployment readiness semantics. They do not enable production-changing authority.
Deployment verification corrected the ingress health route so /healthz, /readyz, and /api/* are served by the portal API rather than the portal web container. The corrected deployment passed remote health checks on ze-tower.
The helper implementation does not add production-changing authority. It only makes the first-party services use consistent contract shapes before database state and real tool execution are added.
The operational store implementation does not add production-changing authority. It persists task create/list/read/cancel behavior and task audit events so future orchestrator, approval, evidence, and RAG work can rely on durable state.
The internal client wiring does not add production-changing authority. It connects the portal API to existing contract stubs and preserves request/task headers across the service boundary.
The internal client wiring deployment passed canonical validation and ze-tower deployment verification. Live smoke checks confirmed portal readiness reports Postgres, orchestrator, MCP gateway, and RAG as reachable, task create/cancel preserves task identity across the orchestrator boundary, and inventory/RAG portal routes proxy to the internal stubs.
The approval and evidence API implementation does not add production-changing authority. It exposes the operator decision and evidence metadata contract so future orchestrator workflows can pause for human approval and attach evidence safely.
Deployment verification passed on ze-tower using public-safe smoke fixtures. The smoke check confirmed approval list/read/decision, approval.decided task events, evidence metadata read, and the standard health script.
The approval-wait workflow implementation does not add production-changing authority. It links task enqueue, durable approval request creation, operator decision, task state transition, and orchestrator resume or stop notification behind the existing service contract.
Deployment verification passed on ze-tower with a public-safe smoke task. The smoke check confirmed an execution task entered awaiting_approval, a durable approval request was created, approval through the portal API returned the task to queued, task events contained the expected approval request and decision events, and the standard health script passed.
The RAG ingestion skeleton does not add production-changing authority. It creates contract-valid source, job, chunk, and keyword query behavior for reviewed non-secret fixtures only. Issue #33 makes that metadata durable in Postgres and stores reviewed source object copies in MinIO when configured.
Deployment verification passed on ze-tower with a public-safe RAG fixture. The smoke check confirmed source ingestion, job completion, source and chunk reads, direct RAG query citations, portal-mediated knowledge query citations, and the standard health script.
The durable RAG storage implementation does not add production-changing authority. It makes reviewed RAG source, job, and chunk metadata survive service restarts and copies reviewed source content to the approved object store when configured.
The RAG semantic indexing implementation does not add production-changing authority. It adds deterministic local embeddings, writes reviewed chunk vectors to Qdrant when the vector index is healthy, keeps keyword fallback for availability, and adds an internal rebuild endpoint for the Qdrant index.
Deployment verification passed on ze-tower with a public-safe reviewed fixture. The smoke check confirmed RAG readiness with Postgres, MinIO, Qdrant, and deterministic embeddings; indexed chunk metadata; direct citation query; index rebuild; portal-mediated knowledge citations; and the standard health script.
The retrieval evaluation baseline does not add production-changing authority. It adds a reviewed control-plane knowledge pack plus a local fixture that verifies expected citations through the RAG service contract before deployment.
Deployment verification passed through GitHub Actions. The public-safe smoke scope confirmed the retrieval fixture and evaluator script were synced to ze-tower, the portal readiness endpoint stayed healthy, and the standard remote health script passed.
The operator chat console does not add production-changing authority. Chat messages enter through the portal API, create tracked task records, query reviewed RAG, and return proposed planning steps, citations, task state, approval state, risk state, and an authority note. Execution-seeking work remains approval-gated and real target changes still require later orchestrator, OPA, MCP, and evidence controls.
The operator portal MVP does not add production-changing authority. It lets operators use existing safe Phase 1 portal API workflows from a browser while preserving the rule that internal services and target infrastructure are not called directly from the frontend.
Deployment verification passed on ze-tower with public-safe smoke data. The smoke check confirmed the rendered portal, task creation, approval decision, task event history, knowledge citations, inventory route, evidence metadata lookup, and standard health check.
The LAN portal ingress change does not add production-changing authority. It keeps the same portal API boundary and only changes how trusted LAN operators reach the existing ingress gateway.
Deployment verification passed on ze-tower and from a trusted LAN client. Public-safe smoke scope included portal health, readiness dependencies, placeholder operator profile, desktop browser render, mobile browser render, and the standard health script against the configured LAN bind.
Shared Helpers
Public-safe helper scope:
| Area | Purpose |
|---|---|
| Request IDs | Preserve incoming X-Request-ID values or generate req_... IDs. |
| Task IDs | Generate and validate opaque task_... IDs. |
| Error envelopes | Return consistent error.code, error.message, error.request_id, and error.details. |
| List envelopes | Return consistent items and page wrappers. |
| Health and readiness | Return consistent service, status, version, and safe dependency status. |
Service Boundaries
| Service | Public-safe contract role |
|---|---|
| Portal API | Operator-facing API for chat, tasks, approvals, evidence, inventory, knowledge query, and live events. |
| Agent orchestrator | Internal task planning, durable workflow coordination, plan revision, approval waits, and task event emission. |
| MCP gateway | Internal tool registry, policy checks, target binding, tool-run mediation, and tool-run evidence. |
| RAG service | Reviewed source ingestion, metadata normalization, chunking, embedding, retrieval, and citation metadata. |
| Evidence records | Metadata references to artifacts, outputs, approvals, plans, validation results, and reviewed evidence. |
| Event stream | Server-Sent Events for task, plan, approval, tool-run, evidence, RAG ingestion, and system status updates. |
Portal API
The portal API is the only operator-facing service boundary for the frontend.
Initial public-safe resource groups:
| Resource group | Purpose |
|---|---|
| Actor profile | Current user, roles, and autonomy limits. |
| Chat sessions | Operator chat sessions and messages. |
| Chat messages | Planning-only chat requests that create tracked tasks, query RAG, and return proposed plans with citations. |
| Tasks | Task creation, task state, cancellation, event history, and evidence references. |
| Approvals | Pending and historical approval decisions. |
| Evidence | Evidence metadata and safe previews. |
| Inventory | Known target scopes from approved sources of truth. |
| Knowledge query | Portal-mediated RAG query. |
| Events | Live Server-Sent Events stream. |
Internal Contracts
The orchestrator, MCP gateway, and RAG service are internal boundaries. They are not called directly by the portal frontend.
| Internal service | Baseline path | Key responsibility |
|---|---|---|
| Agent orchestrator | /internal/v1/orchestrator | Own task state, planning, plan revision, approval waits, and orchestration events. |
| MCP gateway | /internal/v1/mcp | Own policy checks, tool registry, target binding, tool-run state, and safe output metadata. |
| RAG service | /internal/v1/rag | Own ingestion jobs, source metadata, chunk metadata, embeddings, Qdrant indexing, and retrieval for planning. |
State Models
Initial durable state tables:
| Table | Public-safe purpose |
|---|---|
tasks | Operator task requests and task lifecycle state. |
approvals | Human approval requests and decisions. |
evidence_items | Evidence metadata and safe object references. |
audit_events | Request-scoped and task-scoped audit history. |
Initial task states:
draftqueuedplanningawaiting_approvalrunningblockedsucceededfailedcancelled
Initial approval states:
requestedapproveddeniedexpiredsuperseded
Initial tool-run states:
proposedpolicy_checkingapproval_requiredqueuedrunningsucceededfailedcancelleddenied
Evidence And Events
Evidence records point to artifacts and outputs stored in approved systems. They carry metadata such as type, title, object reference, digest, content type, size, redaction status, and creation time.
Allowed redaction states:
| State | Meaning |
|---|---|
raw_private | Private artifact, not safe for public issue or blog use. |
review_required | Needs human review before sharing. |
reviewed_internal | Safe for internal operators. |
reviewed_public_safe | Safe for public docs or public issue comments. |
Initial event types include task updates, plan creation, approval requests and decisions, tool-run updates, evidence creation, RAG ingestion updates, and system degradation signals.
Health And Readiness
Every first-party service must expose:
| Endpoint | Purpose |
|---|---|
/healthz | Liveness check. The service process can respond. |
/readyz | Readiness check. Required dependencies for the service role are reachable. |
/metrics | Internal Prometheus metrics. |
Readiness failures should return safe dependency status without secret values.
Next Implementation Steps
- Replace remaining internal service stub responses with contract-compliant orchestrator and MCP gateway behavior.
- Implement Temporal-backed durable orchestrator runtime behind the approval-wait contract.
- Add target-infrastructure knowledge packs, then compare deterministic local embeddings with a model-backed embedding service after more evaluated packs exist.