@ltm-blueverse/alpha-semantic-hub 0.7.0

package/plugins/skills/export/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: export
+description: Export Alpha Semantic Hub graphs, results, and provenance to JSON, RDF, Parquet, CSV, GraphML, and other formats.
+---
+
+# /alphasemantichub:export
+
+Export knowledge graph data. Usage: `/alphasemantichub:export <format> [args]`
+
+`$ARGUMENTS` = format + optional target or destination.
+
+---
+
+## `json [--output <path>] [--filter <query>]`
+
+Export graph data as JSON.
+
+```python
+from alphasemantichub.export.methods import export_json
+
+export_json(data=graph_data, file_path=output, format='json')
+```
+
+Output: JSON file or inline JSON payload.
+
+---
+
+## `rdf [--format turtle|rdfxml|jsonld|ntriples|n3] [--output <path>]`
+
+Export the graph in RDF serialization.
+
+```python
+from alphasemantichub.export.methods import export_rdf
+
+export_rdf(data=graph_data, file_path=output, format='turtle')
+```
+
+Return: RDF text or file path.
+
+---
+
+## `parquet [--output <path>]`
+
+Export nodes and edges to Parquet for analytics.
+
+```python
+from alphasemantichub.export.methods import export_parquet
+
+export_parquet(data=graph_data, file_path=output, compression='snappy')
+```
+
+Output: Parquet dataset ready for downstream processing.
+
+---
+
+## `graphml|gexf|dot [--output <path>]`
+
+Export the graph to a supported graph format.
+
+```python
+from alphasemantichub.export import GraphExporter
+
+exporter = GraphExporter(format='graphml', include_attributes=True)
+exporter.export(graph_data, output)
+```
+
+Output: Graph format file suitable for visualization tools.

package/plugins/skills/extract/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: extract
+description: Run the full Alpha Semantic Hub semantic extraction pipeline on a file or selected text — NER, relations, events, coreference resolution, triplets, and validation. Clears result cache before each run. Returns Markdown tables with entity/relation/event/triplet results and inline validator warnings.
+---
+
+# /alphasemantichub:extract
+
+Run the full extraction pipeline. Usage: `/alphasemantichub:extract [file_path | "inline text"]`
+
+`$ARGUMENTS` = file path, inline text in quotes, or blank (uses active editor file).
+
+---
+
+## Steps
+
+**1. Resolve the source.**
+- If `$ARGUMENTS` is a readable file path → `text = open(path).read()`
+- If it's quoted inline text → use directly
+- If blank → use the active editor file
+
+**2. Clear the result cache** to prevent cross-invocation pollution:
+
+```python
+from alphasemantichub.semantic_extract.cache import extraction_cache
+extraction_cache.clear()
+```
+
+**3. Run the full pipeline:**
+
+```python
+from alphasemantichub.semantic_extract import (
+    NamedEntityRecognizer,
+    RelationExtractor,
+    EventDetector,
+    CoreferenceResolver,
+    TripletExtractor,
+    ExtractionValidator,
+)
+
+# Named Entity Recognition
+ner = NamedEntityRecognizer()
+entities = ner.extract(text)
+
+# Relation Extraction
+rel = RelationExtractor()
+relations = rel.extract(text)
+
+# Event Detection
+evt = EventDetector()
+events = evt.extract(text)
+
+# Coreference Resolution — resolve pronouns/aliases before extraction
+coref = CoreferenceResolver()
+resolved_text = coref.resolve(text)
+
+# Triplet Extraction (subject–predicate–object)
+triplet = TripletExtractor()
+triplets = triplet.extract(resolved_text)
+
+# Validate quality
+validator = ExtractionValidator()
+issues = validator.validate(entities, relations)
+```
+
+**4. Report validator warnings** above results:
+```
+⚠ ExtractionValidator: <warning message>
+```
+
+**5. Return results as Markdown tables:**
+
+**Entities** (N total)
+| Label | Type | Confidence | Span |
+|-------|------|------------|------|
+
+**Relations** (M total)
+| Source | Relation Type | Target | Confidence |
+|--------|---------------|--------|------------|
+
+**Events** (K total)
+| Label | Type | Participants | Confidence |
+|-------|------|--------------|------------|
+
+**Triplets** (J total)
+| Subject | Predicate | Object | Confidence |
+|---------|-----------|--------|------------|
+
+**6. Summary line:**
+```
+Extracted: N entities, M relations, K events, J triplets — from <source>
+```
+
+For large files (>50KB), process in chunks and show a progress indicator. Highlight any entities appearing in the context graph already (`ContextGraph.has_node(label)`) with `[in graph]` tag.

