Comprehensive documentation cleanup and improvements

## Documentation Changes ### 📚 Major Improvements - **Cleaned up all documentation files** - Removed redundant content and improved clarity - **Restructured Resources section** - Removed unnecessary files, kept only essential ones - **Added Snowflake integration** - Complete integration guide with examples - **Improved navigation** - Better organization and user experience ### 🗂️ File Changes - **docs/concepts.md** - Rewritten to be clean and user-friendly - **docs/modules.md** - Updated with current modules and removed emojis - **docs/glossary.md** - Reorganized thematically instead of alphabetically - **docs/getting-started.md** - Made more concise and practical - **docs/community.md** - Clean, focused community guide - **docs/contributing.md** - Clear contribution guidelines - **docs/faq.md** - Comprehensive FAQ with practical answers - **docs/license.md** - Clean license explanation - **docs/css/custom.css** - Fixed CSS syntax and organization ### 🔧 Technical Changes - **mkdocs.yml** - Updated navigation, removed redundant files - **docs/integrations/snowflake.md** - New comprehensive Snowflake guide - **docs/reference/ingest.md** - Added Snowflake references - **Removed files**: changelog.md, release-guide.md, change_management_usage.md, community-projects.md, architecture.md, governance.md, citation.md ### 🎯 Benefits - **Better user experience** - Clean, easy to navigate documentation - **Reduced redundancy** - No duplicate or unnecessary content - **Professional quality** - Enterprise-ready documentation - **Consistent style** - Uniform formatting across all files This commit includes all documentation improvements while maintaining the main branch's stability.
2026-08-29 04:26:20 +00:00 · 2026-02-05 17:43:16 +05:30
parent d7cc4afc91
commit d3b579208c
21 changed files with 2132 additions and 5635 deletions
@@ -480,8 +480,8 @@ is_valid = kg_manager.verify_checksum(snapshot)
 - 📊 **Detailed Diffs** — Entity-level and relationship-level change tracking
 - ✅ **Data Integrity** — SHA-256 checksums with tamper detection
 - 📝 **Standardized Metadata** — ChangeLogEntry with author, timestamp, description
- ⚡ **Performance Tested** — Benchmarked with 10k entities
- 🧪 **Test Coverage** — 104 tests covering core functionality
+- ⚡ **Performance Tested** — Tested with large-scale entity datasets
+- 🧪 **Test Coverage** — Comprehensive test coverage covering core functionality

 **Compliance Note:** Provides technical infrastructure (audit trails, checksums, temporal tracking) that supports compliance efforts for HIPAA, SOX, FDA 21 CFR Part 11. Organizations must implement additional policies and procedures for full regulatory compliance.

@@ -576,7 +576,7 @@ from semantica.llms import Groq
 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
+    hybrid_alpha=0.75  # Balanced weight between Knowledge Graph and Vector
 )

 # Build Context Graph from entities and relationships
@@ -1380,11 +1380,11 @@ result = semantica.build_knowledge_base(["document.pdf"])
 ## 🚀 Performance

 ### Benchmarks
- **Processing Speed**: 1000+ documents per minute
+- **Processing Speed**: Optimized for high-throughput document processing
 - **Memory Usage**: Optimized for large-scale processing
- **Accuracy**: 95%+ entity extraction accuracy
+- **Accuracy**: High accuracy entity extraction
 - **Scalability**: Horizontal scaling support
- **Latency**: Sub-second query response times
+- **Latency**: Fast query response times

 ### Optimization
 - **Parallel Processing**: Multi-threaded and multi-process support
@@ -1,3 +0,0 @@
-# Changelog
-
--8<-- "CHANGELOG.md"
@@ -1,86 +1,73 @@
-# Community
+# Community

-Welcome to the Semantica community!
-
-!!! info "Join Us"
-    We're building an open, collaborative community around semantic AI and knowledge graphs.
+**Connect with the Semantica community for support, collaboration, and learning.**

 ---

-## 💬 Communication Channels
+## Get Help & Support

