Skip to content

Parallax — Service Interface

Status: Implemented (partial) — engine complete (944 tests, F1=0.973); MCP/UI wiring is M3 work tracked in parallax#36. Depends on: platform.axonis-core, platform.service-contract Realizes: product.lens, product.fusion

Service interface

Port: 8003 API version: /api/v2 Domain: Entity Lens — entity resolution, federated matching, lens configuration management

Defines the externally-facing MCP tools, REST endpoints, and domain objects owned by Parallax. The service conforms to platform.service-contract (dual interface, auth, Helm, CI/CD); this spec covers what makes Parallax unique. Persistence and schema-driven CRUD over ES are provided by component.fedai-rest.dataspace.

Terminology note: Internally, the system is described using Entity Lens and Cost Lens. In external / customer-facing materials, these are referred to as Identity Lens and Decision Lens respectively. See LENS-TAXONOMY.md for the canonical mapping.

Domain Objects

Domain objects come from axonis-core userspace (platform.axonis-core).

Object Schema constant ES index
Lens Schema.LENS fusion
LensBinding Schema.LENS_BINDING fusion
EntityMatch Schema.ENTITY_MATCH fusion
EntityCluster Schema.ENTITY_CLUSTER fusion
FusionRun Schema.FUSION_RUN fusion

MCP Tools (18)

CRUD (8):

  • lens_list(summary), lens_get(uid), lens_create(body)
  • lens_binding_list(summary)
  • entity_match_list(summary), entity_match_get(uid)
  • fusion_run_list(summary), fusion_run_get(uid)

Workflow (3):

  • fusion_run_start(lens_id, node_data, threshold, null_penalty, id_field, privacy, lens_version=None) — full extract→match→resolve; lens_version defaults to the parsed spec's version (#51) pipeline
  • fusion_run_status(run_id) — active run progress
  • fusion_run_cancel(run_id) — cancel active run

Pipeline Stages (3):

  • fusion_extract(lens_id, node_data, ...) — extract only, returns run_id
  • fusion_match_phase(run_id) — match only, returns scored pairs
  • fusion_resolve_phase(run_id, threshold) — cluster, returns entities

Decisions (2):

  • entity_match_review(correlation_id, decision, reason, confidence_adjustment) — confirm/reject/defer
  • entity_match_attest(correlation_id, attester_id, decision, confidence_adjustment, evidence) — add attestation

Introspection (2):

  • entity_match_explain(correlation_id) — per-field score breakdown
  • fusion_run_summary(run_id) — narrative summary

MCP Resources (4)

  • fusion://runs — active run list
  • fusion://runs/{run_id} — run status
  • fusion://runs/{run_id}/matches — scored matches
  • fusion://runs/{run_id}/clusters — resolved clusters

REST Endpoints

Method Path Maps to MCP tool
GET /api/v2/lens lens_list
GET /api/v2/lens/{uid} lens_get
POST /api/v2/lens lens_create
GET /api/v2/lens_binding lens_binding_list
GET /api/v2/entity_match entity_match_list
GET /api/v2/entity_match/{uid} entity_match_get
GET /api/v2/fusion_run fusion_run_list
GET /api/v2/fusion_run/{uid} fusion_run_get
POST /api/v2/fusion/run fusion_run_start
GET /api/v2/fusion/run/{run_id}/status fusion_run_status
DELETE /api/v2/fusion/run/{run_id} fusion_run_cancel
POST /api/v2/fusion/extract fusion_extract
POST /api/v2/fusion/match/{run_id} fusion_match_phase
POST /api/v2/fusion/resolve/{run_id} fusion_resolve_phase
POST /api/v2/entity_match/{uid}/review entity_match_review
POST /api/v2/entity_match/{uid}/attest entity_match_attest
GET /api/v2/entity_match/{uid}/explain entity_match_explain
GET /api/v2/fusion_run/{uid}/summary fusion_run_summary

Compute Library

Parallax owns parallax/ops/fusion/. This is the canonical fusion engine — lens parsing, blocking, scoring, clustering, three-phase protocol, PSI, federation, correlation, entity registry. Imported by Titan's FusionOrchestrator; no other consumer.

Fusion wire type: The federation message envelope (Message, MessageType) lives in axonis-core (platform.axonis-core) at axonis.fusion (axonis-core/axonis/fusion.py). It is not a parallax type. An earlier plan to host it at parallax.protocol.FusionMessage was superseded when it landed in axonis-core as a shared foundation dependency consumed by both titan and parallax. Some consumer wheels (parallax, cortex, prism) may still ship a parallel axonis.protocol.FusionMessage / FusionMessageType surface from an older build; new consumers should import axonis.fusion.Message / MessageType directly per axonis-core main.

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

Realizes: product.fusion, product.lens