Relate two entities
relate_entitiesIdempotent
Record a directed relation between two entities identified by name, creating either entity if it does not exist.
Behavior:
- Each name is matched case-insensitively against entity names and
aliases. With the type omitted ('unclassified'), any same-name entity
is reused. With a real type, a same-name entity of a compatible type
(or an unclassified one, which is then given that type) is reused, and
type-prefixed names are recognized ("Atlas" can match "Project Atlas"
of type project). Otherwise the entity is created and linked to the
NEXUS root entity.
- If a current relation of the same type already exists between the two,
it is reused and its evidence reinforced; otherwise a new one is
created.
- 'same_as' does not create a relation: the entities are resolved (and
created if missing) and a merge proposal is opened for them (the
response carries its id).
- For works_for, reports_to and located_in (one current value per
subject), a conflicting current relation opens a contradiction unless
supersede_previous is true.
- To record that a relation stopped being true, use ``end_relation``.
A person employed by an organization is modeled as works_for
(person -> organization).
Returns {source_entity, target_entity, relation, source_created,
target_created, relation_created, superseded_relation_ids,
contradiction_id}.
Args:
source_name: Name of the source entity.
target_name: Name of the target entity.
relation_type: Relation type from the closed ontology (schema enum).
Use 'related_to' if none fits.
source_type: Entity type of the source, if known. Omit rather than
guessing; 'concept' is a real (abstract) type, not "unknown".
target_type: Same as source_type, for the target.
source_attributes: Extra attributes used only if the source is created.
target_attributes: Extra attributes used only if the target is created.
weight: Relation weight in [0.0, 1.0].
valid_from: ISO 8601 date from which the relation holds. Defaults to now.
supersede_previous: Only for works_for, reports_to and located_in.
True when the information says the value changed; the previous
current relation is closed and kept in history.
epistemic_status: How it is known: 'reported' (default), 'observed',
'measured' or 'inferred'.
evidence_ref: Optional source (URL, file, person) stored as evidence.
Without it the relation is recorded but counted as unjustified.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| weight | No | ||
| valid_from | No | ||
| source_name | Yes | ||
| source_type | No | unclassified | |
| target_name | Yes | ||
| target_type | No | unclassified | |
| evidence_ref | No | ||
| relation_type | Yes | ||
| epistemic_status | No | ||
| source_attributes | No | ||
| target_attributes | No | ||
| supersede_previous | No |