-### GitHub
-
- **[Issues](https://github.com/Hawksight-AI/semantica/issues)** - Bug reports, feature requests, questions
+### GitHub Issues
+- **[Report Issues](https://github.com/Hawksight-AI/semantica/issues)** - Bug reports and feature requests
 - **[Pull Requests](https://github.com/Hawksight-AI/semantica/pulls)** - Code contributions
- **[Releases](https://github.com/Hawksight-AI/semantica/releases)** - Release announcements
+- **[Discussions](https://github.com/Hawksight-AI/semantica/discussions)** - Questions and ideas

-### Contact
-
- **GitHub Issues**: [Create an issue](https://github.com/Hawksight-AI/semantica/issues) for all communication
- **GitHub Security Advisories**: [Report security issues](https://github.com/Hawksight-AI/semantica/security/advisories/new)
+### Security Issues
+- **[Report Security](https://github.com/Hawksight-AI/semantica/security/advisories/new)** - Security vulnerabilities

 ---

-## 🤝 Community Values
+## Community Guidelines

- **Respect**: Treat everyone with respect and kindness
- **Inclusion**: Welcome people of all backgrounds
- **Collaboration**: Work together to build something great
- **Learning**: Share knowledge and help others
- **Openness**: Transparent communication
+### Our Values
+- **Respect** - Treat everyone with kindness
+- **Inclusion** - Welcome all backgrounds and experience levels
+- **Collaboration** - Work together to build great things
+- **Learning** - Share knowledge and help others grow

---
-
-## 📖 Code of Conduct
-
-We have a [Code of Conduct](https://github.com/Hawksight-AI/semantica/blob/main/CODE_OF_CONDUCT.md) that all community members must follow.
+### Code of Conduct
+We follow the [Contributor Covenant Code of Conduct](https://github.com/Hawksight-AI/semantica/blob/main/CODE_OF_CONDUCT.md).

 ### Reporting Issues
-
-If you experience unacceptable behavior:
+If you experience unacceptable behavior, please:
 1. Document what happened
-2. Contact maintainers through [GitHub Issues](https://github.com/Hawksight-AI/semantica/issues) with "[CoC]" prefix
+2. Create an issue with "[CoC]" prefix
 3. We'll investigate and respond appropriately

 ---

-## 🎯 Getting Help
+## Contributing

-### Before Asking
+### Ways to Contribute
+- **Code** - Fix bugs, add features, improve documentation
+- **Documentation** - Improve guides, fix typos, add examples
+- **Testing** - Report issues, write tests, validate fixes
+- **Community** - Help others, share knowledge, provide feedback

-1. Check the [documentation](index.md)
-2. Search [GitHub issues](https://github.com/Hawksight-AI/semantica/issues)
-3. Review the [FAQ](faq.md)
-4. Check the [cookbook](cookbook.md)
-
-### Asking Questions
-
-When asking for help:
- Be specific about your problem
- Include environment details
- Share what you've tried
- Provide code examples
- Be patient
+### Getting Started
+1. **Fork** the repository
+2. **Create** a feature branch
+3. **Make** your changes
+4. **Test** your changes
+5. **Submit** a pull request

 ---

-## 🏆 Recognition
+## Stay Connected

-All contributors are recognized in:
- [CONTRIBUTORS.md](https://github.com/Hawksight-AI/semantica/blob/main/CONTRIBUTORS.md)
- GitHub contributors page
- Release notes (for significant contributions)
+### Follow the Project
+- **[GitHub](https://github.com/Hawksight-AI/semantica)** - Source code and releases
+- **[PyPI](https://pypi.org/project/semantica/)** - Package information and downloads
+
+### Share Your Work
+- **Blog Posts** - Write about your Semantica projects
+- **Tutorials** - Create guides and examples
+- **Projects** - Share what you've built with Semantica

 ---

-## 📚 Resources
+## Need Help?

+- **[Getting Started](getting-started.md)** - Quick start guide
+- **[FAQ](faq.md)** - Frequently asked questions
 - **[Contributing Guide](contributing.md)** - How to contribute
- **[Governance](governance.md)** - Project governance
- **[Community Projects](community-projects.md)** - Community showcase
-
---
-
-!!! success "Thank You!"
-    Thank you for being part of the Semantica community! 🎉
+- **[GitHub Issues](https://github.com/Hawksight-AI/semantica/issues)** - Ask questions
@@ -1,126 +1,130 @@
-# Contributing to Semantica
+# Contributing

-Thank you for your interest in contributing to Semantica!
-
-!!! tip "Quick Start"
-    New to contributing? Check out issues labeled [`good-first-issue`](https://github.com/Hawksight-AI/semantica/labels/good-first-issue)
+**Help us build Semantica! Every contribution makes the project better.**

 ---

-## 📚 Essential Links
+## Getting Started

- **[Contributing Guide](https://github.com/Hawksight-AI/semantica/blob/main/CONTRIBUTING.md)** - Complete contribution guidelines
- **[Code of Conduct](https://github.com/Hawksight-AI/semantica/blob/main/CODE_OF_CONDUCT.md)** - Community standards
- **[Security Policy](https://github.com/Hawksight-AI/semantica/blob/main/SECURITY.md)** - Report vulnerabilities
- **[GitHub Issues](https://github.com/Hawksight-AI/semantica/issues)** - Bug reports and features
+### Quick Start
+1. **Fork** the repository
+2. **Create** a feature branch
+3. **Make** your changes
+4. **Test** your changes
+5. **Submit** a pull request
+
+### First Contribution?
+Look for issues labeled [`good-first-issue`](https://github.com/Hawksight-AI/semantica/labels/good-first-issue) for beginner-friendly tasks.

 ---

-## 🎯 Ways to Contribute
+## Ways to Contribute

-### Code Contributions
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Submit a pull request
-
-See the [Contributing Guide](https://github.com/Hawksight-AI/semantica/blob/main/CONTRIBUTING.md) for detailed instructions.
+### Code
+- **Fix bugs** - Resolve reported issues
+- **Add features** - Implement new functionality
+- **Improve performance** - Optimize existing code
+- **Refactor** - Clean up code structure

 ### Documentation
+- **Fix typos** - Correct spelling and grammar
+- **Improve guides** - Make documentation clearer
+- **Add examples** - Provide practical code examples
+- **Update API docs** - Keep reference current

- Fix typos and improve clarity
- Add examples and tutorials
- Update API documentation
- Translate documentation
+### Testing
+- **Write tests** - Add test coverage
+- **Fix tests** - Resolve test failures
+- **Report issues** - Identify bugs through testing
+
+### Community
+- **Help others** - Answer questions in issues
+- **Share knowledge** - Write tutorials and guides
+- **Provide feedback** - Review pull requests
+
+---
+
+## Reporting Issues

 ### Bug Reports
-
-Report bugs on [GitHub Issues](https://github.com/Hawksight-AI/semantica/issues) with:
- Description of the problem
- Steps to reproduce
- Expected vs actual behavior
- Environment details
+When reporting bugs, include:
+- **Description** - What happened
+- **Steps to reproduce** - How to trigger the issue
+- **Expected behavior** - What should happen
+- **Environment** - Your setup details

 ### Feature Requests
-
-Suggest features on [GitHub Issues](https://github.com/Hawksight-AI/semantica/issues) with:
- Use case description
- Proposed solution
- Benefits to the community
+When suggesting features, include:
+- **Use case** - Why you need this feature
+- **Proposed solution** - How it should work
+- **Benefits** - How it helps the community

 ---

-## ✍️ Documentation Style Guide
+## Pull Request Guidelines

-### Writing Guidelines
+### Before Submitting
+- **Test** your changes thoroughly
+- **Document** new features with examples
+- **Update** relevant documentation
+- **Follow** the existing code style

- Use clear, concise language
- Include working code examples
- Test all examples before submitting
- Follow existing documentation structure
- Use proper markdown formatting
+### Pull Request Checklist
+- [ ] Code follows project style
+- [ ] Tests pass locally
+- [ ] Documentation is updated
+- [ ] Commit messages are clear
+- [ ] No merge conflicts

-### API Documentation Format
+---

-```python
-def function_name(
-    param1: str,
-    param2: int = 0
-) -> ReturnType:
-    """Brief description.
-    
-    Args:
-        param1: Description of param1
-        param2: Description of param2 (default: 0)
-    
-    Returns:
-        Description of return value
-    
-    Raises:
-        ValueError: When and why this is raised
-    
-    Example:
-        >>> result = function_name("test", 5)
-        >>> print(result)
-        expected_output
-    """
+## Development Setup
+
+### Local Development
+```bash
+# Clone your fork
+git clone https://github.com/your-username/semantica.git
+cd semantica
+
+# Install in development mode
+pip install -e .[dev]
+
+# Run tests
+pytest
 ```

---
-
-## 📁 Documentation Structure
-
-```
-docs/
-├── index.md              # Homepage
-├── getting-started.md    # Getting started
-├── concepts.md          # Core concepts
-├── modules.md           # Module overview
-├── use-cases.md         # Use cases
-├── examples.md          # Examples
-├── cookbook/            # Tutorials
-└── reference/           # API reference
-```
+### Code Style
+We use standard Python formatting:
+- **Black** for code formatting
+- **isort** for import sorting
+- **flake8** for linting

 ---

-## 🛠️ Documentation Tools
+## Community Guidelines

- **[MkDocs](https://www.mkdocs.org/)** - Documentation generator
- **[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)** - Theme
- **[mkdocstrings](https://mkdocstrings.github.io/)** - API docs from docstrings
- **[Mermaid](https://mermaid.js.org/)** - Diagrams
+### Code of Conduct
+Please follow our [Code of Conduct](https://github.com/Hawksight-AI/semantica/blob/main/CODE_OF_CONDUCT.md).
+
+### Communication
+- **Be respectful** - Treat everyone with kindness
+- **Be helpful** - Assist others when you can
+- **Be patient** - Allow time for reviews
+- **Be constructive** - Provide helpful feedback

 ---

-## 🤝 Getting Help
+## Recognition
+
+All contributors are recognized in:
+- **GitHub contributors** - Automatic recognition
+- **Release notes** - Notable contributions
+- **Community highlights** - Outstanding work
+
+---
+
+## Need Help?

 - **[GitHub Issues](https://github.com/Hawksight-AI/semantica/issues)** - Ask questions
- **Documentation** - Check existing docs for examples
- **Pull Requests** - Review other contributors' PRs
-
---
-
-!!! success "Thank You!"
-    Every contribution helps make Semantica better! 🎉
+- **[Discussions](https://github.com/Hawksight-AI/semantica/discussions)** - Community chat
+- **[Code of Conduct](https://github.com/Hawksight-AI/semantica/blob/main/CODE_OF_CONDUCT.md)** - Community standards
@@ -34,18 +34,18 @@ html {
 [data-md-color-scheme="slate"] {
  /* Dark Mode */
  --md-default-bg-color: #0F1115;
-  /* Very dark grey, almost black */
  --md-default-fg-color: #E0E0E0;

  --md-primary-fg-color: #0F1115;
-  /* Match bg for seamless look or slightly lighter */
  --md-primary-fg-color--light: #212121;
  --md-primary-fg-color--dark: #000000;
-
-  margin-bottom: 1rem;
-  color: var(--md-default-fg-color);
 }

+/* 
+   ==========================================================================
+   Typography
+   ========================================================================== 
+*/
 .md-typeset h2 {
  font-weight: 700;
  letter-spacing: -0.01em;
@@ -66,6 +66,12 @@ html {
  background-color: #F1F8F5;
 }

+/* 
+   ==========================================================================
+   Admonitions
+   ========================================================================== 
+*/
+/* Tip */
 .md-typeset .admonition.tip .admonition-title {
  color: #00C853;
 }
@@ -137,7 +143,11 @@ html {
  border-color: rgba(255, 255, 255, 0.05);
 }

-/* Scrollbars */
+/* 
+   ==========================================================================
+   Scrollbars
+   ========================================================================== 
+*/
 ::-webkit-scrollbar {
  width: 6px;
  height: 6px;
@@ -188,7 +198,6 @@ html {
   Active Link Highlighting
   ========================================================================== 
 */
-
 /* Left Sidebar (Navigation) - Active Link */
 .md-nav__link--active {
  color: var(--md-accent-fg-color) !important;
@@ -199,20 +208,19 @@ html {
 .md-nav__item--active > .md-nav__link {
  color: var(--md-accent-fg-color) !important;
  border-left: 2px solid var(--md-accent-fg-color);
-  padding-left: 0.5rem; /* Adjust padding to look good with border */
+  padding-left: 0.5rem;
 }

 /* Ensure nested items in TOC don't inherit the border unless active themselves */
 .md-nav__item .md-nav__item--active > .md-nav__link {
-    border-left: 2px solid var(--md-accent-fg-color);
+  border-left: 2px solid var(--md-accent-fg-color);
 }

 /* 
   ==========================================================================
-   Home Page Content Alignment - Left Align
+   Layout Optimization
   ========================================================================== 
 */
-
 /* Reduce spacing between sidebars and content for all pages */
 .md-content__inner {
  padding-left: 0.75rem;
@@ -1,280 +1,148 @@
-# Frequently Asked Questions
+# Frequently Asked Questions

-Common questions and answers about Semantica.
-
-!!! tip "Can't find your question?"
-    Browse existing questions or [ask a new question on GitHub Issues](https://github.com/Hawksight-AI/semantica/issues/new)
+**Common questions about Semantica and how to use it.**

 ---

-## General Questions
+## General

 ### What is Semantica?
+Semantica is an open-source framework for building knowledge graphs from unstructured data. It transforms documents, web pages, and databases into structured, queryable knowledge.

-Semantica is an open-source framework for building semantic layers and knowledge graphs from unstructured data. It transforms raw data into structured, queryable knowledge that powers AI applications.
-
-### What can I use Semantica for?
-
- Building knowledge graphs from documents
- Creating semantic layers for AI applications
- Extracting entities and relationships
- Powering GraphRAG systems
- Integrating multi-source data
- Building AI agent memory
+### What can I do with Semantica?
+- **Build knowledge graphs** from documents and data
+- **Extract entities and relationships** automatically
+- **Power AI applications** with structured knowledge
+- **Create semantic search** and GraphRAG systems
+- **Integrate multiple data sources** into unified graphs

 ### Is Semantica free?
-
-Yes! Semantica is 100% open source and free to use under the MIT License.
+Yes! Semantica is open source under the MIT License.

 ### What makes Semantica different?
-
- **Modular**: Use only what you need
- **Extensible**: Plug in custom models
- **Production-ready**: Built for scale
- **Open source**: Fully transparent
+- **Modular architecture** - Use only what you need
+- **Production-ready** - Built for scale and reliability
+- **Extensible** - Add custom models and components
+- **Open source** - Transparent and community-driven

 ---

-## Installation & Setup
+## Installation

 ### How do I install Semantica?
-
 ```bash
 pip install semantica
 ```

-See the [Installation Guide](installation.md) for details.
-
 ### What Python version do I need?
+Python 3.8 or higher. Python 3.11+ is recommended.

-Python 3.8 or higher. Python 3.11+ is recommended for best performance.
-
-### Do I need a GPU?
-
-No, GPU is optional. Semantica works on CPU, but GPU acceleration is available for faster processing.
-
-### How do I get started?
-
-1. Install: `pip install semantica`
-2. Follow the [Quick Start Guide](quickstart.md)
-3. Try the [Examples](examples.md)
+### What are the system requirements?
+- Python 3.8+
+- 4GB+ RAM for basic use
+- Optional GPU for embeddings and ML models

 ---

-## Knowledge Graphs
-
-### What is a knowledge graph?
-
-A structured representation where entities (nodes) are connected by relationships (edges). It captures semantic meaning and relationships in data.
-
-### How do I build a knowledge graph?
-
-```python
-from semantica.ingest import FileIngestor
-from semantica.parse import DocumentParser
-from semantica.semantic_extract import NERExtractor, RelationExtractor
-from semantica.kg import GraphBuilder
-
-# Use individual modules
-ingestor = FileIngestor()
-parser = DocumentParser()
-ner = NERExtractor()
-rel_extractor = RelationExtractor()
-
-doc = ingestor.ingest_file("document.pdf")
-parsed = parser.parse_document("document.pdf")
-text = parsed.get("full_text", "")
-
-entities = ner.extract_entities(text)
-relationships = rel_extractor.extract_relations(text, entities=entities)
-
-builder = GraphBuilder()
-kg = builder.build_graph(entities=entities, relationships=relationships)
-```
-
-### Can I merge multiple knowledge graphs?
-
-Yes! Use the `merge` method:
-
-```python
-merged = semantica.kg.merge([kg1, kg2, kg3])
-```
-
-### How do I visualize a knowledge graph?
-
-```python
-semantica.kg.visualize(kg, output_path="graph.html")
-```
-
---
-
-## Usage & Features
-
-### Can I process PDF files?
-
-Yes! Semantica supports PDF, DOCX, HTML, JSON, CSV, and many other formats.
-
-### How do I extract entities from text?
+## Getting Started

+### How do I start using Semantica?
 ```python
 from semantica.semantic_extract import NERExtractor
+from semantica.kg import GraphBuilder

-# Use NER extractor directly
+# Extract entities
 ner = NERExtractor()
-entities = ner.extract_entities("Your text")
+entities = ner.extract("Apple Inc. was founded by Steve Jobs.")
+
+# Build knowledge graph
+kg = GraphBuilder().build({"entities": entities})
 ```

-### Can I use my own models?
-
-Yes, Semantica is extensible. You can plug in custom models for entity extraction, embeddings, and more.
-
-### What export formats are supported?
-
- RDF/XML
- OWL (Ontology)
- JSON
- CSV
- YAML
- And more
+### Where can I find examples?
+- **[Getting Started Guide](getting-started.md)** - Quick introduction
+- **[Cookbook](cookbook.md)** - Practical examples
+- **[GitHub Examples](https://github.com/Hawksight-AI/semantica/tree/main/examples)** - Code samples

 ---

-## Conflict Resolution
+## Features

-### What is conflict resolution?
+### What data sources does Semantica support?
+- **Files**: PDF, DOCX, TXT, JSON, CSV
+- **Web**: Websites, RSS feeds, APIs
+- **Databases**: PostgreSQL, MySQL, Snowflake, MongoDB
+- **Streams**: Kafka, RabbitMQ, real-time data

-When the same entity appears in multiple sources with different information, conflict resolution determines which information to use.
+### Can I use custom models?
+Yes! Semantica supports custom:
+- **Entity extraction models**
+- **Embedding models**
+- **Language models**
+- **Custom processors**

-### What strategies are available?
-
- **Voting**: Majority wins
- **Credibility Weighted**: Weight by source credibility
- **Most Recent**: Use latest information
- **Highest Confidence**: Use highest confidence score
-
-### How do I set a resolution strategy?
-
-```python
-from semantica.conflicts import ConflictResolver
-
-resolver = ConflictResolver(default_strategy="voting")
-```
+### Does Semantica support GPUs?
+Yes, Semantica automatically uses GPUs when available for:
+- **Embedding generation**
+- **ML model inference**
+- **Vector operations**

 ---

-## Integration
+## Technical

-### Can I use Semantica with other tools?
+### How does Semantica handle large datasets?
+- **Batching** - Process data in chunks
+- **Streaming** - Handle real-time data
+- **Parallel processing** - Use multiple cores
+- **Memory management** - Efficient resource usage

-Yes! Semantica exports to standard formats that work with:
+### Can I deploy Semantica in production?
+Yes! Semantica is production-ready with:
+- **Scalable architecture**
+- **Error handling**
+- **Monitoring support**
+- **Container deployment**

- Neo4j
- Graph databases
- RDF stores
- Vector databases
- Any tool that accepts RDF/JSON/CSV
-
-### Does it work with LangChain?
-
-Yes, Semantica can be integrated with LangChain for RAG applications.
-
-### Can I connect to databases?
-
-Yes, Semantica supports connections to Neo4j, FalkorDB, and other graph databases.
-
---
-
-## Performance
-
-### How fast is Semantica?
-
-Performance depends on:
-
- Document size
- Number of documents
- Hardware (CPU/GPU)
- Configuration options
-
-For typical documents, processing takes seconds to minutes.
-
-### Can I process large datasets?
-
-Yes, but consider:
-
- Processing in batches
- Using GPU acceleration
- Incremental building
- Optimizing configuration
-
-### How can I improve performance?
-
- Enable GPU if available
- Process in smaller batches
- Use faster models
- Optimize configuration
- Cache embeddings
+### How do I customize Semantica?
+- **Custom processors** - Add new extraction logic
+- **Custom models** - Use your own ML models
+- **Plugins** - Extend functionality
+- **Configuration** - Adjust behavior

 ---

 ## Troubleshooting

-### Installation fails
+### Installation issues
+- **Python version**: Ensure Python 3.8+
+- **Dependencies**: Install with `pip install -e .[dev]`
+- **Permissions**: Use virtual environments

- Upgrade pip: `pip install --upgrade pip`
- Use virtual environment
- Check Python version: `python --version`
+### Performance issues
+- **Memory**: Increase available RAM
+- **GPU**: Install CUDA for GPU acceleration
+- **Batching**: Use smaller chunk sizes

-### No entities extracted
-
- Verify document contains text (not just images)
- Check document format is supported
- Review extraction configuration
-
-### Memory errors
-
- Process documents one at a time
- Reduce batch sizes
- Use smaller models
- Increase available RAM
-
-### Slow processing
-
- Enable GPU if available
- Process in smaller batches
- Optimize configuration
- Use faster models
+### Common errors
+- **Import errors**: Check installation path
+- **Model loading**: Verify model availability
+- **Memory errors**: Reduce batch sizes

 ---

-## Getting Help
+## Support

 ### Where can I get help?
+- **[GitHub Issues](https://github.com/Hawksight-AI/semantica/issues)** - Report problems
+- **[Discussions](https://github.com/Hawksight-AI/semantica/discussions)** - Ask questions
+- **[Documentation](index.md)** - Browse guides and references

- **Documentation**: This site
- **GitHub Issues**: [Report bugs or ask questions](https://github.com/Hawksight-AI/semantica/issues)
-
-### How do I report a bug?
-
-Open an issue on [GitHub](https://github.com/Hawksight-AI/semantica/issues) with:
-
- Description of the problem
- Steps to reproduce
- Expected vs actual behavior
- Environment details
+### How do I report bugs?
+1. **Search** existing issues first
+2. **Create** a new issue with details
+3. **Include** reproduction steps
+4. **Add** environment information

 ### Can I contribute?
-
-Yes! We welcome contributions. See our [Contributing Guide](https://github.com/Hawksight-AI/semantica/blob/main/CONTRIBUTING.md).
-
-### How do I request a feature?
-
-Open a feature request on [GitHub Issues](https://github.com/Hawksight-AI/semantica/issues) with:
-
- Use case description
- Proposed solution
- Benefits to the community
-
---
-
-!!! question "Still have questions?"
-    Check the [API Reference](reference/core.md), browse the [Cookbook](cookbook.md), or [ask on GitHub Issues](https://github.com/Hawksight-AI/semantica/issues/new)
+Yes! See the [Contributing Guide](contributing.md) for details on how to help improve Semantica.
@@ -1,214 +1,101 @@
 # Getting Started

-## Welcome to Semantica
+## Overview

-**Semantica** is a comprehensive knowledge graph and semantic processing framework designed for building production-ready semantic AI applications.
+**Semantica** is a semantic intelligence layer that bridges the gap between raw data and trustworthy AI. It transforms unstructured data into explainable, auditable knowledge graphs perfect for high-stakes domains.

-### 🎯 What You'll Learn
- What Semantica is and why it's useful
- How to install and configure the framework
- Understanding the framework architecture
- Key concepts and terminology
- Next steps for getting started
+### What You Can Build
+- **GraphRAG Systems** - Enhanced retrieval with semantic reasoning
+- **AI Agents** - Trustworthy agents with explainable memory
+- **Knowledge Graphs** - Production-ready semantic databases
+- **Compliance-Ready AI** - Auditable systems with full provenance

 ---

-## 🚀 What is Semantica?
+## Installation

-Semantica is a powerful, production-ready framework for:
+```bash
+pip install semantica
+```

- **Building Knowledge Graphs**: Transform unstructured data into structured knowledge graphs.
- **Semantic Processing**: Extract entities, relationships, and meaning from text, images, and audio.
- **GraphRAG**: Next-generation retrieval augmented generation using knowledge graphs.
- **Temporal Analysis**: Time-aware knowledge graphs for tracking changes over time.
- **Multi-Modal Processing**: Handle text, images, audio, and structured data.
- **Enterprise Features**: Quality assurance, conflict resolution, ontology generation, and more.
+Or with all features:

---
+```bash
+pip install semantica[all]
+```

-## 💡 Use Cases
-
-| Domain | Application |
-| :--- | :--- |
-| **Cybersecurity** | Threat intelligence and analysis |
-| **Healthcare** | Medical research and patient data analysis |
-| **Finance** | Fraud detection and financial analysis |
-| **Supply Chain** | Optimization and risk management |
-| **Research** | Knowledge management and literature review |
-| **AI Systems** | Multi-agent memory and reasoning |
-
---
-
-## 📦 Installation & Setup
-
-### Prerequisites
-Before installing Semantica, ensure you have:
- **Python 3.8** or higher
- **pip** package manager
- (Optional) Virtual environment for isolation
-
-### Installation Methods
-
-=== "PyPI (Stable)"
-    ```bash
-    pip install semantica
-    ```
-
-=== "Source (Dev)"
-    ```bash
-    git clone https://github.com/Hawksight-AI/semantica.git
-    cd semantica
-    pip install -e .
-    ```
-
-=== "Extras"
-    ```bash
-    pip install semantica[all]           # Install all optional dependencies
-    pip install semantica[gpu]           # Install GPU support
-    pip install semantica[visualization] # Install visualization tools
-    ```
-
-### Verify Installation
+Verify installation:

 ```python
 import semantica
-print(semantica.__version__)
+print(f"Semantica {semantica.__version__} installed!")
 ```

 ---

-## 🏗️ Understanding Semantica's Architecture
+## Quick Start

-Semantica uses a **modular architecture** where each module handles a specific aspect of semantic processing. This design gives you flexibility and control over your pipeline.
-
-### Primary Approach: Individual Modules
-
-The recommended approach is to use individual modules directly. Each module can be imported and used independently:
-
- **`semantica.ingest`**: Data ingestion from files, web, databases
- **`semantica.parse`**: Document parsing and text extraction
- **`semantica.semantic_extract`**: Entity and relationship extraction
- **`semantica.kg`**: Knowledge graph construction
- **`semantica.embeddings`**: Vector embedding generation
- **`semantica.vector_store`**: Vector database operations
-
-**Benefits of the modular approach:**
- **Full control**: Customize each step of your pipeline
- **Flexibility**: Mix and match modules as needed
- **Transparency**: Clear understanding of what each step does
- **Easy debugging**: Isolate issues to specific modules
-
-**Quick Example:**
 ```python
-from semantica.ingest import FileIngestor
-from semantica.parse import DocumentParser
-from semantica.semantic_extract import NERExtractor, RelationExtractor
+from semantica.semantic_extract import NERExtractor
 from semantica.kg import GraphBuilder

-# Each module is used independently
-ingestor = FileIngestor()
-parser = DocumentParser()
-ner = NERExtractor()
-builder = GraphBuilder()
+# Extract entities
+ner = NERExtractor(method="ml", model="en_core_web_sm")
+entities = ner.extract("Apple Inc. was founded by Steve Jobs in 1976.")
+
+# Build knowledge graph
+kg = GraphBuilder().build({"entities": entities, "relationships": []})
+print(f"Built KG with {len(kg.get('entities', []))} entities")
 ```

-**For detailed examples, see:**
- **[Welcome to Semantica Cookbook](https://github.com/Hawksight-AI/semantica/blob/main/cookbook/introduction/01_Welcome_to_Semantica.ipynb)**: Comprehensive introduction to all modules and architecture
-  - **Topics**: Framework overview, all modules, architecture, configuration
-  - **Difficulty**: Beginner
-  - **Time**: 30-45 minutes
-  - **Use Cases**: First-time users, understanding the framework structure
-
-### Alternative Approach: Orchestration Class
-
-For complex workflows, you can use the `` `Semantica` `` class for orchestration. This class coordinates multiple modules and provides lifecycle management.
-
-**When to use orchestration:**
- Complex multi-step workflows spanning multiple modules
- Need lifecycle management (initialization, shutdown)
- Want centralized configuration
- Building applications with multiple components
-
-!!! tip "Getting Started"
-    For beginners, start with individual modules to understand how each component works. As you build more complex applications, consider using the orchestration class for workflow management. See the [Core Module Reference](reference/core.md) for orchestration details.
-
-## ⚙️ Configuration
-
-Semantica modules can be configured individually or through environment variables. Configuration options vary by module, allowing you to customize behavior for your specific needs.
-
-### Environment Variables
-
-Common configuration via environment variables:
-
-```bash
-export OPENAI_API_KEY=your_openai_key
-export EMBEDDING_MODEL=all-MiniLM-L6-v2
-export EMBEDDING_DEVICE=cuda
-```
-
-### Module-Specific Configuration
-
-Each module accepts configuration parameters when instantiated. For example, the NER extractor can be configured with different methods, providers, and thresholds.
-
-### Config File (`config.yaml`)
-
-For centralized configuration, you can use a YAML config file to manage settings across multiple modules:
-
-```yaml
-api_keys:
-  openai: your_key_here
-
-embedding:
-  provider: openai
-  model: text-embedding-3-large
-
-knowledge_graph:
-  backend: networkx
-  temporal: true
-```
-
-**For detailed configuration examples, see:**
- **[Welcome to Semantica Cookbook](https://github.com/Hawksight-AI/semantica/blob/main/cookbook/introduction/01_Welcome_to_Semantica.ipynb)**: Configuration examples for all modules
- **[Core Module Reference](reference/core.md)**: Complete configuration documentation
+**What this does:**
+- Extracts entities (people, organizations, dates) from text
+- Builds a knowledge graph from extracted entities
+- Outputs the number of entities found

 ---

-## ⏭️ Next Steps
+## Core Architecture

-Now that you understand the basics, here are recommended next steps:
+Semantica uses a **modular architecture** - use only what you need:

-### 🍳 Interactive Tutorials (Cookbook)
+### 1️⃣ Input Layer - Data Ingestion
+```python
+from semantica.ingest import FileIngestor
+documents = FileIngestor().ingest_directory("docs/")
+```

-Get hands-on experience with these interactive Jupyter notebooks:
+### 2️⃣ Semantic Layer - Intelligence Engine
+```python
+from semantica.semantic_extract import NERExtractor, RelationExtractor
+entities = NERExtractor().extract(text)
+relationships = RelationExtractor().extract(text, entities)
+```

-1. **[Welcome to Semantica](https://github.com/Hawksight-AI/semantica/blob/main/cookbook/introduction/01_Welcome_to_Semantica.ipynb)**: Comprehensive introduction to all Semantica modules
-   - **Topics**: Framework overview, all modules, architecture, configuration
-   - **Difficulty**: Beginner
-   - **Time**: 30-45 minutes
-   - **Use Cases**: First-time users, understanding the framework structure
+### 3️⃣ Output Layer - Knowledge Assets
+```python
+from semantica.kg import GraphBuilder
+kg = GraphBuilder().build_graph(entities, relationships)
+```

-2. **[Your First Knowledge Graph](https://github.com/Hawksight-AI/semantica/blob/main/cookbook/introduction/08_Your_First_Knowledge_Graph.ipynb)**: Build your first knowledge graph from a document
-   - **Topics**: Entity extraction, relationship extraction, graph construction, visualization
-   - **Difficulty**: Beginner
-   - **Time**: 20-30 minutes
-   - **Use Cases**: Learning the basics, quick start
+---

-3. **[Data Ingestion](https://github.com/Hawksight-AI/semantica/blob/main/cookbook/introduction/02_Data_Ingestion.ipynb)**: Learn to ingest from multiple sources
-   - **Topics**: File, web, feed, stream, database ingestion
-   - **Difficulty**: Beginner
-   - **Time**: 15-20 minutes
-   - **Use Cases**: Loading data from various sources
+## Next Steps

-4. **[Document Parsing](https://github.com/Hawksight-AI/semantica/blob/main/cookbook/introduction/03_Document_Parsing.ipynb)**: Parse various document formats
-   - **Topics**: PDF, DOCX, HTML, JSON parsing
-   - **Difficulty**: Beginner
-   - **Time**: 15-20 minutes
-   - **Use Cases**: Extracting text from different file formats
+### 🍳 Interactive Tutorials
+1. **[Welcome to Semantica](https://github.com/Hawksight-AI/semantica/blob/main/cookbook/introduction/01_Welcome_to_Semantica.ipynb)** - Complete framework overview
+2. **[Your First Knowledge Graph](https://github.com/Hawksight-AI/semantica/blob/main/cookbook/introduction/08_Your_First_Knowledge_Graph.ipynb)** - Hands-on graph building
+3. **[GraphRAG Complete](https://github.com/Hawksight-AI/semantica/blob/main/cookbook/use_cases/advanced_rag/01_GraphRAG_Complete.ipynb)** - Production-ready RAG

-### 📚 Documentation
+### 📚 Learn More
+- **[Core Concepts](concepts.md)** - Deep dive into knowledge graphs & ontologies
+- **[Cookbook](cookbook.md)** - 14 domain-specific tutorials
+- **[API Reference](reference/core.md)** - Complete technical documentation

- **[Quick Start Guide](quickstart.md)**: Step-by-step tutorial to build your first knowledge graph
- **[Core Concepts](concepts.md)**: Deep dive into knowledge graphs, ontologies, and semantic reasoning
- **[API Reference](reference/core.md)**: Complete technical documentation for all modules
- **[Examples](examples.md)**: Real-world examples and use cases
- **[Cookbook](cookbook.md)**: Full list of interactive Jupyter notebooks
+---
+
+## Need Help?
+
+- **[💬 Discord Community](https://discord.gg/ggb7vWeP)** - Get help from the community
+- **[🐛 Issues](https://github.com/Hawksight-AI/semantica/issues)** - Report bugs or request features
+- **[📖 Documentation](https://semantica.readthedocs.io/)** - Full documentation site
@@ -1,213 +1,232 @@
 # Glossary

-A comprehensive reference of terms and concepts used in Semantica.
+**Comprehensive reference of terms and concepts used in Semantica and semantic intelligence.**
+
+!!! tip "Quick Reference"
+    Looking for a specific term? Use your browser's search function (Ctrl+F) to find terms quickly.

 ---

-## A
+## Core Concepts

-**Agent**
-: An autonomous AI system that can perceive its environment, reason about information, and take actions to achieve specific goals. In Semantica, agents use knowledge graphs for memory and reasoning.
+### **Agent**
+An autonomous AI system that can perceive its environment, reason about information, and take actions to achieve specific goals. In Semantica, agents use knowledge graphs for memory and reasoning.

-**API (Application Programming Interface)**
-: A set of functions and protocols that allow different software applications to communicate with each other.
+### **Entity**
+A distinct object or concept in the real world, such as a person, place, organization, or event. Entities are the fundamental building blocks of knowledge graphs.

-**Axiom**
-: A statement or rule that is accepted as true without proof, used in ontologies to define logical constraints and relationships.
+### **Knowledge Graph (KG)**
+A structured representation of knowledge using entities (nodes) and relationships (edges). KGs enable reasoning, querying, and semantic analysis of data.
+
+### **Relationship**
+A connection between two entities that describes how they relate to each other (e.g., "works_for", "located_in", "founded_by").
+
+### **Semantic**
+Relating to meaning in language or logic. Semantic understanding goes beyond keywords to comprehend context and intent.

 ---

-## C
+## Data Processing

-**Centrality**
-: A measure of the importance or influence of a node in a graph. Common centrality metrics include PageRank, betweenness centrality, and closeness centrality.
+### **Ingestion**
+The process of loading data from various sources (files, databases, APIs, streams) into a system for processing.

-**Class**
-: In ontologies, a category or type of entity (e.g., `Person`, `Organization`, `Location`).
+### **Normalization**
+The process of standardizing data into a consistent format (e.g., converting dates to ISO format, standardizing entity names).

-**Community Detection**
-: The process of identifying groups or clusters of densely connected nodes in a graph.
+### **Parsing**
+Extracting structured information from unstructured or semi-structured documents like PDFs, Word documents, or web pages.

-**Conflict Resolution**
-: The process of handling contradictory information from multiple sources in a knowledge graph.
-
-**Coreference Resolution**
-: The task of determining when two or more expressions in text refer to the same entity (e.g., "Apple" and "the company" referring to Apple Inc.).
-
-**Cypher**
-: A declarative query language for graph databases, particularly Neo4j.
+### **Chunking**
+Breaking down large documents into smaller, manageable pieces while preserving context and meaning.

 ---

-## E
+## Artificial Intelligence

-**Embedding**
-: A dense vector representation of text, images, or other data that captures semantic meaning in a continuous vector space. Used for similarity search and semantic matching.
+### **LLM (Large Language Model)**
+A type of artificial intelligence model trained on vast amounts of text data, capable of understanding and generating human-like text.

-**Entity**
-: A distinct object or concept in the real world, such as a person, place, organization, or event.
+### **RAG (Retrieval Augmented Generation)**
+A technique that enhances LLM responses by retrieving relevant information from a knowledge base before generating an answer.

-**Entity Resolution**
-: The process of determining when two entity mentions refer to the same real-world entity, also known as entity linking or deduplication.
+### **GraphRAG (Graph-Augmented Retrieval Augmented Generation)**
+An advanced RAG approach that combines vector search with knowledge graph traversal to provide more accurate and contextually relevant information to LLMs.

-**Event Detection**
-: The task of identifying and classifying events (e.g., acquisitions, partnerships, announcements) in text.
+### **Inference**
+The process of deriving new facts or conclusions from existing knowledge using logical rules.

 ---

-## G
+## Knowledge Graph Components

-**Graph**
-: A data structure consisting of nodes (vertices) and edges (relationships) connecting them.
+### **Node**
+A vertex in a graph representing an entity or concept.

-**GraphRAG (Graph-Augmented Retrieval Augmented Generation)**
-: An advanced RAG approach that combines vector search with knowledge graph traversal to provide more accurate and contextually relevant information to LLMs.
+### **Edge**
+A connection between two nodes representing a relationship.
+
+### **Property**
+An attribute or characteristic of an entity or relationship (e.g., name, date, confidence score).
+
+### **Triplet**
+A basic unit of knowledge in RDF, consisting of a subject, predicate, and object (e.g., `<Apple_Inc> <founded_by> <Steve_Jobs>`).
+
+### **Temporal Graph**
+A knowledge graph that tracks changes over time, allowing queries about the state of the graph at specific time points.

 ---

-## H
+## Entity Recognition & Extraction

-**Hybrid Search**
-: A search strategy that combines multiple retrieval methods, typically vector search and keyword search, to improve accuracy.
+### **Named Entity Recognition (NER)**
+The process of identifying and classifying named entities in text into predefined categories such as persons, organizations, locations, dates, and more.
+
+### **Relationship Extraction**
+The task of identifying and extracting semantic relationships between entities in text.
+
+### **Entity Resolution**
+The process of determining when two entity mentions refer to the same real-world entity, also known as entity linking or deduplication.
+
+### **Coreference Resolution**
+The task of determining when two or more expressions in text refer to the same entity (e.g., "Apple" and "the company" referring to Apple Inc.).
+
+### **Event Detection**
+The task of identifying and classifying events (e.g., acquisitions, partnerships, announcements) in text.

 ---

-## I
+## Ontology & Schema

-**Inference**
-: The process of deriving new facts or conclusions from existing knowledge using logical rules.
+### **Ontology**
+A formal specification of concepts, relationships, and constraints in a domain, typically expressed in OWL (Web Ontology Language).

-**Ingestion**
-: The process of loading data from various sources (files, databases, APIs, streams) into a system for processing.
+### **Class**
+In ontologies, a category or type of entity (e.g., `Person`, `Organization`, `Location`).
+
+### **Axiom**
+A statement or rule that is accepted as true without proof, used in ontologies to define logical constraints and relationships.
+
+### **OWL (Web Ontology Language)**
+A W3C standard language for defining and instantiating ontologies on the web.
+
+### **Property**
+In ontologies, a relationship or attribute that connects entities or describes their characteristics.

 ---

-## K
+## Data Storage & Retrieval

-**Knowledge Graph (KG)**
-:   A structured representation of knowledge using entities (nodes) and relationships (edges). KGs enable reasoning, querying, and semantic analysis of data.
+### **Embedding**
+A dense vector representation of text, images, or other data that captures semantic meaning in a continuous vector space. Used for similarity search and semantic matching.

-**Knowledge Graph Analytics**
-:   The application of graph algorithms (e.g., centrality, community detection) to gain insights from the structure of a knowledge graph.
+### **Vector Store**
+A database optimized for storing and searching high-dimensional vectors, used for semantic similarity search.
+
+### **Triplet Store**
+A database designed specifically for storing and querying RDF triplets.
+
+### **Graph Database**
+A database designed specifically for storing and querying graph-structured data.
+
+### **Hybrid Search**
+A search strategy that combines multiple retrieval methods, typically vector search and keyword search, to improve accuracy.

 ---

-## L
+## Graph Analytics

-**LLM (Large Language Model)**
-: A type of artificial intelligence model trained on vast amounts of text data, capable of understanding and generating human-like text.
+### **Centrality**
+A measure of the importance or influence of a node in a graph. Common centrality metrics include PageRank, betweenness centrality, and closeness centrality.
+
+### **PageRank**
+An algorithm used to measure the importance of nodes in a graph based on the structure of incoming links.
+
+### **Community Detection**
+The process of identifying groups or clusters of densely connected nodes in a graph.
+
+### **Graph Analytics**
+The application of graph algorithms (e.g., centrality, community detection) to gain insights from the structure of a knowledge graph.

 ---

-## N
+## Query Languages

-**Named Entity Recognition (NER)**
-: The process of identifying and classifying named entities in text into predefined categories such as persons, organizations, locations, dates, and more.
+### **Cypher**
+A declarative query language for graph databases, particularly Neo4j.

-**Node**
-: A vertex in a graph representing an entity or concept.
+### **SPARQL**
+A query language for RDF data, similar to SQL for relational databases.

-**Normalization**
-: The process of standardizing data into a consistent format (e.g., converting dates to ISO format, standardizing entity names).
+### **RDF (Resource Description Framework)**
+A W3C standard for representing information about resources in the form of subject-predicate-object triplets.

 ---

-## O
+## Data Quality

-**OCR (Optical Character Recognition)**
-: Technology that converts images of text (e.g., scanned documents, photos) into machine-readable text.
+### **Conflict Resolution**
+The process of handling contradictory information from multiple sources in a knowledge graph.

-**Ontology**
-: A formal specification of concepts, relationships, and constraints in a domain, typically expressed in OWL (Web Ontology Language).
+### **Deduplication**
+The process of identifying and removing duplicate records or entities from a dataset.

-**OWL (Web Ontology Language)**
-: A W3C standard language for defining and instantiating ontologies on the web.
+### **Data Provenance**
+Information about the origin, history, and lineage of data, including sources, timestamps, and transformations.

 ---

-## P
+## Technical Terms

-**PageRank**
-: An algorithm used to measure the importance of nodes in a graph based on the structure of incoming links.
+### **API (Application Programming Interface)**
+A set of functions and protocols that allow different software applications to communicate with each other.

-**Pipeline**
-: A sequence of data processing steps that transform raw data into a desired output format.
+### **OCR (Optical Character Recognition)**
+Technology that converts images of text (e.g., scanned documents, photos) into machine-readable text.

-**Property**
-: In ontologies, a relationship or attribute that connects entities or describes their characteristics.
+### **Pipeline**
+A sequence of data processing steps that transform raw data into a desired output format.

-**Provenance**
-: Information about the origin, history, and lineage of data, including sources, timestamps, and transformations.
+### **Vector**
+A mathematical representation of data as an array of numbers, used in embeddings to capture semantic meaning.
+
+### **Visualization**
+The graphical representation of data, such as knowledge graphs, embeddings, or analytics.
+
+### **Web Scraping**
+The automated process of extracting data from websites.

 ---

-## R
+## Semantica-Specific Terms

-**RAG (Retrieval Augmented Generation)**
-: A technique that enhances LLM responses by retrieving relevant information from a knowledge base before generating an answer.
+### **Semantic Layer**
+An abstraction layer that provides a unified, business-friendly view of data by adding context, relationships, and meaning to raw data.

-**RDF (Resource Description Framework)**
-: A W3C standard for representing information about resources in the form of subject-predicate-object triplets.
+### **Semantic Network**
+A knowledge representation that uses a graph structure to represent concepts and their relationships.

-**Reasoning**
-: The process of deriving new knowledge from existing facts using logical rules and inference.
+### **Change Management**
+The process of tracking and managing changes to knowledge graphs over time, including version control and audit trails.

-**Relationship Extraction**
-: The task of identifying and extracting semantic relationships between entities in text.
-
---
-
-## S
-
-**Semantic**
-: Relating to meaning in language or logic.
-
-**Semantic Layer**
-: An abstraction layer that provides a unified, business-friendly view of data by adding context, relationships, and meaning to raw data.
-
-**Semantic Network**
-: A knowledge representation that uses a graph structure to represent concepts and their relationships.
-
-**SPARQL**
-: A query language for RDF data, similar to SQL for relational databases.
-
---
-
-## T
-
-**Temporal Graph**
-: A knowledge graph that tracks changes over time, allowing queries about the state of the graph at specific time points.
-
-**Triplet**
-: A basic unit of knowledge in RDF, consisting of a subject, predicate, and object (e.g., `<Apple_Inc> <founded_by> <Steve_Jobs>`).
-
-**Triplet Store**
-: A database designed specifically for storing and querying RDF triplets.
-
---
-
-## V
-
-**Vector**
-: A mathematical representation of data as an array of numbers, used in embeddings to capture semantic meaning.
-
-**Vector Store**
-: A database optimized for storing and searching high-dimensional vectors, used for semantic similarity search.
-
-**Visualization**
-: The graphical representation of data, such as knowledge graphs, embeddings, or analytics.
-
---
-
-## W
-
-**Web Scraping**
-: The automated process of extracting data from websites.
+### **Provenance Tracking**
+W3C PROV-O compliant tracking of data lineage and source attribution.

 ---

 ## See Also

- [Core Concepts](concepts.md) - Deep dive into fundamental concepts
- [Getting Started](getting-started.md) - Begin your journey with Semantica
- [API Reference](reference/core.md) - Technical documentation
+- **[Core Concepts](concepts.md)** - Deep dive into fundamental concepts
+- **[Getting Started](getting-started.md)** - Begin your journey with Semantica
+- **[Modules Guide](modules.md)** - Complete module overview
+- **[API Reference](reference/)** - Technical documentation
+
+---
+
+## Need Help?
+
+- **Documentation**: [Getting Started](getting-started.md)
+- **Examples**: [Cookbook](cookbook.md)
+- **Community**: [Discord](community.md)
+- **Issues**: [GitHub Issues](https://github.com/Hawksight-AI/semantica/issues)
+- **Support**: [Contact Us](community.md)
@@ -5,19 +5,19 @@
  
  <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://badge.fury.io/py/semantica"><img src="https://badge.fury.io/py/semantica.svg" alt="PyPI version"></a>
+  <a href="https://badge.fury.io/py/semantica"><img src="https://img.shields.io/badge/pypi-v0.2.3-blue.svg" alt="PyPI version"></a>
  <a href="https://pypi.org/project/semantica/"><img src="https://img.shields.io/pypi/dm/semantica" alt="Monthly Downloads"></a>
  <a href="https://pepy.tech/project/semantica"><img src="https://static.pepy.tech/badge/semantica" alt="Total Downloads"></a>
  <a href="https://semantica.readthedocs.io/"><img src="https://img.shields.io/badge/docs-latest-brightgreen.svg" alt="Documentation"></a>
  <a href="https://discord.gg/pMHguUzG"><img src="https://img.shields.io/badge/Discord-Join%20Us-7289da?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
  
-  <p><strong>Open Source Framework for Semantic Layer & Knowledge Engineering</strong></p>
+  <p><strong>Open-Source Semantic Layer & Knowledge Engineering Framework</strong></p>
  
-  <p><strong>Transform chaotic data into intelligent knowledge.</strong></p>
+  <p><strong>Transform Chaos into Intelligence. Build AI systems that are explainable, traceable, and trustworthy — not black boxes.</strong></p>
  
-  <p><em>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.</em></p>
+  <p><em>The semantic intelligence layer that makes your AI agents auditable, explainable, and trustworthy. Perfect for high-stakes domains where mistakes have real consequences.</em></p>
  
-  <p>🆓 <strong>100% Open Source</strong> • 📜 <strong>MIT Licensed</strong> • 🚀 <strong>Latest Version: 0.2.3</strong> • 🚀 <strong>Production Ready</strong> • 🌍 <strong>Community Driven</strong></p>
+  <p>🆓 <strong>Open Source</strong> • 📜 <strong>MIT Licensed</strong> • 🚀 <strong>Production Ready</strong> • 🌍 <strong>Community Driven</strong></p>
  
  <p>
    <a href="getting-started/" class="md-button md-button--primary">Get Started</a>
@@ -27,260 +27,203 @@

 ---

-## 🌟 What is Semantica?
+## 🚀 Why Semantica?

-Semantica bridges the gap between raw data chaos and AI-ready knowledge. It's a **semantic intelligence platform** that transforms unstructured data into structured, queryable knowledge graphs powering GraphRAG, AI agents, and multi-agent systems.
+**Semantica** bridges the **semantic gap** between text similarity and true meaning. It's the **semantic intelligence layer** that makes your AI agents auditable, explainable, and trustworthy.

-### What Makes Semantica Different?
-
-Unlike traditional approaches that process isolated documents and extract text into vectors, Semantica understands **semantic relationships across all content**, provides **automated ontology generation**, and builds a **unified semantic layer** with **production-grade QA**.
-
-| **Traditional Approaches** | **Semantica's Approach** |
-|:---------------------------|:-------------------------|
-| Process data as isolated documents | **Understands semantic relationships across all content** |
-| Extract text and store vectors | **Builds knowledge graphs with meaningful connections** |
-| Generic entity recognition | **General-purpose ontology generation and validation** |
-| Manual schema definition | **Automatic semantic modeling from content patterns** |
-| Disconnected data silos | **Unified semantic layer across all data sources** |
-| Basic quality checks | **Production-grade QA with conflict detection & resolution** |
+Perfect for **high-stakes domains** where mistakes have real consequences.

 ---

-## 🎯 The Problem We Solve
+### ⚡ Get Started in 30 Seconds

-### The Semantic Gap
-
-Organizations today face a **fundamental mismatch** between how data exists and how AI systems need it.
-
-#### The Semantic Gap: Problem vs. Solution
-
-Organizations have **unstructured data** (PDFs, emails, logs), **messy data** (inconsistent formats, duplicates, conflicts), and **disconnected silos** (no shared context, missing relationships). AI systems need **clear rules** (formal ontologies), **structured entities** (validated, consistent), and **relationships** (semantic connections, context-aware reasoning).
-
-| **What Organizations Have** | **What AI Systems Require** |
-|:------------------------------|:------------------------------|
-| **Unstructured Data** | **Clear Rules** |
-| PDFs, emails, logs | Formal ontologies |
-| Mixed schemas | Graphs & Networks |
-| Conflicting facts | |
-| **Messy, Noisy Data** | **Structured Entities** |
-| Inconsistent formats | Validated entities |
-| Duplicate records | Domain Knowledge |
-| Missing relationships | |
-| **Disconnected, Siloed Data** | **Relationships** |
-| Data in separate systems | Semantic connections |
-| No shared context | Context-Aware Reasoning |
-| Isolated knowledge | |
-
-### 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 Framework
-
-Semantica operates through three integrated layers that transform raw data into AI-ready knowledge:
-
-**Input Layer** — Universal ingestion from multiple data formats (PDFs, DOCX, HTML, JSON, CSV, databases, live feeds, APIs, streams, archives, multi-modal content) into a unified pipeline.
-
-**Semantic Layer** — Core intelligence engine performing entity extraction, relationship mapping, ontology generation, context engineering, and quality assurance. Includes **advanced entity deduplication** (Jaro-Winkler, disjoint property handling) to ensure a clean single source of truth.
-
-**Output Layer** — Production-ready knowledge graphs, vector embeddings, and validated ontologies that power GraphRAG systems, AI agents, and multi-agent systems.
-
-**Powers: GraphRAG, AI Agents, Multi-Agent Systems**
-
-#### Semantica Processing Flow
-
-```mermaid
-flowchart TD
-    A[Raw Data Sources<br/>PDFs, Emails, Logs, Databases<br/>Multiple Formats] --> B[Input Layer<br/>Universal Data Ingestion]
-    B --> C[Format Detection<br/>& Parsing]
-    C --> D[Normalization<br/>& Preprocessing]
-    D --> E[Semantic Layer<br/>Core Intelligence]
-    
-    E --> F[Entity Extraction<br/>NER + LLM Enhancement]
-    E --> G[Relationship Mapping<br/>Triplet Generation]
-    E --> H[Ontology Generation<br/>6-Stage Pipeline]
-    E --> I[Context Engineering<br/>Semantic Enrichment]
-    E --> J[Quality Assurance<br/>Conflict Detection]
-    
-    F --> K[Output Layer]
-    G --> K
-    H --> K
-    I --> K
-    J --> K
-    
-    K --> L[Knowledge Graphs<br/>Production-Ready]
-    K --> M[Vector Embeddings<br/>Semantic Search]
-    K --> N[Ontologies<br/>OWL Validated]
-    
-    L --> O[Application Layer]
-    M --> O
-    N --> O
-    
-    O --> P[GraphRAG Engine<br/>91% Accuracy]
-    O --> Q[AI Agents<br/>Persistent Memory]
-    O --> R[Multi-Agent Systems<br/>Shared Models]
-    O --> S[Analytics & BI<br/>Graph Insights]
+```bash
+pip install semantica
 ```

---
+```python
+from semantica.semantic_extract import NERExtractor
+from semantica.kg import GraphBuilder

-## 💡 The Semantica Solution
+# Extract entities and build knowledge graph
+ner = NERExtractor(method="ml", model="en_core_web_sm")
+entities = ner.extract("Apple Inc. was founded by Steve Jobs in 1976.")
+kg = GraphBuilder().build({"entities": entities, "relationships": []})

-**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.
+print(f"Built KG with {len(kg.get('entities', []))} entities")
+```

-### How Semantica Solves These Problems
-
-<div class="grid cards" markdown>
-
-   :material-lightning-bolt: **Efficient Embeddings**
-    ---
-    Uses **FastEmbed** by default for high-performance, lightweight local embedding generation (faster than sentence-transformers).
-
-   :material-database-import: **Universal Data Ingestion**
-    ---
-    Handles multiple formats (PDF, DOCX, HTML, JSON, CSV, databases, APIs, streams) with unified pipeline, no custom parsers needed.
-
-   :material-brain: **Automated Semantic Extraction**
-    ---
-    NER, relationship extraction, and triplet generation with LLM enhancement discovers entities and relationships automatically.
-
-   :material-graph: **Knowledge Graph Construction**
-    ---
-    Production-ready graphs with entity resolution, temporal support, and graph analytics. Queryable knowledge ready for AI applications.
-
-   :material-robot: **GraphRAG Engine**
-    ---
-    Hybrid vector + graph retrieval achieves **91% accuracy** (30% improvement) via semantic search + graph traversal for multi-hop reasoning.
-
-   :material-account-cog: **AI Agent Context Engineering**
-    ---
-    Persistent memory with RAG + knowledge graphs enables context maintenance, action validation, and structured knowledge access.
-
-   :material-book-open-variant: **Automated Ontology Generation**
-    ---
-    6-stage LLM pipeline generates validated OWL ontologies with HermiT/Pellet validation, eliminating manual engineering.
-
-   :material-shield-check: **Production-Grade QA**
-    ---
-    Conflict detection, deduplication, quality scoring, and provenance tracking ensure trusted, production-ready knowledge graphs.
-
-   :material-cog-transfer: **Pipeline Orchestration**
-    ---
-    Flexible pipeline builder with parallel execution enables scalable processing via orchestrator-worker pattern.
-
-</div>
-
-### Core Features at a Glance
-
-| **Feature Category** | **Capabilities** | **Key Benefits** |
-|:---------------------|:-----------------|:------------------|
-| **Data Ingestion** | Multiple 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 |
+**[📖 Full Quick Start](getting-started.md)** • **[🍳 Cookbook Examples](cookbook.md)** • **[💬 Join Discord](https://discord.gg/ggb7vWeP)** • **[⭐ Star Us](https://github.com/Hawksight-AI/semantica)**

 ---

-## ✨ Core Capabilities
+## Core Value Proposition

-### 1. 📊 Universal Data Ingestion
+| **Trustworthy** | **Explainable** | **Auditable** |
+|:------------------:|:------------------:|:-----------------:|
+| Conflict detection & validation | Transparent reasoning paths | Complete provenance tracking |
+| Rule-based governance | Entity relationships & ontologies | W3C PROV-O compliant lineage |
+| Production-grade QA | Multi-hop graph reasoning | Source tracking & integrity verification |

-Process **multiple file formats** with intelligent semantic extraction:
+---

-<div class="grid cards" markdown>
+## Key Features & Benefits

-   __📄 Documents__
-    ---
-    - PDF (with OCR)
-    - DOCX, XLSX, PPTX
-    - TXT, RTF, ODT
-    - EPUB, LaTeX, Markdown
+### Not Just Another Agentic Framework

-   __🌐 Web & Feeds__
-    ---
-    - HTML, XHTML, XML
-    - RSS, Atom feeds
-    - JSON-LD, RDFa
-    - Web scraping
+**Semantica complements** LangChain, LlamaIndex, AutoGen, CrewAI, Google ADK, Agno, and other frameworks to enhance your agents with:

-   __💾 Structured Data__
-    ---
-    - JSON, YAML, TOML
-    - CSV, TSV, Excel
-    - Parquet, Avro, ORC
-    - SQL/NoSQL databases
+| Feature | Benefit |
+|:--------|:--------|
+| **Auditable** | Complete provenance tracking with W3C PROV-O compliance |
+| **Explainable** | Transparent reasoning paths with entity relationships |
+| **Provenance-Aware** | End-to-end lineage from documents to responses |
+| **Validated** | Built-in conflict detection, deduplication, QA |
+| **Governed** | Rule-based validation and semantic consistency |
+| **Version Control** | Enterprise-grade change management with integrity verification |

-   __📧 Communication__
-    ---
-    - EML, MSG, MBOX
-    - PST archives
-    - Email threads
-    - Attachment extraction
+### Perfect For High-Stakes Use Cases

-   __🗜️ Archives__
-    ---
-    - ZIP, TAR, RAR, 7Z
-    - Recursive processing
-    - Multi-level extraction
+| 🏥 **Healthcare** | 💰 **Finance** | ⚖️ **Legal** |
+|:-----------------:|:--------------:|:------------:|
+| Clinical decisions | Fraud detection | Evidence-backed research |
+| Drug interactions | Regulatory support | Contract analysis |
+| Patient safety | Risk assessment | Case law reasoning |

-   __🔬 Scientific__
-    ---
-    - BibTeX, EndNote, RIS
-    - JATS XML
-    - PubMed formats
-    - Citation networks
+| 🔒 **Cybersecurity** | 🏛️ **Government** | 🏭 **Infrastructure** | 🚗 **Autonomous** |
+|:-------------------:|:----------------:|:-------------------:|:-----------------:|
+| Threat attribution | Policy decisions | Power grids | Decision logs |
+| Incident response | Classified info | Transportation | Safety validation |

-</div>
+### Powers Your AI Stack

-### 2. 🧠 Semantic Intelligence Engine
+- **GraphRAG Systems** — Retrieval with graph reasoning and hybrid search
+- **AI Agents** — Trustworthy, accountable multi-agent systems with semantic memory
+- **Reasoning Models** — Explainable AI decisions with reasoning paths
+- **Enterprise AI** — Governed, auditable platforms that support compliance

-Transform raw text into structured semantic knowledge with state-of-the-art NLP and AI models:
+### Integrations

- **Named Entity Recognition (NER)**: Extract people, organizations, locations, dates, and custom entities
- **Relationship Extraction**: Identify semantic, temporal, and causal relationships
- **Event Detection**: Detect and classify events (acquisitions, partnerships, announcements)
- **Coreference Resolution**: Resolve pronouns and entity mentions across documents
- **Triplet Extraction**: Generate RDF triplets for knowledge graph construction
+- **Docling Support** — Document parsing with table extraction (PDF, DOCX, PPTX, XLSX)
+- **AWS Neptune** — Amazon Neptune graph database support with IAM authentication
+- **Custom Ontology Import** — Import existing ontologies (OWL, RDF, Turtle, JSON-LD)

-### 3. 🕸️ Knowledge Graph Construction
+> **Built for environments where every answer must be explainable and governed.**

-Build production-ready knowledge graphs with:
+---

- **Automatic Entity Resolution**: Merge duplicate entities with fuzzy matching
- **Conflict Detection & Resolution**: Handle contradictory information from multiple sources
- **Temporal Knowledge Graphs**: Track changes over time with version history
- **Graph Analytics**: Centrality, community detection, path finding
- **Multi-Format Export**: Neo4j, RDF, JSON-LD, GraphML
+## 🚨 The Problem: The Semantic Gap

-### 4. 📚 Ontology Generation & Management
+### Most AI systems fail in high-stakes domains because they operate on **text similarity**, not **meaning**.

-Generate formal ontologies automatically using a **6-stage LLM-based pipeline**:
+### Understanding the Semantic Gap

-1. **Semantic Network Parsing** → Extract domain concepts
-2. **YAML-to-Definition** → Transform into class definitions
-3. **Definition-to-Types** → Map to OWL types
-4. **Hierarchy Generation** → Build taxonomic structures
-5. **TTL Generation** → Generate OWL/Turtle syntax
-6. **Symbolic Validation** → HermiT/Pellet reasoning (F1 up to 0.99)
+The **semantic gap** is the fundamental disconnect between what AI systems can process (text patterns, vector similarities) and what high-stakes applications require (semantic understanding, meaning, context, and relationships).

-### 5. 🔍 Hybrid Search & Retrieval
+**Traditional AI approaches:**
+- Rely on statistical patterns and text similarity
+- Cannot understand relationships between entities
+- Cannot reason about domain-specific rules
+- Cannot explain why decisions were made
+- Cannot trace back to original sources with confidence

-Power GraphRAG applications with:
+**High-stakes AI requires:**
+- Semantic understanding of entities and their relationships
+- Domain knowledge encoded as formal rules (ontologies)
+- Explainable reasoning paths
+- Source-level provenance
+- Conflict detection and resolution

- **Vector Search**: Semantic similarity using embeddings
- **Graph Traversal**: Multi-hop reasoning for context expansion
- **Hybrid Retrieval**: Combine vector + graph for improved accuracy
- **Temporal Queries**: Query knowledge at specific time points
+**Semantica bridges this gap** by providing a semantic intelligence layer that transforms unstructured data into validated, explainable, and auditable knowledge.
+
+### What Organizations Have vs What They Need
+
+| **Current State** | **Required for High-Stakes AI** |
+|:---------------------|:-----------------------------------|
+| PDFs, DOCX, emails, logs | Formal domain rules (ontologies) |
+| APIs, databases, streams | Structured and validated entities |
+| Conflicting facts and duplicates | Explicit semantic relationships |
+| Siloed systems with no lineage | **Explainable reasoning paths** |
+| | **Source-level provenance** |
+| | **Audit-ready compliance** |
+
+### The Cost of Missing Semantics
+
+- **Decisions cannot be explained** — No transparency in AI reasoning
+- **Errors cannot be traced** — No way to debug or improve
+- **Conflicts go undetected** — Contradictory information causes failures
+- **Compliance becomes impossible** — No audit trails for regulations
+
+**Trustworthy AI requires semantic accountability.**
+
+---
+
+## 🆚 Semantica vs Traditional RAG
+
+| Feature | Traditional RAG | Semantica |
+|:--------|:----------------|:----------|
+| **Reasoning** | ❌ Black-box answers | ✅ Explainable reasoning paths |
+| **Provenance** | ❌ No provenance | ✅ W3C PROV-O compliant lineage tracking |
+| **Search** | ⚠️ Vector similarity only | ✅ Semantic + graph reasoning |
+| **Quality** | ❌ No conflict handling | ✅ Explicit contradiction detection |
+| **Safety** | ⚠️ Unsafe for high-stakes | ✅ Designed for governed environments |
+| **Compliance** | ❌ No audit trails | ✅ Complete audit trails with integrity verification |
+
+---
+
+## 🧩 Semantica Architecture
+
+### 1️⃣ Input Layer — Governed Ingestion
+- 📄 **Multiple Formats** — PDFs, DOCX, HTML, JSON, CSV, Excel, PPTX
+- 🔧 **Docling Support** — Docling parser for table extraction
+- 💾 **Data Sources** — Databases, APIs, streams, archives, web content
+- 🎨 **Media Support** — Image parsing with OCR, audio/video metadata extraction
+- � **Single Pipeline** — Unified ingestion with metadata and source tracking
+
+### 2️⃣ Semantic Layer — Trust & Reasoning Engine
+- 🔍 **Entity Extraction** — NER, normalization, classification
+- 🔗 **Relationship Discovery** — Triplet generation, semantic links
+- 📐 **Ontology Induction** — Automated domain rule generation
+- 🔄 **Deduplication** — Jaro-Winkler similarity, conflict resolution
+- ✅ **Quality Assurance** — Conflict detection, validation
+- 📊 **Provenance Tracking** — W3C PROV-O compliant lineage tracking across all modules
+- 🧠 **Reasoning Traces** — Explainable inference paths
+- 🔐 **Change Management** — Version control with audit trails, checksums, compliance support
+
+### 3️⃣ Output Layer — Auditable Knowledge Assets
+- � **Knowledge Graphs** — Queryable, temporal, explainable
+- 📐 **OWL Ontologies** — HermiT/Pellet validated, custom ontology import support
+- 🔢 **Vector Embeddings** — FastEmbed by default
+- ☁️ **AWS Neptune** — Amazon Neptune graph database support
+- 🔍 **Provenance** — Every AI response links back to:
+  - 📄 Source documents
+  - 🏷️ Extracted entities & relations
+  - 📐 Ontology rules applied
+  - 🧠 Reasoning steps used
+
+---
+
+## 🏥 Built for High-Stakes Domains
+
+Designed for domains where **mistakes have real consequences** and **every decision must be accountable**:
+
+- **🏥 Healthcare & Life Sciences** — Clinical decision support, drug interaction analysis, medical literature reasoning, patient safety tracking
+- **💰 Finance & Risk** — Fraud detection, regulatory support (SOX, GDPR, MiFID II), credit risk assessment, algorithmic trading validation
+- **⚖️ Legal & Compliance** — Evidence-backed legal research, contract analysis, regulatory change tracking, case law reasoning
+- **🔒 Cybersecurity & Intelligence** — Threat attribution, incident response, security audit trails, intelligence analysis
+- **🏛️ Government & Defense** — Governed AI systems, policy decisions, classified information handling, defense intelligence
+- **🏭 Critical Infrastructure** — Power grid management, transportation safety, water treatment, emergency response
+- **🚗 Autonomous Systems** — Self-driving vehicles, drone navigation, robotics safety, industrial automation  
+
+---
+
+## � Who Uses Semantica?
+
+- **🤖 AI / ML Engineers** — Building explainable GraphRAG & agents
+- **⚙️ Data Engineers** — Creating governed semantic pipelines
+- **📊 Knowledge Engineers** — Managing ontologies & KGs at scale
+- **🏢 Enterprise Teams** — Requiring trustworthy AI infrastructure
+- **🛡️ Risk & Compliance Teams** — Needing audit-ready systems  

 ---

@@ -420,7 +363,7 @@ print(f"Created graph with {len(kg.nodes)} nodes and {len(kg.edges)} edges")

 <div class="grid cards" markdown>

-   **🆓 100% Open Source**
+-   **🆓 Open Source**
    ---
    MIT licensed. No vendor lock-in. Full transparency.

@@ -487,13 +430,3 @@ Get hands-on with interactive Jupyter notebooks:
  - **Difficulty**: Advanced
  - **Use Cases**: Building AI applications with knowledge graphs

---
-
-<div align="center">
-
-**Ready to transform your data into knowledge?**
-
-[Get Started Now](getting-started.md){ .md-button .md-button--primary }
-[Join Discord](https://discord.gg/semantica){ .md-button }
-
-</div>
@@ -0,0 +1,280 @@
+# Snowflake Integration
+
+Semantica features a native integration with **Snowflake**, the powerful cloud data warehouse that enables scalable data storage and analytics for enterprise workloads.
+
+## Overview
+
+Snowflake is integrated into Semantica's `ingest` module via the `SnowflakeIngestor`. This allows you to seamlessly extract structured data from Snowflake tables and queries into semantic structures that can be indexed, searched, and analyzed within the Semantica framework.
+
+- 📖 **Semantica Snowflake Integration Docs**: [Reference Guide](../reference/ingest.md)
+- 💻 **Semantica Snowflake Integration GitHub**: [Source Code](https://github.com/Hawksight-AI/semantica/blob/main/semantica/ingest/snowflake_ingestor.py)
+- 🧑🏽‍🍳 **Semantica Snowflake Integration Example**: [Snowflake Clear Code Example](../CodeExamples.md#snowflake-clear-code-example)
+- 📦 **Semantica Snowflake Integration PyPI**: [Installation Guide](../installation.md)
+
+---
+
+## 📖 Integration Documentation
+
+The `SnowflakeIngestor` provides a high-level interface for Snowflake data ingestion. It supports:
+
+*   **Multiple Authentication Methods**: Password, key-pair, OAuth, and SSO authentication.
+*   **Advanced Querying**: Custom SQL queries with parameterization and batching.
+*   **Schema Introspection**: Automatic table schema discovery and metadata extraction.
+*   **Document Export**: Convert Snowflake data to Semantica document format.
+
+### Basic Usage
+
+```python
+from semantica.ingest import SnowflakeIngestor
+
+# Initialize with environment variables
+ingestor = SnowflakeIngestor()
+
+# Ingest a table
+data = ingestor.ingest_table("CUSTOMERS")
+
+# Access the structured data
+print(f"Retrieved {data.row_count} rows")
+print(f"Columns: {data.columns}")
+```
+
+For more details, see the [Ingest Reference](../reference/ingest.md).
+
+---
+
+## 🧑🏽‍🍳 Integration Example
+
+We provide a detailed cookbook and clear code examples to help you get started quickly.
+
+### Snowflake Clear Code Example
+
+```python
+from semantica.ingest import SnowflakeIngestor
+import os
+from dotenv import load_dotenv
+
+# 1. Load environment variables
+load_dotenv()
+
+# 2. Initialize the Snowflake Ingestor
+ingestor = SnowflakeIngestor(
+    account=os.getenv("SNOWFLAKE_ACCOUNT"),
+    user=os.getenv("SNOWFLAKE_USER"),
+    password=os.getenv("SNOWFLAKE_PASSWORD"),
+    warehouse=os.getenv("SNOWFLAKE_WAREHOUSE"),
+    database=os.getenv("SNOWFLAKE_DATABASE"),
+    schema=os.getenv("SNOWFLAKE_SCHEMA")
+)
+
+# 3. Ingest a table with filters
+data = ingestor.ingest_table(
+    "CUSTOMERS",
+    where="COUNTRY = 'USA' AND CREATED_DATE > '2024-01-01'",
+    order_by="CREATED_DATE DESC",
+    limit=10000
+)
+
+# 4. Access the structured data
+print(f"--- Customer Data ---")
+print(f"Retrieved {data.row_count} customers")
+print(f"Columns: {data.columns}")
+
+# 5. Iterate through rows
+for row in data.data[:5]:  # Print first 5 rows
+    print(f"Customer: {row['NAME']} ({row['EMAIL']})")
+
+# 6. Export as documents for Semantica processing
+documents = ingestor.export_as_documents(
+    data,
+    id_field="CUSTOMER_ID",
+    text_fields=["NAME", "EMAIL", "NOTES"]
+)
+
+print(f"Created {len(documents)} documents for processing")
+```
+
+See more in our [Code Examples](../CodeExamples.md).
+
+---
+
+## 💻 GitHub Source
+
+The integration is open-source and available on GitHub. You can explore the implementation, contribute improvements, or report issues.
+
+- [snowflake_ingestor.py](https://github.com/Hawksight-AI/semantica/blob/main/semantica/ingest/snowflake_ingestor.py) - The core implementation of the Snowflake integration.
+
+---
+
+## 📦 PyPI & Installation
+
+Snowflake connector is an optional dependency for Semantica. You can install it along with Semantica or as a separate requirement.
+
+### Install via Semantica
+```bash
+# Install with Snowflake support
+pip install semantica[db-snowflake]
+
+# Or install with all database connectors
+pip install semantica[db-all]
+```
+
+### Install Snowflake connector manually
+If you are working in a custom environment:
+```bash
+pip install snowflake-connector-python
+```
+
+For full installation details, see the [Installation Guide](../installation.md).
+
+---
+
+## 🔐 Authentication Methods
+
+Snowflake integration supports multiple authentication methods for different security requirements:
+
+### Password Authentication
+```python
+ingestor = SnowflakeIngestor(
+    account="myaccount",
+    user="myuser",
+    password="mypassword",
+    warehouse="COMPUTE_WH"
+)
+```
+
+### Key-Pair Authentication (Recommended for Production)
+```python
+ingestor = SnowflakeIngestor(
+    account="myaccount",
+    user="myuser",
+    private_key_path="/path/to/rsa_key.p8",
+    warehouse="COMPUTE_WH"
+)
+```
+
+### OAuth Authentication
+```python
+ingestor = SnowflakeIngestor(
+    account="myaccount",
+    user="myuser",
+    authenticator="oauth",
+    token="your_oauth_token",
+    warehouse="COMPUTE_WH"
+)
+```
+
+### SSO Authentication
+```python
+ingestor = SnowflakeIngestor(
+    account="myaccount",
+    user="myuser",
+    authenticator="externalbrowser",
+    warehouse="COMPUTE_WH"
+)
+```
+
+---
+
+## 🚀 Advanced Features
+
+### Schema Introspection
+```python
+# Get table schema
+schema = ingestor.get_table_schema("CUSTOMERS")
+for column in schema["columns"]:
+    print(f"{column['name']}: {column['type']}")
+```
+
+### Custom Queries
+```python
+# Execute custom SQL
+data = ingestor.ingest_query("""
+    SELECT 
+        CUSTOMER_ID,
+        SUM(AMOUNT) AS TOTAL_AMOUNT
+    FROM SALES
+    WHERE DATE >= '2024-01-01'
+    GROUP BY CUSTOMER_ID
+""")
+```
+
+### Batch Processing
+```python
+# Handle large result sets
+data = ingestor.ingest_query(
+    "SELECT * FROM LARGE_TABLE",
+    batch_size=5000
+)
+```
+
+---
+
+## 📊 Best Practices
+
+### Use Environment Variables
+```python
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+ingestor = SnowflakeIngestor()  # Reads from environment
+```
+
+### Use Key-Pair Authentication for Production
+```python
+ingestor = SnowflakeIngestor(
+    account=os.getenv("SNOWFLAKE_ACCOUNT"),
+    user=os.getenv("SNOWFLAKE_USER"),
+    private_key_path=os.getenv("SNOWFLAKE_PRIVATE_KEY_PATH"),
+    warehouse="COMPUTE_WH"
+)
+```
+
+### Paginate Large Results
+```python
+PAGE_SIZE = 10000
+for page in range(total_pages):
+    data = ingestor.ingest_table(
+        "LARGE_TABLE",
+        limit=PAGE_SIZE,
+        offset=page * PAGE_SIZE
+    )
+    process_batch(data)
+```
+
+---
+
+## 🔍 Troubleshooting
+
+### Connection Issues
+```python
+# Test connection
+connector = SnowflakeConnector(
+    account="myaccount",
+    user="myuser",
+    password="mypassword"
+)
+
+if not connector.test_connection():
+    print("Connection failed - check credentials")
+```
+
+### Performance Optimization
+```python
+# Use appropriate warehouse size
+ingestor = SnowflakeIngestor(
+    account="myaccount",
+    user="myuser",
+    password="mypassword",
+    warehouse="LARGE_WH"  # For heavy workloads
+)
+```
+
+---
+
+## 📚 See Also
+
+- **[Ingest Module Reference](../reference/ingest.md)** - Complete ingestion documentation
+- **[Getting Started Guide](../getting-started.md)** - Quick start with Semantica
+- **[Code Examples](../CodeExamples.md)** - More integration examples
+- **[Installation Guide](../installation.md)** - Installation instructions
@@ -1,570 +0,0 @@
-# Snowflake Ingestion Guide
-
-This guide explains how to use the Snowflake ingestor to extract data from Snowflake data warehouses into Semantica.
-
-## Table of Contents
-
- [Installation](#installation)
- [Authentication Methods](#authentication-methods)
- [Basic Usage](#basic-usage)
- [Advanced Features](#advanced-features)
- [Error Handling](#error-handling)
- [Best Practices](#best-practices)
-
-## Installation
-
-Install Semantica with Snowflake support:
-
-```bash
-# Install with Snowflake support only
-pip install semantica[db-snowflake]
-
-# Or install with all database connectors
-pip install semantica[db-all]
-```
-
-This will install:
- `snowflake-connector-python>=3.0.0`
- `cryptography>=3.4.0` (required for key-pair authentication)
-
-## Authentication Methods
-
-### 1. Password Authentication (Default)
-
-The simplest authentication method using username and password:
-
-```python
-from semantica.ingest import SnowflakeIngestor
-
-ingestor = SnowflakeIngestor(
-    account="myaccount",  # Your Snowflake account identifier
-    user="myuser",
-    password="mypassword",
-    warehouse="COMPUTE_WH",
-    database="MYDB",
-    schema="PUBLIC"
-)
-```
-
-**Environment Variables:**
-
-```bash
-export SNOWFLAKE_ACCOUNT="myaccount"
-export SNOWFLAKE_USER="myuser"
-export SNOWFLAKE_PASSWORD="mypassword"
-export SNOWFLAKE_WAREHOUSE="COMPUTE_WH"
-export SNOWFLAKE_DATABASE="MYDB"
-export SNOWFLAKE_SCHEMA="PUBLIC"
-```
-
-**Note:** For key-pair authentication, you must provide the `private_key_path` parameter directly in code. Environment variables are supported for account, user, warehouse, database, schema, role, authenticator, and token parameters.
-
-```python
-# Now you can omit supported parameters - they'll be read from environment
-ingestor = SnowflakeIngestor()
-```
-
-### 2. Key-Pair Authentication
-
-More secure authentication using RSA key pairs:
-
-**Generate Key Pair:**
-
-```bash
-# Generate private key
-openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
-
-# Generate public key
-openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
-```
-
-**Add public key to Snowflake:**
-
-```sql
-ALTER USER myuser SET RSA_PUBLIC_KEY='MIIBIjANBgkqh...';
-```
-
-**Use in Python:**
-
-```python
-from semantica.ingest import SnowflakeIngestor
-
-ingestor = SnowflakeIngestor(
-    account="myaccount",
-    user="myuser",
-    private_key_path="/path/to/rsa_key.p8",
-    warehouse="COMPUTE_WH",
-    database="MYDB"
-)
-```
-
-**With encrypted private key:**
-
-```python
-ingestor = SnowflakeIngestor(
-    account="myaccount",
-    user="myuser",
-    private_key_path="/path/to/rsa_key.p8",
-    private_key_passphrase="my_passphrase",
-    warehouse="COMPUTE_WH"
-)
-```
-
-### 3. OAuth Authentication
-
-Use OAuth tokens for authentication:
-
-```python
-ingestor = SnowflakeIngestor(
-    account="myaccount",
-    user="myuser",
-    authenticator="oauth",
-    token="your_oauth_token",
-    warehouse="COMPUTE_WH"
-)
-```
-
-### 4. SSO Authentication (External Browser)
-
-For organizations using SSO:
-
-```python
-ingestor = SnowflakeIngestor(
-    account="myaccount",
-    user="myuser",
-    authenticator="externalbrowser",
-    warehouse="COMPUTE_WH"
-)
-# This will open a browser for SSO login
-```
-
-## Basic Usage
-
-### Ingest a Table
-
-```python
-from semantica.ingest import SnowflakeIngestor
-
-ingestor = SnowflakeIngestor(
-    account="myaccount",
-    user="myuser",
-    password="mypassword",
-    warehouse="COMPUTE_WH",
-    database="MYDB",
-    schema="PUBLIC"
-)
-
-# Ingest entire table
-data = ingestor.ingest_table("CUSTOMERS")
-
-print(f"Retrieved {data.row_count} rows")
-print(f"Columns: {data.columns}")
-print(f"First row: {data.data[0]}")
-```
-
-### Ingest with Filters
-
-```python
-# With WHERE clause
-data = ingestor.ingest_table(
-    "CUSTOMERS",
-    where="COUNTRY = 'USA' AND CREATED_DATE > '2024-01-01'"
-)
-
-# With limit and offset for pagination
-data = ingestor.ingest_table(
-    "CUSTOMERS",
-    limit=10000,
-    offset=0,
-    order_by="CREATED_DATE DESC"
-)
-```
-
-### Execute Custom Queries
-
-```python
-# Simple query
-data = ingestor.ingest_query("""
-    SELECT 
-        CUSTOMER_ID,
-        SUM(AMOUNT) AS TOTAL_AMOUNT
-    FROM SALES
-    WHERE DATE >= '2024-01-01'
-    GROUP BY CUSTOMER_ID
-    HAVING SUM(AMOUNT) > 1000
-""")
-
-# Parameterized query
-data = ingestor.ingest_query(
-    "SELECT * FROM SALES WHERE DATE > %(start_date)s AND REGION = %(region)s",
-    params={
-        "start_date": "2024-01-01",
-        "region": "WEST"
-    }
-)
-```
-
-### Large Result Sets with Batching
-
-```python
-# Fetch in batches to manage memory
-data = ingestor.ingest_query(
-    "SELECT * FROM LARGE_TABLE",
-    batch_size=5000  # Fetch 5000 rows at a time
-)
-
-print(f"Total rows: {data.row_count}")
-```
-
-## Advanced Features
-
-### Schema Introspection
-
-```python
-# Get table schema
-schema = ingestor.get_table_schema("CUSTOMERS")
-
-for column in schema["columns"]:
-    print(f"{column['name']}: {column['type']} (nullable: {column['nullable']})")
-
-print(f"Primary keys: {schema['primary_keys']}")
-```
-
-### List All Tables
-
-```python
-# List tables in current schema
-tables = ingestor.list_tables()
-print(f"Found {len(tables)} tables: {tables}")
-
-# List tables in specific database/schema
-tables = ingestor.list_tables(database="OTHER_DB", schema="OTHER_SCHEMA")
-```
-
-### Export as Documents
-
-Convert Snowflake data to Semantica document format:
-
-```python
-# Ingest data
-data = ingestor.ingest_table("ARTICLES")
-
-# Convert to documents
-documents = ingestor.export_as_documents(
-    data,
-    id_field="ARTICLE_ID",
-    text_fields=["TITLE", "CONTENT", "SUMMARY"]
-)
-
-# Now use in Semantica pipeline
-from semantica.pipeline import Pipeline
-
-pipeline = Pipeline()
-for doc in documents:
-    pipeline.process_document(doc)
-```
-
-### Context Manager
-
-Use as a context manager for automatic connection cleanup:
-
-```python
-with SnowflakeIngestor(
-    account="myaccount",
-    user="myuser",
-    password="mypassword"
-) as ingestor:
-    data = ingestor.ingest_table("CUSTOMERS")
-    # Connection automatically closed on exit
-```
-
-### Multiple Schemas/Databases
-
-```python
-# Ingest from different databases and schemas
-data1 = ingestor.ingest_table(
-    "CUSTOMERS",
-    database="SALES_DB",
-    schema="PROD"
-)
-
-data2 = ingestor.ingest_table(
-    "ORDERS",
-    database="SALES_DB",
-    schema="STAGING"
-)
-```
-
-## Error Handling
-
-```python
-from semantica.utils.exceptions import ProcessingError, ValidationError
-
-try:
-    ingestor = SnowflakeIngestor(
-        account="myaccount",
-        user="myuser",
-        password="wrong_password"
-    )
-    data = ingestor.ingest_table("CUSTOMERS")
-    
-except ValidationError as e:
-    print(f"Configuration error: {e}")
-    
-except ProcessingError as e:
-    print(f"Processing failed: {e}")
-    
-except Exception as e:
-    print(f"Unexpected error: {e}")
-```
-
-### Test Connection
-
-```python
-# Test connection before using
-connector = SnowflakeConnector(
-    account="myaccount",
-    user="myuser",
-    password="mypassword"
-)
-
-if connector.test_connection():
-    print("Connection successful!")
-else:
-    print("Connection failed")
-```
-
-## Best Practices
-
-### 1. Use Environment Variables for Credentials
-
-**Don't:**
-```python
-# Hard-coded credentials (bad!)
-ingestor = SnowflakeIngestor(
-    account="myaccount",
-    user="myuser",
-    password="mypassword123"
-)
-```
-
-**Do:**
-```python
-# Use environment variables
-import os
-from dotenv import load_dotenv
-
-load_dotenv()
-
-ingestor = SnowflakeIngestor()  # Reads from environment
-```
-
-### 2. Use Key-Pair Authentication for Production
-
-Key-pair authentication is more secure than passwords:
-
-```python
-ingestor = SnowflakeIngestor(
-    account="myaccount",
-    user="myuser",
-    private_key_path=os.getenv("SNOWFLAKE_PRIVATE_KEY_PATH"),
-    warehouse="COMPUTE_WH"
-)
-```
-
-### 3. Paginate Large Result Sets
-
-```python
-# Don't fetch millions of rows at once
-PAGE_SIZE = 10000
-
-for page in range(total_pages):
-    data = ingestor.ingest_table(
-        "LARGE_TABLE",
-        limit=PAGE_SIZE,
-        offset=page * PAGE_SIZE
-    )
-    process_batch(data)
-```
-
-### 4. Use Query Filters
-
-Push filtering to Snowflake instead of filtering in Python:
-
-**Don't:**
-```python
-# Fetching all rows and filtering in Python (inefficient)
-all_data = ingestor.ingest_table("CUSTOMERS")
-filtered = [row for row in all_data.data if row["COUNTRY"] == "USA"]
-```
-
-**Do:**
-```python
-# Filter in Snowflake (efficient)
-data = ingestor.ingest_table("CUSTOMERS", where="COUNTRY = 'USA'")
-```
-
-### 5. Set Appropriate Warehouse Size
-
-```python
-# Use appropriate warehouse for workload
-ingestor = SnowflakeIngestor(
-    account="myaccount",
-    user="myuser",
-    password="mypassword",
-    warehouse="LARGE_WH"  # For heavy workloads
-)
-```
-
-### 6. Close Connections
-
-```python
-# Always close connections when done
-try:
-    ingestor = SnowflakeIngestor(...)
-    data = ingestor.ingest_table("CUSTOMERS")
-finally:
-    ingestor.close()
-
-# Or use context manager
-with SnowflakeIngestor(...) as ingestor:
-    data = ingestor.ingest_table("CUSTOMERS")
-```
-
-## Examples
-
-### Example 1: ETL Pipeline
-
-```python
-from semantica.ingest import SnowflakeIngestor
-from semantica.pipeline import Pipeline
-
-# Initialize ingestor
-ingestor = SnowflakeIngestor()
-
-# Extract data
-sales_data = ingestor.ingest_query("""
-    SELECT 
-        s.ORDER_ID,
-        s.CUSTOMER_ID,
-        c.CUSTOMER_NAME,
-        s.PRODUCT_ID,
-        p.PRODUCT_NAME,
-        s.AMOUNT,
-        s.ORDER_DATE
-    FROM SALES s
-    JOIN CUSTOMERS c ON s.CUSTOMER_ID = c.ID
-    JOIN PRODUCTS p ON s.PRODUCT_ID = p.ID
-    WHERE s.ORDER_DATE >= CURRENT_DATE - 30
-""")
-
-# Transform to documents
-documents = ingestor.export_as_documents(
-    sales_data,
-    id_field="ORDER_ID",
-    text_fields=["CUSTOMER_NAME", "PRODUCT_NAME"]
-)
-
-# Load into Semantica
-pipeline = Pipeline()
-pipeline.process_documents(documents)
-```
-
-### Example 2: Multi-Table Ingestion
-
-```python
-from semantica.ingest import SnowflakeIngestor
-
-ingestor = SnowflakeIngestor()
-
-# Get all tables
-tables = ingestor.list_tables()
-
-# Ingest each table
-for table_name in tables:
-    print(f"Ingesting {table_name}...")
-    
-    # Get schema first
-    schema = ingestor.get_table_schema(table_name)
-    
-    # Ingest with limit
-    data = ingestor.ingest_table(table_name, limit=1000)
-    
-    # Process data
-    process_table(table_name, data, schema)
-```
-
-### Example 3: Incremental Loading
-
-```python
-import datetime
-from semantica.ingest import SnowflakeIngestor
-
-ingestor = SnowflakeIngestor()
-
-# Get last load timestamp
-last_load = get_last_load_timestamp()  # Your function
-
-# Ingest only new/updated records
-data = ingestor.ingest_table(
-    "CUSTOMERS",
-    where=f"UPDATED_AT > '{last_load}'",
-    order_by="UPDATED_AT ASC"
-)
-
-print(f"Loaded {data.row_count} new/updated records")
-
-# Update last load timestamp
-set_last_load_timestamp(datetime.datetime.now())
-```
-
-## Troubleshooting
-
-### Connection Issues
-
-```python
-# Enable verbose logging
-import logging
-logging.basicConfig(level=logging.DEBUG)
-
-# Test connection
-connector = SnowflakeConnector(
-    account="myaccount",
-    user="myuser",
-    password="mypassword"
-)
-
-if not connector.test_connection():
-    print("Connection failed - check credentials and network")
-```
-
-### Large Query Timeouts
-
-```python
-# Use batching for large queries
-data = ingestor.ingest_query(
-    "SELECT * FROM VERY_LARGE_TABLE",
-    batch_size=10000  # Fetch in batches
-)
-```
-
-### Memory Issues with Large Results
-
-```python
-# Process in chunks instead of loading all at once
-CHUNK_SIZE = 10000
-offset = 0
-
-while True:
-    chunk = ingestor.ingest_table(
-        "LARGE_TABLE",
-        limit=CHUNK_SIZE,
-        offset=offset
-    )
-    
-    if chunk.row_count == 0:
-        break
-        
-    process_chunk(chunk)
-    offset += CHUNK_SIZE
-```
@@ -1,6 +1,6 @@
 # License

-Semantica is released under the MIT License.
+**Semantica is open source under the MIT License.**

 ---

@@ -34,45 +34,52 @@ SOFTWARE.

 ## What This Means

-### You Can:
- ✅ Use commercially
- ✅ Modify the source code
- ✅ Distribute the software
- ✅ Use in private/proprietary projects
- ✅ Sublicense it
+### ✅ You Can
+- **Use commercially** - Free for business use
+- **Modify** - Change the source code
+- **Distribute** - Share with others
+- **Sublicense** - Use in your own projects
+- **Private use** - Use in proprietary software

-### You Must:
- ✅ Include copyright notice
- ✅ Include license text
+### ✅ You Must
+- **Include copyright** - Keep the copyright notice
+- **Include license** - Share the MIT license text

-### You Cannot:
- ❌ Hold authors liable
- ❌ Use authors' names for endorsement
+### ❌ No Warranty
+- **No liability** - Authors not responsible for damages
+- **No endorsement** - Can't use authors' names for promotion

 ---

 ## Commercial Use

-**Semantica is free for commercial use.** No attribution required (though appreciated)!
+**Semantica is completely free for commercial use.** No attribution required (though appreciated!).

 ---

-## Third-Party Licenses
+## Third-Party Dependencies

-Key dependencies:
- Python (PSF), NumPy (BSD), Pandas (BSD)
- spaCy (MIT), Transformers (Apache 2.0), RDFLib (BSD)
-
-See `LICENSE` file for complete list.
+Semantica uses open-source libraries with compatible licenses:
+- **Python** (PSF License)
+- **NumPy, Pandas** (BSD License)
+- **spaCy** (MIT License)
+- **Transformers** (Apache 2.0)
+- **RDFLib** (BSD License)

 ---

 ## Contributing

-By contributing, you agree your contributions will be licensed under MIT.
+By contributing to Semantica, you agree that your contributions will be licensed under the same MIT License.

 ---

-**Questions?** [Open an issue](https://github.com/Hawksight-AI/semantica/issues)
+## Questions?

-**Semantica is 100% open source and free!** 🎉
+- **[GitHub Issues](https://github.com/Hawksight-AI/semantica/issues)** - License questions
+- **[Contributing Guide](contributing.md)** - How to contribute
+- **[Community](community.md)** - Get in touch
+
+---
+
+**Semantica is open source and free for everyone!** 🎉
@@ -14,7 +14,7 @@ The **Ingest Module** is the entry point for loading data into Semantica. It pro
 - **File Systems**: Local files, cloud storage (S3, GCS, Azure)
 - **Web Content**: Websites, RSS feeds, APIs
 - **Streams**: Real-time data from Kafka, RabbitMQ, etc.
- **Databases**: SQL and NoSQL databases
+- **Databases**: SQL, NoSQL, and cloud data warehouses including Snowflake
 - **Repositories**: Git repositories (GitHub, GitLab)
 - **Email**: IMAP, POP3 servers
 - **MCP**: Model Context Protocol servers
@@ -72,7 +72,7 @@ The **Ingest Module** is the entry point for loading data into Semantica. It pro

    ---

-    Ingest tables and query results from SQL databases
+    Ingest tables and query results from SQL, NoSQL, and cloud data warehouses including Snowflake

 </div>

@@ -173,7 +173,7 @@ Handles IMAP and POP3 servers.

 ### DBIngestor

-Handles SQL databases.
+Handles SQL and NoSQL databases including Snowflake.

 **Methods:**

@@ -181,6 +181,16 @@ Handles SQL databases.
 |--------|-------------|
 | `ingest_database(conn)` | Export tables |
 | `execute_query(sql)` | Run custom SQL |
+| `connect_snowflake(account, user, password, warehouse)` | Connect to Snowflake |
+| `ingest_snowflake_table(table_name)` | Ingest Snowflake table |
+| `execute_snowflake_query(sql)` | Run Snowflake SQL |
+
+**Supported Databases:**
+- **PostgreSQL**, **MySQL**, **SQLite**
+- **Microsoft SQL Server**, **Oracle**
+- **Snowflake** (Cloud Data Warehouse)
+- **MongoDB**, **Cassandra** (NoSQL)
+- **BigQuery**, **Redshift** (Cloud Data Warehouses)

 ### MCPIngestor

@@ -258,6 +268,64 @@ ingestor.monitor(
 )
 ```

+### Snowflake Data Warehouse Integration
+
+```python
+from semantica.ingest import DBIngestor
+
+# 1. Connect to Snowflake
+ingestor = DBIngestor()
+ingestor.connect_snowflake(
+    account="your_account.snowflakecomputing.com",
+    user="your_username",
+    password="your_password",
+    warehouse="ANALYTICS_WH",
+    database="PRODUCTION_DB",
+    schema="PUBLIC"
+)
+
+# 2. Ingest entire table
+data = ingestor.ingest_snowflake_table("CUSTOMERS")
+
+# 3. Or run custom query
+results = ingestor.execute_snowflake_query("""
+    SELECT 
+        CUSTOMER_ID, 
+        NAME, 
+        EMAIL, 
+        CREATED_AT 
+    FROM CUSTOMERS 
+    WHERE CREATED_AT > '2024-01-01'
+""")
+
+# 4. Process with pipeline
+for row in results:
+    pipeline.process(row)
+```
+
+!!! info "Comprehensive Snowflake Guide"
+    For detailed Snowflake integration including authentication methods, advanced features, and best practices, see the **[Snowflake Integration Guide](../integrations/snowflake.md)**.
+
+### Multi-Database Integration
+
+```python
+from semantica.ingest import DBIngestor
+
+ingestor = DBIngestor()
+
+# Connect to multiple databases
+connections = {
+    "snowflake": ingestor.connect_snowflake(...),
+    "postgres": ingestor.connect_database("postgresql://..."),
+    "mysql": ingestor.connect_database("mysql://...")
+}
+
+# Ingest from all sources
+for name, conn in connections.items():
+    data = ingestor.ingest_database(conn)
+    print(f"Ingested {len(data)} records from {name}")
+```
+
 ---

 ## Best Practices
@@ -271,6 +339,7 @@ ingestor.monitor(

 ## See Also

+- **[Snowflake Integration Guide](../integrations/snowflake.md)** - Comprehensive Snowflake integration with authentication, advanced features, and best practices
 - [Parse Module](parse.md) - Processes the raw data ingested here
 - [Split Module](split.md) - Chunks the ingested content
 - [Utils Module](utils.md) - Validation helpers
@@ -6,6 +6,58 @@

 The Semantica provenance module provides W3C PROV-O compliant tracking for knowledge graphs, enabling complete end-to-end lineage from source documents to query responses. Designed for high-stakes domains where every decision must be explainable and auditable.

+<div class="grid cards" markdown>
+
+-   :material-web:{ .lg .middle } **W3C PROV-O Compliant**
+
+    ---
+
+    Implements PROV-O ontology (prov:Entity, prov:Activity, prov:Agent, prov:wasDerivedFrom)
+
+-   :material-all-inclusive:{ .lg .middle } **Complete Coverage**
+
+    ---
+
+    All 17 Semantica modules integrated for comprehensive tracking
+
+-   :material-source-document:{ .lg .middle } **Source Tracking**
+
+    ---
+
+    Document identifiers, page numbers, sections, and direct quotes supported
+
+-   :material-backup-restore:{ .lg .middle } **Backward Compatible**
+
+    ---
+
+    100% backward compatible, opt-in only with zero breaking changes
+
+-   :material-database:{ .lg .middle } **Multiple Storage**
+
+    ---
+
+    InMemory (fast) and SQLite (persistent) backends available
+
+-   :material-bridge:{ .lg .middle } **Bridge Axiom Support**
+
+    ---
+
+    Translation chain tracking for domain transformations (L1 → L2 → L3)
+
+-   :material-shield-check:{ .lg .middle } **Integrity Verification**
+
+    ---
+
+    SHA-256 checksums for tamper detection and verification
+
+-   :material-route:{ .lg .middle } **Complete Lineage**
+
+    ---
+
+    End-to-end tracing from document to AI response
+
+</div>
+
 ### Key Features

 - ✅ **W3C PROV-O Compliant** — Implements PROV-O ontology (prov:Entity, prov:Activity, prov:Agent, prov:wasDerivedFrom)
@@ -45,6 +97,12 @@ manager = ProvenanceManager()
 manager = ProvenanceManager(storage_path="provenance.db")
 ```

+**Key capabilities:**
+- Track entities and relationships with complete lineage
+- Store provenance data in memory or persistent SQLite storage
+- Query provenance information for audit and compliance
+- Maintain W3C PROV-O compliant records
+
 **Methods:**
 - `track_entity(entity_id, source, entity_type, **metadata)` — Track entity provenance
 - `track_relationship(relationship_id, source, subject, predicate, obj, **metadata)` — Track relationship provenance
@@ -66,6 +124,12 @@ from semantica.provenance import ProvenanceManager, InMemoryStorage
 manager = ProvenanceManager(storage=InMemoryStorage())
 ```

+**Best for:**
+- Development and testing environments
+- Temporary provenance tracking
+- High-performance scenarios where persistence isn't required
+- Rapid prototyping and debugging
+
 #### SQLiteStorage

 Persistent storage for production use.
@@ -77,6 +141,12 @@ storage = SQLiteStorage("provenance.db")
 manager = ProvenanceManager(storage=storage)
 ```

+**Best for:**
+- Production deployments requiring persistence
+- Long-term provenance storage
+- Compliance and audit requirements
+- Multi-process environments
+
 ### Data Schemas

 #### ProvenanceEntry
@@ -504,9 +574,9 @@ manager = ProvenanceManager(storage=storage)

 ### Benchmarks

- **Entity tracking:** <5ms per operation
- **Lineage retrieval:** <10ms for chains up to 100 levels
- **Batch operations:** 1000+ entities/second
+- **Entity tracking:** Fast per operation
+- **Lineage retrieval:** Quick retrieval for long chains
+- **Batch operations:** High-throughput batch processing
 - **Storage:** InMemory (fastest), SQLite (persistent)

 ### Optimization Tips
@@ -1,3 +0,0 @@
-# Release Guide
-
--8<-- "RELEASE.md"
@@ -133,25 +133,17 @@ nav:
    - Visualization: reference/visualization.md
  - Guides:
    - concepts.md
-    - deep-dive.md
    - modules.md
-    - glossary.md
    - use-cases.md
    - examples.md
-    - Code Examples: CodeExamples.md
-    - learning-more.md
+    - glossary.md
  - Integrations:
    - Docling: integrations/docling.md
+    - Snowflake: integrations/snowflake.md
  - Cookbook: cookbook.md
  - Resources:
-    - community-projects.md
    - community.md
    - contributing.md
-    - architecture.md
-    - governance.md
-    - citation.md
-    - Changelog: changelog.md
-    - Release Guide: release-guide.md
    - faq.md
    - license.md