@ltm-blueverse/alpha-semantic-hub 0.7.0

package/plugins/skills/causal/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: causal
+description: Analyze cause-and-effect relationships in the Alpha Semantic Hub knowledge graph — causal chains, interventions, counterfactuals, and causal influence scores.
+---
+
+# /alphasemantichub:causal
+
+Analyze causal relationships and infer impacts. Usage: `/alphasemantichub:causal <task> [args]`
+
+`$ARGUMENTS` = task + optional target entity, filter, or intervention.
+
+---
+
+## `chain [--subject <node>] [--depth N]`
+
+Build and inspect causal chains for a subject or category.
+
+```python
+from alphasemantichub.context.causal_analyzer import CausalChainAnalyzer
+from alphasemantichub.context import AgentContext
+
+# Option 1: Use an existing AgentContext decision backend
+chain = ctx.get_causal_chain(
+    decision_id=decision_id,
+    direction="upstream",
+    max_depth=depth,
+)
+
+# Option 2: Use CausalChainAnalyzer directly
+analyzer = CausalChainAnalyzer(graph_store=ctx.knowledge_graph)
+downstream = analyzer.get_causal_chain(
+    decision_id=decision_id,
+    direction="downstream",
+    max_depth=depth,
+)
+```
+
+Output: chain steps, cause strength, effect reach, and summary graph.
+
+---
+
+## `intervene <node> <action> [--scenario <json>]`
+
+Analyze decision impact and influenced decisions (current causal API).
+
+```python
+analyzer = CausalChainAnalyzer(graph_store=ctx.knowledge_graph)
+impact_score = analyzer.get_causal_impact_score(decision_id=decision_id)
+influenced = analyzer.get_influenced_decisions(
+    decision_id=decision_id,
+    max_depth=depth,
+)
+``` 
+
+Return: impact score, influenced decisions, and downstream scope.
+
+---
+
+## `counterfactual <fact> [--weight N]`
+
+Trace root causes and temporal causal paths.
+
+```python
+analyzer = CausalChainAnalyzer(graph_store=ctx.knowledge_graph)
+roots = analyzer.find_root_causes(decision_id=decision_id, max_depth=depth)
+historical_chain = analyzer.trace_at_time(
+    event_id=decision_id,
+    at_time="2026-01-01T00:00:00Z",
+    direction="upstream",
+    max_depth=depth,
+)
+```
+
+Output: root decision lineage and time-bounded causal context.

package/plugins/skills/change/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: change
+description: Inspect graph changes over time and ontology version diffs in Alpha Semantic Hub. Uses ContextGraph.state_at for point-in-time graph state and change_management.VersionManager for ontology versioning.
+---
+
+# /alphasemantichub:change
+
+Track what changed. Usage: `/alphasemantichub:change <task> [args]`
+
+> Two distinct mechanisms cover this, and they are **not** interchangeable:
+>
+> | Question | Tool |
+> | --- | --- |
+> | "What did the *graph* look like on date X?" | `ContextGraph.state_at()` |
+> | "What changed between *ontology* versions?" | `change_management.VersionManager` |
+
+---
+
+## `graph-at <timestamp>` — point-in-time graph state
+
+```python
+import os
+from alphasemantichub.context import ContextGraph
+
+graph = ContextGraph()
+graph.load_from_file(os.path.expanduser("~/.alphasemantichub/kg.json"))   # load_from_file does not expand ~
+
+snapshot = graph.state_at("2026-06-01")      # str | int | float | datetime
+```
+
+Diff two moments by comparing node IDs — `state_at()["nodes"]` is a list of
+dicts (unhashable), so compare the `id` fields, not the dicts themselves:
+
+```python
+before = graph.state_at("2026-06-01")
+after  = graph.state_at("2026-09-01")
+before_ids = {n["id"] for n in before["nodes"]}
+after_ids  = {n["id"] for n in after["nodes"]}
+added = after_ids - before_ids
+```
+
+For richer temporal work (scrubbing, evolution, temporal patterns) use
+`/alphasemantichub:temporal`, which wraps the same layer.
+
+---
+
+## `node-history <node_id>` — who touched this node
+
+Node-level history is provenance, not change management:
+
+```python
+import os
+from alphasemantichub.provenance import ProvenanceManager
+
+db_path = os.path.expanduser("~/.alphasemantichub/prov.db")   # storage_path is passed to
+os.makedirs(os.path.dirname(db_path), exist_ok=True)   # sqlite3.connect() unexpanded
+pm = ProvenanceManager(storage_path=db_path)
+history = pm.revision_history(node_id)
+log     = pm.audit_log(since="2026-01-01")
+```
+
+---
+
+## `versions` / `diff <v1> <v2>` — ontology versioning
+
+```python
+from alphasemantichub.change_management import VersionManager
+
+vm = VersionManager()
+vm.create_version("1.1.0", ontology)
+vm.list_versions()
+vm.get_latest_version()
+
+delta = vm.compare_versions("1.0.0", "1.1.0")
+delta = vm.diff_ontologies(base_ontology, target_ontology)
+migrated = vm.migrate_ontology("1.0.0", "1.1.0", ontology)
+```
+
+`TemporalVersionManager` and `OntologyVersionManager` are also exported for
+time-scoped and ontology-specific variants.

