Skip to content

Cortex — Intelligence Service

Cortex — Intelligence Objects and AI Tooling

Port: 8002 API version: /api/v1 Domain: Intelligence objects (insights, signals, blocks, profiles, editions, tasks, workflows) + AI-assisted investigation workflows

Cortex owns all intelligence object types and provides AI-assisted tooling for investigation authoring. It has two access modes depending on what is deployed:

Primary mode (Oracle deployed): Cortex is a pure backend service. Oracle aggregates Cortex's MCP tools and owns the user-facing LLM chat session. Cortex never receives direct chat sessions from external clients. Cortex's AI support tools (narrative drafting, block suggestion, etc.) are invoked by Oracle's tool-use loop on behalf of the user.

Standalone mode (Oracle not deployed, Cortex accessed via agentspace ingress): Cortex exposes a REST chat endpoint ( POST /api/v1/chat) and runs its own scoped tool-use loop. Conversation history uses ConversationStore from axonis.memory. The chat interface contract is identical to Oracle's /api/v1/chat — same ChatRequest / ChatResponse shape per platform.service-contract.

LLM Capability

Cortex has an optional LLM client (LLMSpec.from_env(prefix="CORTEX_LLM")). When LLM is not configured, AI support tools fall back to pack-based templates:

Tool LLM available LLM unavailable (fallback)
draft_narrative_with_evidence AI-generated narrative Structured template with evidence placeholders
suggest_next_blocks AI-ranked block suggestions Domain pack's default block sequence for signal type
recommend_decision_template AI-matched template Experience pack's default template
validate_evidence_sufficiency AI assessment Pack checklist with "manual review required" flag

This means Cortex is fully functional without an LLM — CRUD, workflow, and dataspace tools are unaffected. Only AI support tools degrade to pack-based fallbacks.

Domain Objects (from axonis-core userspace)

Object Schema constant ES index
Accountability Schema.ACCOUNTABILITY intelligence
Block Schema.BLOCK intelligence
DecisionTemplate Schema.DECISION_TEMPLATE intelligence
Domain Schema.DOMAIN intelligence
EditionSnapshot Schema.EDITION_SNAPSHOT intelligence
Experience Schema.EXPERIENCE intelligence
Insight Schema.INSIGHT intelligence
InsightEvent Schema.INSIGHT_EVENT intelligence
InsightRoot Schema.INSIGHT_ROOT intelligence
Profile Schema.PROFILE intelligence
QueryIntent Schema.QUERY_INTENT intelligence
Report Schema.REPORT intelligence
Signal Schema.SIGNAL intelligence
Task Schema.TASK intelligence
TaskTemplate Schema.TASK_TEMPLATE intelligence
VizIntent Schema.VIZ_INTENT intelligence
WorkflowTask Schema.WORKFLOW_TASK intelligence

Domain objects are defined in platform.axonis-core's userspace. Cortex realizes the product specs that govern their lifecycle and data: product.insight, product.signal, product.block, product.profile, product.report, product.task, and product.edition.

MCP Tools (43)

Generic CRUD (5):

  • intelligence_list(target, summary), intelligence_get(target, uid), intelligence_create(target, body), intelligence_update(target, uid, body), intelligence_delete(target, uid)

Insight (4):

  • list_insights(summary), count_insights(), get_insight(uid), create_insight(title, entry_context)

Signal (8):

  • list_signals(summary), signal_get(uid), signal_create(body), signal_acknowledge(uid), start_investigation_from_signal(uid), close_signal(uid), reopen_signal(uid), signal_set_disposition(uid, disposition)

Signal linking (1):

  • signal_link_insight(signal_id, insight_id)

Block/Evidence (6):

  • block_list(insight_id), create_block(insight_id, body), pin_block_to_insight(block_id, insight_id), freeze_block(uid), unpin_block(uid), list_blocks_for_insight(insight_id), explain_block_limits()

Edition lifecycle (8):

  • create_edition(insight_id), freeze_edition_for_attestation(edition_id), attest_edition(edition_id), tag_decision(edition_id, tag), list_decision_tags(insight_id), remove_decision_tag(edition_id, tag), request_edition_review(insight_id), edition_diff(edition_a, edition_b)

Narrative (5):

  • draft_narrative_with_evidence(insight_id), update_insight_text(uid, text), update_insight_narrative(uid, ...), add_comment(insight_id, text), commit_revision(insight_id)

AI Support (3):

  • suggest_next_blocks(insight_id), recommend_decision_template(insight_id), validate_evidence_sufficiency(insight_id)

Governance (7):

  • insight_timeline(insight_id), signal_by_entity(entity_id), get_decision_lineage(insight_id), list_events_for_insight(insight_id), verify_integrity(uid), verify_edition_integrity(edition_id), export_insight_with_attestation(insight_id)

Dataspace (7):

  • query_data(...), aggregate_data(...), kpi_batch(...), latest_per_group(...), list_accessible_data(), describe_model(name), search_subjects(...)

