@ltm-blueverse/alpha-semantic-hub 0.7.0

package/plugins/skills/temporal/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: temporal
+description: Temporal graph operations on Alpha Semantic Hub — scoped queries at a point in time, graph snapshots, node change timelines, temporal causal analysis, and graph state reconstruction. Uses AgentContext.find_precedents(as_of=), ContextGraph.state_at(), CausalChainAnalyzer.trace_at_time(), and TemporalQueryRewriter. Sub-commands: query, snapshot, timeline, causal-at, precedents-at.
+---
+
+# /alphasemantichub:temporal
+
+Temporal graph operations. Usage: `/alphasemantichub:temporal <sub-command> [args]`
+
+`$ARGUMENTS` = sub-command + query/node + date expression.
+
+---
+
+## `query "<question>" [at|before|after <date>]`
+
+Temporally-scoped natural-language graph query.
+
+```python
+from alphasemantichub.kg.temporal_query_rewriter import TemporalQueryRewriter
+from alphasemantichub.kg.temporal_normalizer import TemporalNormalizer
+
+normalizer = TemporalNormalizer()
+# Normalize natural date expressions: "last month", "Q3 2024", "2025-01-15"
+date = normalizer.normalize(date_expr)
+
+rewriter = TemporalQueryRewriter()
+# Rewrite query with temporal constraint
+rewritten = rewriter.rewrite(
+    query=question,
+    temporal_constraint={"op": direction, "value": date},  # op: "at"|"before"|"after"
+)
+```
+
+Then run the rewritten query through `AgentContext.retrieve()` or `ContextGraph.query()`.
+
+Return ranked results with `Valid From`, `Valid Until`, `Active At <date>` columns. Mark nodes that were not yet created at the target time as `[not yet created]`.
+
+---
+
+## `snapshot <date>`
+
+Reconstruct the full graph state as it existed at a specific point in time.
+
+```python
+from alphasemantichub.context import ContextGraph
+
+graph = ContextGraph(advanced_analytics=True)
+
+# state_at returns a dict snapshot of the graph at that timestamp
+snapshot = graph.state_at(timestamp=date)  # ISO string or datetime
+```
+
+Output:
+```
+Graph snapshot at <date>:
+  Nodes:       N  (M added since prev snapshot, K removed)
+  Edges:       P
+  Density:     0.21
+  Communities: Q
+
+Active decision categories at <date>:
+  | Category | Count | Avg Confidence |
+
+Top 10 nodes (by degree at <date>):
+  | Node | Type | Degree |
+
+[Compact Mermaid graph TD — top-10 most connected nodes at that time]
+```
+
+---
+
+## `timeline <node_id>`
+
+Show attribute and relationship changes for a node across its full history.
+
+```python
+from alphasemantichub.context import ContextGraph
+
+graph = ContextGraph()
+
+# Use state_at() at multiple time points to reconstruct history
+# Check add_node timestamps and edge addition times from graph data
+node_data = graph.find_node(node_id)
+```
+
+Output as Markdown timeline:
+```
+Timeline for "<node_id>" (<type>):
+
+  <timestamp>  CREATED
+    Properties: {confidence: 0.71, category: "loan_approval"}
+    Source: extraction/pipeline
+
+  <timestamp>  UPDATED
+    confidence: 0.71 → 0.91  [source: review]
+
+  <timestamp>  RELATIONSHIP ADDED
+    "<node_id>" →[CAUSED]→ "Decision_B"
+
+  <timestamp>  RELATIONSHIP REMOVED
+    "<node_id>" →[PRECEDED_BY]→ "Decision_X"  (superseded)
+
+Total lifespan: <duration>
+Current state:  <active|superseded>
+```
+
+---
+
+## `causal-at <decision_id> <date> [--direction upstream|downstream]`
+
+Trace a causal chain as it existed at a specific point in time.
+
+```python
+from alphasemantichub.context.causal_analyzer import CausalChainAnalyzer
+from alphasemantichub.context import AgentContext
+
+ctx = AgentContext(decision_tracking=True)
+analyzer = CausalChainAnalyzer(graph_store=ctx.graph_store)
+
+historical_chain = analyzer.trace_at_time(
+    event_id=decision_id,
+    at_time=date,           # ISO string or datetime
+    direction=direction or "upstream",
+    max_depth=10,
+)
+```
+
+Output:
+```
+Historical causal chain for <decision_id> at <date>:
+  Direction: upstream (what caused it?)
+
+  [Mermaid graph TD showing chain as it existed at <date>]
+
+  Decisions present then but not now: [list]
+  Decisions added since then: [list]
+```
+
+---
+
+## `precedents-at "<scenario>" <date> [--category <cat>]`
+
+Find precedent decisions that existed as of a specific date — useful for auditing what context was available when a decision was made.
+
+```python
+from alphasemantichub.context import AgentContext
+
+ctx = AgentContext(decision_tracking=True, advanced_analytics=True)
+
+# find_precedents supports as_of parameter for temporal precedent search
+precedents = ctx.find_precedents(
+    scenario=scenario,
+    category=category or None,
+    limit=10,
+    use_hybrid_search=True,
+    include_context=True,
+    include_superseded=False,
+    as_of=date,  # Only return precedents that existed at this date
+)
+```
+
+Return: `| Rank | Decision ID | Scenario | Outcome | Confidence | Set Date | Valid Until |`
+
+Note decisions that were superseded before or after the target date.