package/plugins/skills/decision/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: decision
+description: Full decision lifecycle in Alpha Semantic Hub — record, query, find precedents (hybrid/advanced), analyze influence, explain, insights dashboard, list, and record exceptions. Uses AgentContext, ContextGraph, DecisionQuery, CausalChainAnalyzer, DecisionRecorder.
+---
+
+# /alphasemantichub:decision
+
+Full decision lifecycle management. Usage: `/alphasemantichub:decision <sub-command> [args]`
+
+---
+
+## `record <category> "<scenario>" "<reasoning>" <outcome> <confidence>`
+
+Record a decision with full context.
+
+```python
+from alphasemantichub.context import AgentContext
+
+ctx = AgentContext(decision_tracking=True)
+decision_id = ctx.record_decision(
+    category=category,        # "loan_approval", "deployment", "hiring"
+    scenario=scenario,        # natural-language situation description
+    reasoning=reasoning,      # why this decision was made
+    outcome=outcome,          # "approved", "rejected", "deferred"
+    confidence=float(confidence),
+    entities=entities or [],
+    decision_maker="ai_agent",
+    valid_from=valid_from,    # optional ISO date string
+    valid_until=valid_until,
+)
+```
+
+Output: `Decision <decision_id> recorded | <category> | <outcome> (conf: 0.95)`
+
+---
+
+## `query "<question>" [--hops N] [--hybrid]`
+
+Query decisions using natural language with multi-hop graph traversal.
+
+```python
+from alphasemantichub.context import AgentContext
+
+ctx = AgentContext(decision_tracking=True, advanced_analytics=True)
+results = ctx.query_decisions(
+    query=question,
+    max_hops=int(hops) if hops else 3,
+    include_context=True,
+    use_hybrid_search="--hybrid" in args,
+)
+```
+
+For structured lookups use `DecisionQuery`:
+```python
+from alphasemantichub.context.decision_query import DecisionQuery
+dq = DecisionQuery(graph_store=ctx.graph_store)
+# dq.find_by_category(category, limit=100)
+# dq.find_by_entity(entity_id, limit=100)
+# dq.find_by_time_range(start, end, limit=100)
+# dq.multi_hop_reasoning(start_entity, query_context, max_hops=3)
+# dq.trace_decision_path(decision_id, relationship_types)
+# dq.analyze_decision_influence(decision_id, max_depth=3)
+```
+
+Return: `| ID | Category | Scenario | Outcome | Confidence | Timestamp |`
+
+---
+
+## `precedents "<scenario>" [--category <cat>] [--advanced] [--hops N] [--as-of <date>]`
+
+Find similar past decisions using hybrid semantic + structural + vector search.
+
+```python
+from alphasemantichub.context import AgentContext
+
+ctx = AgentContext(decision_tracking=True, kg_algorithms=True, vector_store_features=True)
+
+if "--advanced" in args:
+    precedents = ctx.find_precedents_advanced(
+        scenario=scenario, category=category, limit=10,
+        use_kg_features=True,
+        similarity_weights={"semantic": 0.5, "structural": 0.3, "vector": 0.2},
+    )
+else:
+    precedents = ctx.find_precedents(
+        scenario=scenario, category=category, limit=10,
+        use_hybrid_search=True,
+        max_hops=int(hops) if hops else 3,
+        include_context=True,
+        include_superseded=False,
+        as_of=as_of_date or None,   # temporal filter: only precedents that existed as_of this date
+    )
+```
+
+Return ranked: `| Rank | ID | Scenario | Outcome | Confidence | Similarity | Date |`
+
+---
+
+## `influence <decision_id> [--depth N]`
+
+Analyze how a decision influences others across the graph.
+
+```python
+from alphasemantichub.context import AgentContext
+
+ctx = AgentContext(decision_tracking=True, advanced_analytics=True, kg_algorithms=True)
+influence = ctx.analyze_decision_influence(decision_id, max_depth=int(depth) if depth else 3)
+predictions = ctx.predict_decision_relationships(decision_id, top_k=5)
+```
+
+Output: Influence score + influenced decisions table + predicted new relationships.
+
+---
+
+## `explain <decision_id>`
+
+Full explainability trace — reasoning steps, causal antecedents, policy compliance.
+
+```python
+from alphasemantichub.context import AgentContext, ContextGraph
+
+ctx = AgentContext(decision_tracking=True)
+explainability = ctx.trace_decision_explainability(decision_id)
+
+graph = ContextGraph(advanced_analytics=True)
+chain = graph.trace_decision_chain(decision_id, max_steps=5)
+causality = graph.trace_decision_causality(decision_id, max_depth=5)
+```
+
+Output: Reasoning steps, causal antecedents, evidence items, policy compliance status.
+
+---
+
+## `insights`
+
+Comprehensive analytics across all tracked decisions.
+
+```python
+from alphasemantichub.context import ContextGraph, AgentContext
+
+ctx = AgentContext(decision_tracking=True, advanced_analytics=True)
+graph = ContextGraph(advanced_analytics=True)
+
+insights = graph.get_decision_insights()
+summary = graph.get_decision_summary()
+context_insights = ctx.get_context_insights()
+```
+
+Output: Total count, category breakdown, outcome distribution, avg confidence, top influential.
+
+---
+
+## `list [--category <cat>] [--entity <id>] [--from <date>] [--to <date>]`
+
+```python
+from alphasemantichub.context.decision_query import DecisionQuery
+from alphasemantichub.context import AgentContext
+from datetime import datetime
+
+ctx = AgentContext(decision_tracking=True)
+dq = DecisionQuery(graph_store=ctx.graph_store)
+
+if category:    decisions = dq.find_by_category(category, limit=100)
+elif entity:    decisions = dq.find_by_entity(entity, limit=100)
+elif from_date: decisions = dq.find_by_time_range(
+                    start=datetime.fromisoformat(from_date),
+                    end=datetime.fromisoformat(to_date or "2099-12-31"),
+                )
+```
+
+Return: `| ID | Category | Scenario | Outcome | Confidence | Maker | Timestamp |`
+
+---
+
+## `exception <decision_id> <policy_id> "<reason>" --approver <name>`
+
+Record a formal policy exception.
+
+```python
+from alphasemantichub.context.decision_recorder import DecisionRecorder
+from alphasemantichub.context import AgentContext
+
+ctx = AgentContext(decision_tracking=True)
+recorder = DecisionRecorder(graph_store=ctx.graph_store)
+
+exception_id = recorder.record_exception(
+    decision_id=decision_id, policy_id=policy_id,
+    reason=reason, approver=approver,
+    approval_method="manual_override", justification=reason,
+)
+
+from alphasemantichub.context.decision_query import DecisionQuery
+dq = DecisionQuery(graph_store=ctx.graph_store)
+similar = dq.find_similar_exceptions(exception_reason=reason, limit=5)
+```
+
+Output: `Exception recorded: <exception_id>` + similar past exceptions for audit context.

