semantica/plugins/skills/embed/SKILL.md

---

name: embed description: Generate, inspect, and use node/text embeddings in Semantica — compute Node2Vec embeddings, find similar nodes, score link predictions, batch similarity, and pairwise similarity. Uses NodeEmbedder, SimilarityCalculator, LinkPredictor, and AgentContext. Sub-commands: compute, similar, similarity, predict-link, top-links, batch, pairwise.

/semantica:embed

Generate and inspect graph embeddings. Usage: /semantica:embed <sub-command> [args]

$ARGUMENTS = sub-command + arguments.

---

compute [--labels <t1,t2>] [--rels <r1,r2>] [--dim N] [--walks N]

Generate Node2Vec embeddings for graph nodes.

from semantica.kg.node_embeddings import NodeEmbedder
from semantica.context import ContextGraph

graph = ContextGraph()
embedder = NodeEmbedder()

node_labels = labels_arg.split(",") if labels_arg else graph.get_all_node_types()
rel_types = rels_arg.split(",") if rels_arg else []

# All positional args required: graph_store, node_labels, relationship_types
embeddings = embedder.compute_embeddings(
    graph_store=graph,
    node_labels=node_labels,
    relationship_types=rel_types,
    embedding_dimension=int(dim_arg) if dim_arg else None,
    num_walks=int(walks_arg) if walks_arg else None,
)

# Store embeddings back on nodes
embedder.store_embeddings(
    graph_store=graph,
    embeddings=embeddings,
    property_name="node2vec_embedding",
)

Output:

Embeddings computed and stored.
  Nodes embedded:     N
  Embedding dim:      128
  Node types covered: [type1, type2, ...]
  
Sample (first 5 nodes):
  | Node | Type | Embedding dim | Stored |

---

similar <node_id> [--top N]

Find the most similar nodes to a given node in embedding space.

from semantica.kg.node_embeddings import NodeEmbedder
from semantica.context import ContextGraph, AgentContext

graph = ContextGraph()
embedder = NodeEmbedder()

# NodeEmbedder.find_similar_nodes uses the stored node2vec_embedding property
neighbors = embedder.find_similar_nodes(
    graph_store=graph,
    node_id=node_id,
    top_k=int(top_n) if top_n else 10,
    embedding_property="node2vec_embedding",
)

# Also use AgentContext for richer similarity with metadata
ctx = AgentContext(kg_algorithms=True)
entity_similar = ctx.find_similar_entities(
    entity_id=node_id,
    similarity_type="content",  # or "structural", "hybrid"
    top_k=int(top_n) if top_n else 10,
)

Return: | Rank | Node ID | Type | Cosine Similarity | Shared Properties |

---

similarity <n1> <n2> [--method cosine|euclidean|manhattan|correlation]

Compute pairwise similarity between two nodes.

from semantica.kg.similarity_calculator import SimilarityCalculator
from semantica.kg.node_embeddings import NodeEmbedder
from semantica.context import ContextGraph

graph = ContextGraph()
embedder = NodeEmbedder()
calc = SimilarityCalculator()

# Get embeddings for both nodes
v1 = embedder.find_similar_nodes(graph, n1, top_k=1)  # placeholder — use stored embedding
v2 = embedder.find_similar_nodes(graph, n2, top_k=1)

method = method_arg or "cosine"
if method == "cosine":
    score = calc.cosine_similarity(vector1=v1, vector2=v2)
elif method == "euclidean":
    score = calc.euclidean_distance(v1, v2)
elif method == "manhattan":
    score = calc.manhattan_distance(v1, v2)
elif method == "correlation":
    score = calc.correlation_similarity(v1, v2)

Output:

Similarity: "<n1>" ↔ "<n2>"
  Method:  cosine
  Score:   0.847

  Interpretation: HIGH similarity (>0.8)
  Shared neighbors:   K
  Common node types:  [types]

---

predict-link <n1> <n2> [--method cosine|jaccard|adamic-adar|common-neighbors]

Score the likelihood of a relationship between two nodes.

from semantica.kg.link_predictor import LinkPredictor
from semantica.context import ContextGraph

graph = ContextGraph()
predictor = LinkPredictor()

# score_link(graph_store, node_id1, node_id2, method=)
score = predictor.score_link(
    graph_store=graph,
    node_id1=n1,
    node_id2=n2,
    method=method_arg or None,
)

Output:

Link Prediction: "<n1>" → "<n2>"
  Method:  cosine
  Score:   0.723  (threshold: 0.5 → LIKELY)

  Recommendation: This link is LIKELY to be meaningful.

---

top-links <node_id> [--top N] [--method <method>]

Find the top-N most likely new connections for a node.

from semantica.kg.link_predictor import LinkPredictor
from semantica.context import ContextGraph

graph = ContextGraph()
predictor = LinkPredictor()

top = predictor.predict_top_links(
    graph_store=graph,
    node_id=node_id,
    top_k=int(top_n) if top_n else 10,
    method=method_arg or None,
)

Return: | Rank | Target Node | Type | Score | Existing Link? |

---

batch <query_node> [--against <n1,n2,...>] [--top N]

Score similarity between a query node and a set of target nodes (or all nodes).

from semantica.kg.similarity_calculator import SimilarityCalculator
from semantica.kg.node_embeddings import NodeEmbedder
from semantica.context import ContextGraph

graph = ContextGraph()
embedder = NodeEmbedder()
calc = SimilarityCalculator()

# Get query embedding and all target embeddings
query_vec = ...  # from stored node2vec_embedding
target_embeddings = {n: embedder.get_embedding(n) for n in targets}

scores = calc.batch_similarity(
    embeddings=target_embeddings,
    query_embedding=query_vec,
    top_k=int(top_n) if top_n else 20,
)

Return: | Node | Type | Score | sorted descending.

---

pairwise [--labels <t1,t2>] [--method cosine|euclidean]

Compute all pairwise similarities among a set of nodes.

from semantica.kg.similarity_calculator import SimilarityCalculator

calc = SimilarityCalculator()

pairwise = calc.pairwise_similarity(
    embeddings=embeddings_dict,
    method=method_arg or None,
)

Show as a heatmap summary — top-5 most similar pairs and bottom-5 most dissimilar pairs. Full matrix on request.

Also use AgentContext.predict_decision_relationships(decision_id, top_k) when working within decision graphs for relationship prediction enriched with KG algorithms.