OntologyAI builds a live Ontology of a small business from its existing tools, and lets AI specialists query and act on it — with every consequential action gated by human approval. In V6 this becomes a living Enterprise Knowledge Model + stakeholder-specific Decision Workspaces, powered by observability-hardened mission pipelines.
- Vision
- Product Principle
- Who it is for
- Scope
- Canonical Data Model
- Knowledge Pipeline
- Agent Roster
- Artifact Catalog
- Feasibility & Decision Readiness
- Architecture
- Project Structure
- Getting Started
- Key Metrics
- Test Coverage
Enterprise knowledge is scattered across meetings, docs, chat, spreadsheets, CRM, and ERP — creating duplicated effort, inconsistent decisions, and slow alignment. OntologyAI V6 converts that fragmented evidence into a living Enterprise Knowledge Model and stakeholder-specific Decision Workspaces that answer:
- What is happening?
- Why does it matter?
- What evidence supports it?
- What options exist?
- What is recommended?
- What are the trade-offs?
- What happens if nothing changes?
- Who owns the decision?
- What changes downstream?
Outcome: One canonical model, many synchronized stakeholder views, and validated decision-ready artifacts.
Evidence first, knowledge second, decision third, artifact last.
No evidence → no artifact. No traceability → block. Low confidence → human review. Unresolved conflict → reject publish. Every layer depends on the layer before it.
| Role | What they get |
|---|---|
| CEO / COO | Executive Decision Brief, Org / Ownership Map, Current-State Pack |
| CFO | Feasibility & Options Report, Measurement Pack, Feasibility Scorecard |
| CTO / Enterprise Architect | Solution Architecture Pack, Requirements Traceability Matrix |
| Product Leaders | PRD / Solution Brief, User Stories + Acceptance Criteria, Wireframes / Storyboards |
| Business Analysts | Stakeholder Register + Influence Matrix, Current-State Pack |
| Ops Leads | Delivery Plan (WBS + roadmap + RACI), Evidence Register |
| Implementation Teams | All 18 artifacts, full traceability and audit trail |
MVP supports 4 connectors only:
| Connector | Purpose |
|---|---|
| Notion | Docs, product specs, meeting notes, wikis |
| Slack | Conversations, decisions, async discussions |
| Jira / Linear | Issues, epics, tickets, sprint data |
| Salesforce | CRM data, opportunities, account hierarchies |
All other systems are future adapters behind the same connector interface.
- No freeform document generation
- No autonomous side effects
- No generic chatbot
- No broad connector sprawl
- No production deployment automation
V6 defines 22 canonical entity types that form the Enterprise Knowledge Model:
| # | Entity | Description |
|---|---|---|
| 1 | Evidence | Raw fact with source, timestamp, confidence, provenance |
| 2 | Source | Origin system or channel (connector, upload, chat, etc.) |
| 3 | Stakeholder | Person or role with influence and interests |
| 4 | OrgUnit | Organizational unit, team, or department |
| 5 | Capability | Business capability or function |
| 6 | Process | Business process or workflow |
| 7 | System | Software system, tool, or platform |
| 8 | Requirement | Functional or non-functional requirement |
| 9 | BusinessRule | Policy, invariant, or business logic |
| 10 | Assumption | Accepted premise without full evidence |
| 11 | Constraint | Limitation or boundary condition |
| 12 | Risk | Identified risk with impact and likelihood |
| 13 | Decision | Recorded decision with rationale and date |
| 14 | Option | Considered alternative or choice |
| 15 | TradeOff | Comparison of two or more options |
| 16 | KPI | Key performance indicator with baseline/target |
| 17 | Project | Initiative, program, or workstream |
| 18 | Artifact | Generated document or deliverable |
| 19 | ArtifactVersion | Versioned snapshot of an artifact |
| 20 | Conflict | Detected contradiction between evidence/entities |
| 21 | ValidationResult | Result of a validation check |
| 22 | FeasibilityScore | Multi-dimensional feasibility score |
| 23 | AuditEvent | Immutable audit log entry |
Ingest → Parse → Normalize → Dedupe → Alias Resolve →
Entity/Relationship Build → Conflict Detection →
Knowledge Graph Update → Gap Analysis → Decision Analysis →
Feasibility Scoring → Artifact Projection → Validation → Publish
Each stage is a deterministic activity (Temporal) that reads from and writes to the canonical model. No stage bypasses validation.
| Stage | Responsibility |
|---|---|
| Ingest | Accept raw data from 4 MVP connectors + uploads + chat |
| Parse | Convert raw data into typed Evidence objects |
| Normalize | Standardize formats, dates, references |
| Dedupe | Merge duplicate evidence from overlapping sources |
| Alias Resolve | Map aliases (e.g. "Acme Inc" ↔ "Acme Corporation") |
| Entity/Relationship Build | Construct canonical entities and links |
| Conflict Detection | Identify contradictions across sources |
| Knowledge Graph Update | Persist to the Enterprise Knowledge Model |
| Gap Analysis | Identify missing evidence or relationships |
| Decision Analysis | Surface decisions, options, and trade-offs |
| Feasibility Scoring | Score across 8 dimensions |
| Artifact Projection | Generate external and internal artifacts |
| Validation | Run all validation gates before publishing |
| Publish | Release artifacts to Decision Workspaces |
| # | Agent | Responsibility |
|---|---|---|
| 1 | ChiefOfStaff | Front-door orchestrator, context assembly, routing, state merge |
| 2 | IngestionParser | Parse raw input into typed Evidence; handle all 4 connectors |
| 3 | KnowledgeMapper | Build entities, relationships, and the knowledge graph |
| 4 | ConflictResolver | Detect and resolve contradictions across sources |
| 5 | FeasibilityAnalyst | Score recommendations across 8 dimensions |
| 6 | DecisionAnalyst | Surface decisions, options, trade-offs, and rationale |
| 7 | ArtifactComposer | Template-driven artifact generation from canonical model |
| 8 | GovernanceAgent | Enforce guardrails, validation gates, and approval flows |
| 9 | EvaluationAgent | Measure quality, coverage, freshness, and calibration |
- One responsibility per agent
- Typed I/O only — no unstructured data passing between agents
- No agent mutates canonical state directly (writes go through governance)
- No agent bypasses validation
- No agent executes side effects without governance
| # | Artifact | Consumer |
|---|---|---|
| 1 | Executive Decision Brief | CEO, COO, Board |
| 2 | Stakeholder Register + Influence Matrix | Business Analysts, PMs |
| 3 | Org / Ownership Map | COO, Enterprise Architects |
| 4 | Current-State Pack (capability map + SIPOC + context diagram + process map) | All stakeholders |
| 5 | Feasibility & Options Report | CFO, CTO, Product Leaders |
| 6 | PRD / Solution Brief | Product, Engineering |
| 7 | User Stories + Acceptance Criteria | Engineering, QA |
| 8 | Wireframes / Storyboards | Design, Product |
| 9 | Solution Architecture Pack | CTO, Architects, Engineering |
| 10 | Requirements Traceability Matrix | QA, Compliance, PMs |
| 11 | Delivery Plan (WBS + roadmap + RACI) | Ops Leads, Implementation Teams |
| 12 | Measurement Pack (KPIs + baseline + target + retrospective) | CFO, COO |
| # | Artifact | Purpose |
|---|---|---|
| 13 | Evidence Register | All evidence with provenance, confidence, and source |
| 14 | Data Quality / Mismatch Report | Detected inconsistencies and gaps |
| 15 | Conflict Register | All unresolved and resolved conflicts |
| 16 | Decision Log | Immutable record of every decision and rationale |
| 17 | Feasibility Scorecard | Multi-dimensional scores for every recommendation |
| 18 | Artifact Health Report | Freshness, completeness, and validation status of all artifacts |
- Template-driven — every artifact uses a deterministic template
- Evidence-linked — every claim maps back to underlying Evidence
- Versioned — every regeneration creates a new ArtifactVersion
- Regenerated only from the canonical model — never from freeform LLM output
- LLM may fill fields but may not invent sections or authoritative facts
Every recommendation is scored across 8 dimensions:
| Dimension | Description |
|---|---|
| Business Value | Strategic impact and ROI |
| Technical Complexity | Implementation difficulty and unknowns |
| Operational Fit | Alignment with existing processes |
| Financial Impact | Cost, savings, and payback period |
| Compliance Risk | Regulatory and policy exposure |
| Data Readiness | Availability and quality of required data |
| Change Effort | Organizational change management load |
| Stakeholder Alignment | Buy-in and support from affected parties |
| Score | Action |
|---|---|
| 85–100 | Publish — ready for decision |
| 70–84 | Publish with caveats |
| 60–69 | Human review required |
| Below 60 | Block and return to discovery |
The system blocks publication when any of the following is true:
- Any requirement lacks evidence
- Any claim lacks traceability
- Any artifact section conflicts with the canonical model
- Any KPI lacks baseline or owner
- Any numeric claim fails source reconciliation
- Any policy or governance rule is violated
flowchart TD
U["Enterprise Stakeholder"] --> WS["Decision Workspace (HTMX + SSE)"]
WS --> CORE["Go Core (Fiber HTTP)"]
subgraph CONNECTORS["MVP Connectors (4)"]
N["Notion"]
S["Slack"]
JL["Jira / Linear"]
SF["Salesforce"]
end
CONNECTORS --> ING["Ingestion Service"]
UPL["Upload / Chat / Email / Screenshot"] --> ING
ING --> EV["Evidence Store"]
EV --> PIPELINE["Knowledge Pipeline (Temporal Orchestration)"]
PIPELINE --> PARSE["Parse"]
PIPELINE --> NORM["Normalize"]
PIPELINE --> DEDUPE["Dedupe"]
PIPELINE --> ALIAS["Alias Resolve"]
PIPELINE --> ER["Entity / Relationship Build"]
PIPELINE --> CD["Conflict Detection"]
PIPELINE --> KG["Knowledge Graph Update"]
PIPELINE --> GA["Gap Analysis"]
PIPELINE --> DA["Decision Analysis"]
PIPELINE --> FS["Feasibility Scoring"]
PIPELINE --> AP["Artifact Projection"]
PIPELINE --> VAL["Validation"]
PIPELINE --> PUB["Publish"]
KG --> EKM[("Enterprise Knowledge Model<br/>PostgreSQL + Qdrant + Graphiti")]
AP --> ARTIFACTS["Artifact Generator"]
ARTIFACTS --> EXT["12 External Artifacts<br/>Executive Brief, PRD, RTM, ..."]
ARTIFACTS --> INT["6 Internal Artifacts<br/>Evidence Register, Conflict Log, ..."]
VAL --> GATES["Decision Readiness Gates<br/>85–100 Publish | 70–84 Caveats | 60–69 Review | <60 Block"]
PUB --> WORKSPACES["Stakeholder Decision Workspaces"]
WORKSPACES --> CEO["CEO Dashboard"]
WORKSPACES --> CFO["CFO Dashboard"]
WORKSPACES --> CTO["CTO Dashboard"]
WORKSPACES --> PM["Product Dashboard"]
WORKSPACES --> OPS["Ops Dashboard"]
subgraph AGENTS["Agent Roster (9)"]
COS["ChiefOfStaff"]
IP["IngestionParser"]
KM["KnowledgeMapper"]
CR["ConflictResolver"]
FA["FeasibilityAnalyst"]
DANA["DecisionAnalyst"]
AC["ArtifactComposer"]
GOV["GovernanceAgent"]
EA["EvaluationAgent"]
end
CORE --> COS
COS --> PIPELINE
COS --> AGENTS
subgraph TEMPORAL["Temporal Orchestration Layer"]
WF1["IngestionWorkflow"]
WF2["KnowledgeWorkflow"]
WF3["FeasibilityWorkflow"]
WF4["ArtifactWorkflow"]
WF5["GovernanceWorkflow"]
end
PIPELINE --> TEMPORAL
| Layer | Responsibility |
|---|---|
Interface (apps/core/ HTMX) |
Decision Workspaces, stakeholder-specific dashboards, SSE streaming |
Go Core (apps/core/) |
Fiber HTTP server, SSE, workspace routing, Temporal client |
| Ingestion | 4 MVP connectors (Notion, Slack, Jira/Linear, Salesforce) + upload/chat intake |
| Knowledge Pipeline | 14-stage Temporal-orchestrated pipeline from ingest to publish |
| Enterprise Knowledge Model | 22 canonical entity types in PostgreSQL, Qdrant, Graphiti |
| Agent Roster | 9 agents with typed I/O, governed writes, no direct state mutation |
| Feasibility Engine | 8-dimension scoring with Decision Readiness Gates |
| Validation Engine | Evidence-gated, traceability-checked, conflict-blocked publication |
| Artifact Projection | 18 artifact templates (12 external + 6 internal) |
| Decision Workspaces | Stakeholder-specific views of the same canonical model |
| Observability | Langfuse tracing, audit events, evaluation metrics |
apps/
core/ # Go Modular Monolith (control / gateway)
cmd/
server/ # HTTP server entrypoint
worker/ # Temporal worker entrypoint
internal/
web/ # HTTP handlers (Fiber + HTMX + SSE)
handler.go # All endpoints, workspace routing
sse.go # SSE handler
templates/
workspaces/ # Decision Workspace views
ceo.html
cfo.html
cto.html
product.html
ops.html
partials/ # HTMX partials
agents/ # Go agent stubs
config/ # LLM configuration
db/ # sqlc generated code
database/ # Connection utilities
temporal/ # Temporal client
workflow/ # Temporal workflow stubs
ai/ # Python AI Worker
src/
connectors/ # V6 — MVP connector implementations
base.py # Connector ABC
notion.py
slack.py
jira_linear.py
salesforce.py
evidence/ # V6 — Evidence ingestion and parsing
parser.py # Input parser (chat, upload, transcript, etc.)
evidence_store.py # Evidence persistence
normalizer.py # Normalize and dedupe
ontology/ # V6 — Canonical data model
entities.py # 22 entity types
relationships.py # Entity relationship definitions
knowledge_graph.py # Graph operations
adapter.py # Read/write bridge
pipeline/ # V6 — Knowledge Pipeline stages
ingest.py
parse.py
normalize.py
dedupe.py
alias_resolve.py
entity_build.py
conflict_detection.py
graph_update.py
gap_analysis.py
decision_analysis.py
feasibility_scoring.py
artifact_projection.py
validation.py
publish.py
artifacts/ # V6 — Artifact generation
templates/ # 18 artifact templates
composer.py # Template-driven artifact generation
external/ # 12 external artifacts
internal/ # 6 internal artifacts
feasibility/ # V6 — Feasibility engine
scorer.py # 8-dimension scoring
gates.py # Decision Readiness Gates
decision/ # V6 — Decision analysis
workspace.py # Decision Workspace contract
stakeholder_view.py # Stakeholder-specific projections
validation/ # V6 — Validation engine
rules.py # Validation rules
gates.py # Publication gates
agents/ # V6 — Agent roster
chief_of_staff.py
ingestion_parser.py
knowledge_mapper.py
conflict_resolver.py
feasibility_analyst.py
decision_analyst.py
artifact_composer.py
governance_agent.py
evaluation_agent.py
governance/ # V6 — Governance agent
guardrails.py # Guardrail enforcement
approval.py # HITL approval flows
audit.py # Audit event logging
workflows/ # Temporal workflow definitions
ingestion_workflow.py
knowledge_workflow.py
feasibility_workflow.py
artifact_workflow.py
governance_workflow.py
mission/ # V4.2+ — mission state, decision engine, timeline
storage.py # MissionStateStore (asyncpg, Go-mirrored DDL)
timeline.py # Frozen MissionEventType + MissionTimeline + MissionSnapshotStore (diff)
decision.py # MissionDecisionEngine (real LLM via src/config/llm.py)
runtime.py # MissionRuntime + KPI writeback
observability/ # Hardening — typed E2E trace/correlation propagation
trace_context.py # TraceContext (trace_id / correlation_id / tenant_id), contextvars
pipeline.py # PipelineRun + run_stage (retry, latency, status)
workspace/ # Mission / Decision workspace schema
policy/ # Governed policy runtime
goal/ # Goal runtime + models
evaluation/ # Evaluation runtime
session/ # Engagement and session-state
memory/ # Knowledge graph, Qdrant, spine
services/ # Evidence layer, trust battery
worker.py # Temporal worker registration
tests/
integration/ # Live infra suites (skip when DB/LLM absent)
test_mission_live_infra.py # Postgres + real LLM (8 passing)
hardening/ # E2E observability (live Postgres + Groq)
test_pipeline_e2e.py
test_mission_timeline.py # Deterministic timeline/diff unit tests
scripts/
hardening/ # Chaos smoke + resource-limit documentation
chaos_smoke.sh # Restart postgres+temporal, assert recovery
README.md
- Docker (Temporal, Qdrant, PostgreSQL, Neo4j/Graphiti)
- Go 1.24
- Python 3.13 with
uv
# 1. Start infrastructure
make up
# 2. Run the Go server
cd apps/core && go run cmd/server/main.go
# 3. Run the Go Temporal worker
cd apps/core && go run cmd/worker/main.go
# 4. Install Python deps and run the Python worker
cd apps/ai && uv sync
cd apps/ai && uv run python -m src.worker
# 5. Open a Decision Workspace
# http://localhost:8080# Go — all packages
cd apps/core && go test ./...
# Python — full suite
cd apps/ai && uv run pytest tests/ -v
# Python — specific V6 suites
cd apps/ai && uv run pytest tests/test_pipeline/ -v
cd apps/ai && uv run pytest tests/test_connectors/ -v
cd apps/ai && uv run pytest tests/test_feasibility/ -v
cd apps/ai && uv run pytest tests/test_validation/ -v
# Python — hardening + live-infra suites (need Postgres up + GROQ_API_KEY)
cd apps/ai && set -a && . ../../.env && set +a && \
uv run pytest tests/integration/hardening/test_pipeline_e2e.py -q -p no:cacheprovider
cd apps/ai && uv run pytest tests/integration/test_mission_live_infra.py -q -p no:cacheprovider| Provider | Variables |
|---|---|
| Azure AI Foundry | AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY |
| Groq | GROQ_API_KEY |
| OpenAI | OPENAI_API_KEY |
| Ollama (local) | OLLAMA_BASE_URL, OLLAMA_API_KEY |
| Control | Variable | Default |
|---|---|---|
| Temporal task queue | ONTOLOGYAI-MAIN-QUEUE |
TRACKGUARD-MAIN-QUEUE |
| Live Postgres DSN | ITERATESWARM_DATABASE_URL |
postgresql://iterateswarm:iterateswarm@localhost:5433/iterateswarm |
Secrets live in a local .env file (never committed).
V6 measures success across 12 evaluation dimensions:
| Metric | Description |
|---|---|
| Parser Accuracy | % of raw input correctly parsed into typed Evidence |
| Entity Merge Accuracy | % of entity merges that are correct (precision/recall) |
| Conflict Detection Rate | % of true conflicts detected |
| Evidence Coverage | % of entities with ≥1 evidence link |
| Traceability Coverage | % of claims with traceable evidence chain |
| Artifact Completeness | % of required sections populated in generated artifacts |
| Decision Readiness | % of workspaces meeting the Decision Workspace Contract |
| Feasibility Calibration | Correlation between feasibility scores and actual outcomes |
| Human Override Rate | % of gated decisions that humans override |
| Stakeholder Usefulness | NPS or satisfaction score from workspace consumers |
| Regeneration Correctness | % of regenerated artifacts that match prior versions |
| Freshness | Age of evidence underpinning published artifacts |
Operating rule: No new business features until every stage is observable, typed, replayable, testable, recoverable. The hardening sprints add operational qualities without new capabilities.
| Sprint | Delivered |
|---|---|
| A — E2E Observability | src/observability/ — typed TraceContext (trace_id/correlation_id/tenant_id) + PipelineRun/run_stage (retry, latency, status). tests/integration/hardening/test_pipeline_e2e.py proves one event carries the ids through connector-event → evidence → mission → decision (real Groq) → snapshot → timeline, with idempotent de-duplication on re-delivery (2/2 passing against live Postgres + real LLM). |
| Timeline & Versioning | src/mission/timeline.py — frozen MissionEventType verbs, append-only per-entity timeline_events (UNIQUE (entity_type, entity_id, version)), mission_snapshots (UNIQUE (mission_id, version)), and MissionSnapshotStore.diff (yesterday-vs-today, confidence_delta). |
| Mission Decisioning | src/mission/decision.py — MissionDecisionEngine calls only through src/config/llm.py (json_mode=True), defensive JSON parsing, safe confidence clamping. |
| G — Lightweight Metrics | VictoriaMetrics (single binary, Prometheus-compatible) added to docker-compose.yml. No Prometheus / Grafana. |
| J — Resource Limits | Hard deploy.resources.limits on every service: neo4j 4G/2cpu, redpanda 2G/1cpu, temporal 1G/1cpu, postgres 512M/1cpu, qdrant 512M/1cpu, victoriametrics 256M/0.5cpu. |
| Chaos Smoke | scripts/hardening/chaos_smoke.sh — restarts PostgreSQL + Temporal, waits up to 90s for healthy, exits non-zero on failure. |
Infra discipline (dev): one container at a time — stop all others before testing a specific service; test, then stop. All containers use tight CPU/memory limits.
| Dimension | V6 |
|---|---|
| Vision | Decision Intelligence Platform |
| Connectors | 4 MVP (Notion, Slack, Jira/Linear, Salesforce) |
| Canonical Entities | 22 (Evidence, Stakeholder, Decision, KPI, etc.) |
| Pipeline Stages | 14 (Ingest → Parse → ... → Publish) |
| Agents | 9 (ChiefOfStaff, IngestionParser, ..., EvaluationAgent) |
| External Artifacts | 12 (Executive Brief, PRD, RTM, Delivery Plan, etc.) |
| Internal Artifacts | 6 (Evidence Register, Conflict Log, etc.) |
| Feasibility Dimensions | 8 (Business Value, Technical Complexity, etc.) |
| Decision Gates | 4 tiers (85–100 publish, <60 block) |
| Orchestration | Temporal (replay-safe, deterministic, continue-as-new) |
| Guardrails | No evidence = no artifact; unresolved conflict = reject |
| Suite | Scope |
|---|---|
| Unit Tests | Parsers, merge logic, scoring, template rendering, validators |
| Integration Tests | Connectors, evidence flow, artifact projection, approval gates |
| Temporal Tests | Replay, pause/resume, retries, signals, updates, continue-as-new |
| Adversarial Tests | Conflicting sources, missing fields, duplicates, stale data, prompt injection, malformed files, inconsistent numbers |
| End-to-End Tests | Executive Brief → PRD → Architecture → RTM → Delivery Plan → Measurement Pack |
| Hardening Tests | E2E observability (live Postgres + Groq), mission timeline/diff unit suites, Postgres live-infra suite (8 passing) |
| Go Build | ✅ Clean |
| Python Unit Tests | ✅ Baseline + V6 suites |
Key ADRs governing V6 design:
- ADR-001: Evidence-first pipeline — no artifact without evidence chain
- ADR-002: Temporal as single orchestration backbone — activities are deterministic and replayable
- ADR-003: Governance exclusivity — only GovernanceAgent finalizes side effects
- ADR-004: Template-driven artifacts — LLM fills fields, never invents sections
- ADR-005: Decision Readiness Gates — publication is gated by scored readiness
- ADR-006: Connector interface — abstract adapter pattern for all future connectors beyond the MVP 4
- ADR-007: Context engineering — layered context assembly never passes raw unbounded history
- ADR-008: 22-entity canonical model — single source of truth for all projections
- Feature branches:
git checkout -b feature/description— never commit directly tomain. - Conventional Commits:
feat:,fix:,refactor:,docs:,test:,chore:. - Never commit to
main. Open a PR from your feature branch. - Secrets: use a local
.envfile; never commit secrets. - Agent guidelines: full coding standards and build/test commands in
AGENTS.md. - Definition of Done: A feature is done only when it updates the canonical model, survives validation, appears correctly in all affected workspaces, passes tests, carries traceability, and can be replayed from evidence.