package/plugins/skills/validate/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: validate
+description: Validate Alpha Semantic Hub pipelines, extraction quality, graph schemas, and ontology consistency. Returns structured error/warning checklists. Uses PipelineValidator, PipelineBuilder.validate_pipeline(), GraphValidator, and OntologyValidator. Sub-commands: pipeline, step, dependencies, extraction, graph, ontology, performance.
+---
+
+# /alphasemantichub:validate
+
+Validate pipeline and graph quality. Usage: `/alphasemantichub:validate <target> [options]`
+
+`$ARGUMENTS` = target type + optional config or path.
+
+---
+
+## `pipeline [--config '<json>']`
+
+Validate a full pipeline builder configuration.
+
+```python
+from alphasemantichub.pipeline.pipeline_builder import PipelineBuilder
+from alphasemantichub.pipeline.pipeline_validator import PipelineValidator
+
+builder = PipelineBuilder()
+if config_json:
+    import json
+    builder.build_pipeline(json.loads(config_json))
+
+# PipelineBuilder has its own quick validate
+quick = builder.validate_pipeline()  # returns Dict
+
+# PipelineValidator gives full ValidationResult(valid, errors, warnings)
+# Does NOT raise — always returns a result object
+validator = PipelineValidator()
+result = validator.validate(builder)
+
+# Also check inter-step dependencies
+deps = validator.check_dependencies(builder)
+```
+
+Output:
+```
+Pipeline Validation:  VALID ✓  |  INVALID ✗
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Steps:    N registered
+Valid:    M steps
+
+Errors (K):
+  ✗ [step_name] <error message>
+
+Warnings (J):
+  ⚠ [step_name] <warning message>
+
+Dependencies:
+  ✓ All dependencies resolved
+  ✗ Step "<name>" depends on missing step "<dep>"
+
+Result: <valid> — K errors, J warnings
+```
+
+---
+
+## `step <step_name> [--type <type>] [--constraints '<json>']`
+
+Validate a single pipeline step.
+
+```python
+from alphasemantichub.pipeline.pipeline_builder import PipelineBuilder
+from alphasemantichub.pipeline.pipeline_validator import PipelineValidator
+import json
+
+builder = PipelineBuilder()
+step = builder.get_step(step_name)
+
+validator = PipelineValidator()
+result = validator.validate_step(
+    step=step,
+    **json.loads(constraints_json) if constraints_json else {},
+)
+```
+
+Output: same checklist format but scoped to a single step.
+
+---
+
+## `dependencies`
+
+Check all inter-step dependency resolution for the active pipeline.
+
+```python
+from alphasemantichub.pipeline.pipeline_builder import PipelineBuilder
+from alphasemantichub.pipeline.pipeline_validator import PipelineValidator
+
+builder = PipelineBuilder()
+validator = PipelineValidator()
+
+deps = validator.check_dependencies(builder)
+```
+
+Output:
+```
+Dependency Graph:
+  | Step | Depends On | Status |
+  | step_A | — | ✓ |
+  | step_B | step_A | ✓ |
+  | step_C | step_X | ✗ MISSING |
+
+Cycles detected: YES / NO
+Missing steps:   [list]
+```
+
+---
+
+## `extraction <file_path>`
+
+Validate extraction quality for a file — entity confidence, relation density, coverage.
+
+```python
+from alphasemantichub.semantic_extract.extraction_validator import ExtractionValidator
+from alphasemantichub.semantic_extract import (
+    NamedEntityRecognizer,
+    RelationExtractor,
+)
+from alphasemantichub.semantic_extract.cache import extraction_cache
+
+extraction_cache.clear()  # prevent cross-invocation cache pollution
+
+text = open(file_path).read()
+
+ner = NamedEntityRecognizer()
+rel = RelationExtractor()
+entities = ner.extract(text)
+relations = rel.extract(text)
+
+validator = ExtractionValidator()
+issues = validator.validate(entities, relations)
+```
+
+Output:
+```
+Extraction Validation: <file_path>
+  Entities:    N extracted
+  Relations:   M extracted
+  Avg confidence: 0.83
+
+Errors (K):
+  ✗ <issue>
+
+Warnings (J):
+  ⚠ <warning>
+
+Quality score: X/100
+```
+
+---
+
+## `graph`
+
+Check schema conformance, referential integrity, and structural health.
+
+```python
+from alphasemantichub.kg.graph_validator import GraphValidator
+from alphasemantichub.context import ContextGraph
+
+graph = ContextGraph()
+validator = GraphValidator(graph)
+result = validator.validate()
+```
+
+Output:
+```
+Graph Validation:
+  Nodes:         N  |  Edges: M
+  Node types:    K valid, J unknown
+  
+Referential integrity:
+  ✗ Dangling edge: <source> → <missing target>
+
+Schema conformance:
+  ✗ Node "<id>" missing required property "<prop>"
+
+Result: N errors, M warnings
+```
+
+---
+
+## `ontology`
+
+Validate ontology consistency and evaluate competency questions.
+
+```python
+from alphasemantichub.ontology import OntologyValidator
+
+validator = OntologyValidator()
+result = validator.validate()
+cq_results = validator.evaluate_competency_questions()
+```
+
+Output:
+```
+Ontology Validation:
+  Classes:      N
+  Properties:   M
+  Consistent:   YES ✓  |  NO ✗
+
+Competency questions:
+  ✓ "Can we find all instances of X?" — answered
+  ✗ "Is Y a subclass of Z?" — failed: <reason>
+
+Result: N consistency errors, M CQ failures
+```
+
+---
+
+## `performance`
+
+Validate pipeline performance characteristics — bottlenecks, parallelism, and resource use.
+
+```python
+from alphasemantichub.pipeline.pipeline_builder import PipelineBuilder
+from alphasemantichub.pipeline.pipeline_validator import PipelineValidator
+
+builder = PipelineBuilder()
+pipeline = builder.build()
+validator = PipelineValidator()
+
+perf = validator.validate_performance(pipeline)
+```
+
+Output: step-by-step timing estimates, parallelism opportunities, and recommended parallelism level.

