okto-pulse-core

Domain and application engine for Okto Pulse, with transport-neutral ports, contracts and MCP commands.

Ship with AI. Stay in control.

You probably want to install okto-pulse instead.
This package is the internal engine. The okto-pulse package provides the CLI, frontend, and everything you need to get started.

What's inside

• 0 SQLAlchemy models — Core owns no concrete relational mappings. This is checked by scanning for __tablename__ assignments anywhere under core/; the Community edition owns the SQLAlchemy model and repository adapters.
• 54 service classes — Full business logic with governance rules, board agent governance, resource propagation + lineage, bug-regression workflow, archive/restore, traceability and board-level resource readiness. Source: classes ending in Service under core/services.
• 0 API route modules — Core owns application contracts and use cases, not concrete FastAPI routers. The count scans core/api/*.py; Community owns the REST adapter and route modules.
• Governance gates — Resource readiness, resource-to-task coverage, spec coverage, validation, evaluation, task completion, cognitive closeout, architecture-findings, evidence and bug traceability controls.
• 282 MCP tools — Complete Model Context Protocol command catalog for AI agent integration, counted from the transport-neutral Core catalog after importing the server, including:
  • Pipeline CRUD (Ideation, Refinement, Spec, Card)
  • Q&A and choice questions across every entity
  • Mockups (HTML+Tailwind, sanitised) and Knowledge Bases at spec/refinement/card scope
  • Decisions with supersedence and coverage gates
  • Per-card Knowledge attachment lifecycle (add_card_knowledge and friends)
  • 32 Knowledge Graph tools: logical queries, cognitive consolidation, public schema, bounded Health and governed deletion status. Maintenance and recovery controls are internal.
  • Community runtime exposure: 282 core MCP tools, 0 community-only MCP tools
• Application composition contracts — edition-neutral runtime, auth, storage, persistence, graph, telemetry and transport ports; concrete app construction belongs to the edition
• Hexagonal backend ports — runtime, telemetry, repository/UoW and KG provider seams, plus the adapter readiness ledger, documented in ARCHITECTURE.md
• Knowledge Graph contracts and orchestration — graph schema vocabulary, query/consolidation semantics, deterministic + cognitive workers, 11 node types and 16 relationship types. Source: len(KGEdgeType) in core/kg/schemas.py; Community supplies the concrete Okto Grafx Board and Global runtimes through public ports.
• Bounded operational metric samples — governance, architecture, bug-regression, resource-lineage and global-discovery observability keep capped diagnostic samples. Global-discovery count APIs remain monotonic totals and do not derive totals from the retained sample ring.

Governance Gate Surface

See Cognitive Action Center sections
for its read-only attention/history grouping and unchanged completion authority.

Project Structure agent protocol: Spec authors/evaluators must either author
a relevant tree or explicitly persist a justified non-applicability statement
in the Spec context before advancing. This is an agent-review obligation, not
an additional server gate. See the canonical protocol and tested examples.

The main governance families are:

The two execution-quality additions introduced in 0.2.3 — cognitive closeout (a done transition is blocked while active cognitive-consolidation items remain) and the architecture-findings done gate (active architecture warnings block spec/card done) — remain enforced in the current release.

Architecture

The core is a ports-and-policy package: it owns the SDLC domain, the governance gates and
the Knowledge Graph contracts, and delegates every concrete mechanism (database, graph runtime,
filesystem, HTTP, scheduler) to the active edition.

→ Architecture overview — layering, boundary governance
(AF-20/21/22, AF-28/29/30/31), MCP composition helpers and the edition-ownership rules.
→ ARCHITECTURE.md — the deep hexagonal reference (ports, adapter readiness
ledger, provider registry).
→ Relational ownership matrix —
the executable AF-35 Core/edition ownership boundary and residual inventory.

Ports & Adapter Interfaces

See also Optional graph observation ports for
ranked retrieval, retained history/diff and bounded analytics without an engine
dependency in Core.

Core defines ~100 Protocol contracts across 78 modules in okto_pulse/core/ports/ plus
30 Knowledge-Graph interfaces in okto_pulse/core/kg/interfaces/. Each one is a seam: core
declares what it needs; it never constructs a database, opens a file, resolves an environment
variable or speaks a wire protocol.

Unfilled slots fail closed (R-P2-03A-D) rather than falling back to a silent default.

→ Full port catalogue — every protocol with its method count and contract,
grouped by persistence, KG storage/runtime, KG governance, delivery/workers, MCP/inbound,
read models and telemetry.

Docker

This repo has no Dockerfile. The deployable artifact is a single image built from the sibling okto-pulse repo:

• okto-pulse/Dockerfile target local-runtime builds wheels from this repo and okto-pulse/ as siblings (used by okto-pulse/docker-compose.yml and the release pipeline's smoke build).
• okto-pulse/Dockerfile target pypi-runtime installs okto-pulse==<version> from PyPI, which transitively pulls this package off PyPI per the floor in okto-pulse/pyproject.toml (used by okto-pulse/docker-compose.prod.yml).

To run the published image:

docker run -d --name okto-pulse \
  -e HOST=0.0.0.0 -e MCP_HOST=0.0.0.0 \
  -p 8100:8100 -p 8101:8101 \
  -v okto-pulse-data:/data \
  ghcr.io/oktolabsai/okto-pulse:latest

See okto-pulse/README.md for the full Docker quickstart, and okto-pulse/CLAUDE.md for the multi-stage build architecture.

Release Notes

Current: 0.3.3 — Core defines actionable semantic evidence, agent-mediated
Code Traceability, governed lifecycle validation, exact KG recovery, canonical
delivery Analytics, immutable Sprint commitment and dependency-aware lineage as
edition-neutral contracts.

→ Full release notes — 0.3.3, 0.3.2, 0.3.1 and 0.3.0 changesets, plus 0.2.6, 0.2.5,
0.2.3, 0.2.2, 0.2.1, 0.2.0 and the 0.1.x line.

SaaS Closure Audit

The executable ownership matrix is generated by okto-pulse-saas-closure. Every transitional budget must remain zero; the command fails closed on import, dependency, adapter, wheel, or documentation drift.

License

Elastic License 2.0 — free for personal and commercial use. Cannot be offered as a hosted/managed service.

Glossary

Implementation and integration tracking: Delivery Evidence — tasks, test cards and Spec closure.
Includes the provider-neutral completion gate, REST/MCP contracts, agent guidance
and paired Community persistence/UI. Not installed into the active user runtime.

For plain-language definitions of recurring domain and architecture terms used in this repository, see the Glossary.