Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

fix(plugins): rewrite five skills against the real v0.7.0 API

gyrocbd33fba67f3
diff --git a/plugins/skills/change/SKILL.md b/plugins/skills/change/SKILL.md
index 8791654f..5c2cdbec 100644
--- a/plugins/skills/change/SKILL.md
+++ b/plugins/skills/change/SKILL.md
@@ -1,38 +1,73 @@
---
name: change
-description: Track and inspect graph changes, diffs, temporal updates, and the impact of new data on Semantica knowledge graphs.
+description: Inspect graph changes over time and ontology version diffs in Semantica. Uses ContextGraph.state_at for point-in-time graph state and change_management.VersionManager for ontology versioning.
---
# /semantica:change
-Inspect changes over time and evaluate updates. Usage: `/semantica:change <task> [args]`
+Track what changed. Usage: `/semantica:change <task> [args]`
-`$ARGUMENTS` = task + optional node, time window, or filter.
+> 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` |
---
-## `diff [--from <ts>] [--to <ts>] [--node <id>]`
-
-Compute graph diffs between two snapshots.
+## `graph-at <timestamp>` — point-in-time graph state
```python
-from semantica.provenance.change_tracker import ChangeTracker
from semantica.context import ContextGraph
-tracker = ChangeTracker()
-diff = tracker.compute_diff(from_ts=from_ts, to_ts=to_ts, node_id=node_id)
+graph = ContextGraph()
+graph.load_from_file("~/.semantica/kg.json")
+
+snapshot = graph.state_at("2026-06-01") # str | int | float | datetime
+```
+
+Diff two moments by taking two snapshots and comparing node/edge sets:
+
+```python
+before = graph.state_at("2026-06-01")
+after = graph.state_at("2026-09-01")
+added = set(after["nodes"]) - set(before["nodes"])
```
-Output: added/removed nodes and edges, attribute changes, and impact summary.
+For richer temporal work (scrubbing, evolution, temporal patterns) use
+`/semantica:temporal`, which wraps the same layer.
---
-## `history <node_id> [--limit N]`
+## `node-history <node_id>` — who touched this node
-Show the change history for a node or relationship.
+Node-level history is provenance, not change management:
```python
-history = tracker.get_node_history(node_id=node_id, limit=limit)
+from semantica.provenance import ProvenanceManager
+
+pm = ProvenanceManager(storage_path="~/.semantica/prov.db")
+history = pm.revision_history(node_id)
+log = pm.audit_log(since="2026-01-01")
+```
+
+---
+
+## `versions` / `diff <v1> <v2>` — ontology versioning
+
+```python
+from semantica.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)
```
-Return: revisions, timestamps, authors, and summary comments.
+`TemporalVersionManager` and `OntologyVersionManager` are also exported for
+time-scoped and ontology-specific variants.
diff --git a/plugins/skills/ontology/SKILL.md b/plugins/skills/ontology/SKILL.md
index 4702d137..991aed4d 100644
--- a/plugins/skills/ontology/SKILL.md
+++ b/plugins/skills/ontology/SKILL.md
@@ -1,37 +1,86 @@
---
name: ontology
-description: Manage ontology schemas, concepts, relationships, and alignments for Semantica knowledge graphs.
+description: Manage ontology schemas, concepts, alignments, and SHACL/OWL validation for Semantica knowledge graphs. Uses OntologyEngine and OntologyValidator.
---
# /semantica:ontology
Manage ontology definitions and validation. Usage: `/semantica:ontology <task> [args]`
-`$ARGUMENTS` = task + optional ontology item or schema file.
+> Entry points: `OntologyEngine` (authoring, export, alignments) and
+> `OntologyValidator` (consistency checking).
---
-## `describe <concept>`
+## `concepts <scheme_uri>`
-Show ontology concept details.
+List SKOS concepts in a vocabulary scheme.
```python
-from semantica.ontology import OntologyManager
+from semantica.ontology import OntologyEngine
-manager = OntologyManager()
-concept = manager.get_concept(concept_name)
+engine = OntologyEngine()
+concepts = engine.list_concepts(scheme_uri)
+vocabs = engine.list_vocabularies()
```
-Output: properties, relationships, inherited types, and examples.
+---
+
+## `validate <ontology>`
+
+Check an ontology for consistency and satisfiability.
+
+```python
+from semantica.ontology import OntologyValidator
+
+validator = OntologyValidator(check_consistency=True, check_satisfiability=True)
+result = validator.validate(ontology) # dict or path to an ontology file
+# result.is_valid, result.errors, result.warnings
+```
+
+For SHACL shape validation of instance data use `SHACLGenerator` / `SHACLValidationReport`:
+
+```python
+from semantica.ontology import SHACLGenerator
+```
---
-## `validate [--schema <file>]`
+## `build <text|data>`
-Validate the graph or schema against the ontology.
+Generate an ontology from unstructured text or structured records.
```python
-result = manager.validate_graph(graph=graph, schema_file=schema_file)
+engine = OntologyEngine()
+onto = engine.from_text(text) # LLM-assisted (needs an llm-* extra + API key)
+onto = engine.from_data(records) # deterministic, from structured data
```
-Return: validation status, errors, and correction suggestions.
+---
+
+## `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)
+```
diff --git a/plugins/skills/policy/SKILL.md b/plugins/skills/policy/SKILL.md
index 2c564370..8ccf7f5c 100644
--- a/plugins/skills/policy/SKILL.md
+++ b/plugins/skills/policy/SKILL.md
@@ -1,37 +1,66 @@
---
name: policy
-description: Define and enforce policies, access controls, and compliance rules over Semantica knowledge graphs.
+description: Define and enforce decision policies, compliance rules, and exceptions over Semantica graphs. Uses ContextGraph.check_decision_rules/enforce_decision_policy and context.PolicyEngine.
---
# /semantica:policy
-Apply policy rules and checks. Usage: `/semantica:policy <task> [args]`
+Policy governance over recorded decisions. Usage: `/semantica:policy <task> [args]`
-`$ARGUMENTS` = task + optional policy name, rule set, or target entity.
+> `PolicyEngine` lives in `semantica.context`. For most cases the two policy
+> methods on `ContextGraph` itself are enough.
---
-## `check [--rule <name>] [--target <id>]`
+## `check <decision>` — the simple path
-Run policy checks against the graph.
+No policy store needed; rules default to a built-in policy set.
```python
-from semantica.policy import PolicyEngine
+from semantica.context import ContextGraph
-engine = PolicyEngine()
-result = engine.check(rule_name=rule_name, target=target)
+graph = ContextGraph()
+result = graph.check_decision_rules({
+ "category": "vendor_selection",
+ "outcome": "approved",
+ "confidence": 0.93,
+ "decision_maker": "gyro",
+})
+# {'compliant': bool, 'violations': [...], 'warnings': [...], 'policy_rules': {...}}
```
-Output: compliance status, failing rules, and remediation guidance.
+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)
+```
---
-## `list`
+## Managed policies — the full path
-List available policy rules and categories.
+`PolicyEngine` requires a graph store and versioned `Policy` objects.
```python
-rules = engine.list_rules()
+from semantica.context import PolicyEngine
+from semantica.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)
```
-Return: rule name, description, severity, and category.
+Note `check_compliance` takes a `Decision` object, not a dict — fetch it from the
+graph rather than constructing one by hand.
diff --git a/plugins/skills/provenance/SKILL.md b/plugins/skills/provenance/SKILL.md
index dabdd1a0..c4e89ab2 100644
--- a/plugins/skills/provenance/SKILL.md
+++ b/plugins/skills/provenance/SKILL.md
@@ -1,37 +1,67 @@
---
name: provenance
-description: Trace data lineage, source attribution, audit trails, and provenance assertions in Semantica graphs.
+description: Trace data lineage, source attribution, audit trails, and W3C PROV-O export in Semantica graphs. Uses ProvenanceManager.
---
# /semantica:provenance
-Inspect provenance metadata. Usage: `/semantica:provenance <task> [args]`
-
-`$ARGUMENTS` = task + optional node, edge, or time range.
+Lineage and audit trails. Usage: `/semantica:provenance <task> [args]`
---
-## `trace <node_id> [--depth N]`
+## `lineage <entity_id> [--depth N]`
+
+```python
+from semantica.provenance import ProvenanceManager
+
+pm = ProvenanceManager(storage_path="~/.semantica/prov.db") # 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
+```
-Trace the provenance of a node or fact.
+---
+
+## `sources <entity_id>`
```python
-from semantica.provenance import ProvenanceTracer
+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]`
-tracer = ProvenanceTracer()
-trace = tracer.trace_node(node_id=node_id, depth=depth)
+```python
+log = pm.audit_log(since="2026-01-01", format="table")
+between = pm.query_recorded_between(start, end)
+stats = pm.get_statistics()
```
-Output: source chain, authors, timestamps, and validation status.
+---
+
+## `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/")
+```
---
-## `audit [--since <ts>] [--actor <id>]`
+## `invalidate <entity_id> <agent_id> [--reason ...]`
-View audit logs for graph changes.
+Mark an entity superseded without deleting history.
```python
-audit_log = tracer.get_audit_log(since=since, actor=actor)
+pm.invalidate(entity_id, agent_id, reason="source retracted")
```
-Return: change events, actor, affected objects, and action details.
+## `check [--strict]`
+
+```python
+report = pm.check(strict=False) # integrity check over the provenance store
+```
diff --git a/plugins/skills/query/SKILL.md b/plugins/skills/query/SKILL.md
index 7b3ed407..7ec2fabc 100644
--- a/plugins/skills/query/SKILL.md
+++ b/plugins/skills/query/SKILL.md
@@ -1,49 +1,78 @@
---
name: query
-description: Query the Semantica knowledge graph using SPARQL, Cypher, keyword search, and structured graph query patterns.
+description: Query Semantica knowledge graphs — in-memory ContextGraph search, SPARQL over RDF triple stores, and Cypher over LPG backends.
---
# /semantica:query
-Run graph queries and search. Usage: `/semantica:query <mode> [args]`
+Query the graph. Usage: `/semantica:query <task> [args]`
-`$ARGUMENTS` = query mode + query string or filter.
+> Which API you want depends on where the graph lives.
---
-## `sparql <query>`
+## `search "<keywords>"` — the in-memory ContextGraph
-Execute a SPARQL query against the graph.
+This is the one that works with no external server.
```python
-from semantica.query import QueryEngine
+from semantica.context import ContextGraph
-engine = QueryEngine()
-results = engine.query_sparql(query)
+graph = ContextGraph()
+graph.load_from_file("~/.semantica/kg.json")
+
+results = graph.query("vendor selection", skip=0, limit=20)
```
-Return: query bindings as a Markdown table.
+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 `/semantica:decision`.
---
-## `cypher <query>`
+## `sparql "<query>"` — RDF triple stores
-Execute a Cypher-like query.
+```python
+from semantica.triplet_store import TripletStore
+
+store = TripletStore(backend="oxigraph") # embedded; needs semantica[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
-results = engine.query_cypher(query)
+from semantica.triplet_store import QueryEngine
+
+qe = QueryEngine()
+plan = qe.plan_query(sparql)
+tuned = qe.optimize_query(sparql)
+result = qe.execute_query(sparql, store_backend=store)
+stats = qe.get_query_statistics()
```
-Output: node/relationship results and path summaries.
+Blazegraph / Jena / RDF4J need **no** extra — `semantica.triplet_store` speaks
+SPARQL over HTTP using the core `requests` dependency.
---
-## `search <keywords> [--filter <type>]`
-
-Search graph entities by keyword.
+## `cypher "<query>"` — labeled property graphs
```python
-results = engine.search(keywords=keywords, filter_type=filter_type)
+from semantica.graph_store import Neo4jStore # needs semantica[graph-neo4j]
+
+store = Neo4jStore(uri=..., user=..., password=...)
```
-Return: ranked matches with entity types and relevance scores.
+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 "semantica[graph-neo4j]"`.