package/plugins/skills/ingest/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: ingest
+description: Ingest data from files, databases, APIs, or streams into Alpha Semantic Hub knowledge graphs with schema mapping and entity linking.
+---
+
+# /alphasemantichub:ingest
+
+Ingest new data into the knowledge graph. Usage: `/alphasemantichub:ingest <source> [args]`
+
+`$ARGUMENTS` = source type + optional file path, connection string, or dataset identifier.
+
+---
+
+## `file <path> [--format json|csv|yaml|xml]`
+
+Ingest structured data from a local file.
+
+```python
+from alphasemantichub.ingest import ingest_file
+
+data = ingest_file(file_path=path, method='file', file_format=file_format)
+```
+
+Output: imported node/edge count and ingestion summary.
+
+---
+
+## `db <connection> [--query <sql>]`
+
+Ingest data from a database source.
+
+```python
+from alphasemantichub.ingest import ingest_database
+
+result = ingest_database(connection_string=conn, query=query)
+```
+
+Return: rows ingested, mapped entities, and warnings.

package/plugins/skills/ontology/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: ontology
+description: Manage ontology schemas, concepts, alignments, and SHACL/OWL validation for Alpha Semantic Hub knowledge graphs. Uses OntologyEngine and OntologyValidator.
+---
+
+# /alphasemantichub:ontology
+
+Manage ontology definitions and validation. Usage: `/alphasemantichub:ontology <task> [args]`
+
+> Entry points: `OntologyEngine` (authoring, export, alignments) and
+> `OntologyValidator` (consistency checking).
+
+---
+
+## `concepts <scheme_uri>`
+
+List SKOS concepts in a vocabulary scheme.
+
+```python
+from alphasemantichub.ontology import OntologyEngine
+from alphasemantichub.triplet_store import TripletStore
+
+store = TripletStore(backend="oxigraph")   # needs alphasemantichub[tripletstore-oxigraph]
+engine = OntologyEngine(store=store)       # list_concepts/list_vocabularies need a
+                                            # configured store — raises ProcessingError without one
+concepts = engine.list_concepts(scheme_uri)
+vocabs = engine.list_vocabularies()
+```
+
+---
+
+## `validate <ontology>`
+
+Check an ontology for consistency and satisfiability.
+
+```python
+from alphasemantichub.ontology import OntologyValidator
+
+validator = OntologyValidator(check_consistency=True, check_satisfiability=True)
+result = validator.validate(ontology)   # dict or path to an ontology file
+# result.valid, result.errors, result.warnings
+```
+
+For SHACL shape validation of instance data use `SHACLGenerator` / `SHACLValidationReport`:
+
+```python
+from alphasemantichub.ontology import SHACLGenerator
+```
+
+---
+
+## `build <text|data>`
+
+Generate an ontology from unstructured text or structured records.
+
+```python
+engine = OntologyEngine()
+onto = engine.from_text(text)          # LLM-assisted (needs an llm-* extra + API key)
+onto = engine.from_data(records)       # deterministic, from structured data
+```
+
+---
+
+## `export <ontology> <path> [--format turtle]`
+
+```python
+engine.export_owl(onto, path, format="turtle")
+engine.export_shacl(onto, path, format="turtle")
+```
+
+---
+
+## `align <source_uri> <target_uri> <predicate>`
+
+```python
+engine.create_alignment(source_uri, target_uri, predicate)
+engine.get_alignments(entity_uri)
+engine.list_alignments()
+```
+
+---
+
+## `evaluate <ontology>`
+
+Quality-gate an ontology (`OntologyEvaluator` / `OntologyQualityReport` under the hood).
+
+```python
+report = engine.evaluate(onto)
+```