Profile context (4):

  • get_profile_context(), explain_result_limits(), explain_visibility_boundary(), list_users()

Task/Workflow (3):

  • create_task(...), list_tasks_for_user(), list_tasks_for_insight(insight_id)

Monitor (2):

  • execute_monitor_block(...), monitor_kpis(...)

Pack (5):

  • get_domain_pack(name), get_experience_pack(name), get_profile_pack(profile_id), list_packs(), validate_against_pack(insight_id)

Batch (1): batch_operations(...)

Lifecycle (1): initialize(profile_id)

The Dataspace tools delegate to component.fedai-rest.dataspace; in primary mode Cortex's MCP tools are aggregated by component.oracle.gateway.

MCP Server Boundary — Cortex vs Dataspace

Two MCP servers expose tools to the same agent ecosystem: Cortex's MCP handler (the intelligence/OODA layer) and the dataspace MCP server at component.fedai-rest.dataspace (/agentspace, generic CRUD over userspace target types + dataspace queries). They expose overlapping capabilities — e.g. the dataspace server's dataspace_query does the same work as Cortex's query_data, and a generic userspace_create(target=signal|insight|edition_snapshot) reaches the same objects as Cortex's create_signal / create_insight / create_edition. Cortex's gating and governance cannot be bypassed by connecting to the dataspace server: network-layer routing delivers intelligence-object operations to their owning service (Cortex, which owns their component schemas), so the dataspace generic CRUD never receives an intelligence-object mutation. This section defines the Cortex side of the boundary — the governed surface that owns these objects; the dataspace server carries no intelligence-object refusal requirement (network routing makes one unnecessary).

  • #REQ.mcp-boundary-cortex-owns — Cortex owns the intelligence/OODA tool surface, end to end and exclusively: all signal tools (OBSERVE); all gated query/aggregate/batch tools (ORIENT); all insight, evidence, and block tools (ORIENT); all edition and attestation tools (DECIDE); all task and workflow tools (ACT); governance/lineage/audit; and the AI-support, memory, report, and monitor/KPI tools. These are the tools enumerated under #cortex.mcp-tools.
  • #REQ.mcp-boundary-governance-gating — every intelligence-object mutation reachable over MCP MUST traverse Cortex's governed path, which the dataspace server's generic CRUD does not provide: capability check, profile scoping, size clamping + filter injection on reads, evidence-block creation, schema validation / severity computation / dedup on signal create, entry_mode+subject+pack enforcement on insight create, the attestation ceremony (freeze + hash) on edition create, and auto-journaling of every mutation. Network-layer routing sends intelligence-object operations to this governed Cortex path, so an intelligence object never reaches the dataspace server's ungoverned generic userspace_create — that path is not a supported route to these objects.
  • #REQ.mcp-boundary-no-uncontrolled-overlap — the dataspace server MUST NOT expose an ungated tool that duplicates a governed Cortex tool over intelligence objects. dataspace_query over intelligence indices routes to Cortex query_data; generic userspace_* CRUD for intelligence objects (signal, insight, edition_snapshot, block, workflow_task, etc.) is not a supported surface there — network-layer routing directs those mutations to the governed Cortex tools. The dataspace server retains platform/admin CRUD (dataset, trained-model, operation/transform, data-pipeline, federation/connection, system health, and generic userspace CRUD for platform objects such as marketplace, notebook, project). Removing or redirecting an overlapping tool requires auditing direct callers first (Beacon's MCP connection, admin/ops bulk scripts, CI/CD test-data setup) and providing a migration path; the cross-repo change spans the dataspace server and possibly Beacon.

REST Endpoints

Generic CRUD: | Method | Path | Purpose | |--------|------|---------| | GET | /api/v1/{target} | List objects by type | | GET | /api/v1/{target}/{uid} | Get by UID | | POST | /api/v1/{target} | Create | | POST | /api/v1/{target}/{uid} | Update | | DELETE | /api/v1/{target}/{uid} | Delete |

Domain-specific: | Method | Path | Purpose | |--------|------|---------| | GET | /api/v1/insight/{uid}/timeline | Ordered event history | | GET | /api/v1/signal/by-entity/{entity_id} | Signals for entity | | GET | /api/v1/edition/diff | Compare editions | | POST | /api/v1/chat | Chat with tool-use loop (standalone mode; requires llm_chat profile capability; 503 if LLM not configured) | | GET | /api/v1/chat/history | Conversation history by conversation_id | | DELETE | /api/v1/chat/{conversation_id} | Clear conversation |

Depends on: platform.axonis-core, platform.service-contract

Realizes: product.block, product.edition, product.insight, product.profile, product.report, product.signal, product.task

Required by: component.cortex.block-card, component.cortex.data-shape, component.cortex.decision-evidence, component.cortex.domain-loading, component.cortex.pack-reference, component.cortex.platform-architecture, component.oracle.apollo