Graph-Native Infrastructure for Context and Accountable AI Systems
Contributing to Semantica
Thank you for your interest in contributing! Every contribution, no matter how small, is valuable. π
β Give us a Star β’ π΄ Fork Semantica β’ π¬ Join our Discord
New to contributing? Start with a
good first issueor join our Discord community.
π Quick Start
- Find a
good first issue - Fork Semantica & clone the repository
- Make your changes
- Submit a pull request!
Need help? Join Discord or GitHub Discussions
ποΈ Working on an Existing Issue
If you want to work on an open GitHub issue, please follow these steps to keep things coordinated and avoid duplicate effort:
Check the issue. Look at the issue's assignees and recent comments. If someone is already actively working on it, consider a different issue or ask in the comments whether help is welcome.
Comment if you'd like the issue reserved. Leaving a comment like "I'd like to take this on" is the fastest way to get assigned, but it isn't required β maintainers can also assign an issue directly to a contributor (e.g., based on recent activity in the repo) without waiting for a comment first.
Wait for assignment. A maintainer will assign the issue when appropriate, whether or not a comment was left. Please wait for this before investing significant time in implementation, as priorities and approaches can shift.
Create a branch and implement. Once assigned, fork the repository (if you haven't already), create a dedicated branch, and begin your work.
git checkout -b fix/short-description # or feature/short-descriptionOpen a focused PR and link the issue. When you're ready, open a pull request and reference the issue in the description (e.g.,
Closes #123). Keep the PR scoped to the work described in the issue.
Why this matters: Assignment (with or without a comment) helps maintainers track who is working on what and prevent two contributors from solving the same problem independently. It also gives you a chance to align on the expected approach before writing code.
Not sure where to start? Try a good first issue or ask in Discord.
π Duplicate PRs & Issue Priority
When more than one pull request targets the same issue, maintainers triage using this order of priority. These rules decide between PRs that are otherwise following the assignment workflow above β opening a PR before being assigned doesn't grant priority on its own, and an unassigned PR can still be closed as a duplicate once someone else is assigned to the issue.
- Contributor-raised issue with an existing PR. If the person who opened the issue has also opened a PR for it, that PR is prioritized (they still need to be assigned before it's merged).
- Maintainer-raised issue with a claim comment. If we opened the issue and someone has commented asking to work on it, we assign it to them and check their PR before picking up any other PR for the same issue.
- No prior assignment or comment. If multiple PRs exist and no one was assigned or claimed the issue first, priority goes to whichever contributor has the most consistent activity in the repo over the last 60 days (e.g., merged PRs, substantive reviews, or issue triage participation) β not just PR volume.
- Late duplicate PRs. If a PR is opened after another contributor has already been assigned to the issue, we close the duplicate early rather than let it sit open, and point the author to another open issue (or ask them to check
mainfor newly opened ones). This avoids contributors spending time updating a PR that won't be merged. - Overlapping scope. If a PR covers multiple issues, or there's genuine overlap between competing PRs, maintainers discuss it on Discord before deciding rather than resolving it unilaterally.
Why this matters: it keeps triage predictable, avoids wasted contributor effort on PRs that won't merge, and helps retain active contributors.
π― Ways to Contribute
π» Code
What you can do:
- Fix bugs
- Add new features
- Improve code quality (add type hints, docstrings, improve error messages)
- Optimize performance
Where: semantica/ directory
Good first issues: Add docstrings, type hints, or improve error messages
π Documentation
What you can do:
- Fix typos and grammar errors
- Improve clarity and readability
- Add code examples and tutorials
- Create new cookbook notebooks
- Improve API documentation (docstrings)
- Create troubleshooting guides
- Update installation instructions
- Add missing documentation
Where: README.md, docs/, cookbook/, docstrings in code
Good first issues: Fix typos, add examples, create cookbook tutorials, improve docstrings
Documentation formatting:
- Use clear, concise language
- Include code examples where helpful
- Follow markdown best practices
- Use proper headings hierarchy
- Add links to related sections
- Include screenshots for UI-related docs
π§ͺ Testing
What you can do:
- Add unit tests
- Improve test coverage
- Add integration tests
Where: tests/ directory
Good first issues: Add tests for specific functions or classes
π Bug Reports
What: Report bugs you find
How: Use the bug report template
Include: Description, steps to reproduce, expected vs actual behavior, environment details
π‘ Feature Requests
What: Suggest new features or improvements
How: Use the feature request template
Include: Problem statement, proposed solution, use cases
π¨ Cookbook & Examples
What: Create tutorials and examples
Where: cookbook/ directory
Examples: Create new notebooks, add examples, improve existing tutorials
π¬ Community Support
What: Help others in the community
Where: Discord, GitHub Discussions
Examples: Answer questions, review PRs, share your projects
π Educational Content
What: Create educational materials
Examples: Blog posts, video tutorials, talks, workshops, case studies
π§ Other Contributions
- Design & Graphics: Logos, diagrams, visualizations
- Tools & Integrations: CLI tools, integrations with other frameworks
- Infrastructure: CI/CD improvements, Docker optimization
- Security: Report security vulnerabilities (privately)
π Getting Started
1. Fork & Clone
First, fork Semantica on GitHub, then:
git clone https://github.com/your-username/semantica.git
cd semantica
git remote add upstream https://github.com/semantica-agi/semantica.git
2. Set Up Environment
# Create virtual environment
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# Install the package plus the contributor tooling (pytest, black, ...).
# The tooling lives in the PEP 735 `dev` dependency group, not in an extra;
# `--group` needs pip 25.1+ (run `pip install --upgrade pip` first).
pip install -e . --group dev
# Install pre-commit hooks (optional)
pre-commit install
Semantica supports Python 3.11β3.13 (requires-python = ">=3.11,<3.14"). Python 3.10
support ended in 0.8.0; see the CHANGELOG.
CI runs on 3.11 and the Install Matrix covers the whole range.
Reproducible environment with uv (recommended)
The repository commits a uv.lock, so uv can build the exact same
environment for every contributor:
pip install uv==0.13.4 # same version CI uses (.github/requirements/uv-tool.txt)
uv sync # creates .venv from uv.lock, including the `dev` group
uv sync --extra explorer # add whichever extras you are working on
uv sync --python 3.11 # match CI's interpreter (any of 3.11-3.13 works)
uv run pytest tests/
uv sync installs the core dependencies plus the dev dependency group
(uv's default group). Optional extras are opt-in via --extra <name>, exactly
like pip install -e ".[<name>]".
uv.lock is a universal lock: it must resolve for every Python version in
requires-python and covers the dev group and every optional extra
currently declared in pyproject.toml. After changing dependencies
in pyproject.toml, refresh and commit it:
uv lock # regenerate
uv lock --check # what CI runs: fails if uv.lock is stale or unresolvable
uv.lock is for local development. It is separate from the hash-pinned
requirements-ci.txt below, which remains the source of truth for CI and
release builds.
Pinned CI dependencies
requirements-ci.txt pins every transitive dependency at exact versions so CI,
security scans, and release builds install the same packages every run (the
Python equivalent of explorer/package-lock.json + npm ci). It is a
separate build environment: every package carries a SHA-256 hash
(--generate-hashes), so installs are reproducible and supply-chain safe β
never install into your local dev environment from it.
Regenerate it after changing pyproject.toml dependencies:
pip install uv==0.12.1
uv pip compile pyproject.toml --python-version 3.11 --python-platform linux --extra all --group dev --generate-hashes -o requirements-ci.txt
The all extra is the repo's cross-platform dependency set (GPU extras like
faiss-gpu/cupy are excluded and installed separately on Linux β see
pyproject.toml). The dev dependency group (pytest, black, ...) is not part of
all, so it is added with --group dev. Keep the pinned uv version in sync with CI so regeneration
is deterministic.
CI's staleness check re-resolves with the committed lockfile as a constraint
and compares version lines only: upstream package releases never fail CI β
the lockfile changes only when pyproject.toml changes intentionally.
CI fails if requirements-ci.txt is stale relative to pyproject.toml
(the version-line comparison detects new/removed/changed dependencies).
When the Security Scan's pip-audit gate flags a pinned dependency, bump it
to the latest release with no known advisories, not the first fixed
version: a minimal bump tends to land just inside the range of the next
advisory. Regenerate with --upgrade-package <name> so other pins stay put.
Build-system pins: [build-system].requires is pinned to exact versions
(setuptools==84.2.1, wheel==0.48.0) and release builds run
python -m build --no-isolation against the lockfile β no unpinned
build-time isolation anywhere.
3. Create Branch
git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description
4. Make Changes
- Follow code style (see below)
- Add tests for new features
- Update documentation
5. Run Checks
pytest # Run tests
black semantica/ tests/ # Format code
isort semantica/ tests/ # Sort imports
flake8 semantica/ tests/ # Lint
Or use pre-commit hooks: pre-commit run --all-files
6. Commit & Push
git commit -m "feat(module): add new feature"
git push origin feature/your-feature-name
Then create a pull request on GitHub!
π Code Style
We use automated tools:
| Tool | Purpose | Command |
|---|---|---|
| Black | Code formatting | black semantica/ tests/ |
| isort | Import sorting | isort semantica/ tests/ |
| flake8 | Style enforcement | flake8 semantica/ tests/ |
| mypy | Type checking | mypy semantica/ |
Run all: black semantica/ tests/ && isort semantica/ tests/ && flake8 semantica/ tests/ && mypy semantica/
π§ͺ Testing
pytest # Run all tests
pytest --cov=semantica # With coverage
pytest tests/test_file.py # Specific file
Coverage goal: 80% minimum, 90%+ for critical modules
Known failures list
.github/full-suite-known-failures.txt lists tests that already fail on an unmodified checkout. CI runs them under xfail instead of skipping them, and the marker is strict in CI. If your change makes a listed test pass, CI reports XPASS(strict) and fails. Delete that test's line from the file in the same PR.
Don't add a line to hide a failure your change introduces. Fix the test or the code instead.
π Commit Messages
Use Conventional Commits:
feat(kg): add temporal graph support
fix(parse): handle empty PDF files
docs(readme): add installation guide
test(extract): add unit tests
Types: feat, fix, docs, test, refactor, perf, style, chore
β PR Checklist
Before submitting:
- Code follows style guidelines
- Tests pass locally
- New tests added (if applicable)
- Documentation updated
- Commit messages follow conventions
- No merge conflicts
π Documentation Standards
Code Documentation (Docstrings)
Format: Use Google-style docstrings
def extract_entities(text: str, model: str = "transformer") -> List[Entity]:
"""Extract named entities from text.
Args:
text: Input text to process
model: NER model to use (default: "transformer")
Returns:
List of extracted Entity objects
Raises:
ValueError: If text is empty or model is invalid
Example:
>>> from semantica.semantic_extract import NERExtractor
>>> ner = NERExtractor(method="ml", model="en_core_web_sm")
>>> entities = ner.extract("Apple Inc. was founded in 1976.")
>>> len(entities)
2
"""
Markdown Documentation Formatting
General Guidelines:
- Use clear headings (H1 for title, H2 for main sections, H3 for subsections)
- Keep paragraphs short and focused
- Use bullet points for lists
- Add code blocks with syntax highlighting
- Include links to related documentation
Code Blocks:
- Use triple backticks with language identifier:
```python,```bash - Include comments in code examples
- Show expected output when helpful
Examples:
## Section Title
Brief introduction paragraph.
### Subsection
- Bullet point 1
- Bullet point 2
**Code example:**
```python
from semantica import SomeClass
instance = SomeClass()
result = instance.method()
Note: Additional context or warnings.
**Best Practices:**
- Start with an overview/introduction
- Use consistent terminology
- Include "See also" links
- Add examples for complex concepts
- Keep formatting consistent across docs
---
## π Getting Help
- π¬ [Discord](https://discord.gg/sV34vps5hH) - Real-time chat
- π [GitHub Discussions](https://github.com/semantica-agi/semantica/discussions) - Q&A
- π [GitHub Issues](https://github.com/semantica-agi/semantica/issues) - Bug reports
**Before asking:** Check existing documentation, search issues/discussions, review cookbook examples
---
## π Recognition
All contributors are recognized in:
- [CONTRIBUTORS.md](CONTRIBUTORS.md)
- GitHub contributors page
- Release notes
We follow the [all-contributors](https://allcontributors.org) specification!
---
## π Code of Conduct
This project follows a [Code of Conduct](CODE_OF_CONDUCT.md). Be respectful and inclusive.
---
## π Resources
- [README.md](README.md) - Project overview
- [Cookbook](cookbook/) - Tutorials and examples
- [Documentation](docs/) - Comprehensive guides
---
**Thank you for contributing!** π
Every contribution matters - whether it's a single line of code, a typo fix, a helpful answer, or a bug report. We appreciate you! π
β **Give us a Star** β’ π΄ **[Fork Semantica](https://github.com/semantica-agi/semantica/fork)** β’ π¬ **Join our [Discord](https://discord.gg/sV34vps5hH)**