package/plugins/skills/deduplicate/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: deduplicate
+description: Detect duplicate entities, duplicate groups, and relationship duplicates in Alpha Semantic Hub using fuzzy matching, schema heuristics, and graph similarity.
+---
+
+# /alphasemantichub:deduplicate
+
+Remove duplicates from the knowledge graph. Usage: `/alphasemantichub:deduplicate <strategy> [args]`
+
+`$ARGUMENTS` = deduplication strategy + optional entity or threshold.
+
+---
+
+## `entities [--threshold <score>] [--field <name>]`
+
+Detect duplicate entities and group them by similarity.
+
+```python
+from alphasemantichub.deduplication import DuplicateDetector
+
+finder = DuplicateDetector()
+candidates = finder.detect_duplicates(entities, threshold=threshold)
+groups = finder.detect_duplicate_groups(entities, threshold=threshold)
+```
+
+Output: duplicate candidate list, duplicate groups, and representative merge recommendations.
+
+---
+
+## `relations [--similarity <score>]`
+
+Detect duplicate relationships and normalize edge representations.
+
+```python
+from alphasemantichub.deduplication import DuplicateDetector
+
+finder = DuplicateDetector()
+relations = finder.detect_duplicates(relation_list, threshold=similarity)
+```
+
+Result: duplicate relation candidates, normalized relationship groups, and cleanup summary.