package/plugins/skills/policy/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: policy
+description: Define and enforce decision policies, compliance rules, and exceptions over Alpha Semantic Hub graphs. Uses ContextGraph.check_decision_rules/enforce_decision_policy and context.PolicyEngine.
+---
+
+# /alphasemantichub:policy
+
+Policy governance over recorded decisions. Usage: `/alphasemantichub:policy <task> [args]`
+
+> `PolicyEngine` lives in `alphasemantichub.context`. For most cases the two policy
+> methods on `ContextGraph` itself are enough.
+
+---
+
+## `check <decision>` — the simple path
+
+No policy store needed; rules default to a built-in policy set.
+
+```python
+from alphasemantichub.context import ContextGraph
+
+graph = ContextGraph()
+result = graph.check_decision_rules({
+    "category": "vendor_selection",
+    "outcome": "approved",
+    "confidence": 0.93,
+    "decision_maker": "gyro",
+})
+# {'compliant': bool, 'violations': [...], 'warnings': [...], 'policy_rules': {...}}
+```
+
+Default rules: `min_confidence=0.7`, `required_outcomes=['approved','rejected','flagged']`,
+`required_metadata=['decision_maker']`, `max_reasoning_length=1000`. Override by
+passing your own `rules=` dict.
+
+## `enforce <decision> [--rules <dict>]`
+
+```python
+verdict = graph.enforce_decision_policy(decision_data, policy_rules=None)
+```
+
+---
+
+## Managed policies — the full path
+
+`PolicyEngine` requires a graph store and versioned `Policy` objects.
+
+```python
+from alphasemantichub.context import PolicyEngine
+from alphasemantichub.context.decision_models import Policy
+
+engine = PolicyEngine(graph_store)
+
+policy_id = engine.add_policy(Policy(...))
+policies  = engine.get_applicable_policies(category="vendor_selection", entities=[...])
+ok        = engine.check_compliance(decision, policy_id)
+history   = engine.get_policy_history(policy_id)
+
+engine.update_policy(policy_id, rules={...}, change_reason="tightened threshold")
+engine.record_exception(decision_id, policy_id, reason="...", approver="...")
+impact    = engine.analyze_policy_impact(policy_id, proposed_rules={...})
+affected  = engine.get_affected_decisions(policy_id, from_version, to_version)
+```
+
+Note `check_compliance` takes a `Decision` object, not a dict — fetch it from the
+graph rather than constructing one by hand.

package/plugins/skills/provenance/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: provenance
+description: Trace data lineage, source attribution, audit trails, and W3C PROV-O export in Alpha Semantic Hub graphs. Uses ProvenanceManager.
+---
+
+# /alphasemantichub:provenance
+
+Lineage and audit trails. Usage: `/alphasemantichub:provenance <task> [args]`
+
+---
+
+## `lineage <entity_id> [--depth N]`
+
+```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)   # SQLite, or omit for in-memory
+chain = pm.lineage(entity_id, depth=3)
+full  = pm.get_lineage(entity_id)          # complete ancestry
+down  = pm.get_descendants(entity_id)      # what this entity influenced
+```
+
+---
+
+## `sources <entity_id>`
+
+```python
+srcs = pm.get_all_sources(entity_id)       # every source that contributed
+prov = pm.get_provenance(entity_id)        # the raw PROV entry
+hist = pm.revision_history(entity_id)
+```
+
+---
+
+## `audit [--since <iso-date>] [--format table|json]`
+
+```python
+log = pm.audit_log(since="2026-01-01", format="table")
+between = pm.query_recorded_between(start, end)
+stats = pm.get_statistics()
+```
+
+---
+
+## `export [--format turtle|json-ld|xml]`
+
+W3C PROV-O export — this is the regulator-facing artifact.
+
+```python
+rdf = pm.export_prov(format="turtle", base_uri="https://example.org/prov/")
+```
+
+---
+
+## `invalidate <entity_id> <agent_id> [--reason ...]`
+
+Mark an entity superseded without deleting history.
+
+```python
+pm.invalidate(entity_id, agent_id, reason="source retracted")
+```
+
+## `check [--strict]`
+
+```python
+report = pm.check(strict=False)   # integrity check over the provenance store
+```

