How to Contribute to the Semantica AGI Project: A Complete Developer Guide

To contribute to the Semantica AGI project, fork the repository, create a descriptive feature branch, implement changes within the appropriate modular pipeline stage (such as semantica.ingest or semantica.semantic_extract), validate your code with the full quality-check suite (black, isort, flake8, mypy), and submit a Pull Request that references the associated issue.

The Semantica AGI project is an open-source knowledge-graph construction framework that transforms raw data into actionable intelligence through an 11-stage modular pipeline. Contributing to this repository involves extending capabilities in specific architectural layers, from data ingestion to semantic extraction and reasoning. Understanding the repository's stage-based structure ensures your contributions integrate seamlessly with the existing data-to-insight workflow.

Understanding the Semantica Architecture

The Semantica codebase follows a strict modular design where each pipeline stage is implemented as a distinct Python package under the semantica/ namespace. According to the ARCHITECTURE.md specification, the processing workflow proceeds through eleven distinct stages:

• Ingest (semantica.ingest): Normalizes diverse sources (files, web pages, databases, streams) into Raw Document representations.
• Parse (semantica.parse): Converts raw documents into structured data formats.
• Normalize (semantica.normalize): Cleans and standardizes textual content.
• Split (semantica.split): Segments normalized data into entity-aware or graph-aware chunks.
• Extract (semantica.semantic_extract): Generates semantic extracts including entities, relations, events, triples, and coreference data.
• Conflict Detection (semantica.conflicts): Identifies overlapping or contradictory information.
• Deduplication (semantica.deduplication): Merges duplicate facts across sources.
• KG Construction (semantica.kg): Builds the knowledge graph from processed extracts.
• Intelligence Layer (semantica.ontology, semantica.reasoning, semantica.provenance, semantica.context): Applies ontology enrichment, reasoning, provenance tracking, and decision-context handling.
• Storage (semantica.vector_store, semantica.graph_store): Persists the enriched graph to vector or graph databases.
• Outputs (semantica.export, semantica.visualization, semantica CLI): Exports data, generates visualizations, or exposes services via REST API and MCP tools.

Because each stage is isolated in its own sub-module, contributors can locate the correct layer quickly. For example, adding a new Extractor requires creating a class in semantica/semantic_extract/, while a new data source connector belongs in semantica/ingest/.

Contribution Workflow

The CONTRIBUTING.md file defines the standard workflow for all contributors. Follow this checklist to ensure your PR meets repository standards:

1. Select an Issue: Browse open issues for labels like "good first issue" and comment to request assignment, or create a new issue to propose features.
2. Fork and Clone: Fork the repository on GitHub, then clone your local copy and add the upstream remote.
3. Branch Naming: Create a dedicated branch using the pattern feature/<description> or fix/<description>.
4. Development: Implement your changes within the appropriate semantica/ sub-module, adhering to existing class hierarchies.
5. Testing: Add or update unit tests in the tests/ directory to cover new functionality.
6. Documentation: Update docstrings, README files, or add tutorials to the cookbook/ directory.
7. Quality Checks: Run formatting, linting, and type checking before committing (see commands below).
8. Submit PR: Push your branch and open a Pull Request that references the issue using keywords like Closes #123.

Setting Up the Development Environment

Begin by forking the repository and installing development dependencies. The project uses pyproject.toml to manage optional development extras.

# Clone your fork

git clone https://github.com/your-username/semantica.git
cd semantica
git remote add upstream https://github.com/semantica-agi/semantica.git

# Install with development dependencies

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

pip install -e ".[dev]"

Create a feature branch before making changes:

git checkout -b feature/add-custom-extractor

Implementing a New Feature

Most contributions involve extending base classes within specific pipeline stages. For example, to add a custom semantic extractor, inherit from BaseExtractor in the semantica.semantic_extract module.

Create a new file at semantica/semantic_extract/custom_extractor.py:

from semantica.semantic_extract import BaseExtractor
from typing import List, Dict

class CustomExtractor(BaseExtractor):
    """Extracts uppercase words as dummy entities."""
    def extract(self, text: str) -> List[Dict]:
        return [{"entity": w, "type": "UPPERCASE"} for w in text.split() if w.isupper()]

This implementation follows the established pattern where extractors return structured dictionaries containing entity metadata and classification types.

Testing and Code Quality Standards

All contributions must include unit tests and pass the automated quality suite configured in the repository. Place tests in the tests/ directory following existing naming conventions.

Example test file at tests/test_custom_extractor.py:

import pytest
from semantica.semantic_extract.custom_extractor import CustomExtractor

def test_custom_extractor():
    extractor = CustomExtractor()
    result = extractor.extract("Hello WORLD from SEMANTICA")
    assert {"entity": "WORLD", "type": "UPPERCASE"} in result
    assert {"entity": "SEMANTICA", "type": "UPPERCASE"} in result

Before submitting, run the full quality-check suite to ensure compliance with project standards:

pytest                        # Execute all tests

black . && isort .            # Format code and sort imports

flake8 . && mypy .            # Lint and type-check

pre-commit run --all-files    # Optional: run all git hooks locally

Key Project Files and Resources

Understanding these core files accelerates the contribution process and provides architectural context:

• CONTRIBUTING.md: Complete contribution guidelines, coding standards, and detailed testing commands.
• ARCHITECTURE.md: Visual documentation of the 11-stage pipeline and data flow between modules.
• README.md: High-level project overview, installation instructions, and CLI entry points.
• pyproject.toml: Declares package dependencies, optional [dev] extras for development tools, and build settings.
• semantica/: Core library containing stage-specific modules including ingest, parse, semantic_extract, kg, and reasoning.
• tests/: Unit and integration test suites that must remain green for every PR.
• cookbook/: Jupyter notebooks and tutorials illustrating real-world usage patterns for contributors and users.

Summary

• The Semantica AGI project uses an 11-stage modular architecture where each pipeline phase lives in a dedicated semantica/ sub-package (e.g., semantica.ingest, semantica.semantic_extract).
• Contributors should locate the correct architectural layer before implementing changes, ensuring new classes inherit from appropriate base classes like BaseExtractor.
• The contribution workflow requires forking, creating descriptive branches (feature/<name> or fix/<description>), and submitting PRs that reference specific issues.
• All code must pass automated checks: black for formatting, isort for import sorting, flake8 for linting, and mypy for type safety.
• Include unit tests in tests/ and update documentation in docstrings, README files, or the cookbook/ directory to maintain project quality.

Frequently Asked Questions

What programming language is the Semantica AGI project written in?

The project is implemented in Python 3.x, utilizing type hints throughout the codebase for improved developer experience and static analysis compatibility with mypy.

Do I need to understand the entire 11-stage pipeline to make a contribution?

No. The modular architecture allows contributors to focus on specific stages in isolation. You can extend the ingestion layer in semantica/ingest/ or add extractors in semantica/semantic_extract/ without modifying downstream knowledge graph construction logic, provided you maintain the expected input/output interfaces for your specific module.

How do I run tests locally before submitting my contribution?

Execute pytest from the repository root to run the full test suite. For rapid iteration during development, target specific test files with pytest tests/test_specific_file.py. Ensure you also run black, isort, flake8, and mypy to validate code quality before pushing.

Are there specific commit message conventions I should follow?

Yes. Use descriptive messages that reference the component changed, following the pattern shown in the contribution guide: git commit -m "feat(semantic_extract): add CustomExtractor for uppercase entities". This convention maintains a clear git history and facilitates automated changelog generation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}