Graph-Native Infrastructure for Context and Accountable AI Systems
Python agent-memoryaiai-governanceai-infrastructureartificial-intelligencecontext-engineeringcontext-graphsdata-engineeringdecision-intelligencedeveloper-toolsexplainable-aigenerative-aigraph-ragknowledge-graphllmontologyprovenancepythonreasoningsemantic-search
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.mdindex 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 ChangeTrackerfrom 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.mdindex 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:ontologyManage 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.mdindex 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.mdindex 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.mdindex 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]"`.