package/plugins/skills/query/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: query
+description: Query Alpha Semantic Hub knowledge graphs — in-memory ContextGraph search, SPARQL over RDF triple stores, and Cypher over LPG backends.
+---
+
+# /alphasemantichub:query
+
+Query the graph. Usage: `/alphasemantichub:query <task> [args]`
+
+> Which API you want depends on where the graph lives.
+
+---
+
+## `search "<keywords>"` — the in-memory ContextGraph
+
+This is the one that works with no external server.
+
+```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 ~
+
+results = graph.query("vendor selection", skip=0, limit=20)
+```
+
+Related lookups on the same object:
+
+```python
+graph.find_nodes(...)          graph.find_node(...)
+graph.find_related_nodes(...)  graph.get_neighbors(node_id)
+graph.find_similar_nodes(...)  graph.get_nodes_by_label(label)
+```
+
+Decision-specific queries belong to `/alphasemantichub:decision`.
+
+---
+
+## `sparql "<query>"` — RDF triple stores
+
+```python
+from alphasemantichub.triplet_store import TripletStore
+
+store = TripletStore(backend="oxigraph")       # embedded; needs alphasemantichub[tripletstore-oxigraph]
+# or backend="blazegraph" | "jena" | "rdf4j" with endpoint="http://..."
+result = store.execute_query(sparql)
+```
+
+For query planning, optimisation, and caching over a backend:
+
+```python
+from alphasemantichub.triplet_store import QueryEngine, OxigraphStore
+
+# QueryEngine needs an object exposing execute_sparql() — the raw backend,
+# not the TripletStore wrapper above (which only exposes execute_query()).
+backend = OxigraphStore()
+
+qe = QueryEngine()
+plan   = qe.plan_query(sparql)
+tuned  = qe.optimize_query(sparql)
+result = qe.execute_query(sparql, store_backend=backend)
+stats  = qe.get_query_statistics()
+```
+
+Blazegraph / Jena / RDF4J need **no** extra — `alphasemantichub.triplet_store` speaks
+SPARQL over HTTP using the core `requests` dependency.
+
+---
+
+## `cypher "<query>"` — labeled property graphs
+
+```python
+from alphasemantichub.graph_store import Neo4jStore    # needs alphasemantichub[graph-neo4j]
+
+store = Neo4jStore(uri=..., user=..., password=...)
+result = store.execute_query(query, parameters={...})
+```
+
+Also available: `FalkorDBStore`, `ApacheAgeStore`, `AmazonNeptuneStore`,
+and `GraphManager` / `GraphStore` for backend-agnostic access.
+
+**Not installed in this environment** — add the backend extra first, e.g.
+`pip install "alphasemantichub[graph-neo4j]"`.