package/plugins/skills/visualize/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: visualize
+description: Visualize the Alpha Semantic Hub knowledge graph — topology, centrality, communities, paths, embeddings, decision insights, and temporal evolution. Uses GraphAnalyzer, CentralityCalculator, CommunityDetector, PathFinder, and ContextGraph analytics. Sub-commands: topology, centrality, community, path, decision-graph, insights, temporal, embedding.
+---
+
+# /alphasemantichub:visualize
+
+Render graph visualizations as Mermaid, ASCII, or structured Markdown. Usage: `/alphasemantichub:visualize <sub-command> [args]`
+
+`$ARGUMENTS` = sub-command + optional node label or filter.
+
+---
+
+## `topology [--filter <node_type>]`
+
+Full graph structure analysis — node types, edge distribution, connectivity metrics.
+
+```python
+from alphasemantichub.kg.graph_analyzer import GraphAnalyzer
+from alphasemantichub.context import ContextGraph
+
+graph = ContextGraph(advanced_analytics=True)
+analyzer = GraphAnalyzer()
+
+# Comprehensive analysis
+analysis = analyzer.analyze_graph(graph=graph.to_dict())
+metrics = analyzer.compute_metrics(graph=graph)
+connectivity = analyzer.analyze_connectivity(graph=graph)
+```
+
+Output:
+```
+Graph Topology:
+  Nodes:         N (M types)
+  Edges:         P
+  Density:       0.23
+  Avg degree:    4.7
+  Connected:     YES / NO (K components)
+
+Node type distribution:
+  [Mermaid pie chart]
+  | Type | Count | % | Avg Degree |
+
+Top-10 connected nodes:
+  | Node | Type | Degree | Betweenness |
+```
+
+---
+
+## `centrality [--type degree|betweenness|closeness|eigenvector|pagerank|all] [--top N]`
+
+Calculate and rank nodes by centrality.
+
+```python
+from alphasemantichub.kg.centrality_calculator import CentralityCalculator
+from alphasemantichub.context import ContextGraph
+
+graph = ContextGraph()
+calc = CentralityCalculator()
+
+if centrality_type == "all" or not centrality_type:
+    scores = calc.calculate_all_centrality(graph=graph)
+elif centrality_type == "degree":
+    scores = calc.calculate_degree_centrality(graph=graph)
+elif centrality_type == "betweenness":
+    scores = calc.calculate_betweenness_centrality(graph=graph)
+elif centrality_type == "closeness":
+    scores = calc.calculate_closeness_centrality(graph=graph)
+elif centrality_type == "eigenvector":
+    scores = calc.calculate_eigenvector_centrality(graph=graph)
+elif centrality_type == "pagerank":
+    scores = calc.calculate_pagerank(
+        graph=graph,
+        max_iterations=100,
+        damping_factor=0.85,
+    )
+```
+
+Return: `| Rank | Node | Type | Degree | Betweenness | Closeness | Eigenvector | PageRank |`
+
+For a single node, also call `ContextGraph.get_node_centrality(node_id)` and `get_node_importance(node_id)`.
+
+---
+
+## `community [--algorithm louvain|leiden|label-propagation|overlapping]`
+
+Detect and visualize graph communities/clusters.
+
+```python
+from alphasemantichub.kg.community_detector import CommunityDetector
+from alphasemantichub.context import ContextGraph
+
+graph = ContextGraph()
+detector = CommunityDetector()
+
+algorithm = algo_arg or "louvain"
+
+if algorithm == "louvain":
+    result = detector.detect_communities_louvain(graph, resolution=1.0)
+elif algorithm == "leiden":
+    result = detector.detect_communities_leiden(graph, resolution=1.0)
+elif algorithm == "label-propagation":
+    result = detector.detect_communities_label_propagation(graph)
+elif algorithm == "overlapping":
+    result = detector.detect_overlapping_communities(graph)
+else:
+    result = detector.detect_communities(graph, algorithm=algorithm)
+
+structure = detector.analyze_community_structure(graph, result)
+metrics = detector.calculate_community_metrics(graph, result)
+```
+
+Output:
+```
+Community Detection (algorithm: louvain)
+  Communities: N
+  Modularity:  0.71
+
+Community summary:
+  | ID | Size | Top Node | Internal Density | Bridge Nodes |
+
+[Mermaid graph TD — nodes colored/grouped by community ID]
+```
+
+---
+
+## `path <n1> <n2> [--k N] [--algorithm bfs|dijkstra|astar|k-shortest]`
+
+Find and visualize paths between two nodes.
+
+```python
+from alphasemantichub.kg.path_finder import PathFinder
+from alphasemantichub.context import ContextGraph
+
+graph = ContextGraph()
+finder = PathFinder()
+
+k = int(k_arg) if k_arg else 3
+
+if algorithm == "bfs":
+    path = finder.bfs_shortest_path(graph, source=n1, target=n2)
+    paths = [path]
+elif algorithm == "dijkstra":
+    path = finder.dijkstra_shortest_path(graph, source=n1, target=n2)
+    paths = [path]
+else:  # default: k-shortest
+    paths = finder.find_k_shortest_paths(graph, source=n1, target=n2, k=k)
+
+lengths = [finder.path_length(graph, p) for p in paths]
+```
+
+Output as Mermaid `sequenceDiagram` for each path:
+```
+Path 1 (length: 2.3):
+  n1 →[rel_type]→ Middle →[rel_type]→ n2
+
+Path 2 (length: 3.7): ...
+```
+
+---
+
+## `decision-graph [--category <cat>] [--depth N]`
+
+Visualize the decision influence graph for a category or all decisions.
+
+```python
+from alphasemantichub.context import ContextGraph
+from alphasemantichub.context.causal_analyzer import CausalChainAnalyzer
+from alphasemantichub.context import AgentContext
+
+ctx = AgentContext(decision_tracking=True, advanced_analytics=True)
+graph = ContextGraph(advanced_analytics=True)
+
+# Get decision insights
+insights = graph.get_decision_insights()
+
+# Build causal network
+analyzer = CausalChainAnalyzer(graph_store=ctx.graph_store)
+network = analyzer.analyze_causal_network()
+```
+
+Output as Mermaid `graph TD` with:
+- Node size proportional to causal impact score
+- Color by outcome (green=approved, red=rejected, yellow=deferred)
+- Edge labels showing relationship type
+
+---
+
+## `insights`
+
+Comprehensive decision analytics dashboard.
+
+```python
+from alphasemantichub.context import ContextGraph, AgentContext
+
+ctx = AgentContext(decision_tracking=True, advanced_analytics=True, kg_algorithms=True)
+graph = ContextGraph(advanced_analytics=True, centrality_analysis=True)
+
+insights = graph.get_decision_insights()
+summary = graph.get_decision_summary()
+graph_summary = graph.get_graph_summary()
+context_insights = ctx.get_context_insights()
+```
+
+Output a full analytics dashboard:
+```
+Decision Intelligence Dashboard
+════════════════════════════════
+Decisions:         N total (M active)
+Categories:        K unique
+Avg confidence:    0.87
+Outcome split:     approved 55% | rejected 30% | deferred 15%
+Causal chains:     P chains, longest: Q hops
+Loops detected:    R circular dependencies
+
+Graph health:
+  Nodes:           N  |  Edges: M  |  Density: 0.23
+  Communities:     K  |  Isolated nodes: J
+
+[Mermaid pie — outcome distribution]
+[Mermaid bar — decisions by category]
+```
+
+---
+
+## `temporal [--node <id>] [--start <date>] [--end <date>]`
+
+Analyze how the graph evolved over time.
+
+```python
+from alphasemantichub.kg.graph_analyzer import GraphAnalyzer
+from alphasemantichub.context import ContextGraph
+
+graph = ContextGraph()
+analyzer = GraphAnalyzer()
+
+evolution = analyzer.analyze_temporal_evolution(
+    graph=graph,
+    start_time=start_date or None,
+    end_time=end_date or None,
+    metrics=["node_count", "edge_count", "density", "communities"],
+)
+
+# For a specific node, use ContextGraph.state_at()
+if node_id:
+    snapshot = graph.state_at(timestamp=end_date or "now")
+```
+
+Output as Markdown timeline with metrics per interval.