Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

fix(docs): resolve 4 Qodo bot review bugs in README and docs/index.md

KaifAhmad1069af2a038fb
diff --git a/README.md b/README.md
index e4560c20..14374490 100644
--- a/README.md
+++ b/README.md
@@ -213,7 +213,7 @@ Turn ontologies into executable data contracts — no hand-authoring.
- Validate any RDF graph and get back a report with plain-English violation explanations ready to feed into an LLM or pipeline.
- Use in CI to catch breaking ontology changes before they reach production.
-→ `pip install semantica[shacl]`
+→ SHACL shape generation and validation are available via the `OntologyEngine` — see [ontology docs](docs/reference/ontology.md)
### 🔧 Infrastructure & Fixes
@@ -323,7 +323,7 @@ Build, import, and enforce data contracts for your knowledge graphs.
- Derive SHACL shapes from any ontology and validate graphs against them.
- Manage SKOS controlled vocabularies with hierarchy, search, and REST APIs.
-→ [Ontology docs](docs/reference/ontology.md) · `pip install semantica[shacl]`
+→ [Ontology docs](docs/reference/ontology.md)
### 🏭 Pipeline & Production
@@ -356,14 +356,15 @@ from semantica.context import ContextGraph
graph = ContextGraph(advanced_analytics=True)
# Record decisions with full reasoning context
-loan_id = graph.add_decision(
+# record_decision() accepts keyword args and returns the decision ID
+loan_id = graph.record_decision(
category="loan_approval",
scenario="Mortgage — 780 credit score, 28% DTI",
reasoning="Strong credit history, stable 8-year income, low DTI",
outcome="approved",
confidence=0.95,
)
-rate_id = graph.add_decision(
+rate_id = graph.record_decision(
category="interest_rate",
scenario="Set rate for approved mortgage",
reasoning="Prime applicant qualifies for lowest tier",
@@ -424,12 +425,13 @@ start, end = normalizer.normalize("Q1 2024")
```python
from semantica.context import ContextGraph, AgentContext
+from semantica.vector_store import VectorStore
from datetime import datetime, timezone
graph = ContextGraph()
-# Decisions carry explicit validity windows
-graph.add_decision(
+# record_decision() accepts keyword args and supports validity windows
+graph.record_decision(
category="policy",
scenario="Approve supplier A",
outcome="approved",
@@ -442,7 +444,12 @@ graph.add_decision(
# The source graph is never mutated
snapshot = graph.state_at(datetime(2024, 3, 15, tzinfo=timezone.utc))
-# Named checkpoints — snapshot context, then diff what changed
+# Named checkpoints — checkpoint() and diff_checkpoints() live on AgentContext
+context = AgentContext(
+ vector_store=VectorStore(backend="inmemory"),
+ knowledge_graph=graph,
+ decision_tracking=True,
+)
context.checkpoint("before_merge")
# ... make changes ...
diff = context.diff_checkpoints("before_merge", "after_merge")
@@ -470,18 +477,28 @@ for rel in relations:
### Knowledge Graphs & Algorithms
```python
-from semantica.kg import KnowledgeGraph, Entity, Relationship
-from semantica.kg import CentralityAnalyzer, NodeEmbedder, LinkPredictor
-
-kg = KnowledgeGraph()
-kg.add_entity(Entity(id="bert", label="BERT", type="Model"))
-kg.add_entity(Entity(id="transformer", label="Transformer", type="Architecture"))
-kg.add_relationship(Relationship(source="bert", target="transformer", type="based_on"))
+from semantica.kg import GraphBuilder, CentralityCalculator, NodeEmbedder, LinkPredictor
+
+# Build a KG from entity/relationship dicts
+builder = GraphBuilder()
+graph = builder.build({
+ "entities": [
+ {"id": "bert", "label": "BERT", "type": "Model"},
+ {"id": "transformer", "label": "Transformer", "type": "Architecture"},
+ {"id": "gpt4", "label": "GPT-4", "type": "Model"},
+ ],
+ "relationships": [
+ {"source": "bert", "target": "transformer", "type": "based_on"},
+ {"source": "gpt4", "target": "transformer", "type": "based_on"},
+ ],
+})
# Graph algorithms
-centrality = CentralityAnalyzer(kg).compute_pagerank()
-embeddings = NodeEmbedder().compute_embeddings(kg, node_labels=["Model"], relationship_types=["based_on"])
-link_score = LinkPredictor().score_link(kg, "gpt4", "bert", method="common_neighbors")
+centrality = CentralityCalculator().calculate_pagerank(graph)
+embeddings = NodeEmbedder().compute_embeddings(
+ graph, node_labels=["Model"], relationship_types=["based_on"]
+)
+link_score = LinkPredictor().score_link(graph, "gpt4", "bert", method="common_neighbors")
```
→ [KG algorithm docs](docs/reference/) · [KG cookbook](cookbook/)
@@ -512,36 +529,30 @@ matches = rete.match({"amount": 15000, "country": "IR", "id": "txn_9921"})
→ [Reasoning docs](docs/reference/)
-### SHACL — Ontology to Data Contract
+### Ontology Generation & Validation
```python
from semantica.ontology import OntologyEngine
-import pathlib
engine = OntologyEngine()
-ontology = engine.from_data(your_ontology_dict)
-# Generate shapes — zero hand-authoring, fully deterministic
-engine.export_shacl(ontology, path="shapes/domain.ttl")
+# Derive an OWL ontology from any data dict
+ontology = engine.from_data(your_data_dict)
-# Validate a graph and get plain-English explanations
-report = engine.validate_graph(
- data_graph=pathlib.Path("data/graph.ttl").read_text(),
- ontology=ontology,
- explain=True,
-)
+# Export as OWL (Turtle or RDF/XML)
+engine.export_owl(ontology, path="domain_ontology.owl", format="turtle")
-print(report.summary())
-# → "Graph does NOT conform: 2 violation(s)."
+# Validate ontology consistency
+result = engine.validate(ontology)
-for v in report.violations:
- print(v.explanation)
-# → "Node <.../john> is missing required property <ex:name>. At least 1 value required."
-```
+# Generate ontology from raw text using an LLM
+ontology = engine.from_text("Employees work at companies. Companies have departments.")
-> Requires `pip install semantica[shacl]` for validation. Shape generation works with no extras.
+# Convert ontology to OWL string
+owl_str = engine.to_owl(ontology, format="turtle")
+```
-→ [SHACL docs](docs/reference/ontology.md)
+→ [Ontology docs](docs/reference/ontology.md)
### Pipeline Orchestration
@@ -555,7 +566,7 @@ pipeline = (
.add_stage("ingest", FileIngestor(recursive=True))
.add_stage("extract", extract_triplets)
.add_stage("deduplicate", DuplicateDetector())
- .add_stage("build_kg", KnowledgeGraph())
+ .add_stage("build_kg", GraphBuilder())
.add_stage("export", RDFExporter())
.with_parallel_workers(4)
)
@@ -729,7 +740,7 @@ pip install semantica[vectorstore-weaviate]
pip install semantica[vectorstore-qdrant]
pip install semantica[vectorstore-milvus]
pip install semantica[vectorstore-pgvector]
-pip install semantica[shacl] # SHACL validation
+pip install semantica[shacl] # pyshacl for SHACL validation (optional)
pip install semantica[db-snowflake] # Snowflake ingestion
pip install semantica[agno] # Agno integration
diff --git a/docs/index.md b/docs/index.md
index 932da0ab..4d5cecdf 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -6,7 +6,7 @@
<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.8+-blue.svg" alt="Python 3.8+"></a>
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
<a href="https://pypi.org/project/semantica/"><img src="https://img.shields.io/pypi/v/semantica.svg" alt="PyPI"></a>
- <a href="https://github.com/Hawksight-AI/semantica/releases/tag/v0.3.0"><img src="https://img.shields.io/badge/version-0.3.0-brightgreen.svg" alt="Version"></a>
+ <a href="https://github.com/Hawksight-AI/semantica/releases/tag/v0.4.0"><img src="https://img.shields.io/badge/version-0.4.0-brightgreen.svg" alt="Version"></a>
<a href="https://pepy.tech/project/semantica"><img src="https://static.pepy.tech/badge/semantica" alt="Total Downloads"></a>
<a href="https://github.com/Hawksight-AI/semantica/actions"><img src="https://github.com/Hawksight-AI/semantica/workflows/CI/badge.svg" alt="CI"></a>
<a href="https://discord.gg/sV34vps5hH"><img src="https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white" alt="Discord"></a>