diff --git a/README.md b/README.md
index 7cf78e66..216e424d 100644
--- a/README.md
+++ b/README.md
@@ -1,612 +1,615 @@
-
-
-
-
-# π§ Semantica
-
-[](https://www.python.org/downloads/)
-[](https://opensource.org/licenses/MIT)
-[](https://pypi.org/project/semantica/0.0.1/)
-[](https://pepy.tech/project/semantica)
-[](https://discord.gg/semantica)
-[](https://github.com/Hawksight-AI/semantica/actions)
-
-
-
- 
-
-
-
- 
-
-
-
-**Open Source Framework for Semantic Layer & Knowledge Engineering**
-
-> **Transform chaotic data into intelligent knowledge.**
-
-*The missing fabric between raw data and AI engineering. A comprehensive open-source framework for building semantic layers and knowledge engineering systems that transform unstructured data into AI-ready knowledge β powering Knowledge Graph-Powered RAG (GraphRAG), AI Agents, Multi-Agent Systems, and AI applications with structured semantic knowledge.*
-
-**100% Open Source** β’ **MIT Licensed** β’ **Production Ready** β’ **Community Driven**
-
-[**Discord**](https://discord.gg/semantica) β’ [**GitHub**](https://github.com/Hawksight-AI/semantica)
-
-
-View Interactive Flowchart
-
-```mermaid
-flowchart TD
- A[Raw Data Sources
PDFs, Emails, Logs, Databases
50+ Formats] --> B[Input Layer
Universal Data Ingestion]
- B --> C[Format Detection
& Parsing]
- C --> D[Normalization
& Preprocessing]
- D --> E[Semantic Layer
Core Intelligence]
-
- E --> F[Entity Extraction
NER + LLM Enhancement]
- E --> G[Relationship Mapping
Triplet Generation]
- E --> H[Ontology Generation
6-Stage Pipeline]
- E --> I[Context Engineering
Semantic Enrichment]
- E --> J[Quality Assurance
Conflict Detection]
-
- F --> K[Output Layer]
- G --> K
- H --> K
- I --> K
- J --> K
-
- K --> L[Knowledge Graphs
Production-Ready]
- K --> M[Vector Embeddings
Semantic Search]
- K --> N[Ontologies
OWL Validated]
-
- L --> O[Application Layer]
- M --> O
- N --> O
-
- O --> P[GraphRAG Engine
91% Accuracy]
- O --> Q[AI Agents
Persistent Memory]
- O --> R[Multi-Agent Systems
Shared Models]
- O --> S[Analytics & BI
Graph Insights]
-
- style A fill:#e1f5ff
- style E fill:#fff4e1
- style K fill:#e8f5e9
- style O fill:#f3e5f5
-```
-
-
-
-
-### What Happens Without Semantics?
-
-**They Break** β Systems crash due to inconsistent formats and missing structure.
-
-**They Hallucinate** β AI models generate false information without semantic context to validate outputs.
-
-**They Fail Silently** β Systems return wrong answers without warnings, leading to bad decisions.
-
-**Why?** Systems have data β not semantics. They can't connect concepts, understand relationships, validate against domain rules, or detect conflicts.
-
----
-
-## π‘ The Semantica Solution
-
-**Semantica** is an **open-source framework** that closes the semantic gap between real-world messy data and the structured semantic layers required by advanced AI systems β GraphRAG, agents, multi-agent systems, reasoning models, and more.
-
-### How Semantica Solves These Problems
-
-**Efficient Embeddings** β Uses **FastEmbed** by default for high-performance, lightweight local embedding generation (faster than sentence-transformers).
-
-**Universal Data Ingestion** β Handles 50+ formats (PDF, DOCX, HTML, JSON, CSV, databases, APIs, streams) with unified pipeline, no custom parsers needed.
-
-**Automated Semantic Extraction** β NER, relationship extraction, and triplet generation with LLM enhancement discovers entities and relationships automatically.
-
-**Knowledge Graph Construction** β Production-ready graphs with entity resolution, temporal support, and graph analytics. Queryable knowledge ready for AI applications.
-
-**GraphRAG Engine** β Hybrid vector + graph retrieval achieves 91% accuracy (30% improvement) via semantic search + graph traversal for multi-hop reasoning.
-
-**AI Agent Context Engineering** β Persistent memory with RAG + knowledge graphs enables context maintenance, action validation, and structured knowledge access.
-
-**Automated Ontology Generation** β 6-stage LLM pipeline generates validated OWL ontologies with HermiT/Pellet validation, eliminating manual engineering.
-
-**Production-Grade QA** β Conflict detection, deduplication, quality scoring, and provenance tracking ensure trusted, production-ready knowledge graphs.
-
-**Pipeline Orchestration** β Flexible pipeline builder with parallel execution enables scalable processing via orchestrator-worker pattern.
-
-### Core Features at a Glance
-
-| **Feature Category** | **Capabilities** | **Key Benefits** |
-|:---------------------|:-----------------|:------------------|
-| **Data Ingestion** | 50+ formats (PDF, DOCX, HTML, JSON, CSV, databases, APIs, streams, archives) | Universal ingestion, no custom parsers needed |
-| **Semantic Extraction** | NER, relationship extraction, triplet generation, LLM enhancement | Automated discovery of entities and relationships |
-| **Knowledge Graphs** | Entity resolution, temporal support, graph analytics, query interface | Production-ready, queryable knowledge structures |
-| **Ontology Generation** | 6-stage LLM pipeline, OWL generation, HermiT/Pellet validation | Automated ontology creation from documents |
-| **GraphRAG** | Hybrid vector + graph retrieval, multi-hop reasoning | 91% accuracy, 30% improvement over vector-only |
-| **Agent Memory** | Persistent memory (Save/Load), Hybrid Retrieval (Vector+Graph), FastEmbed support | Context-aware agents with semantic understanding |
-| **Pipeline Orchestration** | Parallel execution, custom steps, orchestrator-worker pattern | Scalable, flexible data processing |
-| **Quality Assurance** | Conflict detection, deduplication, quality scoring, provenance | Trusted knowledge graphs ready for production |
-
----
-
-## π₯ Who Is This For?
-
-Semantica is designed for **developers, data engineers, and organizations** building the next generation of AI applications that require semantic understanding and knowledge graphs.
-
-### Who Uses Semantica
-
-**AI/ML Engineers & Data Scientists** β Build GraphRAG systems, AI agents, and multi-agent systems.
-
-**Data Engineers** β Build scalable pipelines with semantic enrichment.
-
-**Knowledge Engineers & Ontologists** β Create knowledge graphs and ontologies with automated pipelines.
-
-**Enterprise Data Teams** β Unify semantic layers, improve data quality, resolve conflicts.
-
-**Software & DevOps Engineers** β Build semantic APIs and infrastructure with production-ready SDK.
-
-**Analysts & Researchers** β Transform data into queryable knowledge graphs for insights.
-
-**Security & Compliance Teams** β Threat intelligence, regulatory reporting, audit trails.
-
-**Product Teams & Startups** β Rapid prototyping of AI products and semantic features.
-
----
-
-## π¦ Installation
-
-**Prerequisites:** Python 3.8+ (3.9+ recommended) β’ pip (latest version)
-
-### Install from PyPI (Recommended)
-
-```bash
-# Install latest version from PyPI
-pip install semantica
-
-# Or install with optional dependencies
-pip install semantica[all]
-
-# Verify installation
-python -c "import semantica; print(semantica.__version__)"
-```
-
-**Current Version:** [](https://pypi.org/project/semantica/0.0.1/) β’ [View on PyPI](https://pypi.org/project/semantica/0.0.1/)
-
-### Install from Source (Development)
-
-```bash
-# Clone and install in editable mode
-git clone https://github.com/Hawksight-AI/semantica.git
-cd semantica
-pip install -e .
-
-# Or with all optional dependencies
-pip install -e ".[all]"
-
-# Development setup
-pip install -e ".[dev]"
-```
-
-## π Resources
-
-> **New to Semantica?** Check out the [**Cookbook**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook) for hands-on examples!
-
-- [**Cookbook**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook) - 50+ interactive notebooks
- - [Introduction](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction) - Getting started tutorials
- - [Advanced](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/advanced) - Advanced techniques
- - [Use Cases](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/use_cases) - Real-world applications
-
-## β¨ Core Capabilities
-
-| **Data Ingestion** | **Semantic Extract** | **Knowledge Graphs** | **Ontology** |
-|:--------------------:|:----------------------:|:----------------------:|:--------------:|
-| [50+ Formats](#universal-data-ingestion) | [Entity & Relations](#semantic-intelligence-engine) | [Graph Analytics](#knowledge-graph-construction) | [Auto Generation](#ontology-generation--management) |
-| **Context** | **GraphRAG** | **Pipeline** | **QA** |
-| [Agent Memory](#context-engineering-for-ai-agents) | [Hybrid RAG](#knowledge-graph-powered-rag-graphrag) | [Parallel Workers](#pipeline-orchestration--parallel-processing) | [Conflict Resolution](#production-ready-quality-assurance) |
-
----
-
-### Universal Data Ingestion
-
-> **50+ file formats** β’ PDF, DOCX, HTML, JSON, CSV, databases, feeds, archives
-
-```python
-from semantica.ingest import FileIngestor, WebIngestor, DBIngestor
-
-file_ingestor = FileIngestor(recursive=True)
-web_ingestor = WebIngestor(max_depth=3)
-db_ingestor = DBIngestor(connection_string="postgresql://...")
-
-sources = []
-sources.extend(file_ingestor.ingest("documents/"))
-sources.extend(web_ingestor.ingest("https://example.com"))
-sources.extend(db_ingestor.ingest(query="SELECT * FROM articles"))
-
-print(f" Ingested {len(sources)} sources")
-```
-
-[**Cookbook: Data Ingestion**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/02_Data_Ingestion.ipynb) β’ [**Document Parsing**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/03_Document_Parsing.ipynb) β’ [**Data Normalization**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/04_Data_Normalization.ipynb) β’ [**Chunking & Splitting**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/11_Chunking_and_Splitting.ipynb)
-
-### Semantic Intelligence Engine
-
-> **Entity & Relation Extraction** β’ NER, Relationships, Events, Triplets with LLM Enhancement
-
-```python
-from semantica.core import Semantica
-
-text = "Apple Inc., founded by Steve Jobs in 1976, acquired Beats Electronics for $3 billion."
-
-core = Semantica(ner_model="transformer", relation_strategy="hybrid")
-results = core.extract_semantics(text)
-
-print(f"Entities: {len(results.entities)}, Relationships: {len(results.relationships)}")
-```
-
-[**Cookbook: Entity Extraction**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/05_Entity_Extraction.ipynb) β’ [**Relation Extraction**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/06_Relation_Extraction.ipynb) β’ [**Advanced Extraction**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/advanced/01_Advanced_Extraction.ipynb)
-
-### Knowledge Graph Construction
-
-> **Production-Ready KGs** β’ Entity Resolution β’ Temporal Support β’ Graph Analytics
-
-```python
-from semantica.core import Semantica
-from semantica.kg import GraphAnalyzer
-
-documents = ["doc1.txt", "doc2.txt", "doc3.txt"]
-core = Semantica(graph_db="neo4j", merge_entities=True)
-kg = core.build_knowledge_graph(documents, generate_embeddings=True)
-
-analyzer = GraphAnalyzer()
-pagerank = analyzer.compute_centrality(kg, method="pagerank")
-communities = analyzer.detect_communities(kg, method="louvain")
-
-result = kg.query("Who founded the company?", return_format="structured")
-print(f"Nodes: {kg.node_count}, Answer: {result.answer}")
-```
-
-[**Cookbook: Building Knowledge Graphs**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/07_Building_Knowledge_Graphs.ipynb) β’ [**Graph Store**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/09_Graph_Store.ipynb) β’ [**Triplet Store**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/20_Triplet_Store.ipynb) β’ [**Visualization**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/16_Visualization.ipynb)
-
-[**Graph Analytics**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/10_Graph_Analytics.ipynb) β’ [**Advanced Graph Analytics**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/advanced/02_Advanced_Graph_Analytics.ipynb)
-
-### Triplet Store Integration
-
-> **SPARQL Support** β’ **Blazegraph, Jena, RDF4J** β’ **Reasoning & Inference**
-
-```python
-from semantica.triplet_store import TripletStore
-
-# Initialize store (Blazegraph, Jena, or RDF4J)
-store = TripletStore(backend="blazegraph", endpoint="http://localhost:9999/blazegraph")
-
-# Add triplets and execute SPARQL queries
-store.add_triplet({
- "subject": "http://example.org/Alice",
- "predicate": "http://example.org/knows",
- "object": "http://example.org/Bob"
-})
-
-results = store.execute_query("SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10")
-```
-
-[**Cookbook: Triplet Store**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/20_Triplet_Store.ipynb)
-
-### Ontology Generation & Management
-
-> **6-Stage LLM Pipeline** β’ Automatic OWL Generation β’ HermiT/Pellet Validation
-
-```python
-from semantica.ontology import OntologyGenerator
-
-generator = OntologyGenerator(llm_provider="openai", model="gpt-4")
-ontology = generator.generate_from_documents(sources=["domain_docs/"])
-
-print(f"Classes: {len(ontology.classes)}")
-```
-
-[**Cookbook: Ontology**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/14_Ontology.ipynb)
-
-### Context Engineering & Memory Systems
-
-> **Persistent Memory** β’ **Hybrid Retrieval (Vector + Graph)** β’ **Hierarchical Storage** β’ **Entity Linking**
-
-```python
-from semantica.context import AgentContext
-from semantica.vector_store import VectorStore
-
-# Initialize Context with Hybrid Retrieval (Graph + Vector)
-context = AgentContext(
- vector_store=VectorStore(backend="faiss"),
- hybrid_alpha=0.75 # 75% weight to Knowledge Graph, 25% to Vector
-)
-
-# Store memory with automatic entity linking
-context.store(
- "User is building a RAG system with Semantica",
- metadata={"priority": "high", "topic": "rag"}
-)
-
-# Retrieve with context expansion
-results = context.retrieve("What is the user building?", use_graph_expansion=True)
-```
-
-**Core Notebooks:**
-- [**Context Module Introduction**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/19_Context_Module.ipynb) - Basic memory and storage.
-- [**Advanced Context Engineering**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/advanced/11_Advanced_Context_Engineering.ipynb) - Hybrid retrieval, graph builders, and custom memory policies.
-
-**Related Components:**
-[**Vector Store**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/13_Vector_Store.ipynb) β’ [**Embedding Generation**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/12_Embedding_Generation.ipynb) β’ [**Advanced Vector Store**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/advanced/Advanced_Vector_Store_and_Search.ipynb)
-
-### Knowledge Graph-Powered RAG (GraphRAG)
-
-> **30% Accuracy Improvement** β’ Vector + Graph Hybrid Search β’ 91% Accuracy
-
-```python
-from semantica.qa_rag import GraphRAGEngine
-from semantica.vector_store import VectorStore
-
-graphrag = GraphRAGEngine(
- vector_store=VectorStore(backend="faiss"),
- knowledge_graph=kg
-)
-result = graphrag.query("Who founded the company?", top_k=5, expand_graph=True)
-print(f"Answer: {result.answer} (Confidence: {result.confidence:.2f})")
-```
-
-[**Cookbook: GraphRAG**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/use_cases/advanced_rag/01_GraphRAG_Complete.ipynb)
-
-### Pipeline Orchestration & Parallel Processing
-
-> **Orchestrator-Worker Pattern** β’ Parallel Execution β’ Scalable Processing
-
-```python
-from semantica.pipeline import PipelineBuilder, ExecutionEngine
-
-pipeline = PipelineBuilder() \
- .add_step("ingest", "custom", func=ingest_data) \
- .add_step("extract", "custom", func=extract_entities) \
- .add_step("build", "custom", func=build_graph) \
- .build()
-
-result = ExecutionEngine().execute_pipeline(pipeline, parallel=True)
-```
-
-
-### Production-Ready Quality Assurance
-
-> **Enterprise-Grade QA** β’ Conflict Detection β’ Deduplication
-
-```python
-from semantica.deduplication import DuplicateDetector
-from semantica.conflicts import ConflictDetector
-
-entities = kg.get("entities", [])
-conflicts = ConflictDetector().detect_conflicts(entities)
-duplicates = DuplicateDetector(similarity_threshold=0.85).detect_duplicates(entities)
-
-print(f"Conflicts: {len(conflicts)} | Duplicates: {len(duplicates)}")
-```
-
-[**Cookbook: Conflict Detection & Resolution**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/17_Conflict_Detection_and_Resolution.ipynb) β’ [**Deduplication**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/18_Deduplication.ipynb)
-
-### Export & Integration
-
-> **Multi-Format Export** β’ JSON, CSV, RDF, GraphML
-
-```python
-from semantica.export import GraphExporter
-
-exporter = GraphExporter(kg)
-exporter.export("graph.json", format="json")
-exporter.export("graph.ttl", format="turtle")
-```
-
-[**Cookbook: Export**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/15_Export.ipynb) β’ [**Multi-Format Export**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/advanced/05_Multi_Format_Export.ipynb) β’ [**Multi-Source Integration**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/advanced/06_Multi_Source_Data_Integration.ipynb)
-
-## π Quick Start
-
-> **For comprehensive examples, see the [**Cookbook**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook) with 50+ interactive notebooks!**
-
-```python
-from semantica.core import Semantica
-
-# Initialize and build knowledge graph
-core = Semantica(ner_model="transformer", relation_strategy="hybrid")
-documents = ["doc1.txt", "doc2.txt", "doc3.txt"]
-kg = core.build_knowledge_graph(documents, merge_entities=True)
-
-# Query the graph
-result = kg.query("Who founded the company?", return_format="structured")
-print(f"Answer: {result.answer} | Nodes: {kg.node_count}, Edges: {kg.edge_count}")
-```
-
-[**Cookbook: Your First Knowledge Graph**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/08_Your_First_Knowledge_Graph.ipynb)
-
-## π― Use Cases
-
-**Enterprise Knowledge Engineering** β Unify data sources into knowledge graphs, breaking down silos.
-
-**AI Agents & Autonomous Systems** β Build agents with persistent memory and semantic understanding.
-
-**Multi-Format Document Processing** β Process 50+ formats through a unified pipeline.
-
-**Data Pipeline Processing** β Build scalable pipelines with parallel execution.
-
-**Intelligence & Security** β Analyze networks, threat intelligence, forensic analysis.
-
-**Finance & Trading** β Fraud detection, market intelligence, risk assessment.
-
-**Healthcare & Biomedical** β Clinical reports, drug discovery, medical literature analysis.
-
-[**Explore Use Case Examples**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/use_cases) β See real-world implementations in finance, healthcare, cybersecurity, trading, and more.
-
-## π¬ Advanced Features
-
-**Incremental Updates** β Real-time stream processing with Kafka, RabbitMQ, Kinesis for live updates.
-
-**Multi-Language Support** β Process 50+ languages with automatic detection.
-
-**Custom Ontology Import** β Import and extend Schema.org and custom ontologies.
-
-**Advanced Reasoning** β Deductive, inductive, abductive reasoning with HermiT/Pellet.
-
-**Graph Analytics** β Centrality, community detection, path finding, temporal analysis.
-
-**Custom Pipelines** β Build custom pipelines with parallel execution.
-
-**API Integration** β Integrate external APIs for entity enrichment.
-
-[**See Advanced Examples**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/advanced) β Advanced extraction, graph analytics, reasoning, and more.
-
-## πΊοΈ Roadmap
-
-### Q1 2026
-- [x] Core framework (v1.0)
-- [x] GraphRAG engine
-- [x] 6-stage ontology pipeline
-- [ ] Quality assurance features and Quality Assurance module
-- [ ] Enhanced multi-language support
-- [ ] Real-time streaming improvements
-- [ ] Advanced reasoning v2
-
-### Q2 2026
-- [ ] Multi-modal processing
-
----
-
-## π€ Community & Support
-
-### Join Our Community
-
-| **Channel** | **Purpose** |
-|:-----------:|:-----------|
-| [**Discord**](https://discord.gg/semantica) | Real-time help, showcases |
-| [**GitHub Discussions**](https://github.com/Hawksight-AI/semantica/discussions) | Q&A, feature requests |
-
-### Learning Resources
-
-
-### Enterprise Support
-
-| **Tier** | **Features** | **SLA** | **Price** |
-|:--------:|:-----------|:-------:|:--------:|
-| **Community** | Public support | Best effort | Free |
-| **Professional** | Email support | 48h | Contact |
-| **Enterprise** | 24/7 support | 4h | Contact |
-| **Premium** | Phone, custom dev | 1h | Contact |
-
-**Contact:** [GitHub Issues](https://github.com/Hawksight-AI/semantica/issues) with "[Enterprise]" prefix
-
-## π€ Contributing
-
-### How to Contribute
-
-```bash
-# Fork and clone
-git clone https://github.com/your-username/semantica.git
-cd semantica
-
-# Create branch
-git checkout -b feature/your-feature
-
-# Install dev dependencies
-pip install -e ".[dev,test]"
-
-# Make changes and test
-pytest tests/
-black semantica/
-flake8 semantica/
-
-# Commit and push
-git commit -m "Add feature"
-git push origin feature/your-feature
-```
-
-### Contribution Types
-
-1. **Code** - New features, bug fixes
-2. **Documentation** - Improvements, tutorials
-3. **Bug Reports** - [Create issue](https://github.com/Hawksight-AI/semantica/issues/new)
-4. **Feature Requests** - [Request feature](https://github.com/Hawksight-AI/semantica/issues/new)
-
-### Recognition
-
-Contributors receive:
-- Recognition in [CONTRIBUTORS.md](https://github.com/Hawksight-AI/semantica/blob/main/CONTRIBUTORS.md)
-- GitHub badges
-- Semantica swag
-- Featured showcases
-
-## π Contributors
-
-
- 
-
-
-## π License
-
-Semantica is licensed under the **MIT License** - see the [LICENSE](https://github.com/Hawksight-AI/semantica/blob/main/LICENSE) file for details.
-
-
-
-**Built by the Semantica Community**
-
-[GitHub](https://github.com/Hawksight-AI/semantica) β’ [Discord](https://discord.gg/semantica)
-
-
+
+
+
+
+# π§ Semantica
+
+[](https://www.python.org/downloads/)
+[](https://opensource.org/licenses/MIT)
+[](https://pypi.org/project/semantica/0.0.1/)
+[](https://pepy.tech/project/semantica)
+[](https://discord.gg/semantica)
+[](https://github.com/Hawksight-AI/semantica/actions)
+
+
+
+
+
+
+
+
+
+
+
+**Open Source Framework for Semantic Layer & Knowledge Engineering**
+
+> **Transform chaotic data into intelligent knowledge.**
+
+*The missing fabric between raw data and AI engineering. A comprehensive open-source framework for building semantic layers and knowledge engineering systems that transform unstructured data into AI-ready knowledge β powering Knowledge Graph-Powered RAG (GraphRAG), AI Agents, Multi-Agent Systems, and AI applications with structured semantic knowledge.*
+
+**100% Open Source** β’ **MIT Licensed** β’ **Production Ready** β’ **Community Driven**
+
+[**Discord**](https://discord.gg/semantica) β’ [**GitHub**](https://github.com/Hawksight-AI/semantica)
+
+
+View Interactive Flowchart
+
+```mermaid
+flowchart TD
+ A[Raw Data Sources
PDFs, Emails, Logs, Databases
50+ Formats] --> B[Input Layer
Universal Data Ingestion]
+ B --> C[Format Detection
& Parsing]
+ C --> D[Normalization
& Preprocessing]
+ D --> E[Semantic Layer
Core Intelligence]
+
+ E --> F[Entity Extraction
NER + LLM Enhancement]
+ E --> G[Relationship Mapping
Triplet Generation]
+ E --> H[Ontology Generation
6-Stage Pipeline]
+ E --> I[Context Engineering
Semantic Enrichment]
+ E --> J[Quality Assurance
Conflict Detection]
+
+ F --> K[Output Layer]
+ G --> K
+ H --> K
+ I --> K
+ J --> K
+
+ K --> L[Knowledge Graphs
Production-Ready]
+ K --> M[Vector Embeddings
Semantic Search]
+ K --> N[Ontologies
OWL Validated]
+
+ L --> O[Application Layer]
+ M --> O
+ N --> O
+
+ O --> P[GraphRAG Engine
91% Accuracy]
+ O --> Q[AI Agents
Persistent Memory]
+ O --> R[Multi-Agent Systems
Shared Models]
+ O --> S[Analytics & BI
Graph Insights]
+
+ style A fill:#e1f5ff
+ style E fill:#fff4e1
+ style K fill:#e8f5e9
+ style O fill:#f3e5f5
+```
+
+
+
+
+### What Happens Without Semantics?
+
+**They Break** β Systems crash due to inconsistent formats and missing structure.
+
+**They Hallucinate** β AI models generate false information without semantic context to validate outputs.
+
+**They Fail Silently** β Systems return wrong answers without warnings, leading to bad decisions.
+
+**Why?** Systems have data β not semantics. They can't connect concepts, understand relationships, validate against domain rules, or detect conflicts.
+
+---
+
+## π‘ The Semantica Solution
+
+**Semantica** is an **open-source framework** that closes the semantic gap between real-world messy data and the structured semantic layers required by advanced AI systems β GraphRAG, agents, multi-agent systems, reasoning models, and more.
+
+### How Semantica Solves These Problems
+
+**Efficient Embeddings** β Uses **FastEmbed** by default for high-performance, lightweight local embedding generation (faster than sentence-transformers).
+
+**Universal Data Ingestion** β Handles 50+ formats (PDF, DOCX, HTML, JSON, CSV, databases, APIs, streams) with unified pipeline, no custom parsers needed.
+
+**Automated Semantic Extraction** β NER, relationship extraction, and triplet generation with LLM enhancement discovers entities and relationships automatically.
+
+**Knowledge Graph Construction** β Production-ready graphs with entity resolution, temporal support, and graph analytics. Queryable knowledge ready for AI applications.
+
+**GraphRAG Engine** β Hybrid vector + graph retrieval achieves 91% accuracy (30% improvement) via semantic search + graph traversal for multi-hop reasoning. [See Comparison Benchmark](cookbook/use_cases/advanced_rag/02_RAG_vs_GraphRAG_Comparison.ipynb)
+
+**AI Agent Context Engineering** β Persistent memory with RAG + knowledge graphs enables context maintenance, action validation, and structured knowledge access.
+
+**Automated Ontology Generation** β 6-stage LLM pipeline generates validated OWL ontologies with HermiT/Pellet validation, eliminating manual engineering.
+
+**Production-Grade QA** β Conflict detection, deduplication, quality scoring, and provenance tracking ensure trusted, production-ready knowledge graphs.
+
+**Pipeline Orchestration** β Flexible pipeline builder with parallel execution enables scalable processing via orchestrator-worker pattern.
+
+### Core Features at a Glance
+
+| **Feature Category** | **Capabilities** | **Key Benefits** |
+|:---------------------|:-----------------|:------------------|
+| **Data Ingestion** | 50+ formats (PDF, DOCX, HTML, JSON, CSV, databases, APIs, streams, archives) | Universal ingestion, no custom parsers needed |
+| **Semantic Extraction** | NER, relationship extraction, triplet generation, LLM enhancement | Automated discovery of entities and relationships |
+| **Knowledge Graphs** | Entity resolution, temporal support, graph analytics, query interface | Production-ready, queryable knowledge structures |
+| **Ontology Generation** | 6-stage LLM pipeline, OWL generation, HermiT/Pellet validation | Automated ontology creation from documents |
+| **GraphRAG** | Hybrid vector + graph retrieval, multi-hop reasoning | 91% accuracy, 30% improvement over vector-only |
+| **Agent Memory** | Persistent memory (Save/Load), Hybrid Retrieval (Vector+Graph), FastEmbed support | Context-aware agents with semantic understanding |
+| **Pipeline Orchestration** | Parallel execution, custom steps, orchestrator-worker pattern | Scalable, flexible data processing |
+| **Quality Assurance** | Conflict detection, deduplication, quality scoring, provenance | Trusted knowledge graphs ready for production |
+
+---
+
+## π₯ Who Is This For?
+
+Semantica is designed for **developers, data engineers, and organizations** building the next generation of AI applications that require semantic understanding and knowledge graphs.
+
+### Who Uses Semantica
+
+**AI/ML Engineers & Data Scientists** β Build GraphRAG systems, AI agents, and multi-agent systems.
+
+**Data Engineers** β Build scalable pipelines with semantic enrichment.
+
+**Knowledge Engineers & Ontologists** β Create knowledge graphs and ontologies with automated pipelines.
+
+**Enterprise Data Teams** β Unify semantic layers, improve data quality, resolve conflicts.
+
+**Software & DevOps Engineers** β Build semantic APIs and infrastructure with production-ready SDK.
+
+**Analysts & Researchers** β Transform data into queryable knowledge graphs for insights.
+
+**Security & Compliance Teams** β Threat intelligence, regulatory reporting, audit trails.
+
+**Product Teams & Startups** β Rapid prototyping of AI products and semantic features.
+
+---
+
+## π¦ Installation
+
+**Prerequisites:** Python 3.8+ (3.9+ recommended) β’ pip (latest version)
+
+### Install from PyPI (Recommended)
+
+```bash
+# Install latest version from PyPI
+pip install semantica
+
+# Or install with optional dependencies
+pip install semantica[all]
+
+# Verify installation
+python -c "import semantica; print(semantica.__version__)"
+```
+
+**Current Version:** [](https://pypi.org/project/semantica/0.0.1/) β’ [View on PyPI](https://pypi.org/project/semantica/0.0.1/)
+
+### Install from Source (Development)
+
+```bash
+# Clone and install in editable mode
+git clone https://github.com/Hawksight-AI/semantica.git
+cd semantica
+pip install -e .
+
+# Or with all optional dependencies
+pip install -e ".[all]"
+
+# Development setup
+pip install -e ".[dev]"
+```
+
+## π Resources
+
+> **New to Semantica?** Check out the [**Cookbook**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook) for hands-on examples!
+
+- [**Cookbook**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook) - 50+ interactive notebooks
+ - [Introduction](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction) - Getting started tutorials
+ - [Advanced](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/advanced) - Advanced techniques
+ - [Use Cases](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/use_cases) - Real-world applications
+
+## β¨ Core Capabilities
+
+| **Data Ingestion** | **Semantic Extract** | **Knowledge Graphs** | **Ontology** |
+|:--------------------:|:----------------------:|:----------------------:|:--------------:|
+| [50+ Formats](#universal-data-ingestion) | [Entity & Relations](#semantic-intelligence-engine) | [Graph Analytics](#knowledge-graph-construction) | [Auto Generation](#ontology-generation--management) |
+| **Context** | **GraphRAG** | **Pipeline** | **QA** |
+| [Agent Memory](#context-engineering-for-ai-agents) | [Hybrid RAG](#knowledge-graph-powered-rag-graphrag) | [Parallel Workers](#pipeline-orchestration--parallel-processing) | [Conflict Resolution](#production-ready-quality-assurance) |
+
+---
+
+### Universal Data Ingestion
+
+> **50+ file formats** β’ PDF, DOCX, HTML, JSON, CSV, databases, feeds, archives
+
+```python
+from semantica.ingest import FileIngestor, WebIngestor, DBIngestor
+
+file_ingestor = FileIngestor(recursive=True)
+web_ingestor = WebIngestor(max_depth=3)
+db_ingestor = DBIngestor(connection_string="postgresql://...")
+
+sources = []
+sources.extend(file_ingestor.ingest("documents/"))
+sources.extend(web_ingestor.ingest("https://example.com"))
+sources.extend(db_ingestor.ingest(query="SELECT * FROM articles"))
+
+print(f" Ingested {len(sources)} sources")
+```
+
+[**Cookbook: Data Ingestion**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/02_Data_Ingestion.ipynb) β’ [**Document Parsing**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/03_Document_Parsing.ipynb) β’ [**Data Normalization**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/04_Data_Normalization.ipynb) β’ [**Chunking & Splitting**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/11_Chunking_and_Splitting.ipynb)
+
+### Semantic Intelligence Engine
+
+> **Entity & Relation Extraction** β’ NER, Relationships, Events, Triplets with LLM Enhancement
+
+```python
+from semantica.core import Semantica
+
+text = "Apple Inc., founded by Steve Jobs in 1976, acquired Beats Electronics for $3 billion."
+
+core = Semantica(ner_model="transformer", relation_strategy="hybrid")
+results = core.extract_semantics(text)
+
+print(f"Entities: {len(results.entities)}, Relationships: {len(results.relationships)}")
+```
+
+[**Cookbook: Entity Extraction**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/05_Entity_Extraction.ipynb) β’ [**Relation Extraction**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/06_Relation_Extraction.ipynb) β’ [**Advanced Extraction**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/advanced/01_Advanced_Extraction.ipynb)
+
+### Knowledge Graph Construction
+
+> **Production-Ready KGs** β’ Entity Resolution β’ Temporal Support β’ Graph Analytics
+
+```python
+from semantica.core import Semantica
+from semantica.kg import GraphAnalyzer
+
+documents = ["doc1.txt", "doc2.txt", "doc3.txt"]
+core = Semantica(graph_db="neo4j", merge_entities=True)
+kg = core.build_knowledge_graph(documents, generate_embeddings=True)
+
+analyzer = GraphAnalyzer()
+pagerank = analyzer.compute_centrality(kg, method="pagerank")
+communities = analyzer.detect_communities(kg, method="louvain")
+
+result = kg.query("Who founded the company?", return_format="structured")
+print(f"Nodes: {kg.node_count}, Answer: {result.answer}")
+```
+
+[**Cookbook: Building Knowledge Graphs**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/07_Building_Knowledge_Graphs.ipynb) β’ [**Graph Store**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/09_Graph_Store.ipynb) β’ [**Triplet Store**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/20_Triplet_Store.ipynb) β’ [**Visualization**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/16_Visualization.ipynb)
+
+[**Graph Analytics**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/10_Graph_Analytics.ipynb) β’ [**Advanced Graph Analytics**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/advanced/02_Advanced_Graph_Analytics.ipynb)
+
+### Triplet Store Integration
+
+> **SPARQL Support** β’ **Blazegraph, Jena, RDF4J** β’ **Reasoning & Inference**
+
+```python
+from semantica.triplet_store import TripletStore
+
+# Initialize store (Blazegraph, Jena, or RDF4J)
+store = TripletStore(backend="blazegraph", endpoint="http://localhost:9999/blazegraph")
+
+# Add triplets and execute SPARQL queries
+store.add_triplet({
+ "subject": "http://example.org/Alice",
+ "predicate": "http://example.org/knows",
+ "object": "http://example.org/Bob"
+})
+
+results = store.execute_query("SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10")
+```
+
+[**Cookbook: Triplet Store**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/20_Triplet_Store.ipynb)
+
+### Ontology Generation & Management
+
+> **6-Stage LLM Pipeline** β’ Automatic OWL Generation β’ HermiT/Pellet Validation
+
+```python
+from semantica.ontology import OntologyGenerator
+
+generator = OntologyGenerator(llm_provider="openai", model="gpt-4")
+ontology = generator.generate_from_documents(sources=["domain_docs/"])
+
+print(f"Classes: {len(ontology.classes)}")
+```
+
+[**Cookbook: Ontology**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/14_Ontology.ipynb)
+
+### Context Engineering & Memory Systems
+
+> **Persistent Memory** β’ **Hybrid Retrieval (Vector + Graph)** β’ **Production Graph Store (Neo4j)** β’ **Entity Linking**
+
+```python
+from semantica.context import AgentContext
+from semantica.vector_store import VectorStore
+from semantica.graph_store import GraphStore
+
+# Initialize Context with Hybrid Retrieval (Graph + Vector)
+context = AgentContext(
+ vector_store=VectorStore(backend="faiss"),
+ knowledge_graph=GraphStore(backend="neo4j"), # Optional: Use persistent graph
+ hybrid_alpha=0.75 # 75% weight to Knowledge Graph, 25% to Vector
+)
+
+# Store memory with automatic entity linking
+context.store(
+ "User is building a RAG system with Semantica",
+ metadata={"priority": "high", "topic": "rag"}
+)
+
+# Retrieve with context expansion
+results = context.retrieve("What is the user building?", use_graph_expansion=True)
+```
+
+**Core Notebooks:**
+- [**Context Module Introduction**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/19_Context_Module.ipynb) - Basic memory and storage.
+- [**Advanced Context Engineering**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/advanced/11_Advanced_Context_Engineering.ipynb) - Hybrid retrieval, graph builders, and custom memory policies.
+
+**Related Components:**
+[**Vector Store**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/13_Vector_Store.ipynb) β’ [**Embedding Generation**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/12_Embedding_Generation.ipynb) β’ [**Advanced Vector Store**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/advanced/Advanced_Vector_Store_and_Search.ipynb)
+
+### Knowledge Graph-Powered RAG (GraphRAG)
+
+> **30% Accuracy Improvement** β’ Vector + Graph Hybrid Search β’ 91% Accuracy
+
+```python
+from semantica.qa_rag import GraphRAGEngine
+from semantica.vector_store import VectorStore
+
+graphrag = GraphRAGEngine(
+ vector_store=VectorStore(backend="faiss"),
+ knowledge_graph=kg
+)
+result = graphrag.query("Who founded the company?", top_k=5, expand_graph=True)
+print(f"Answer: {result.answer} (Confidence: {result.confidence:.2f})")
+```
+
+[**Cookbook: GraphRAG**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/use_cases/advanced_rag/01_GraphRAG_Complete.ipynb)
+
+### Pipeline Orchestration & Parallel Processing
+
+> **Orchestrator-Worker Pattern** β’ Parallel Execution β’ Scalable Processing
+
+```python
+from semantica.pipeline import PipelineBuilder, ExecutionEngine
+
+pipeline = PipelineBuilder() \
+ .add_step("ingest", "custom", func=ingest_data) \
+ .add_step("extract", "custom", func=extract_entities) \
+ .add_step("build", "custom", func=build_graph) \
+ .build()
+
+result = ExecutionEngine().execute_pipeline(pipeline, parallel=True)
+```
+
+
+
+### Production-Ready Quality Assurance
+
+> **Enterprise-Grade QA** β’ Conflict Detection β’ Deduplication
+
+```python
+from semantica.deduplication import DuplicateDetector
+from semantica.conflicts import ConflictDetector
+
+entities = kg.get("entities", [])
+conflicts = ConflictDetector().detect_conflicts(entities)
+duplicates = DuplicateDetector(similarity_threshold=0.85).detect_duplicates(entities)
+
+print(f"Conflicts: {len(conflicts)} | Duplicates: {len(duplicates)}")
+```
+
+[**Cookbook: Conflict Detection & Resolution**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/17_Conflict_Detection_and_Resolution.ipynb) β’ [**Deduplication**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/18_Deduplication.ipynb)
+
+### Export & Integration
+
+> **Multi-Format Export** β’ JSON, CSV, RDF, GraphML
+
+```python
+from semantica.export import GraphExporter
+
+exporter = GraphExporter(kg)
+exporter.export("graph.json", format="json")
+exporter.export("graph.ttl", format="turtle")
+```
+
+[**Cookbook: Export**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/15_Export.ipynb) β’ [**Multi-Format Export**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/advanced/05_Multi_Format_Export.ipynb) β’ [**Multi-Source Integration**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/advanced/06_Multi_Source_Data_Integration.ipynb)
+
+## π Quick Start
+
+> **For comprehensive examples, see the [**Cookbook**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook) with 50+ interactive notebooks!**
+
+```python
+from semantica.core import Semantica
+
+# Initialize and build knowledge graph
+core = Semantica(ner_model="transformer", relation_strategy="hybrid")
+documents = ["doc1.txt", "doc2.txt", "doc3.txt"]
+kg = core.build_knowledge_graph(documents, merge_entities=True)
+
+# Query the graph
+result = kg.query("Who founded the company?", return_format="structured")
+print(f"Answer: {result.answer} | Nodes: {kg.node_count}, Edges: {kg.edge_count}")
+```
+
+[**Cookbook: Your First Knowledge Graph**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/introduction/08_Your_First_Knowledge_Graph.ipynb)
+
+## π― Use Cases
+
+**Enterprise Knowledge Engineering** β Unify data sources into knowledge graphs, breaking down silos.
+
+**AI Agents & Autonomous Systems** β Build agents with persistent memory and semantic understanding.
+
+**Multi-Format Document Processing** β Process 50+ formats through a unified pipeline.
+
+**Data Pipeline Processing** β Build scalable pipelines with parallel execution.
+
+**Intelligence & Security** β Analyze networks, threat intelligence, forensic analysis.
+
+**Finance & Trading** β Fraud detection, market intelligence, risk assessment.
+
+**Healthcare & Biomedical** β Clinical reports, drug discovery, medical literature analysis.
+
+[**Explore Use Case Examples**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/use_cases) β See real-world implementations in finance, healthcare, cybersecurity, trading, and more.
+
+## π¬ Advanced Features
+
+**Incremental Updates** β Real-time stream processing with Kafka, RabbitMQ, Kinesis for live updates.
+
+**Multi-Language Support** β Process 50+ languages with automatic detection.
+
+**Custom Ontology Import** β Import and extend Schema.org and custom ontologies.
+
+**Advanced Reasoning** β Deductive, inductive, abductive reasoning with HermiT/Pellet.
+
+**Graph Analytics** β Centrality, community detection, path finding, temporal analysis.
+
+**Custom Pipelines** β Build custom pipelines with parallel execution.
+
+**API Integration** β Integrate external APIs for entity enrichment.
+
+[**See Advanced Examples**](https://github.com/Hawksight-AI/semantica/tree/main/cookbook/advanced) β Advanced extraction, graph analytics, reasoning, and more.
+
+## πΊοΈ Roadmap
+
+### Q1 2026
+- [x] Core framework (v1.0)
+- [x] GraphRAG engine
+- [x] 6-stage ontology pipeline
+- [ ] Quality assurance features and Quality Assurance module
+- [ ] Enhanced multi-language support
+- [ ] Real-time streaming improvements
+- [ ] Advanced reasoning v2
+
+### Q2 2026
+- [ ] Multi-modal processing
+
+---
+
+## π€ Community & Support
+
+### Join Our Community
+
+| **Channel** | **Purpose** |
+|:-----------:|:-----------|
+| [**Discord**](https://discord.gg/semantica) | Real-time help, showcases |
+| [**GitHub Discussions**](https://github.com/Hawksight-AI/semantica/discussions) | Q&A, feature requests |
+
+### Learning Resources
+
+
+### Enterprise Support
+
+| **Tier** | **Features** | **SLA** | **Price** |
+|:--------:|:-----------|:-------:|:--------:|
+| **Community** | Public support | Best effort | Free |
+| **Professional** | Email support | 48h | Contact |
+| **Enterprise** | 24/7 support | 4h | Contact |
+| **Premium** | Phone, custom dev | 1h | Contact |
+
+**Contact:** [GitHub Issues](https://github.com/Hawksight-AI/semantica/issues) with "[Enterprise]" prefix
+
+## π€ Contributing
+
+### How to Contribute
+
+```bash
+# Fork and clone
+git clone https://github.com/your-username/semantica.git
+cd semantica
+
+# Create branch
+git checkout -b feature/your-feature
+
+# Install dev dependencies
+pip install -e ".[dev,test]"
+
+# Make changes and test
+pytest tests/
+black semantica/
+flake8 semantica/
+
+# Commit and push
+git commit -m "Add feature"
+git push origin feature/your-feature
+```
+
+### Contribution Types
+
+1. **Code** - New features, bug fixes
+2. **Documentation** - Improvements, tutorials
+3. **Bug Reports** - [Create issue](https://github.com/Hawksight-AI/semantica/issues/new)
+4. **Feature Requests** - [Request feature](https://github.com/Hawksight-AI/semantica/issues/new)
+
+### Recognition
+
+Contributors receive:
+- Recognition in [CONTRIBUTORS.md](https://github.com/Hawksight-AI/semantica/blob/main/CONTRIBUTORS.md)
+- GitHub badges
+- Semantica swag
+- Featured showcases
+
+## π Contributors
+
+
+
+
+
+## π License
+
+Semantica is licensed under the **MIT License** - see the [LICENSE](https://github.com/Hawksight-AI/semantica/blob/main/LICENSE) file for details.
+
+
+
+**Built by the Semantica Community**
+
+[GitHub](https://github.com/Hawksight-AI/semantica) β’ [Discord](https://discord.gg/semantica)
+
+
diff --git a/cookbook/advanced/Advanced_Vector_Store_and_Search.ipynb b/cookbook/advanced/Advanced_Vector_Store_and_Search.ipynb
index 33630060..3176bcfb 100644
--- a/cookbook/advanced/Advanced_Vector_Store_and_Search.ipynb
+++ b/cookbook/advanced/Advanced_Vector_Store_and_Search.ipynb
@@ -69,7 +69,7 @@
"\n",
"### Simple Rule\n",
"- Less than 10,000 items? Use **Flat**\n",
- "- Between 10,000 and 1 million? Use **HNSW** \u2705 (recommended)\n",
+ "- Between 10,000 and 1 million? Use **HNSW** β
(recommended)\n",
"- More than 1 million? Use **IVF**"
]
},
@@ -286,7 +286,7 @@
"# Small dataset (< 10,000 items)\n",
"index = adapter.create_index(index_type=\"flat\", metric=\"L2\")\n",
"\n",
- "# Medium dataset (10,000 - 1,000,000 items) \u2705 RECOMMENDED\n",
+ "# Medium dataset (10,000 - 1,000,000 items) β
RECOMMENDED\n",
"index = adapter.create_index(index_type=\"hnsw\", metric=\"L2\", m=16)\n",
"\n",
"# Large dataset (> 1,000,000 items)\n",
@@ -340,10 +340,10 @@
"\n",
"You've learned:\n",
"\n",
- "1. \u2705 **Index Selection**: Use HNSW for most cases\n",
- "2. \u2705 **Smart Filtering**: Combine vector search with metadata\n",
- "3. \u2705 **Result Fusion**: Merge searches from different sources\n",
- "4. \u2705 **Data Isolation**: Keep users' data separate\n",
+ "1. β
**Index Selection**: Use HNSW for most cases\n",
+ "2. β
**Smart Filtering**: Combine vector search with metadata\n",
+ "3. β
**Result Fusion**: Merge searches from different sources\n",
+ "4. β
**Data Isolation**: Keep users' data separate\n",
"\n",
"### Next Steps\n",
"\n",
@@ -377,4 +377,4 @@
},
"nbformat": 4,
"nbformat_minor": 2
-}
\ No newline at end of file
+}
diff --git a/cookbook/use_cases/advanced_rag/02_RAG_vs_GraphRAG_Comparison.ipynb b/cookbook/use_cases/advanced_rag/02_RAG_vs_GraphRAG_Comparison.ipynb
new file mode 100644
index 00000000..8e789c7f
--- /dev/null
+++ b/cookbook/use_cases/advanced_rag/02_RAG_vs_GraphRAG_Comparison.ipynb
@@ -0,0 +1,277 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# RAG vs. GraphRAG: A Side-by-Side Comparison\n",
+ "\n",
+ "This notebook demonstrates the difference between **Standard RAG** (Vector-based) and **GraphRAG** (Graph-based) using the `semantica` framework. We will use a real-world text source to build both systems and compare their retrieval capabilities.\n",
+ "\n",
+ "## What is the difference?\n",
+ "- **Standard RAG**: Retrieves documents based on semantic similarity (vector distance). Good for direct matching but can miss connected concepts.\n",
+ "- **GraphRAG**: Retrieves information by traversing a Knowledge Graph (nodes and edges). Excellent for multi-hop reasoning and understanding relationships between entities.\n",
+ "\n",
+ "## Workflow\n",
+ "1. **Ingest Data**: Load a technical article.\n",
+ "2. **Build Standard RAG**: Chunk text -> Embeddings -> Vector Store -> Similarity Search.\n",
+ "3. **Build GraphRAG**: Extract Entities/Relations -> Knowledge Graph -> Graph Traversal.\n",
+ "4. **Compare Results**: Ask the same complex question to both systems."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Install semantica if not already installed\n",
+ "!pip install semantica networkx matplotlib plotly sentence-transformers"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "import networkx as nx\n",
+ "import matplotlib.pyplot as plt\n",
+ "import numpy as np\n",
+ "\n",
+ "# Import Semantica Core Modules\n",
+ "from semantica.core import Semantica\n",
+ "from semantica.ingest import WebIngestor\n",
+ "from semantica.split import TextSplitter # Proper Semantica splitter\n",
+ "from semantica.vector_store import FAISSStore\n",
+ "from semantica.embeddings import EmbeddingGenerator # Proper embedding generator\n",
+ "from semantica.semantic_extract import NamedEntityRecognizer, RelationExtractor\n",
+ "from semantica.kg import GraphBuilder\n",
+ "from semantica.visualization import KGVisualizer # Proper visualization module\n",
+ "\n",
+ "# Initialize Semantica\n",
+ "semantica = Semantica()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## 1. Data Ingestion\n",
+ "We'll use a text about **\"The Impact of AI on Healthcare\"**. This topic has rich relationships (AI -> improves -> Diagnosis, Privacy -> challenges -> AI)."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Sample \"Real World\" Data Source\n",
+ "text_content = \"\"\"\n",
+ "Artificial Intelligence (AI) is revolutionizing healthcare by enabling early diagnosis and personalized treatment plans.\n",
+ "Machine Learning algorithms analyze medical imaging to detect anomalies like tumors faster than human radiologists.\n",
+ "For instance, DeepMind's AlphaFold has solved the protein folding problem, accelerating drug discovery.\n",
+ "However, the integration of AI in healthcare faces significant challenges, primarily concerning patient data privacy and algorithmic bias.\n",
+ "Regulatory bodies like the FDA are establishing guidelines to ensure AI tools are safe and effective.\n",
+ "Unlike traditional software, AI systems can adapt and learn, which complicates validation processes.\n",
+ "Hospitals using predictive analytics have seen a 30% reduction in patient readmission rates.\n",
+ "Yet, cybersecurity threats remain a critical risk for connected medical devices.\n",
+ "\"\"\"\n",
+ "\n",
+ "print(f\"Loaded text with {len(text_content)} characters.\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## 2. Standard RAG (Vector Search)\n",
+ "We will chunk the text using `TextSplitter`, create embeddings with `EmbeddingGenerator`, and store them in a `FAISSStore`."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# 1. Split Text using Semantica's TextSplitter\n",
+ "splitter = TextSplitter(method=\"recursive\", chunk_size=100, chunk_overlap=20)\n",
+ "chunks = splitter.split(text_content)\n",
+ "\n",
+ "# Extract text from chunk objects\n",
+ "chunk_texts = [chunk.text for chunk in chunks]\n",
+ "print(f\"Created {len(chunks)} chunks.\")\n",
+ "\n",
+ "# 2. Initialize Vector Store\n",
+ "vector_store = FAISSStore(dimension=384) # Standard dimension for MiniLM\n",
+ "vector_store.create_index(index_type=\"flat\", metric=\"L2\")\n",
+ "\n",
+ "# 3. Generate Embeddings using Semantica's EmbeddingGenerator\n",
+ "# This uses local Sentence Transformers by default\n",
+ "generator = EmbeddingGenerator(text={\"method\": \"sentence_transformers\", \"model_name\": \"all-MiniLM-L6-v2\"})\n",
+ "embeddings = generator.generate_embeddings(chunk_texts, data_type=\"text\")\n",
+ "\n",
+ "# 4. Store Vectors\n",
+ "vector_store.add_vectors(embeddings, ids=[f\"chunk_{i}\" for i in range(len(chunks))])\n",
+ "\n",
+ "# 5. Define a search function\n",
+ "def standard_rag_search(query):\n",
+ " # Generate query embedding\n",
+ " query_vec = generator.generate_embeddings(query, data_type=\"text\")\n",
+ " \n",
+ " # Search\n",
+ " results = vector_store.search_similar(query_vec, k=2)\n",
+ " \n",
+ " # Retrieve actual text\n",
+ " retrieved_texts = []\n",
+ " for res in results:\n",
+ " idx = int(res['id'].split('_')[1])\n",
+ " retrieved_texts.append(chunk_texts[idx])\n",
+ " return retrieved_texts\n",
+ "\n",
+ "print(\"Standard RAG Pipeline Built.\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## 3. GraphRAG (Knowledge Graph)\n",
+ "Now we extract entities and relationships to build a structured graph using `GraphBuilder` and visualize it with `KGVisualizer`."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# 1. Extract Entities and Relations\n",
+ "ner = NamedEntityRecognizer()\n",
+ "rel_extractor = RelationExtractor()\n",
+ "\n",
+ "entities = ner.extract_entities(text_content)\n",
+ "relations = rel_extractor.extract_relations(text_content, entities=entities)\n",
+ "\n",
+ "print(f\"Extracted {len(entities)} entities and {len(relations)} relationships.\")\n",
+ "\n",
+ "# 2. Build Graph using Semantica's GraphBuilder\n",
+ "builder = GraphBuilder()\n",
+ "kg = builder.build([{\"entities\": entities, \"relationships\": relations}])\n",
+ "\n",
+ "# 3. Visualize Graph using Semantica's KGVisualizer\n",
+ "viz = KGVisualizer()\n",
+ "fig = viz.visualize_network(kg, output=\"interactive\")\n",
+ "fig.show()\n",
+ "\n",
+ "# Fallback static visualization if interactive fails in some environments\n",
+ "# plt.figure(figsize=(10, 8))\n",
+ "# pos = nx.spring_layout(kg, k=0.5)\n",
+ "# nx.draw(kg, pos, with_labels=True, node_color='lightblue', node_size=2000, font_size=10)\n",
+ "# edge_labels = nx.get_edge_attributes(kg, 'relation')\n",
+ "# nx.draw_networkx_edge_labels(kg, pos, edge_labels=edge_labels)\n",
+ "# plt.show()"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# 4. Define Graph Search Function\n",
+ "def graph_rag_search(start_entity, hops=1):\n",
+ " if start_entity not in kg:\n",
+ " # Try simple fuzzy match\n",
+ " for node in kg.nodes():\n",
+ " if start_entity.lower() in node.lower():\n",
+ " start_entity = node\n",
+ " break\n",
+ " else:\n",
+ " return [f\"Entity '{start_entity}' not found in graph.\"]\n",
+ " \n",
+ " # Traverse graph\n",
+ " subgraph_nodes = list(nx.bfs_tree(kg, source=start_entity, depth_limit=hops))\n",
+ " subgraph = kg.subgraph(subgraph_nodes)\n",
+ " \n",
+ " # Convert paths to natural language\n",
+ " facts = []\n",
+ " for u, v, data in subgraph.edges(data=True):\n",
+ " relation = data.get('relation', 'related to')\n",
+ " facts.append(f\"{u} --[{relation}]--> {v}\")\n",
+ " \n",
+ " return facts"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## 4. Comparison Results\n",
+ "Let's compare what each system retrieves for the query: **\"What are the risks associated with AI?\"**"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "query = \"What are the risks associated with AI?\"\n",
+ "\n",
+ "print(f\"Query: {query}\\n\")\n",
+ "\n",
+ "print(\"--- Standard RAG Results (Vector Similarity) ---\")\n",
+ "rag_results = standard_rag_search(query)\n",
+ "for i, res in enumerate(rag_results):\n",
+ " print(f\"{i+1}. {res}...\")\n",
+ "\n",
+ "print(\"\\n--- GraphRAG Results (Graph Traversal) ---\")\n",
+ "# In a full system, we would link the query \"AI\" to the node \"Artificial Intelligence\"\n",
+ "graph_results = graph_rag_search(\"Artificial Intelligence\", hops=2)\n",
+ "for i, res in enumerate(graph_results):\n",
+ " print(f\"{i+1}. {res}\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Conclusion\n",
+ "\n",
+ "| Feature | Standard RAG | GraphRAG |\n",
+ "|---------|--------------|----------|\n",
+ "| **Mechanism** | Semantic Similarity (Vector) | Graph Traversal (Structural) |\n",
+ "| **Strengths** | Fast, good for general queries | Captures explicit relationships, multi-hop reasoning |\n",
+ "| **Weaknesses**| May miss disconnected chunks | Requires entity extraction & graph construction overhead |\n",
+ "| **Best For** | Fact retrieval | Complex reasoning & relationship mapping |\n",
+ "\n",
+ "**Semantica** allows you to combine both into a **Hybrid RAG** system for optimal performance."
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Python 3",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.8.5"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}
\ No newline at end of file
diff --git a/docs/cookbook.md b/docs/cookbook.md
index 64f4ea21..8117a565 100644
--- a/docs/cookbook.md
+++ b/docs/cookbook.md
@@ -44,6 +44,16 @@ Hand-picked tutorials to show you the power of Semantica.
[Open Notebook](https://github.com/Hawksight-AI/semantica/blob/main/cookbook/use_cases/advanced_rag/01_GraphRAG_Complete.ipynb)
+- :material-scale-balance: **RAG vs. GraphRAG Comparison**
+ ---
+ Side-by-side comparison of Standard RAG vs. GraphRAG using real-world data.
+
+ **Topics**: RAG, GraphRAG, Benchmarking, Visualization
+
+ **Difficulty**: Intermediate
+
+ [Open Notebook](https://github.com/Hawksight-AI/semantica/blob/main/cookbook/use_cases/advanced_rag/02_RAG_vs_GraphRAG_Comparison.ipynb)
+
- :material-graph: **Your First Knowledge Graph**
---
Go from raw text to a queryable knowledge graph in 20 minutes.
diff --git a/docs/use-cases.md b/docs/use-cases.md
index d57b52dd..10623609 100644
--- a/docs/use-cases.md
+++ b/docs/use-cases.md
@@ -252,6 +252,7 @@ ontology = ontology_gen.generate_from_graph(kg)
**Goal**: Use the knowledge graph to retrieve precise context for RAG applications.
[:material-arrow-right: View Cookbook](https://github.com/Hawksight-AI/semantica/blob/main/cookbook/use_cases/advanced_rag/01_GraphRAG_Complete.ipynb)
+ [:material-scale-balance: RAG vs GraphRAG Benchmark](https://github.com/Hawksight-AI/semantica/blob/main/cookbook/use_cases/advanced_rag/02_RAG_vs_GraphRAG_Comparison.ipynb)
- :material-domain: **Corporate Intelligence**
---