package/plugins/skills/embed/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: embed
+description: Generate, inspect, and use node/text embeddings in Alpha Semantic Hub — 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.
+---
+
+# /alphasemantichub:embed
+
+Generate and inspect graph embeddings. Usage: `/alphasemantichub: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.
+
+```python
+from alphasemantichub.kg.node_embeddings import NodeEmbedder
+from alphasemantichub.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.
+
+```python
+from alphasemantichub.kg.node_embeddings import NodeEmbedder
+from alphasemantichub.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.
+
+```python
+from alphasemantichub.kg.similarity_calculator import SimilarityCalculator
+from alphasemantichub.kg.node_embeddings import NodeEmbedder
+from alphasemantichub.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.
+
+```python
+from alphasemantichub.kg.link_predictor import LinkPredictor
+from alphasemantichub.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.
+
+```python
+from alphasemantichub.kg.link_predictor import LinkPredictor
+from alphasemantichub.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).
+
+```python
+from alphasemantichub.kg.similarity_calculator import SimilarityCalculator
+from alphasemantichub.kg.node_embeddings import NodeEmbedder
+from alphasemantichub.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.
+
+```python
+from alphasemantichub.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.

package/plugins/skills/explain/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: explain
+description: Explain Alpha Semantic Hub reasoning, decision logic, and graph results with traceability, causal context, and human-readable rationale.
+---
+
+# /alphasemantichub:explain
+
+Produce explanations for decisions, rules, and graph analytics. Usage: `/alphasemantichub:explain <target> [args]`
+
+`$ARGUMENTS` = explanation target + optional detail level.
+
+---
+
+## `decision <decision_id> [--detail <level>]`
+
+Explain why a decision was reached.
+
+```python
+from alphasemantichub.reasoning.explanation_generator import ExplanationGenerator
+
+# For decision explainability in Alpha Semantic Hub contexts:
+decision_trace = ctx.trace_decision_explainability(decision_id=decision_id)
+
+# For reasoning/proof explanations:
+generator = ExplanationGenerator(detail_level=detail)
+explanation = generator.generate_explanation(reasoning_result)
+```
+
+Output: decision factors, rule traces, confidence, and suggested next steps.
+
+---
+
+## `graph <node_id> [--path N]`
+
+Explain graph relationships and why a node is connected.
+
+```python
+# Use AgentContext explainability + causal tracing for graph-connected decisions
+graph_explanation = ctx.trace_decision_explainability(decision_id=node_id)
+upstream = ctx.get_causal_chain(decision_id=node_id, direction="upstream", max_depth=depth)
+downstream = ctx.get_causal_chain(decision_id=node_id, direction="downstream", max_depth=depth)
+```
+
+Return: cause/effect chains, supporting evidence, and relevant metadata.