Synergies API — Find related entities

Use GET /retrieve/entity/synergies to find entities related to a target through the graph. The endpoint resolves a target, explores direct and event-mediated anchors, scores eligible peer nodes, and returns the strongest associations.

This is useful beyond ecommerce. Examples include services connected to the same incident, courses related through shared skills, researchers connected through projects, or controls connected through the same policy requirement.

Mental model

Suppose two SERVICE nodes participate in the same incident event. The incident can act as an anchor connecting them. The response returns each peer as node, the anchors that explain the association in connected_by, and an association_score for ordering.

The endpoint is still graph retrieval:

• It needs useful nodes and relationships.
• It returns entities, not passages.
• It can use same or opposite node polarity.
• It is not the same as query search or the multi-channel recommendation endpoint.

Event hubs connect peers

In the diagram below, Maria initiates an employment event that targets Tom and Lisa. The event hub preserves the action as a first-class node. Because Tom and Lisa participate in the same event structure, the graph has an explainable path for treating them as related peers.

The same pattern can represent services participating in an incident, researchers contributing to a project, or courses addressing a shared skill. The domain changes; the shared-anchor principle does not.

Find services related to an incident participant

curl --get "http://localhost:8000/retrieve/entity/synergies" \
  -H "BrainPAT: $BRAINPAT_TOKEN" \
  -H "X-Brain-ID: operations" \
  --data-urlencode "target=payments-api" \
  --data-urlencode "polarity=same" \
  --data-urlencode "labels=SERVICE" \
  --data-urlencode "top_k=10" \
  --data-urlencode "ppa=true"

A shortened response looks like:

{
  "target_node": {
    "uuid": "service-42",
    "labels": ["SERVICE"],
    "name": "payments-api"
  },
  "synergies": [
    {
      "node": {
        "uuid": "service-77",
        "labels": ["SERVICE"],
        "name": "checkout-api"
      },
      "connected_by": [
        {
          "uuid": "incident-19",
          "labels": ["EVENT"],
          "name": "Connection pool saturation"
        }
      ],
      "association_score": 0.0
    }
  ],
  "anchors": []
}

The numeric value above demonstrates the response type only; it is not a quality claim or expected score. Interpret rankings within one result set and evaluate them against your graph and task.

Request controls

labels is serialized as repeated query parameters, for example labels=COURSE&labels=WORKSHOP.

Visual guide to traversal controls

The controls change which graph evidence is returned or allowed to contribute. They do not turn the endpoint into passage search.

Direct-only results with do=true

Direct-only mode restricts discovery to direct synergy structure. In this example, Maria has direct graph branches through the Owns and Graduated hubs; James and Michael are found through those directly shared structures.

Use direct-only mode when indirect event or similarity expansion creates too many weak peers. Avoid it when multi-step event structure carries important evidence.

Seed anchors with ppa=true

Seed anchors are the graph nodes reached from the target and used to discover peers. Requesting ppa=true includes them in the response as anchors, making the association easier to inspect.

Potential anchors with pa=true

Potential anchors are similar nodes that could explain or extend an association but are not necessarily connected through the same direct path. Requesting pa=true includes them as potential_anchors when available.

Potential anchors are diagnostic evidence, not automatically accepted relationships. Inspect them before changing the graph or using them as application truth.

How the association score is calculated

association_score is a ranking signal built from embedding similarity and graph-path evidence. It is not a probability, confidence percentage, or globally calibrated value. Compare scores within one request and one configuration.

The implementation is in entity_sibilings.py, with similarity helpers in numbers.py.

1. Cosine similarity

BrainAPI compares available node, relationship, and event-context embeddings with cosine similarity:

A value closer to 1 means the vectors point in a similar direction. A zero-length vector produces 0 in the shipped helper. Cosine similarity alone does not prove that two entities have a valid graph relationship; it supplies one component of the path score.

2. Weighted similarity

For event-mediated candidates, BrainAPI strengthens the node-to-target description component with wsim:

The shipped node-description weight is:

Therefore that branch uses the square root of the node similarity:

This transformation assumes a non-negative similarity input. It raises smaller positive similarities while preserving 0 and 1; it should not be interpreted as learned calibration.

3. Relationship and event-context similarity

For an event-mediated path, the candidate-side context combines the relevant event-edge embeddings, then compares that representation with the target-side context:

Here, v_{e,c} and v_{r,c} represent the candidate-side event and relationship evidence, while v_{ctx,t} represents the relationship context collected from the target side. Direct paths use the available direct-relationship embedding evidence instead of an event-context mean.

4. Per-path association score

When both the target-side similarity component t and relationship/context component r are non-zero, BrainAPI calculates:

The multiplier favors graph evidence reached through a direct seed over evidence reached through a similar, remote seed:

If either required component is missing or zero, the shipped implementation assigns that path a score of 0. Because the direct multiplier is greater than one, an association score can exceed 1; this is another reason not to treat it as a probability.

For intuition only, if t=0.64 and r=0.48, the mean component is 0.56. The same evidence would contribute 0.728 through a direct seed and 0.392 through a remote seed. These numbers demonstrate the formula; they are not expected production scores.

5. Merge evidence from multiple anchors

When another seed connects to a candidate already found, BrainAPI merges the previous association score p and new path score n with wmean and FACTORS_INCREMENTAL_WEIGHT=0.3:

The general helper defines:

and transforms its first two inputs before taking the mean:

The Synergies merge passes two values, so w_eff=0.15 and the two exponents are 0.85. This rewards a candidate supported through more than one useful anchor without simply summing scores.

Scoring constants and limits

Before scoring, BrainAPI excludes deprecated or invalidated predicates and applies candidate label and polarity constraints. It sorts the remaining candidates by descending association_score, then truncates to top_k. A strong score cannot rescue a candidate rejected by those eligibility rules.

Same and opposite polarity

Use same when peers should express compatible orientation: two helpful courses, two preferred media items, or two services affected in the same way. Nodes with neutral or missing polarity are compatible with each other in this mode.

Use opposite only when the graph deliberately models positive and negative sides of a need. A negative problem node might connect to a positive remediation node. Neutral or missing polarity never qualifies for opposite.

Do not introduce polarity merely to make this endpoint return results. If your domain is not naturally polar, use same and model meaningful anchors and labels.

Decide between related surfaces

Evaluate before relying on it

Create a small set of targets with expected peers and explanations. Measure whether the relevant peer appears in the first k, then inspect connected_by for spurious high-degree anchors. Compare do=true with the default path to learn whether indirect event structure contributes signal or noise.

Stop using a channel or anchor type when it repeatedly produces unrelated peers and cannot be corrected through cleaner labels, relationships, or ingestion. A higher graph score is not evidence of business usefulness by itself.

Troubleshoot

For exact schemas and generated request examples, open the Retrieve API reference.