package/plugins/skills/reason/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: reason
+description: Run reasoning over the Alpha Semantic Hub knowledge graph — deductive logic, abductive hypothesis generation, Datalog programs, SPARQL queries, Rete network evaluation. Uses DeductiveReasoner, AbductiveReasoner, DatalogReasoner, SPARQLReasoner, ReteEngine. Sub-commands: deductive, abductive, datalog, sparql, rete, prove, hypotheses.
+---
+
+# /alphasemantichub:reason
+
+Apply reasoning over the knowledge graph. Usage: `/alphasemantichub:reason <mode> [args]`
+
+`$ARGUMENTS` = reasoning mode + rules/observations/query.
+
+---
+
+## `deductive [--facts '<json-list>'] [--rules '<rule1>|<rule2>']`
+
+Apply deductive rules to known facts to derive new conclusions.
+
+```python
+from alphasemantichub.reasoning.deductive_reasoner import DeductiveReasoner, Premise
+
+reasoner = DeductiveReasoner()
+
+# Add base facts to working memory
+# Facts can be strings like "Person(John)" or structured dicts
+import json
+facts = json.loads(facts_json) if facts_json else []
+reasoner.add_facts(facts)
+
+# Apply logic with explicit premises
+# Premise objects have: statement, confidence, source
+premises = [
+    Premise(statement=fact, confidence=1.0)
+    for fact in facts
+]
+
+conclusions = reasoner.apply_logic(premises=premises)
+```
+
+Return: `| Conclusion | Triggering Premises | Confidence | Rule Applied |`
+
+If zero rules given, run `reasoner.prove_theorem()` on any provided theorem:
+```python
+proof = reasoner.prove_theorem(theorem=theorem_text)
+```
+
+Output: `Proof: <proof.steps>  |  Valid: YES / NO`
+
+---
+
+## `prove <theorem> [--facts '<json-list>']`
+
+Prove or disprove a theorem against known facts.
+
+```python
+from alphasemantichub.reasoning.deductive_reasoner import DeductiveReasoner
+
+reasoner = DeductiveReasoner()
+import json
+reasoner.add_facts(json.loads(facts_json) if facts_json else [])
+
+proof = reasoner.prove_theorem(theorem=theorem)
+```
+
+Output:
+```
+Theorem: "<theorem>"
+Result:  PROVED ✓  |  DISPROVED ✗  |  UNDECIDABLE ⚠
+
+Proof steps:
+  1. <premise> — <justification>
+  2. ...
+  → QED: <theorem>
+
+Confidence: <proof.confidence>
+```
+
+---
+
+## `abductive <observation> [--knowledge '<json-list>'] [--top N]`
+
+Generate and rank hypotheses that explain an observation.
+
+```python
+from alphasemantichub.reasoning.abductive_reasoner import (
+    AbductiveReasoner, Observation
+)
+
+reasoner = AbductiveReasoner()
+
+import json
+if knowledge_json:
+    reasoner.add_knowledge(json.loads(knowledge_json))
+
+obs = Observation(description=observation)
+
+# Generate all hypotheses then rank them
+hypotheses = reasoner.generate_hypotheses(observations=[obs])
+ranked = reasoner.rank_hypotheses(hypotheses)
+best = reasoner.get_best_explanation(obs)
+
+# Also get full explanations with evidence
+explanations = reasoner.find_explanations(observations=[obs])
+```
+
+Output:
+```
+Abductive Reasoning for: "<observation>"
+
+Best explanation:
+  <best.description>  (confidence: 0.87)
+
+All hypotheses (ranked):
+  | Rank | Hypothesis | Confidence | Supporting Evidence |
+  |  1   | <hyp>      | 0.87       | <evidence>         |
+  |  2   | ...
+
+Full explanations:
+  Explanation 1: <explanation.summary>
+    Evidence: <evidence items>
+```
+
+---
+
+## `datalog <program>`
+
+Evaluate a Datalog program over graph facts.
+
+```python
+from alphasemantichub.reasoning.datalog_reasoner import DatalogReasoner
+from alphasemantichub.context import ContextGraph
+
+graph = ContextGraph()
+reasoner = DatalogReasoner()
+
+# program is a string of Datalog rules and queries
+results = reasoner.evaluate(program=program, graph=graph)
+```
+
+Return derived tuples as a relation table. Show rule derivation counts.
+
+---
+
+## `sparql <query>`
+
+Run a SPARQL query over the knowledge graph and return results.
+
+```python
+from alphasemantichub.reasoning.sparql_reasoner import SPARQLReasoner
+from alphasemantichub.context import ContextGraph
+
+graph = ContextGraph()
+reasoner = SPARQLReasoner()
+
+results = reasoner.query(sparql_query=query, graph=graph)
+```
+
+Return as a Markdown table with bound variable columns matching the SELECT clause.
+
+---
+
+## `rete [--rules '<rule1>|<rule2>'] [--facts '<json-list>']`
+
+Incremental rule evaluation using the Rete network with working memory.
+
+```python
+from alphasemantichub.reasoning.rete_engine import ReteEngine
+import json
+
+engine = ReteEngine()
+
+rules = rules_str.split("|") if rules_str else []
+facts = json.loads(facts_json) if facts_json else []
+
+engine.load_rules(rules)
+engine.process_facts(facts)
+activations = engine.get_activations()
+```
+
+Return: `| Rule Fired | Variable Bindings | Working Memory Delta | Activation Order |`
+
+---
+
+## `hypotheses "<scenario>" [--knowledge '<json-list>'] [--top N]`
+
+Generate the top-N most probable explanations for a complex scenario.
+
+```python
+from alphasemantichub.reasoning.abductive_reasoner import AbductiveReasoner, Observation
+import json
+
+reasoner = AbductiveReasoner()
+if knowledge_json:
+    reasoner.add_knowledge(json.loads(knowledge_json))
+
+obs = Observation(description=scenario)
+hypotheses = reasoner.generate_hypotheses(observations=[obs])
+ranked = reasoner.rank_hypotheses(hypotheses)
+top_n = ranked[:int(n) if n else 5]
+```
+
+For each hypothesis also show: what evidence supports it, what would falsify it, and which is the most parsimonious (fewest assumptions).