diff --git a/docs/architecture.md b/docs/architecture.md
index 8d3fe72b..dbe483a2 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,324 +1,96 @@
# Architecture
-This document describes the architecture of the Semantica framework.
+Semantica's modular, extensible framework for semantic intelligence and knowledge engineering.
-## Overview
+---
-Semantica is built as a modular, extensible framework for semantic intelligence and knowledge engineering. The architecture is designed to be:
+## Design Principles
- **Modular**: Independent, reusable components
- **Extensible**: Easy to add new functionality
- **Scalable**: Handle large-scale data processing
- **Maintainable**: Clear separation of concerns
+---
+
## System Architecture
-```
-┌─────────────────────────────────────────────────────────────┐
-│ SEMANTICA FRAMEWORK │
-├─────────────────────────────────────────────────────────────┤
-│ │
-│ ┌─────────────────────────────────────────────────────┐ │
-│ │ DATA INGESTION LAYER │ │
-│ │ ┌──────┬──────┬──────┬──────┬──────┬──────────┐ │ │
-│ │ │Files │ Web │Feeds │ APIs │Stream│ Archives │ │ │
-│ │ └──────┴──────┴──────┴──────┴──────┴──────────┘ │ │
-│ │ 50+ Formats • Real-time • Multi-modal │ │
-│ └─────────────────────────────────────────────────────┘ │
-│ ↓ │
-│ ┌─────────────────────────────────────────────────────┐ │
-│ │ SEMANTIC PROCESSING LAYER │ │
-│ │ ┌──────────┬────────────┬────────────┬──────────┐ │ │
-│ │ │ Parse │ Normalize │ Extract │ Build │ │ │
-│ │ │ │ │ Semantics │ Graph │ │ │
-│ │ └──────────┴────────────┴────────────┴──────────┘ │ │
-│ │ NLP • Embeddings • Ontologies • Quality Assurance│ │ │
-│ └─────────────────────────────────────────────────────┘ │
-│ ↓ │
-│ ┌─────────────────────────────────────────────────────┐ │
-│ │ APPLICATION LAYER │ │
-│ │ ┌──────────┬────────────┬────────────┬──────────┐ │ │
-│ │ │ GraphRAG │ AI Agents │Multi-Agent │Analytics │ │ │
-│ │ │ │ │ Systems │ Copilots │ │ │
-│ │ └──────────┴────────────┴────────────┴──────────┘ │ │
-│ │ Hybrid Retrieval • Context • Reasoning │ │ │
-│ └─────────────────────────────────────────────────────┘ │
-│ │
-└─────────────────────────────────────────────────────────────┘
+```mermaid
+graph TB
+ A[Data Ingestion Layer] --> B[Semantic Processing Layer]
+ B --> C[Application Layer]
+
+ A1[Files • Web • APIs • Streams] --> A
+ B1[Parse • Normalize • Extract • Build] --> B
+ C1[GraphRAG • AI Agents • Analytics] --> C
```
-## Module Architecture
+### Three-Layer Architecture
-### Core Modules
+**1. Data Ingestion Layer**
+- 50+ file formats (PDF, DOCX, JSON, CSV, etc.)
+- Web scraping and APIs
+- Real-time streams (Kafka, RabbitMQ)
+- Database connectors (SQL, NoSQL)
-#### `semantica.core`
+**2. Semantic Processing Layer**
+- Document parsing and normalization
+- Entity and relationship extraction
+- Embedding generation
+- Knowledge graph construction
+- Quality assurance and deduplication
-The core orchestration module that coordinates all framework components.
+**3. Application Layer**
+- GraphRAG for enhanced retrieval
+- AI agent memory and context
+- Multi-agent systems
+- Analytics and visualization
-**Key Components**:
-- `Semantica`: Main framework class
-- `Orchestrator`: Pipeline coordination
-- `ConfigManager`: Configuration management
-- `PluginRegistry`: Plugin system
-- `LifecycleManager`: System lifecycle
+---
-**Responsibilities**:
-- Initialize and configure components
-- Coordinate data flow between modules
-- Manage plugin system
-- Handle errors and recovery
+## Core Modules
-#### `semantica.pipeline`
+### Orchestration
+- **`semantica.core`** - Main framework class and coordination
+- **`semantica.pipeline`** - Pipeline management and execution
-Pipeline management and execution.
+### Data Processing
+- **`semantica.ingest`** - Universal data ingestion
+- **`semantica.parse`** - Document parsing
+- **`semantica.normalize`** - Data cleaning and normalization
-**Key Components**:
-- `PipelineBuilder`: Pipeline construction DSL
-- `ExecutionEngine`: Pipeline execution
-- `PipelineValidator`: Validation
-- `ParallelismManager`: Parallel execution
-- `ResourceScheduler`: Resource allocation
+### Semantic Intelligence
+- **`semantica.semantic_extract`** - Entity and relationship extraction
+- **`semantica.embeddings`** - Vector embedding generation
+- **`semantica.ontology`** - Ontology generation and management
-**Responsibilities**:
-- Define processing pipelines
-- Execute pipelines with parallelism
-- Manage resources
-- Handle failures
+### Knowledge Graphs
+- **`semantica.kg`** - Knowledge graph construction
+- **`semantica.vector_store`** - Vector storage (Pinecone, Weaviate, FAISS)
+- **`semantica.triple_store`** - RDF triple storage (Jena, Blazegraph)
+- **`semantica.graph_store`** - Property graphs (Neo4j, KuzuDB, FalkorDB)
-### Data Processing Modules
+### Quality Assurance
+- **`semantica.deduplication`** - Entity deduplication
+- **`semantica.conflicts`** - Conflict detection and resolution
+- **`semantica.kg_qa`** - Quality assessment
-#### `semantica.ingest`
-
-Universal data ingestion from multiple sources.
-
-**Supported Sources**:
-- Files (50+ formats)
-- Web (scraping, APIs)
-- Databases (SQL, NoSQL)
-- Streams (Kafka, RabbitMQ)
-- Archives (ZIP, TAR, etc.)
-
-**Key Components**:
-- `FileIngestor`: File processing
-- `WebIngestor`: Web scraping
-- `DBIngestor`: Database access
-- `StreamIngestor`: Real-time streams
-
-#### `semantica.parse`
-
-Document parsing and extraction.
-
-**Key Components**:
-- `DocumentParser`: PDF, DOCX, etc.
-- `WebParser`: HTML, XML
-- `StructuredDataParser`: JSON, CSV
-- `EmailParser`: Email formats
-
-#### `semantica.normalize`
-
-Data normalization and cleaning.
-
-**Key Components**:
-- `TextNormalizer`: Text normalization
-- `EntityNormalizer`: Entity name normalization
-- `DateNormalizer`: Date format normalization
-- `EncodingHandler`: Character encoding
-
-### Semantic Intelligence Modules
-
-#### `semantica.semantic_extract`
-
-Entity and relationship extraction.
-
-**Key Components**:
-- `NamedEntityRecognizer`: NER
-- `RelationExtractor`: Relationship extraction
-- `EventDetector`: Event detection
-- `CoreferenceResolver`: Coreference resolution
-- `TripleExtractor`: RDF triple extraction
-
-#### `semantica.embeddings`
-
-Vector embedding generation.
-
-**Key Components**:
-- `EmbeddingGenerator`: Main generator
-- `TextEmbedder`: Text embeddings
-- `MultiModalEmbedder`: Multi-modal embeddings
-- `ProviderAdapters`: Provider-specific adapters
-
-#### `semantica.ontology`
-
-Ontology generation and management.
-
-**Key Components**:
-- `OntologyGenerator`: 6-stage generation pipeline
-- `ClassInferrer`: Class discovery
-- `PropertyGenerator`: Property inference
-- `OntologyValidator`: Validation
-
-### Knowledge Graph Modules
-
-#### `semantica.kg`
-
-Knowledge graph construction and analysis.
-
-**Key Components**:
-- `GraphBuilder`: Graph construction
-- `EntityResolver`: Entity resolution
-- `GraphAnalyzer`: Graph analytics
-- `TemporalGraphQuery`: Time-aware queries
-
-#### `semantica.vector_store`
-
-Vector storage and search.
-
-**Key Components**:
-- `VectorStore`: Main interface
-- `PineconeAdapter`: Pinecone integration
-- `WeaviateAdapter`: Weaviate integration
-- `FAISSAdapter`: FAISS integration
-
-#### `semantica.triple_store`
-
-RDF triple storage.
-
-**Key Components**:
-- `TripleManager`: Triple management
-- `QueryEngine`: SPARQL queries
-- `JenaAdapter`: Apache Jena
-- `BlazegraphAdapter`: Blazegraph
-
-#### `semantica.graph_store`
-
-Property graph database storage with multiple backend support.
-
-**Key Components**:
-- `GraphStore`: Main graph store interface
-- `Neo4jAdapter`: Neo4j integration
-- `KuzuAdapter`: KuzuDB embedded database
-- `FalkorDBAdapter`: FalkorDB (Redis-based) integration
-- `NodeManager`: Node CRUD operations
-- `RelationshipManager`: Relationship operations
-- `QueryEngine`: Cypher query execution
-- `GraphAnalytics`: Graph algorithms
-
-**Supported Backends**:
-- Neo4j (production-grade, server/cloud)
-- KuzuDB (embedded, analytics-optimized)
-- FalkorDB (ultra-fast, Redis-based, LLM apps)
-
-### Quality Assurance Modules
-
-#### `semantica.deduplication`
-
-Entity deduplication.
-
-**Key Components**:
-- `DuplicateDetector`: Duplicate detection
-- `EntityMerger`: Entity merging
-- `SimilarityCalculator`: Similarity calculation
-
-#### `semantica.conflicts`
-
-Conflict detection and resolution.
-
-**Key Components**:
-- `ConflictDetector`: Conflict detection
-- `ConflictResolver`: Conflict resolution
-- `ConflictAnalyzer`: Conflict analysis
-
-#### `semantica.kg_qa`
-
-Knowledge graph quality assessment.
-
-**Key Components**:
-- `QualityAssessor`: Quality assessment
-- Quality metrics calculation
-- Validation rules
+---
## Data Flow
-### Typical Processing Flow
-
```
-1. Ingestion
- └─> Raw data from various sources
-
-2. Parsing
- └─> Structured content extraction
-
-3. Normalization
- └─> Cleaned and normalized data
-
-4. Semantic Extraction
- ├─> Entity extraction
- ├─> Relationship extraction
- └─> Event detection
-
-5. Knowledge Graph Construction
- ├─> Entity resolution
- ├─> Conflict resolution
- └─> Graph building
-
-6. Quality Assurance
- ├─> Deduplication
- ├─> Conflict detection
- └─> Quality assessment
-
-7. Storage
- ├─> Knowledge graph storage
- ├─> Vector embeddings
- ├─> Triple store (RDF)
- └─> Graph store (Property Graphs)
-
-8. Application
- ├─> GraphRAG queries
- ├─> AI agent context
- └─> Analytics
+1. Ingestion → Raw data from sources
+2. Parsing → Structured content extraction
+3. Normalization → Cleaned data
+4. Semantic Extraction → Entities, relationships, events
+5. Graph Construction → Entity resolution, conflict resolution
+6. Quality Assurance → Deduplication, validation
+7. Storage → Vector, triple, and graph stores
+8. Application → GraphRAG, agents, analytics
```
-## Design Decisions
-
-### Modularity
-
-**Decision**: Modular architecture with independent components
-
-**Rationale**:
-- Easy to understand and maintain
-- Components can be used independently
-- Easy to test in isolation
-- Simple to extend
-
-### Plugin System
-
-**Decision**: Plugin-based architecture for extensibility
-
-**Rationale**:
-- Users can add custom functionality
-- Community can contribute plugins
-- Core remains stable
-- Easy to integrate third-party tools
-
-### Configuration Management
-
-**Decision**: Centralized configuration with environment variable support
-
-**Rationale**:
-- Consistent configuration across modules
-- Easy to override for different environments
-- Supports both programmatic and file-based config
-- Secure handling of sensitive data
-
-### Error Handling
-
-**Decision**: Comprehensive error handling with recovery
-
-**Rationale**:
-- Production-ready reliability
-- Graceful degradation
-- Detailed error reporting
-- Recovery mechanisms
+---
## Extension Points
@@ -355,43 +127,62 @@ class CustomValidator(BaseValidator):
pass
```
-## Performance Considerations
+---
-### Scalability
+## Design Decisions
+### Modularity
+Independent components that can be used standalone or together. Easy to test, maintain, and extend.
+
+### Plugin System
+Extensible architecture allowing custom functionality without modifying core code.
+
+### Configuration Management
+Centralized configuration with environment variable support for different deployment environments.
+
+### Error Handling
+Comprehensive error handling with graceful degradation and recovery mechanisms.
+
+---
+
+## Performance
+
+**Scalability**
- Parallel processing support
- Streaming for large datasets
- Efficient memory usage
-- Caching strategies
+- Intelligent caching
-### Optimization
-
-- Lazy loading where possible
+**Optimization**
+- Lazy loading
- Batch processing
- Connection pooling
- Query optimization
+---
+
## Security
-### Data Security
-
+**Data Security**
- Secure credential handling
-- Input validation
-- Output sanitization
+- Input validation and output sanitization
- Audit logging
-### Access Control
-
-- Authentication support
-- Authorization mechanisms
+**Access Control**
+- Authentication and authorization
- API key management
-- Role-based access
+- Role-based access control
-## Future Enhancements
+---
+
+## Future Roadmap
- Distributed processing
- Real-time streaming improvements
-- Advanced reasoning
+- Advanced reasoning capabilities
- Multi-modal expansion
- Enhanced visualization
+---
+
+For detailed module documentation, see [Modules Guide](modules.md)
diff --git a/docs/citation.md b/docs/citation.md
index 16210554..57a11aaf 100644
--- a/docs/citation.md
+++ b/docs/citation.md
@@ -2,67 +2,51 @@
How to cite Semantica in academic papers and research.
+---
+
## BibTeX
```bibtex
-@software{semantica2024,
+@software{semantica2025,
title = {Semantica: An Open Source Framework for Semantic Layers and Knowledge Engineering},
author = {Hawksight AI},
- year = {2024},
+ year = {2025},
url = {https://github.com/Hawksight-AI/semantica},
- version = {0.0.1},
+ version = {0.0.5},
license = {MIT}
}
```
-## APA Format
+---
-Hawksight AI. (2024). *Semantica: An Open Source Framework for Semantic Layers and Knowledge Engineering* (Version 0.0.1) [Computer software]. GitHub. https://github.com/Hawksight-AI/semantica
+## Citation Formats
-## MLA Format
+### APA
+Hawksight AI. (2025). *Semantica: An Open Source Framework for Semantic Layers and Knowledge Engineering* (Version 0.0.5) [Computer software]. https://github.com/Hawksight-AI/semantica
-Hawksight AI. *Semantica: An Open Source Framework for Semantic Layers and Knowledge Engineering*. Version 0.0.1, GitHub, 2024, https://github.com/Hawksight-AI/semantica.
+### MLA
+Hawksight AI. *Semantica: An Open Source Framework for Semantic Layers and Knowledge Engineering*. Version 0.0.5, GitHub, 2025, https://github.com/Hawksight-AI/semantica.
-## Chicago Style
+### Chicago
+Hawksight AI. *Semantica: An Open Source Framework for Semantic Layers and Knowledge Engineering*. Version 0.0.5. GitHub, 2025. https://github.com/Hawksight-AI/semantica.
-Hawksight AI. *Semantica: An Open Source Framework for Semantic Layers and Knowledge Engineering*. Version 0.0.1. GitHub, 2024. https://github.com/Hawksight-AI/semantica.
-
-## IEEE Format
-
-Hawksight AI, "Semantica: An Open Source Framework for Semantic Layers and Knowledge Engineering," Version 0.0.1, GitHub, 2024. [Online]. Available: https://github.com/Hawksight-AI/semantica
-
-## Plain Text Citation
-
-If you use Semantica in your research, please cite:
-
-```
-Semantica: An Open Source Framework for Semantic Layers and Knowledge Engineering
-Hawksight AI (2024)
-https://github.com/Hawksight-AI/semantica
-Version 0.0.1
-```
-
-## Research Papers
-
-If you publish research using Semantica, we'd love to know! Please:
-
-1. Share your paper with us
-2. Let us know how Semantica was used
-3. We may feature your work in our documentation
-
-Contact: [GitHub Discussions](https://github.com/Hawksight-AI/semantica/discussions)
-
-## Acknowledgments
-
-If you use Semantica in your work, we appreciate acknowledgments such as:
-
-> "This work uses Semantica (Hawksight AI, 2024), an open-source framework for semantic layer construction and knowledge engineering."
-
-## License
-
-Semantica is licensed under the MIT License. See the [License](license.md) page for details.
+### IEEE
+Hawksight AI, "Semantica: An Open Source Framework for Semantic Layers and Knowledge Engineering," Version 0.0.5, GitHub, 2025. [Online]. Available: https://github.com/Hawksight-AI/semantica
---
-**Questions about citation?** [Open a discussion](https://github.com/Hawksight-AI/semantica/discussions) or [contact us](https://github.com/Hawksight-AI/semantica/issues).
+## Acknowledgment
+If you use Semantica in your work:
+
+> "This work uses Semantica (Hawksight AI, 2025), an open-source framework for semantic layer construction and knowledge engineering."
+
+---
+
+## Share Your Research
+
+Published research using Semantica? [Let us know](https://github.com/Hawksight-AI/semantica/issues) - we may feature your work!
+
+---
+
+**License**: MIT - See [License](license.md) for details
diff --git a/docs/community-projects.md b/docs/community-projects.md
index d0490981..123a8ea7 100644
--- a/docs/community-projects.md
+++ b/docs/community-projects.md
@@ -1,251 +1,63 @@
# Community Projects
-Projects, integrations, and contributions from the Semantica community.
+Projects and integrations from the Semantica community.
!!! tip "Showcase Your Project"
- Have a project using Semantica? We'd love to feature it! [Submit your project](https://github.com/Hawksight-AI/semantica/discussions/categories/show-and-tell)
+ Have a project using Semantica? [Submit it here](https://github.com/Hawksight-AI/semantica/issues/new)
---
## 🚀 Projects Using Semantica
-
+**Research & Academia**
+- Academic research and scientific literature analysis
+- Biomedical analysis and drug discovery
+- Social network analysis and community detection
-- :material-school: **Academic Research**
- ---
- Knowledge graph construction for research papers and scientific literature.
-
- **Domain**: Research & Academia
-
-- :material-dna: **Biomedical Analysis**
- ---
- Drug discovery, genomic analysis, and medical knowledge graphs.
-
- **Domain**: Healthcare & Life Sciences
-
-- :material-account-network: **Social Network Analysis**
- ---
- Relationship mapping and community detection in social networks.
-
- **Domain**: Social Sciences
-
-- :material-domain: **Business Intelligence**
- ---
- Company knowledge bases and corporate intelligence systems.
-
- **Domain**: Enterprise
-
-- :material-shield-lock: **Cybersecurity**
- ---
- Threat intelligence, incident analysis, and security knowledge graphs.
-
- **Domain**: Security
-
-- :material-hospital-box: **Healthcare**
- ---
- Medical record processing and patient journey mapping.
-
- **Domain**: Healthcare
-
-- :material-finance: **Finance**
- ---
- Market analysis, fraud detection, and financial intelligence.
-
- **Domain**: Finance & Trading
-
-
+**Enterprise & Industry**
+- Business intelligence and corporate knowledge bases
+- Cybersecurity and threat intelligence
+- Healthcare and medical record processing
+- Finance, trading, and fraud detection
---
-## 🔌 Community Integrations
+## 🔌 Integrations
-### Vector Database Integrations
+### Vector Databases
+- **Pinecone** - Cloud-native vector database
+- **Weaviate** - Open-source vector search
+- **Qdrant** - High-performance similarity search
-
-
-- :material-database: **Pinecone**
- ---
- Cloud-native vector database integration.
-
- [View Example](https://github.com/Hawksight-AI/semantica/tree/main/examples/pinecone)
-
-- :material-database-search: **Weaviate**
- ---
- Open-source vector search engine integration.
-
- [View Example](https://github.com/Hawksight-AI/semantica/tree/main/examples/weaviate)
-
-- :material-database-arrow-right: **Qdrant**
- ---
- High-performance vector similarity search.
-
- [View Example](https://github.com/Hawksight-AI/semantica/tree/main/examples/qdrant)
-
-
-
-### Knowledge Graph Databases
-
-
-
-- :material-graph: **Neo4j**
- ---
- Export and query with the leading graph database.
-
- **Features**: Cypher queries, graph algorithms
-
-- :material-aws: **Amazon Neptune**
- ---
- Cloud-based graph database integration.
-
- **Features**: Managed service, scalable
-
-- :material-database-cog: **ArangoDB**
- ---
- Multi-model database support.
-
- **Features**: Document, graph, key-value
-
-
+### Graph Databases
+- **Neo4j** - Leading graph database with Cypher queries
+- **Amazon Neptune** - Cloud-based managed graph database
+- **ArangoDB** - Multi-model database support
---
-## 🛠️ Plugins and Extensions
+## 🛠️ Community Extensions
-Community-created tools and extensions:
-
-
-
-- :material-puzzle: **Custom Entity Extractors**
- ---
- Domain-specific entity extraction models and patterns.
-
-- :material-export: **Domain-Specific Exporters**
- ---
- Specialized export formats for various industries.
-
-- :material-connection: **Integration Adapters**
- ---
- Connectors for popular data sources and platforms.
-
-- :material-chart-box: **Visualization Tools**
- ---
- Enhanced graph visualization and analytics dashboards.
-
-
-
----
-
-## 📚 Community Tutorials
-
-### User-Created Tutorials
-
-Coming soon! Share your tutorials with the community.
-
-### Video Tutorials
-
-Coming soon! Create and share video guides.
+- Custom entity extractors for domain-specific use cases
+- Specialized export formats for various industries
+- Integration adapters for popular data sources
+- Enhanced visualization tools and dashboards
---
## 🤝 How to Contribute
-
+1. **Code**: Fork, create branch, submit PR
+2. **Documentation**: Fix typos, add examples, improve clarity
+3. **Community**: Answer questions, share experiences
+4. **Testing**: Write tests, report bugs
-- :material-code-braces: **Code Contributions**
- ---
- 1. Fork the repository
- 2. Create a feature branch
- 3. Make your changes
- 4. Submit a pull request
-
- [Contributing Guide](https://github.com/Hawksight-AI/semantica/blob/main/CONTRIBUTING.md)
-
-- :material-file-document-edit: **Documentation**
- ---
- - Fix typos
- - Improve examples
- - Add tutorials
- - Translate documentation
-
-- :material-account-group: **Community Support**
- ---
- - Answer questions in discussions
- - Help with issues
- - Share your experiences
- - Provide feedback
-
-- :material-test-tube: **Testing**
- ---
- - Write tests
- - Improve coverage
- - Report bugs
- - Test new features
-
-
-
----
-
-## 🎯 Submit Your Project
-
-### Submission Template
-
-```markdown
-## Project Name
-
-**Description**: Brief description of your project
-
-**Use Case**: How you're using Semantica
-
-**Key Features**:
-- Feature 1
-- Feature 2
-- Feature 3
-
-**Tech Stack**:
-- Semantica modules used
-- Other technologies
-
-**Links**:
-- GitHub: [link]
-- Demo: [link]
-- Documentation: [link]
-
-**Screenshots**: (Optional)
-```
-
-### How to Submit
-
-1. Go to [GitHub Discussions](https://github.com/Hawksight-AI/semantica/discussions/categories/show-and-tell)
-2. Create a new post using the template above
-3. Tag it with relevant labels
-4. Share your project!
-
----
-
-## 🏆 Recognition
-
-### Contributors
-
-Thank you to all contributors! See our [Contributors](https://github.com/Hawksight-AI/semantica/graphs/contributors) page.
-
-### Featured Projects
-
-We feature community projects in:
-- 📖 Documentation
-- ✍️ Blog posts
-- 📢 Release notes
-- 📱 Social media
+See our [Contributing Guide](https://github.com/Hawksight-AI/semantica/blob/main/CONTRIBUTING.md)
---
## 📞 Resources
-- **[GitHub Discussions](https://github.com/Hawksight-AI/semantica/discussions)** - Community discussions
-- **[GitHub Issues](https://github.com/Hawksight-AI/semantica/issues)** - Bug reports and feature requests
-- **[Examples Repository](https://github.com/Hawksight-AI/semantica/tree/main/examples)** - More examples
-- **[Contributing Guide](https://github.com/Hawksight-AI/semantica/blob/main/CONTRIBUTING.md)** - How to contribute
-
----
-
-!!! success "Get Involved"
- Join our community and help shape the future of Semantica! [Start Contributing](https://github.com/Hawksight-AI/semantica)
+- [GitHub Repository](https://github.com/Hawksight-AI/semantica)
+- [GitHub Issues](https://github.com/Hawksight-AI/semantica/issues)
+- [Contributing Guide](https://github.com/Hawksight-AI/semantica/blob/main/CONTRIBUTING.md)
diff --git a/docs/community.md b/docs/community.md
index 59c97fde..9e9bb183 100644
--- a/docs/community.md
+++ b/docs/community.md
@@ -1,299 +1,86 @@
# Community
-Welcome to the Semantica community! This guide will help you get involved and make the most of our community.
+Welcome to the Semantica community!
-## Community Values
-
-Our community is built on:
-
-- **Respect**: Treat everyone with respect and kindness
-- **Inclusion**: Welcome people of all backgrounds and experience levels
-- **Collaboration**: Work together to build something great
-- **Learning**: Share knowledge and help others learn
-- **Openness**: Transparent communication and decision-making
-
-## Communication Channels
-
-### GitHub Discussions
-
-**Purpose**: General questions, feature discussions, and community chat
-
-**Best for**:
-- Asking questions
-- Discussing ideas
-- Sharing use cases
-- Getting help
-
-**Link**: [GitHub Discussions](https://github.com/Hawksight-AI/semantica/discussions)
-
-### Discord
-
-**Purpose**: Real-time chat and community support
-
-**Best for**:
-- Quick questions
-- Real-time help
-- Community showcases
-- Casual conversation
-
-**Link**: [Join Discord](https://discord.gg/semantica)
-
-### GitHub Issues
-
-**Purpose**: Bug reports and feature requests
-
-**Best for**:
-- Reporting bugs
-- Requesting features
-- Documentation issues
-- Security vulnerabilities (use private reporting)
-
-**Link**: [GitHub Issues](https://github.com/Hawksight-AI/semantica/issues)
-
-### Email
-
-**Purpose**: Security issues and private communication
-
-**Best for**:
-- Security vulnerabilities
-- Private matters
-- Maintainer contact
-
-**Email**: semantica-dev@users.noreply.github.com
-
-## Code of Conduct
-
-We have a [Code of Conduct](../CODE_OF_CONDUCT.md) that all community members are expected to follow. It ensures a welcoming and inclusive environment for everyone.
-
-### Key Points
-
-- Be respectful and inclusive
-- Welcome newcomers
-- Give constructive feedback
-- Focus on what's best for the community
-
-### Reporting Issues
-
-If you experience or witness unacceptable behavior:
-
-1. **Document**: Note what happened, when, and who was involved
-2. **Report**: Contact maintainers at semantica-dev@users.noreply.github.com
-3. **Response**: We'll investigate and respond appropriately
-
-## Getting Help
-
-### Before Asking
-
-1. **Check Documentation**: Review the docs and cookbook
-2. **Search**: Search GitHub issues and discussions
-3. **Review Examples**: Check the cookbook for examples
-4. **Read FAQ**: Check the [FAQ](faq.md)
-
-### Asking Good Questions
-
-When asking for help:
-
-- **Be specific**: Describe your problem clearly
-- **Provide context**: Include environment details
-- **Show your work**: Share what you've tried
-- **Include code**: Provide minimal reproducible examples
-- **Be patient**: Community members are volunteers
-
-### Where to Ask
-
-- **Quick questions**: Discord
-- **Technical questions**: GitHub Discussions
-- **Bug reports**: GitHub Issues
-- **Feature requests**: GitHub Issues
-
-## Giving Feedback
-
-We value your feedback! Here's how to share it:
-
-### Feature Requests
-
-- Use the [feature request template](https://github.com/Hawksight-AI/semantica/issues/new?template=feature_request.md)
-- Describe the problem and proposed solution
-- Include use cases
-
-### Bug Reports
-
-- Use the [bug report template](https://github.com/Hawksight-AI/semantica/issues/new?template=bug_report.md)
-- Include steps to reproduce
-- Provide environment details
-
-### Documentation Feedback
-
-- Use the [documentation issue template](https://github.com/Hawksight-AI/semantica/issues/new?template=documentation_issue.md)
-- Describe what's unclear or missing
-- Suggest improvements
-
-## Recognition Programs
-
-### Contributors
-
-All contributors are recognized in:
-
-- [CONTRIBUTORS.md](../CONTRIBUTORS.md)
-- GitHub contributors page
-- Release notes for significant contributions
-
-### Contribution Types
-
-We recognize many types of contributions:
-
-- 💻 Code
-- 📝 Documentation
-- 🐛 Bug reports
-- 💡 Ideas
-- 🎨 Design
-- 📖 Examples
-- 🔍 Testing
-- 💬 Answering questions
-- 🌍 Translation
-- And more!
-
-### Special Recognition
-
-- **Top Contributors**: Featured in release notes
-- **Hall of Fame**: Exceptional contributors
-- **Monthly Spotlight**: Featured contributors
-
-## Community Projects
-
-We love seeing what the community builds with Semantica!
-
-### Showcase Your Project
-
-1. Create a PR or issue
-2. Include:
- - Project description
- - Use case
- - Code examples
- - Screenshots or demos
- - Link to your project
-
-See [Community Projects](community-projects.md) for more details.
-
-### Featured Projects
-
-We feature community projects in:
-
-- Documentation
-- Blog posts
-- Release notes
-- Social media
-
-## Events and Activities
-
-### Community Events
-
-- **Monthly Community Calls**: (Coming soon)
-- **Hackathons**: (Coming soon)
-- **Workshops**: (Coming soon)
-
-### Contributing Events
-
-- **Hacktoberfest**: October
-- **24 Pull Requests**: December
-- **Google Summer of Code**: (If applicable)
-
-## Learning Resources
-
-### Documentation
-
-- [Getting Started](getting-started.md)
-- [Concepts](concepts.md)
-- [API Reference](reference/core.md)
-- [Cookbook](cookbook.md)
-
-### Examples
-
-- [Code Examples](examples.md)
-- [Use Cases](use-cases.md)
-- [Cookbook Tutorials](cookbook.md)
-
-### External Resources
-
-- Blog posts
-- Video tutorials
-- Community tutorials
-
-## Ways to Contribute
-
-### Code
-
-- Fix bugs
-- Add features
-- Improve performance
-- Refactor code
-
-See [Contributing Guide](../CONTRIBUTING.md) for details.
-
-### Documentation
-
-- Fix typos
-- Improve clarity
-- Add examples
-- Create tutorials
-- Translate docs
-
-### Community
-
-- Answer questions
-- Help with issues
-- Review PRs
-- Share use cases
-- Organize events
-
-### Testing
-
-- Write tests
-- Improve coverage
-- Report bugs
-- Test new features
-
-## Getting Started as a Contributor
-
-1. **Read**: [Contributing Guide](../CONTRIBUTING.md)
-2. **Set up**: Development environment
-3. **Find**: Good first issue (labeled `good-first-issue`)
-4. **Ask**: Questions in Discussions or Discord
-5. **Contribute**: Submit your first PR!
-
-## Community Guidelines
-
-### Do
-
-- ✅ Be respectful and inclusive
-- ✅ Help newcomers
-- ✅ Give constructive feedback
-- ✅ Follow the code of conduct
-- ✅ Credit others' work
-
-### Don't
-
-- ❌ Be rude or disrespectful
-- ❌ Spam or self-promote excessively
-- ❌ Share private information
-- ❌ Harass or discriminate
-- ❌ Violate the code of conduct
-
-## Resources
-
-- [Contributing Guide](../CONTRIBUTING.md)
-- [Code of Conduct](../CODE_OF_CONDUCT.md)
-- [Security Policy](../SECURITY.md)
-- [Governance](governance.md)
-- [Community Projects](community-projects.md)
-
-## Contact
-
-- **Discord**: [Join our server](https://discord.gg/semantica)
-- **GitHub**: [Discussions](https://github.com/Hawksight-AI/semantica/discussions)
-- **Email**: semantica-dev@users.noreply.github.com
+!!! info "Join Us"
+ We're building an open, collaborative community around semantic AI and knowledge graphs.
---
-**Thank you for being part of the Semantica community!** 🎉
+## 💬 Communication Channels
+### GitHub
+
+- **[Issues](https://github.com/Hawksight-AI/semantica/issues)** - Bug reports, feature requests, questions
+- **[Pull Requests](https://github.com/Hawksight-AI/semantica/pulls)** - Code contributions
+- **[Releases](https://github.com/Hawksight-AI/semantica/releases)** - Release announcements
+
+### Contact
+
+- **Email**: semantica-dev@users.noreply.github.com (for security issues)
+- **GitHub**: Preferred for all other communication
+
+---
+
+## 🤝 Community Values
+
+- **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
+
+---
+
+## 📖 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.
+
+### Reporting Issues
+
+If you experience unacceptable behavior:
+1. Document what happened
+2. Contact maintainers at semantica-dev@users.noreply.github.com
+3. We'll investigate and respond appropriately
+
+---
+
+## 🎯 Getting Help
+
+### Before Asking
+
+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
+
+---
+
+## 🏆 Recognition
+
+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)
+
+---
+
+## 📚 Resources
+
+- **[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! 🎉
diff --git a/docs/contributing.md b/docs/contributing.md
index cbb74239..c2c6317e 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -1,198 +1,126 @@
# Contributing to Semantica
-Thank you for your interest in contributing to Semantica! This guide provides detailed information about contributing to the project.
+Thank you for your interest in contributing to Semantica!
-## Quick Links
+!!! tip "Quick Start"
+ New to contributing? Check out issues labeled [`good-first-issue`](https://github.com/Hawksight-AI/semantica/labels/good-first-issue)
-- [Contributing Guide](../CONTRIBUTING.md) - Main contributing guide
-- [Code of Conduct](../CODE_OF_CONDUCT.md) - Community standards
-- [Security Policy](../SECURITY.md) - Security reporting
-- [GitHub Discussions](https://github.com/Hawksight-AI/semantica/discussions) - Community discussions
+---
-## Documentation-Specific Guidelines
+## 📚 Essential Links
-### Writing Documentation
+- **[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
-When contributing documentation, please follow these guidelines:
+---
-#### Style Guide
+## 🎯 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.
+
+### Documentation
+
+- Fix typos and improve clarity
+- Add examples and tutorials
+- Update API documentation
+- Translate documentation
+
+### 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
+
+### Feature Requests
+
+Suggest features on [GitHub Issues](https://github.com/Hawksight-AI/semantica/issues) with:
+- Use case description
+- Proposed solution
+- Benefits to the community
+
+---
+
+## ✍️ Documentation Style Guide
+
+### Writing Guidelines
- Use clear, concise language
-- Write for a technical audience but explain complex concepts
-- Include code examples where helpful
+- Include working code examples
+- Test all examples before submitting
+- Follow existing documentation structure
- Use proper markdown formatting
-- Follow the existing documentation structure
-#### Code Examples
-
-- Always include working code examples
-- Test examples before submitting
-- Use realistic scenarios
-- Include expected output when relevant
-- Add comments for clarity
-
-#### API Documentation
-
-When documenting APIs:
-
-- Include function/class signatures with type hints
-- Document all parameters and return values
-- Provide usage examples
-- Note any exceptions that may be raised
-- Include performance considerations if relevant
-
-Example:
+### API Documentation Format
```python
-def extract_entities(
- text: str,
- model: str = "transformer",
- confidence_threshold: float = 0.7
-) -> List[Entity]:
- """Extract named entities from text.
+def function_name(
+ param1: str,
+ param2: int = 0
+) -> ReturnType:
+ """Brief description.
Args:
- text: Input text to process
- model: NER model to use (default: "transformer")
- confidence_threshold: Minimum confidence score (default: 0.7)
+ param1: Description of param1
+ param2: Description of param2 (default: 0)
Returns:
- List of extracted Entity objects
+ Description of return value
Raises:
- ValueError: If text is empty or model is invalid
+ ValueError: When and why this is raised
Example:
- >>> from semantica.semantic_extract import NamedEntityRecognizer
- >>> ner = NamedEntityRecognizer()
- >>> entities = ner.extract("Apple Inc. was founded in 1976.")
- >>> len(entities)
- 2
+ >>> result = function_name("test", 5)
+ >>> print(result)
+ expected_output
"""
```
-### Documentation Structure
+---
-The documentation is organized as follows:
+## 📁 Documentation Structure
```
docs/
├── index.md # Homepage
-├── getting-started.md # Getting started guide
+├── getting-started.md # Getting started
├── concepts.md # Core concepts
├── modules.md # Module overview
-├── use-cases.md # Use case examples
-├── examples.md # Code examples
-├── learning-more.md # Additional resources
-├── cookbook/ # Interactive tutorials
-│ ├── introduction/ # Beginner tutorials
-│ ├── advanced/ # Advanced tutorials
-│ └── use_cases/ # Domain-specific examples
+├── use-cases.md # Use cases
+├── examples.md # Examples
+├── cookbook/ # Tutorials
└── reference/ # API reference
- ├── core.md
- ├── ingest.md
- └── ...
```
-### Adding New Documentation
+---
-1. **Choose the right location**:
- - Concepts → `concepts.md`
- - Tutorials → `cookbook/`
- - API docs → `reference/`
- - Examples → `examples.md` or `cookbook/`
+## 🛠️ Documentation Tools
-2. **Follow naming conventions**:
- - Use lowercase with hyphens: `my-new-doc.md`
- - Be descriptive but concise
+- **[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
-3. **Update navigation**:
- - Add to `mkdocs.yml` in the appropriate section
+---
-4. **Add to index if needed**:
- - Update `docs/index.md` if it's a major new section
+## 🤝 Getting Help
-### Code Review Process
+- **[GitHub Issues](https://github.com/Hawksight-AI/semantica/issues)** - Ask questions
+- **Documentation** - Check existing docs for examples
+- **Pull Requests** - Review other contributors' PRs
-Documentation PRs go through the same review process as code:
-
-1. **Automated checks**:
- - Markdown linting
- - Link checking
- - Build verification
-
-2. **Manual review**:
- - Accuracy and clarity
- - Code example correctness
- - Consistency with existing docs
-
-3. **Feedback**:
- - Reviewers provide constructive feedback
- - Address all comments before merging
-
-### Example Contributions
-
-#### Fixing Typos
-
-```markdown
-# Before
-Semantica is a knowlege graph framework.
-
-# After
-Semantica is a knowledge graph framework.
-```
-
-#### Improving Clarity
-
-```markdown
-# Before
-The function does entity extraction.
-
-# After
-The function extracts named entities (people, organizations, locations, etc.) from text using advanced NLP models.
-```
-
-#### Adding Examples
-
-```markdown
-## Example
-
-Here's how to extract entities from text:
-
-```python
-from semantica.semantic_extract import NamedEntityRecognizer
-
-ner = NamedEntityRecognizer()
-entities = ner.extract("Apple Inc. was founded by Steve Jobs.")
-print(f"Found {len(entities)} entities")
-```
-```
-
-### Translation
-
-We welcome translations of the documentation! If you'd like to translate:
-
-1. Create a new directory: `docs/i18n//`
-2. Translate the markdown files
-3. Update `mkdocs.yml` to include the new language
-4. Maintain the same structure as the English version
-
-### Documentation Tools
-
-We use:
-
-- **MkDocs**: Documentation generator
-- **Material for MkDocs**: Theme
-- **mkdocstrings**: API documentation from docstrings
-- **Mermaid**: Diagrams
-
-### Getting Help
-
-If you need help with documentation:
-
-- Ask in [GitHub Discussions](https://github.com/Hawksight-AI/semantica/discussions)
-- Check existing documentation for examples
-- Review other contributors' PRs
-
-Thank you for helping improve Semantica's documentation! 📚
+---
+!!! success "Thank You!"
+ Every contribution helps make Semantica better! 🎉
diff --git a/docs/faq.md b/docs/faq.md
index e90a0d22..ce8ffd9f 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -3,293 +3,263 @@
Common questions and answers about Semantica.
!!! tip "Can't find your question?"
- Check our [GitHub Discussions](https://github.com/Hawksight-AI/semantica/discussions) or [open an issue](https://github.com/Hawksight-AI/semantica/issues)
+ Browse existing questions or [ask a new question on GitHub Issues](https://github.com/Hawksight-AI/semantica/issues/new)
---
-## 🎯 General Questions
+## General Questions
-
+### What is Semantica?
-- **What is Semantica?**
- ---
- 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.
+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 use Semantica for?
-- **Is Semantica free?**
- ---
- Yes! Semantica is 100% open source and free to use under the MIT License.
+- 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 makes Semantica different?**
- ---
- - **Modular**: Use only what you need
- - **Extensible**: Plug in custom models
- - **Production-ready**: Built for scale
- - **Open source**: Fully transparent
+### Is Semantica free?
-
+Yes! Semantica is 100% open source and free to use 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
---
-## 💻 Installation & Setup
+## Installation & Setup
-
+### How do I install Semantica?
-- **How do I install Semantica?**
- ---
- ```bash
- pip install semantica
- ```
- See the [Installation Guide](installation.md) for details.
+```bash
+pip install semantica
+```
-- **What Python version do I need?**
- ---
- Python 3.8 or higher. Python 3.11+ is recommended for best performance.
+See the [Installation Guide](installation.md) for details.
-- **Do I need a GPU?**
- ---
- No, GPU is optional. Semantica works on CPU, but GPU acceleration is available for faster processing.
+### What Python version do I need?
-- **How do I get started?**
- ---
- 1. Install: `pip install semantica`
- 2. Follow the [Quick Start Guide](quickstart.md)
- 3. Try the [Examples](examples.md)
+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)
---
-## 📊 Knowledge Graphs
+## Knowledge Graphs
-
+### What is a knowledge graph?
-- **What is a knowledge graph?**
- ---
- A structured representation where entities (nodes) are connected by relationships (edges). It captures semantic meaning and relationships in data.
+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 import Semantica
-
- semantica = Semantica()
- result = semantica.build_knowledge_base(["document.pdf"])
- kg = result["knowledge_graph"]
- ```
+### How do I build a knowledge graph?
-- **Can I merge multiple knowledge graphs?**
- ---
- Yes! Use the `merge` method:
- ```python
- merged = semantica.kg.merge([kg1, kg2, kg3])
- ```
+```python
+from semantica import Semantica
-- **How do I visualize a knowledge graph?**
- ---
- ```python
- semantica.kg.visualize(kg, output_path="graph.html")
- ```
+semantica = Semantica()
+result = semantica.build_knowledge_base(["document.pdf"])
+kg = result["knowledge_graph"]
+```
-
+### 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
+## Usage & Features
-
+### Can I process PDF files?
-- **Can I process PDF files?**
- ---
- Yes! Semantica supports PDF, DOCX, HTML, JSON, CSV, and many other formats.
+Yes! Semantica supports PDF, DOCX, HTML, JSON, CSV, and many other formats.
-- **How do I extract entities from text?**
- ---
- ```python
- from semantica import Semantica
-
- semantica = Semantica()
- result = semantica.semantic_extract.extract_entities("Your text")
- entities = result["entities"]
- ```
+### How do I extract entities from text?
-- **Can I use my own models?**
- ---
- Yes, Semantica is extensible. You can plug in custom models for entity extraction, embeddings, and more.
+```python
+from semantica import Semantica
-- **What export formats are supported?**
- ---
- - RDF/XML
- - OWL (Ontology)
- - JSON
- - CSV
- - YAML
- - And more
+semantica = Semantica()
+result = semantica.semantic_extract.extract_entities("Your text")
+entities = result["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
---
-## ⚖️ Conflict Resolution
+## Conflict Resolution
-
+### What is conflict resolution?
-- **What is conflict resolution?**
- ---
- When the same entity appears in multiple sources with different information, conflict resolution determines which information to use.
+When the same entity appears in multiple sources with different information, conflict resolution determines which information to use.
-- **What strategies are available?**
- ---
- - **Voting**: Majority wins
- - **Credibility Weighted**: Weight by source credibility
- - **Most Recent**: Use latest information
- - **Highest Confidence**: Use highest confidence score
+### What strategies are available?
-- **How do I set a resolution strategy?**
- ---
- ```python
- from semantica.conflicts import ConflictResolver
-
- resolver = ConflictResolver(default_strategy="voting")
- ```
+- **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")
+```
---
-## 🔌 Integration
+## Integration
-
+### Can I use Semantica with other tools?
-- **Can I use Semantica with other tools?**
- ---
- Yes! Semantica exports to standard formats that work with:
- - Neo4j
- - Graph databases
- - RDF stores
- - Vector databases
- - Any tool that accepts RDF/JSON/CSV
+Yes! Semantica exports to standard formats that work with:
-- **Does it work with LangChain?**
- ---
- Yes, Semantica can be integrated with LangChain for RAG applications.
+- Neo4j
+- Graph databases
+- RDF stores
+- Vector databases
+- Any tool that accepts RDF/JSON/CSV
-- **Can I connect to databases?**
- ---
- Yes, Semantica supports connections to Neo4j, KuzuDB, FalkorDB, and other graph databases.
+### 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, KuzuDB, FalkorDB, and other graph databases.
---
-## ⚡ Performance
+## Performance
-
+### How fast is Semantica?
-- **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.
+Performance depends on:
-- **Can I process large datasets?**
- ---
- Yes, but consider:
- - Processing in batches
- - Using GPU acceleration
- - Incremental building
- - Optimizing configuration
+- Document size
+- Number of documents
+- Hardware (CPU/GPU)
+- Configuration options
-- **How can I improve performance?**
- ---
- - Enable GPU if available
- - Process in smaller batches
- - Use faster models
- - Optimize configuration
- - Cache embeddings
+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
---
-## 🐛 Troubleshooting
+## Troubleshooting
-
+### Installation fails
-- **Installation fails**
- ---
- - Upgrade pip: `pip install --upgrade pip`
- - Use virtual environment
- - Check Python version: `python --version`
+- Upgrade pip: `pip install --upgrade pip`
+- Use virtual environment
+- Check Python version: `python --version`
-- **No entities extracted**
- ---
- - Verify document contains text (not just images)
- - Check document format is supported
- - Review extraction configuration
+### No entities extracted
-- **Memory errors**
- ---
- - Process documents one at a time
- - Reduce batch sizes
- - Use smaller models
- - Increase available RAM
+- Verify document contains text (not just images)
+- Check document format is supported
+- Review extraction configuration
-- **Slow processing**
- ---
- - Enable GPU if available
- - Process in smaller batches
- - Optimize configuration
- - Use faster models
+### 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
---
-## 🤝 Getting Help
+## Getting Help
-
+### Where can I get help?
-- **Where can I get help?**
- ---
- - **Documentation**: This site
- - **GitHub Issues**: [Report bugs](https://github.com/Hawksight-AI/semantica/issues)
- - **Discussions**: [Ask questions](https://github.com/Hawksight-AI/semantica/discussions)
+- **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 a bug?
-- **Can I contribute?**
- ---
- Yes! We welcome contributions. See our [Contributing Guide](https://github.com/Hawksight-AI/semantica/blob/main/CONTRIBUTING.md).
+Open an issue on [GitHub](https://github.com/Hawksight-AI/semantica/issues) with:
-- **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
+- Description of the problem
+- Steps to reproduce
+- Expected vs actual behavior
+- Environment details
-
+### 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 [open a discussion](https://github.com/Hawksight-AI/semantica/discussions)
+ 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)
diff --git a/docs/governance.md b/docs/governance.md
index 4be491a4..4703c1f1 100644
--- a/docs/governance.md
+++ b/docs/governance.md
@@ -1,246 +1,95 @@
# Governance
-This document describes the governance model for the Semantica project.
+Project governance model for Semantica.
-## Project Structure
+!!! info "Open Source"
+ Semantica is maintained by Hawksight AI with community contributions.
-Semantica is an open-source project maintained by Hawksight AI with community contributions.
+---
-### Roles
+## 👥 Roles
-#### Maintainers
+**Maintainers** (Hawksight AI team)
+- Review and merge pull requests
+- Manage releases and code quality
+- Community management and project direction
-Maintainers are responsible for:
+**Contributors**
+- Submit code, documentation, and bug reports
+- Help with issues and reviews
+- Recognized in [CONTRIBUTORS.md](https://github.com/Hawksight-AI/semantica/blob/main/CONTRIBUTORS.md)
-- Reviewing and merging pull requests
-- Managing releases
-- Maintaining code quality
-- Resolving conflicts
-- Community management
-- Project direction
+**Community Members**
+- Use Semantica and provide feedback
+- Share use cases and participate in discussions
-**Current Maintainers**:
-- Hawksight AI team
+---
-#### Contributors
-
-Contributors are community members who:
-
-- Submit code contributions
-- Improve documentation
-- Report bugs
-- Suggest features
-- Help with issues
-- Review pull requests
-
-**Recognition**: All contributors are recognized in [CONTRIBUTORS.md](../CONTRIBUTORS.md)
-
-#### Community Members
-
-Community members:
-
-- Use Semantica
-- Provide feedback
-- Answer questions
-- Share use cases
-- Participate in discussions
-
-## Decision-Making Process
+## 🔄 Decision Process
### Code Changes
-
-1. **Proposal**: Feature requests or bug reports via GitHub Issues
-2. **Discussion**: Community discussion in Issues or Discussions
-3. **Implementation**: Contributor creates PR
-4. **Review**: Maintainers review PR
-5. **Approval**: At least one maintainer approval required
-6. **Merge**: PR merged after approval and CI checks pass
+1. Proposal via GitHub Issues
+2. Community discussion
+3. Implementation (PR)
+4. Review by maintainers
+5. Approval (at least 1 maintainer)
+6. Merge after CI passes
### Major Decisions
+- RFC in GitHub Issues
+- 1 week minimum discussion
+- Maintainers decide based on community feedback and technical feasibility
-For major decisions (breaking changes, architecture changes, etc.):
+---
-1. **RFC Process**: Request for Comments in GitHub Discussions
-2. **Community Input**: Open discussion period (minimum 1 week)
-3. **Decision**: Maintainers make final decision based on:
- - Community feedback
- - Technical feasibility
- - Project goals
- - Maintenance burden
-
-### Release Process
-
-1. **Planning**: Roadmap planning in GitHub Projects
-2. **Development**: Feature development in feature branches
-3. **Testing**: Comprehensive testing and CI checks
-4. **Release Candidate**: RC for major releases
-5. **Release**: Tagged release with changelog
-6. **Documentation**: Updated documentation
-
-## Release Process
-
-### Versioning
-
-We follow [Semantic Versioning](https://semver.org/):
+## 📦 Releases
+### Versioning (Semantic Versioning)
- **MAJOR**: Breaking changes
- **MINOR**: New features (backward compatible)
- **PATCH**: Bug fixes (backward compatible)
-### Release Schedule
-
-- **Major Releases**: Quarterly or as needed
-- **Minor Releases**: Monthly or as features are ready
-- **Patch Releases**: As bugs are fixed
-
-### Release Checklist
-
-- [ ] All tests pass
-- [ ] Documentation updated
-- [ ] Changelog updated
-- [ ] Version bumped
-- [ ] Release notes prepared
-- [ ] Tagged release created
-- [ ] Announcement posted
-
-## Roadmap Planning
-
-### Planning Process
-
-1. **Community Input**: Gather feature requests and feedback
-2. **Prioritization**: Maintainers prioritize based on:
- - Community demand
- - Technical feasibility
- - Project goals
- - Resource availability
-3. **Roadmap Publication**: Roadmap published in README and docs
-4. **Regular Updates**: Roadmap updated quarterly
-
-### Roadmap Categories
-
-- **Short-term** (1-3 months): Current sprint
-- **Medium-term** (3-6 months): Next quarter
-- **Long-term** (6+ months): Future vision
-
-## Code Review Process
-
-### Review Criteria
-
-PRs are reviewed for:
-
-- **Functionality**: Does it work as intended?
-- **Code Quality**: Follows style guidelines?
-- **Tests**: Adequate test coverage?
-- **Documentation**: Documentation updated?
-- **Performance**: No performance regressions?
-- **Security**: No security issues?
-
-### Review Timeline
-
-- **Initial Review**: Within 48 hours
-- **Follow-up**: Within 7 days
-- **Resolution**: Depends on complexity
-
-### Review Guidelines
-
-**For Reviewers**:
-- Be constructive and respectful
-- Explain reasoning for suggestions
-- Approve when criteria are met
-- Request changes when needed
-
-**For Contributors**:
-- Address all review comments
-- Ask questions if unclear
-- Be open to feedback
-- Update PR based on feedback
-
-## Conflict Resolution
-
-### Code Conflicts
-
-- Technical disagreements: Discuss in PR comments
-- Unresolved: Escalate to maintainers
-- Final decision: Maintainers
-
-### Community Conflicts
-
-- Follow [Code of Conduct](../CODE_OF_CONDUCT.md)
-- Report violations to maintainers
-- Maintainers handle enforcement
-
-## Communication Channels
-
-### GitHub
-
-- **Issues**: Bug reports and feature requests
-- **Discussions**: Questions and general discussion
-- **Pull Requests**: Code contributions
-- **Releases**: Release announcements
-
-### Discord
-
-- Real-time community chat
-- Quick questions
-- Community support
-- Showcases
-
-### Email
-
-- Security issues: semantica-dev@users.noreply.github.com
-- General inquiries: GitHub Discussions preferred
-
-## Contribution Guidelines
-
-See [CONTRIBUTING.md](../CONTRIBUTING.md) for detailed contribution guidelines.
-
-### Types of Contributions
-
-- Code contributions
-- Documentation improvements
-- Bug reports
-- Feature suggestions
-- Code reviews
-- Community support
-
-### Recognition
-
-All contributors are recognized in:
-- [CONTRIBUTORS.md](../CONTRIBUTORS.md)
-- GitHub contributors page
-- Release notes for significant contributions
-
-## Project Goals
-
-### Primary Goals
-
-1. **Usability**: Easy to use and understand
-2. **Reliability**: Production-ready quality
-3. **Performance**: Efficient and scalable
-4. **Extensibility**: Easy to extend and customize
-5. **Community**: Welcoming and inclusive
-
-### Success Metrics
-
-- Contributor engagement
-- Issue resolution time
-- Code quality metrics
-- Community growth
-- User satisfaction
-
-## License
-
-Semantica is licensed under the MIT License. See [LICENSE](../LICENSE) for details.
-
-## Contact
-
-For governance questions or concerns:
-
-- **GitHub Discussions**: General questions
-- **Email**: semantica-dev@users.noreply.github.com
-- **Discord**: Community chat
+### Schedule
+- **Major**: Quarterly or as needed
+- **Minor**: Monthly or when ready
+- **Patch**: As bugs are fixed
---
-**Last Updated**: 2024-01-XX
+## 🔍 Code Review
+**Criteria**: Functionality, code quality, tests, documentation, performance, security
+
+**Timeline**: Initial review within 48 hours, follow-up within 7 days
+
+**Guidelines**:
+- Reviewers: Be constructive, explain reasoning
+- Contributors: Address comments, ask questions, be open to feedback
+
+---
+
+## 💬 Communication
+
+- **GitHub Issues**: Bug reports, features, questions
+- **GitHub PRs**: Code contributions
+- **Email**: semantica-dev@users.noreply.github.com (security only)
+
+---
+
+## 🎯 Project Goals
+
+1. **Usability** - Easy to use and understand
+2. **Reliability** - Production-ready quality
+3. **Performance** - Efficient and scalable
+4. **Extensibility** - Easy to extend
+5. **Community** - Welcoming and inclusive
+
+---
+
+## 📄 License
+
+MIT License - See [LICENSE](https://github.com/Hawksight-AI/semantica/blob/main/LICENSE)
+
+---
+
+**Contact**: [GitHub Issues](https://github.com/Hawksight-AI/semantica/issues) or semantica-dev@users.noreply.github.com
diff --git a/docs/license.md b/docs/license.md
index dfa54b95..aeb4b822 100644
--- a/docs/license.md
+++ b/docs/license.md
@@ -2,12 +2,14 @@
Semantica is released under the MIT License.
+---
+
## MIT License
```
MIT License
-Copyright (c) 2024 Hawksight AI
+Copyright (c) 2025 Hawksight AI
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
@@ -28,64 +30,49 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```
+---
+
## What This Means
### You Can:
-
-- ✅ Use Semantica commercially
+- ✅ Use commercially
- ✅ Modify the source code
- ✅ Distribute the software
-- ✅ Use it in private projects
+- ✅ Use in private/proprietary projects
- ✅ Sublicense it
-- ✅ Use it in proprietary software
### You Must:
-
-- ✅ Include the copyright notice
-- ✅ Include the license text
+- ✅ Include copyright notice
+- ✅ Include license text
### You Cannot:
-
-- ❌ Hold authors liable for damages
-- ❌ Use the authors' names to endorse products without permission
-
-## Third-Party Licenses
-
-Semantica uses several open-source libraries. Their licenses are included in the distribution. Key dependencies:
-
-- **Python**: PSF License
-- **NumPy**: BSD License
-- **Pandas**: BSD License
-- **spaCy**: MIT License
-- **Transformers**: Apache 2.0 License
-- **RDFLib**: BSD License
-
-See the full list in `LICENSE` file or check individual package licenses.
-
-## Commercial Use
-
-Semantica is **free for commercial use**. You can:
-
-- Use it in commercial products
-- Build commercial services with it
-- Include it in proprietary software
-- Sell products that use Semantica
-
-No attribution required in your product, though we appreciate it!
-
-## Contributing
-
-By contributing to Semantica, you agree that your contributions will be licensed under the MIT License.
-
-## Questions?
-
-If you have questions about the license:
-
-- Check the [full license text](../LICENSE)
-- [Open an issue](https://github.com/Hawksight-AI/semantica/issues)
-- [Start a discussion](https://github.com/Hawksight-AI/semantica/discussions)
+- ❌ Hold authors liable
+- ❌ Use authors' names for endorsement
---
-**Semantica is 100% open source and free to use!** 🎉
+## Commercial Use
+**Semantica is free for commercial use.** No attribution required (though appreciated)!
+
+---
+
+## Third-Party Licenses
+
+Key dependencies:
+- Python (PSF), NumPy (BSD), Pandas (BSD)
+- spaCy (MIT), Transformers (Apache 2.0), RDFLib (BSD)
+
+See `LICENSE` file for complete list.
+
+---
+
+## Contributing
+
+By contributing, you agree your contributions will be licensed under MIT.
+
+---
+
+**Questions?** [Open an issue](https://github.com/Hawksight-AI/semantica/issues)
+
+**Semantica is 100% open source and free!** 🎉