From 03b84ab2388924247f17a1aa54e234fb12297f70 Mon Sep 17 00:00:00 2001 From: KaifAhmad1 Date: Mon, 24 Nov 2025 13:30:49 +0530 Subject: [PATCH] docs: Add comprehensive open source project improvements - Add essential open source files (CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, CHANGELOG.md, CONTRIBUTORS.md) - Add GitHub issue and PR templates - Add CI/CD workflows (CI, docs, release, dependabot) - Add pre-commit hooks configuration - Add documentation enhancements (architecture, governance, contributing, community) - Add developer experience scripts (setup-dev, run-tests, format-code, check-code) - Add community features (SUPPORT.md, .all-contributorsrc) - Enhance README badges and project metadata - Update mkdocs.yml navigation structure --- .all-contributorsrc | 17 + .github/ISSUE_TEMPLATE/bug_report.md | 59 +++ .github/ISSUE_TEMPLATE/config.yml | 12 + .github/ISSUE_TEMPLATE/documentation_issue.md | 64 +++ .github/ISSUE_TEMPLATE/feature_request.md | 59 +++ .github/ISSUE_TEMPLATE/question.md | 63 +++ .github/dependabot.yml | 25 ++ .github/pull_request_template.md | 120 ++++++ .github/workflows/ci.yml | 99 +++++ .github/workflows/dependabot.yml | 33 ++ .github/workflows/docs.yml | 98 +++-- .github/workflows/release.yml | 55 +++ .pre-commit-config.yaml | 80 ++++ CHANGELOG.md | 69 +++ CODE_OF_CONDUCT.md | 125 ++++++ CONTRIBUTING.md | 392 ++++++++++++++++++ CONTRIBUTORS.md | 97 +++++ README.md | 5 + SECURITY.md | 166 ++++++++ SUPPORT.md | 130 ++++++ docs/architecture.md | 377 +++++++++++++++++ docs/community.md | 299 +++++++++++++ docs/contributing.md | 198 +++++++++ docs/governance.md | 246 +++++++++++ mkdocs.yml | 20 +- pyproject.toml | 19 +- remove_mkdocstrings.ps1 | 19 - scripts/check-code.sh | 31 ++ scripts/format-code.sh | 23 + scripts/run-tests.sh | 20 + scripts/setup-dev.ps1 | 50 +++ scripts/setup-dev.sh | 53 +++ test-docs.py | 63 --- 33 files changed, 3056 insertions(+), 130 deletions(-) create mode 100644 .all-contributorsrc create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/documentation_issue.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/ISSUE_TEMPLATE/question.md create mode 100644 .github/dependabot.yml create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/dependabot.yml create mode 100644 .github/workflows/release.yml create mode 100644 .pre-commit-config.yaml create mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 CONTRIBUTORS.md create mode 100644 SECURITY.md create mode 100644 SUPPORT.md create mode 100644 docs/architecture.md create mode 100644 docs/community.md create mode 100644 docs/contributing.md create mode 100644 docs/governance.md delete mode 100644 remove_mkdocstrings.ps1 create mode 100644 scripts/check-code.sh create mode 100644 scripts/format-code.sh create mode 100644 scripts/run-tests.sh create mode 100644 scripts/setup-dev.ps1 create mode 100644 scripts/setup-dev.sh delete mode 100644 test-docs.py diff --git a/.all-contributorsrc b/.all-contributorsrc new file mode 100644 index 00000000..77741d45 --- /dev/null +++ b/.all-contributorsrc @@ -0,0 +1,17 @@ +{ + "projectName": "Semantica", + "projectOwner": "Hawksight-AI", + "repoType": "github", + "repoHost": "https://github.com", + "files": [ + "CONTRIBUTORS.md" + ], + "imageSize": 100, + "commit": true, + "commitConvention": "conventional", + "contributors": [], + "contributorsPerLine": 7, + "badgeTemplate": "[![All Contributors](https://img.shields.io/badge/all_contributors-<%= contributors.length %>-orange.svg?style=flat-square)](#contributors)", + "skipCi": true +} + diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..46a50bbf --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,59 @@ +--- +name: Bug Report +about: Create a report to help us improve +title: '[BUG] ' +labels: bug +assignees: '' +--- + +## Bug Description + +A clear and concise description of what the bug is. + +## Steps to Reproduce + +1. Go to '...' +2. Run command '...' +3. See error + +## Expected Behavior + +A clear and concise description of what you expected to happen. + +## Actual Behavior + +A clear and concise description of what actually happened. + +## Environment + +- **OS**: [e.g., Windows 10, Ubuntu 22.04, macOS 13.0] +- **Python Version**: [e.g., 3.9.7] +- **Semantica Version**: [e.g., 0.0.1] +- **Installation Method**: [e.g., pip, source, conda] + +## Code Example + +```python +# Minimal code example that reproduces the issue +from semantica import Semantica + +core = Semantica() +# ... your code here +``` + +## Error Messages / Logs + +``` +Paste error messages or logs here +``` + +## Additional Context + +- Screenshots (if applicable) +- Related issues or PRs +- Any other context about the problem + +## Possible Solution + +If you have ideas on how to fix this, please share them here. + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..7dc393d7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,12 @@ +blank_issues_enabled: false +contact_links: + - name: GitHub Discussions + url: https://github.com/Hawksight-AI/semantica/discussions + about: Ask questions and discuss ideas with the community + - name: Discord Community + url: https://discord.gg/semantica + about: Join our Discord server for real-time help and discussions + - name: Security Issues + url: https://github.com/Hawksight-AI/semantica/security/advisories/new + about: Report security vulnerabilities privately + diff --git a/.github/ISSUE_TEMPLATE/documentation_issue.md b/.github/ISSUE_TEMPLATE/documentation_issue.md new file mode 100644 index 00000000..dcac72c3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation_issue.md @@ -0,0 +1,64 @@ +--- +name: Documentation Issue +about: Report an issue or suggest improvements to documentation +title: '[DOCS] ' +labels: documentation +assignees: '' +--- + +## Documentation Section + +Which section or page is affected? + +- [ ] Getting Started +- [ ] API Reference +- [ ] Concepts +- [ ] Cookbook +- [ ] Examples +- [ ] Other: ___________ + +**URL or File Path**: [e.g., docs/getting-started.md] + +## Current Content + +What is the current content or issue? + +```markdown +Paste current content here +``` + +## Problem + +What is wrong or unclear about the current documentation? + +- [ ] Typo or grammar error +- [ ] Outdated information +- [ ] Missing information +- [ ] Unclear explanation +- [ ] Broken link +- [ ] Code example doesn't work +- [ ] Other: ___________ + +## Proposed Changes + +What should the documentation say instead? + +```markdown +Proposed content here +``` + +## Rationale + +Why is this change needed? How does it improve the documentation? + +## Additional Context + +- Screenshots (if applicable) +- Related issues or PRs +- Any other context + +## Contribution + +- [ ] I'm willing to submit a PR with the fix +- [ ] I can help review the changes + diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 00000000..e1b224a1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,59 @@ +--- +name: Feature Request +about: Suggest an idea for this project +title: '[FEATURE] ' +labels: enhancement +assignees: '' +--- + +## Problem Statement + +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +## Proposed Solution + +A clear and concise description of what you want to happen. + +## Alternatives Considered + +A clear and concise description of any alternative solutions or features you've considered. + +## Use Cases + +Describe specific use cases where this feature would be helpful: + +1. Use case 1 +2. Use case 2 +3. Use case 3 + +## Impact Assessment + +- **Who would benefit?** [e.g., All users, specific user groups] +- **Priority**: [Low, Medium, High, Critical] +- **Breaking Changes**: [Yes/No - if yes, describe] +- **Dependencies**: [Any dependencies or related features] + +## Implementation Ideas + +If you have ideas on how this could be implemented, please share: + +```python +# Example API or code structure +from semantica import NewFeature + +feature = NewFeature() +# ... +``` + +## Additional Context + +- Related issues or PRs +- References to similar features in other projects +- Any other context, mockups, or examples + +## Contribution + +- [ ] I'm willing to help implement this feature +- [ ] I can help with documentation +- [ ] I can help with testing + diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md new file mode 100644 index 00000000..53baaefc --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.md @@ -0,0 +1,63 @@ +--- +name: Question +about: Ask a question about Semantica +title: '[QUESTION] ' +labels: question +assignees: '' +--- + +## Question + +What is your question? + +## Context + +Provide context about your question: + +- What are you trying to accomplish? +- What have you tried so far? +- What specific aspect do you need help with? + +## Code Example + +If applicable, include code that demonstrates your question: + +```python +from semantica import Semantica + +# Your code here +``` + +## Environment + +- **OS**: [e.g., Windows 10, Ubuntu 22.04, macOS 13.0] +- **Python Version**: [e.g., 3.9.7] +- **Semantica Version**: [e.g., 0.0.1] + +## What You've Tried + +- [ ] Checked the documentation +- [ ] Searched GitHub issues +- [ ] Searched GitHub discussions +- [ ] Checked the cookbook examples +- [ ] Tried debugging on my own + +## Additional Information + +Any other information that might be helpful: + +- Error messages +- Logs +- Screenshots +- Related issues or discussions + +## Expected Response + +What kind of help are you looking for? + +- [ ] Quick answer +- [ ] Detailed explanation +- [ ] Code example +- [ ] Point to documentation +- [ ] Other: ___________ + diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 00000000..f7bf7849 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,25 @@ +version: 2 +updates: + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" + open-pull-requests-limit: 10 + reviewers: + - "Hawksight-AI" + labels: + - "dependencies" + - "python" + commit-message: + prefix: "deps" + include: "scope" + + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "monthly" + open-pull-requests-limit: 5 + labels: + - "dependencies" + - "github-actions" + diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..9006c0dc --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,120 @@ +## Description + + + +## Type of Change + + + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Documentation update +- [ ] Code refactoring +- [ ] Performance improvement +- [ ] Test addition or update +- [ ] Other (please describe): ___________ + +## Related Issues + + + +Closes # +Related to # +Fixes # + +## Changes Made + + + +- Change 1 +- Change 2 +- Change 3 + +## Testing + + + +- [ ] Tests pass locally +- [ ] Added new tests for new functionality +- [ ] Updated existing tests +- [ ] All tests pass (`pytest`) +- [ ] Code coverage maintained or improved + +### Test Results + +``` +Paste test output or command here +``` + +## Documentation + + + +- [ ] Updated relevant documentation +- [ ] Added code examples if applicable +- [ ] Updated API reference if adding new APIs +- [ ] Updated cookbook if adding new examples +- [ ] No documentation changes needed + +## Code Quality + + + +- [ ] Code follows style guidelines (black, isort, flake8) +- [ ] Type hints added for new functions +- [ ] Docstrings added/updated +- [ ] No new warnings or errors +- [ ] Self-review completed + +### Code Quality Checks + +```bash +# Run these commands and ensure they pass +black semantica/ tests/ +isort semantica/ tests/ +flake8 semantica/ tests/ +mypy semantica/ +pytest +``` + +## Breaking Changes + + + +**Breaking Changes**: [Yes/No] + +If yes, describe: +- What breaks +- Why it's necessary +- How to migrate + +## Screenshots / Examples + + + +```python +# Example usage of new feature +``` + +## Checklist + + + +- [ ] My code follows the project's style guidelines +- [ ] I have performed a self-review of my code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] I have made corresponding changes to the documentation +- [ ] My changes generate no new warnings +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] New and existing unit tests pass locally with my changes +- [ ] Any dependent changes have been merged and published + +## Additional Notes + + + +## Reviewer Notes + + + diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 00000000..cbf1fd3d --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,99 @@ +name: CI + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main, develop ] + +jobs: + test: + name: Test Python ${{ matrix.python-version }} on ${{ matrix.os }} + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, windows-latest, macos-latest] + python-version: ['3.8', '3.9', '3.10', '3.11', '3.12'] + + steps: + - uses: actions/checkout@v4 + + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + + - name: Cache pip packages + uses: actions/cache@v4 + with: + path: ~/.cache/pip + key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt', '**/pyproject.toml') }} + restore-keys: | + ${{ runner.os }}-pip- + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -e ".[dev]" + + - name: Run tests + run: | + pytest --cov=semantica --cov-report=xml --cov-report=html + + - name: Upload coverage to Codecov + uses: codecov/codecov-action@v4 + if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11' + with: + file: ./coverage.xml + flags: unittests + name: codecov-umbrella + + lint: + name: Lint Code + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -e ".[dev]" + + - name: Run black + run: black --check semantica/ tests/ + + - name: Run isort + run: isort --check-only semantica/ tests/ + + - name: Run flake8 + run: flake8 semantica/ tests/ + + - name: Run mypy + run: mypy semantica/ + continue-on-error: true + + type-check: + name: Type Check + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -e ".[dev]" + + - name: Run mypy + run: mypy semantica/ + diff --git a/.github/workflows/dependabot.yml b/.github/workflows/dependabot.yml new file mode 100644 index 00000000..b7bcfd3b --- /dev/null +++ b/.github/workflows/dependabot.yml @@ -0,0 +1,33 @@ +name: Dependabot Auto-merge + +on: + pull_request: + types: [opened, synchronize, reopened] + +jobs: + dependabot: + name: Dependabot + runs-on: ubuntu-latest + if: github.actor == 'dependabot[bot]' + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -e ".[dev]" + + - name: Run tests + run: pytest + + - name: Auto-merge Dependabot PRs + if: success() + uses: fastify/github-action-merge-dependabot@v3 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index f66b3039..205cb514 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,49 +1,79 @@ -name: Deploy Documentation +name: Documentation on: push: - branches: - - main + branches: [ main ] paths: - 'docs/**' + - 'mkdocs.yml' - '.github/workflows/docs.yml' - workflow_dispatch: - -permissions: - contents: read - pages: write - id-token: write - -concurrency: - group: "pages" - cancel-in-progress: false + pull_request: + branches: [ main ] + paths: + - 'docs/**' + - 'mkdocs.yml' jobs: build: + name: Build Documentation runs-on: ubuntu-latest steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Setup Pages - uses: actions/configure-pages@v4 - - - name: Build with Jekyll - uses: actions/jekyll-build-pages@v1 - with: - source: ./docs - - - name: Upload artifact - uses: actions/upload-pages-artifact@v3 + - uses: actions/checkout@v4 - deploy: - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r requirements-docs.txt + pip install mkdocs-material mkdocstrings[python] + + - name: Build documentation + run: mkdocs build --strict + + - name: Check for broken links + run: | + pip install linkchecker + linkchecker site/ --check-extern + + - name: Deploy to GitHub Pages + if: github.ref == 'refs/heads/main' && github.event_name == 'push' + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./site + + preview: + name: Preview Documentation runs-on: ubuntu-latest - needs: build + if: github.event_name == 'pull_request' steps: - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r requirements-docs.txt + pip install mkdocs-material mkdocstrings[python] + + - name: Build documentation + run: mkdocs build --strict + + - name: Comment PR with preview link + uses: actions/github-script@v7 + with: + script: | + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: 'πŸ“š Documentation preview will be available after merge.' + }) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 00000000..5a305b4e --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,55 @@ +name: Release + +on: + push: + tags: + - 'v*' + +jobs: + release: + name: Create Release + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install build twine + + - name: Extract version from tag + id: tag + run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT + + - name: Build package + run: python -m build + + - name: Check package + run: twine check dist/* + + - name: Create GitHub Release + uses: actions/create-release@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + tag_name: ${{ github.ref }} + release_name: Release ${{ steps.tag.outputs.VERSION }} + body_path: CHANGELOG.md + draft: false + prerelease: false + + - name: Publish to PyPI + if: startsWith(github.ref, 'refs/tags/v') + env: + TWINE_USERNAME: __token__ + TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} + run: twine upload dist/* + continue-on-error: true + diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 00000000..60fc6a1b --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,80 @@ +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-yaml + - id: check-json + - id: check-toml + - id: check-added-large-files + args: ['--maxkb=1000'] + - id: check-merge-conflict + - id: check-case-conflict + - id: check-docstring-first + - id: debug-statements + - id: mixed-line-ending + - id: name-tests-test + args: ['--pytest-test-first'] + + - repo: https://github.com/psf/black + rev: 24.1.1 + hooks: + - id: black + language_version: python3 + args: ['--line-length=88'] + + - repo: https://github.com/pycqa/isort + rev: 5.13.2 + hooks: + - id: isort + args: ['--profile', 'black', '--line-length=88'] + + - repo: https://github.com/pycqa/flake8 + rev: 7.0.0 + hooks: + - id: flake8 + args: ['--max-line-length=88', '--extend-ignore=E203,W503'] + additional_dependencies: + - flake8-docstrings + - flake8-bugbear + + - repo: https://github.com/pre-commit/mirrors-mypy + rev: v1.8.0 + hooks: + - id: mypy + additional_dependencies: + - types-all + args: ['--ignore-missing-imports', '--no-strict-optional'] + + - repo: https://github.com/pre-commit/pygrep-hooks + rev: v1.10.0 + hooks: + - id: python-check-blanket-noqa + - id: python-check-mock-methods + - id: python-no-eval + - id: python-no-log-warn + + - repo: https://github.com/PyCQA/bandit + rev: 1.7.6 + hooks: + - id: bandit + args: ['-r', 'semantica/', '-f', 'json', '-o', 'bandit-report.json'] + exclude: ^tests/ + + - repo: https://github.com/adrienverge/yamllint + rev: v1.33.0 + hooks: + - id: yamllint + args: ['-d', '{extends: default, rules: {line-length: {max: 120}}}'] + + - repo: local + hooks: + - id: pytest + name: pytest + entry: pytest + language: system + pass_filenames: false + always_run: true + args: ['-v', '--tb=short'] + diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..853eae21 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,69 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added +- Initial open source project structure +- Comprehensive documentation framework +- Contributing guidelines and code of conduct +- Security policy and vulnerability reporting process + +## [0.0.1] - 2024-01-XX + +### Added +- Core framework architecture +- Universal data ingestion (50+ file formats) +- Semantic intelligence engine (NER, relation extraction, event detection) +- Knowledge graph construction with entity resolution +- 6-stage ontology generation pipeline +- GraphRAG engine for hybrid retrieval +- Multi-agent system infrastructure +- Production-ready quality assurance modules +- Comprehensive documentation with MkDocs +- Cookbook with interactive tutorials +- Support for multiple vector stores (Pinecone, Weaviate, Qdrant, FAISS) +- Support for multiple graph databases (Neo4j, NetworkX, RDFLib) +- Temporal knowledge graph support +- Conflict detection and resolution +- Deduplication and entity merging +- Schema template enforcement +- Seed data management +- Multi-format export (RDF, JSON-LD, CSV, GraphML) +- Visualization tools +- Pipeline orchestration +- Streaming support (Kafka, RabbitMQ, Kinesis) +- Context engineering for AI agents +- Reasoning and inference engine + +### Documentation +- Getting started guide +- API reference for all modules +- Concepts and architecture documentation +- Use case examples +- Cookbook tutorials +- Community projects showcase + +--- + +## Types of Changes + +- **Added** for new features +- **Changed** for changes in existing functionality +- **Deprecated** for soon-to-be removed features +- **Removed** for now removed features +- **Fixed** for any bug fixes +- **Security** for vulnerability fixes + +## Migration Guides + +When breaking changes are introduced, migration guides will be provided in the release notes and documentation. + +--- + +For detailed release notes, see [GitHub Releases](https://github.com/Hawksight-AI/semantica/releases). + diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..228f84f0 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,125 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +semantica-dev@users.noreply.github.com. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1] + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see +[https://www.contributor-covenant.org/faq][FAQ] + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..e18c4d60 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,392 @@ +# Contributing to Semantica + +Thank you for your interest in contributing to Semantica! This document provides guidelines and instructions for contributing to the project. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Development Setup](#development-setup) +- [Code Style Guidelines](#code-style-guidelines) +- [Testing Requirements](#testing-requirements) +- [Commit Message Conventions](#commit-message-conventions) +- [Pull Request Process](#pull-request-process) +- [Documentation Standards](#documentation-standards) +- [Types of Contributions](#types-of-contributions) +- [Getting Help](#getting-help) + +## Code of Conduct + +This project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the maintainers. + +## Getting Started + +1. **Fork the repository** on GitHub +2. **Clone your fork** locally: + ```bash + git clone https://github.com/your-username/semantica.git + cd semantica + ``` +3. **Add the upstream remote**: + ```bash + git remote add upstream https://github.com/Hawksight-AI/semantica.git + ``` + +## Development Setup + +### Prerequisites + +- Python 3.8 or higher (3.9+ recommended) +- pip package manager +- Git + +### Installation + +1. **Create a virtual environment** (recommended): + ```bash + python -m venv venv + source venv/bin/activate # On Windows: venv\Scripts\activate + ``` + +2. **Install the project in editable mode with dev dependencies**: + ```bash + pip install -e ".[dev]" + ``` + +3. **Install pre-commit hooks**: + ```bash + pre-commit install + ``` + +### Verify Installation + +```bash +python -c "import semantica; print(semantica.__version__)" +pytest --version +black --version +``` + +## Code Style Guidelines + +We use several tools to maintain code quality and consistency: + +### Formatting + +- **Black**: Code formatting (line length: 88) + ```bash + black semantica/ + ``` + +- **isort**: Import sorting + ```bash + isort semantica/ + ``` + +### Linting + +- **flake8**: Style guide enforcement + ```bash + flake8 semantica/ + ``` + +- **mypy**: Static type checking + ```bash + mypy semantica/ + ``` + +### Running All Checks + +```bash +# Format code +black semantica/ tests/ + +# Sort imports +isort semantica/ tests/ + +# Lint +flake8 semantica/ tests/ + +# Type check +mypy semantica/ +``` + +Or use pre-commit hooks (automatically runs on commit): +```bash +pre-commit run --all-files +``` + +## Testing Requirements + +### Running Tests + +```bash +# Run all tests +pytest + +# Run with coverage +pytest --cov=semantica --cov-report=html + +# Run specific test file +pytest tests/test_specific.py + +# Run with verbose output +pytest -v +``` + +### Test Coverage + +- Minimum coverage: **80%** +- Critical modules: **90%+** +- Coverage reports are generated in `htmlcov/` + +### Writing Tests + +- Follow pytest conventions +- Use descriptive test names +- Include docstrings for complex tests +- Test both success and failure cases +- Use fixtures for common setup + +Example: +```python +def test_entity_extraction(): + """Test basic entity extraction functionality.""" + from semantica.semantic_extract import NamedEntityRecognizer + + ner = NamedEntityRecognizer() + entities = ner.extract("Apple Inc. was founded by Steve Jobs.") + + assert len(entities) > 0 + assert any(e.text == "Apple Inc." for e in entities) +``` + +## Commit Message Conventions + +We follow [Conventional Commits](https://www.conventionalcommits.org/) specification: + +### Format + +``` +(): + + + +