Contributing¶

Guidelines for contributing to Aletheia.

Development Setup¶

# Clone the repository
git clone https://github.com/david-morales/aletheia.git
cd aletheia

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

Development Workflow¶

Branch and Commit¶

1. Create a feature branch from main
2. Make changes, write tests
3. Commit with conventional messages (feat:, fix:, refactor:, docs:, test:, chore:)
4. Push and merge to main

# Example workflow
git checkout -b feat/my-feature
# ... make changes ...
pytest tests/ -v
git add -A && git commit -m "feat: add my feature"
git push origin feat/my-feature

Graphiti Fork¶

Aletheia depends on a maintained fork of Graphiti. When reinstalling after fork changes, always force-reinstall to bypass pip's version cache:

pip install --no-cache-dir --force-reinstall \
  "graphiti-core[falkordb] @ git+https://github.com/david-morales/aletheia-graphiti.git@aletheia"
pip install -e ".[dev]"

Key Rules¶

• Schemas are auto-generated — files in schemas/<use_case>/ are regenerated by schema inference on every run. Never edit them manually.
• Core must not know about specific use cases — fixes go in use_cases/<name>/ or in generic core code.

Code Style¶

Python¶

• Follow PEP 8
• Use type hints
• Maximum line length: 100 characters
• Use docstrings for public functions

def build_episode(entity: MyEntity) -> str:
    """Convert entity to markdown episode.

    Args:
        entity: The entity to convert.

    Returns:
        Markdown string representation of the entity.
    """
    ...

Markdown¶

• Use ATX-style headers (#)
• Use fenced code blocks with language hints
• One sentence per line (for diffs)

Testing¶

Running Tests¶

# All tests
pytest tests/ -v

# Specific test file
pytest tests/test_parser.py -v

# With coverage
pytest tests/ -v --cov=aletheia

Writing Tests¶

# tests/test_my_feature.py
import pytest
from aletheia.core.my_module import my_function


def test_my_function_basic():
    """Test basic functionality."""
    result = my_function("input")
    assert result == "expected"


def test_my_function_edge_case():
    """Test edge case handling."""
    with pytest.raises(ValueError):
        my_function("")

Test Coverage Requirements¶

• New public methods should have unit tests
• New parsing/validation logic should have edge case tests
• Integration points should have integration tests

Documentation¶

When to Update Docs¶

• New features → Add to relevant guide
• API changes → Update reference
• Bug fixes → Add to troubleshooting if relevant

Documentation Location¶

Building Docs Locally¶

mkdocs serve
# Visit http://localhost:8000

Pull Request Guidelines¶

Before Submitting¶

• [ ] Tests pass locally
• [ ] Code follows style guidelines
• [ ] Documentation updated (if applicable)
• [ ] Commit message follows format

PR Description Template¶

## Summary
Brief description of changes.

## Changes
- Change 1
- Change 2

## Testing
How was this tested?

## TODO Reference
Closes TODO-XXX

Getting Help¶

• Open an issue for bugs or feature requests
• Check existing issues before creating new ones
• Provide minimal reproduction cases for bugs

Learn More¶

• Architecture - System overview
• Creating Use Cases - Adding new use cases