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 [args]` +Track what changed. Usage: `/semantica:change [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 ] [--to ] [--node ]` - -Compute graph diffs between two snapshots. +## `graph-at ` — 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 ``` -Output: added/removed nodes and edges, attribute changes, and impact summary. +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"]) +``` + +For richer temporal work (scrubbing, evolution, temporal patterns) use +`/semantica:temporal`, which wraps the same layer. --- -## `history [--limit N]` +## `node-history ` — 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") ``` -Return: revisions, timestamps, authors, and summary comments. +--- + +## `versions` / `diff ` — 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) +``` + +`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 [args]` -`$ARGUMENTS` = task + optional ontology item or schema file. +> Entry points: `OntologyEngine` (authoring, export, alignments) and +> `OntologyValidator` (consistency checking). --- -## `describe ` +## `concepts ` -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 [--schema ]` +## `validate ` -Validate the graph or schema against the ontology. +Check an ontology for consistency and satisfiability. ```python -result = manager.validate_graph(graph=graph, schema_file=schema_file) +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 ``` -Return: validation status, errors, and correction suggestions. +For SHACL shape validation of instance data use `SHACLGenerator` / `SHACLValidationReport`: + +```python +from semantica.ontology import SHACLGenerator +``` + +--- + +## `build ` + +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 [--format turtle]` + +```python +engine.export_owl(onto, path, format="turtle") +engine.export_shacl(onto, path, format="turtle") +``` + +--- + +## `align ` + +```python +engine.create_alignment(source_uri, target_uri, predicate) +engine.get_alignments(entity_uri) +engine.list_alignments() +``` + +--- + +## `evaluate ` + +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 [args]` +Policy governance over recorded decisions. Usage: `/semantica:policy [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 ] [--target ]` +## `check ` — 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 [--rules ]` + +```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 [args]` - -`$ARGUMENTS` = task + optional node, edge, or time range. +Lineage and audit trails. Usage: `/semantica:provenance [args]` --- -## `trace [--depth N]` - -Trace the provenance of a node or fact. +## `lineage [--depth N]` ```python -from semantica.provenance import ProvenanceTracer +from semantica.provenance import ProvenanceManager -tracer = ProvenanceTracer() -trace = tracer.trace_node(node_id=node_id, depth=depth) +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 ``` -Output: source chain, authors, timestamps, and validation status. - --- -## `audit [--since ] [--actor ]` - -View audit logs for graph changes. +## `sources ` ```python -audit_log = tracer.get_audit_log(since=since, actor=actor) +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) ``` -Return: change events, actor, affected objects, and action details. +--- + +## `audit [--since ] [--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 [--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 +``` 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 [args]` +Query the graph. Usage: `/semantica:query [args]` -`$ARGUMENTS` = query mode + query string or filter. +> Which API you want depends on where the graph lives. --- -## `sparql ` +## `search ""` — 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 ` - -Execute a Cypher-like query. +## `sparql ""` — RDF triple stores ```python -results = engine.query_cypher(query) +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) ``` -Output: node/relationship results and path summaries. +For query planning, optimisation, and caching over a backend: + +```python +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() +``` + +Blazegraph / Jena / RDF4J need **no** extra — `semantica.triplet_store` speaks +SPARQL over HTTP using the core `requests` dependency. --- -## `search [--filter ]` - -Search graph entities by keyword. +## `cypher ""` — 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]"`.