distillery_relations

Manage typed relations between knowledge entries.

USE WHEN: linking entries together (e.g. marking one as blocking another, citing a reference, or flagging duplicates), walking the relation graph from a seed entry to surface multi-hop neighbours, or computing graph metrics (bridges, communities) on the relations subgraph.

PARAMS:

• action (str, required): Operation. Valid: [add, get, remove, traverse, metrics, promote_entities].

• from_id (str, required for add): Source entry UUID.

• to_id (str, required for add): Target entry UUID.

• relation_type (str, required for add, optional for get/traverse): Relation type. Valid: [link, corrects, supersedes, related, blocks, depends_on, citation, duplicate, merge_source, sync_source, mentions, chunk].

• weight (float, optional for add): Edge strength (e.g. interest/engagement magnitude). On a re-assert of an existing edge, supplied attributes are upserted.

• valid_at / invalid_at (str ISO 8601, optional for add): Bi-temporal validity window — when the relationship became / stopped being true (invalid_at null = current).

• metadata (object, optional for add): Arbitrary per-edge attributes (JSON).

• entry_id (str, required for get/traverse, required for metrics scope='ego'): Entry UUID to query relations for (BFS root for traverse / ego-graph).

• direction (str, optional for get/traverse, default="both"): Filter direction. Valid: [outgoing, incoming, both].

• relation_id (str, required for remove): UUID of the relation to delete.

• hops (int, optional for traverse, default=2): BFS depth, capped at [1, 3].

• metric (str, required for metrics): Graph metric to compute. Valid: [bridges, communities, constraint, link_prediction, orphans]. Requires the [graph] optional extra.

• scope (str, optional for metrics, default="global"): Subgraph scope. Valid: [global, ego]. "ego" requires entry_id.

• limit (int, optional for metrics, default=10): top-k results. bridges = entries by betweenness centrality; communities = K largest communities; constraint = entries by lowest Burt constraint (strongest structural-hole brokers); link_prediction = top predicted edges by Adamic-Adar (pass entry_id to score adjacencies for one entry); orphans = sample (<=50) of entry IDs absent from the relations graph (unlinked entries — feeds a linking / gap-scan pass).

• project / tags / date_from / date_to (optional, metrics global scope): restrict the entries whose relations participate in the graph.

RETURNS (success): { relation_id: str, from_id: str, to_id: str, relation_type: str, weight: float | null, valid_at: str | null, invalid_at: str | null, metadata: object | null } (add) or { entry_id: str, relations: list, count: int } (get) or { relation_id: str, removed: bool } (remove) or { action: "traverse", root: str, hops: int, direction: str, relation_type: str | null, nodes: [{id: str, depth: int}], edges: [{from_id, to_id, relation_type}], node_count: int, edge_count: int } (traverse) or { action: "metrics", metric: str, scope: str, node_count: int, edge_count: int, total_entries: int, graph_node_count: int, orphan_rate: float, results: list, count: int, computed_at: str, cache_hit: bool } (metrics). orphan_rate = 1 - graph_node_count/total_entries (graph-health signal; 0.0 when total_entries is 0). Or { action: "promote_entities", entities_created: int, entities_reused: int, mentions_created: int, threshold: int } (promote_entities). Scans entity/* and tech/* tags and promotes any canonical tag meeting the configured tags.entity_promotion_threshold to an ENTITY entry node, linking each tagged entry with a mentions edge. Idempotent. RETURNS (error): { error: true, code: "NOT_FOUND" | "INVALID_PARAMS" | "INTERNAL", message: "..." }

RELATED: distillery_correct (creates 'corrects' relations automatically), distillery_find_similar (to discover related entries)