mirror of
https://github.com/semantica-agi/semantica.git
synced 2026-09-12 04:01:35 +00:00
fix(plugins): rewrite five skills against the real v0.7.0 API
The ontology, policy, provenance, change and query skills documented classes and methods that do not exist in the package. Every import in them fails, so following the skill produces ImportError or AttributeError immediately: | Documented | Reality in 0.7.0 | | --- | --- | | `semantica.policy.PolicyEngine` | no `semantica.policy` module; `PolicyEngine` is in `semantica.context` | | `semantica.query.QueryEngine` | no `semantica.query` module; `QueryEngine` is in `semantica.triplet_store` | | `semantica.ontology.OntologyManager` | no such class; use `OntologyEngine` / `OntologyValidator` | | `semantica.provenance.ProvenanceTracer` | no such class; use `ProvenanceManager` | | `semantica.provenance.change_tracker.ChangeTracker` | no such module; ontology versioning lives in `semantica.change_management` | The method names were wrong too, so a path-only fix was not possible: `.check()`, `.list_rules()`, `.trace_node()`, `.get_audit_log()`, `.compute_diff()`, `.get_node_history()`, `.query_sparql()`, `.query_cypher()` and `.search()` do not exist on any of the real classes. Each skill is rewritten against signatures verified by introspection on an installed 0.7.0. Two notes on scope: - policy now leads with `ContextGraph.check_decision_rules()` / `enforce_decision_policy()`, which need no graph store, and keeps `context.PolicyEngine` as the managed-policy path. - change previously conflated graph-state-over-time with ontology versioning. These are separate mechanisms in 0.7.0, so the skill now documents `ContextGraph.state_at()` and `change_management.VersionManager` separately. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
gyro
@@ -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
|
||||
```
|
||||
|
||||
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 <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")
|
||||
```
|
||||
|
||||
Return: revisions, timestamps, authors, and summary comments.
|
||||
---
|
||||
|
||||
## `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)
|
||||
```
|
||||
|
||||
`TemporalVersionManager` and `OntologyVersionManager` are also exported for
|
||||
time-scoped and ontology-specific variants.
|
||||
|
||||
@@ -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 [--schema <file>]`
|
||||
## `validate <ontology>`
|
||||
|
||||
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 <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)
|
||||
```
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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]`
|
||||
|
||||
Trace the provenance of a node or fact.
|
||||
## `lineage <entity_id> [--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 <ts>] [--actor <id>]`
|
||||
|
||||
View audit logs for graph changes.
|
||||
## `sources <entity_id>`
|
||||
|
||||
```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 <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
|
||||
```
|
||||
|
||||
@@ -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>`
|
||||
|
||||
Execute a Cypher-like query.
|
||||
## `sparql "<query>"` — 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 <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]"`.
|
||||
|
||||
Reference in New Issue
Block a user