Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
152 lines (111 loc) · 4.69 KB

CONTRIBUTING.md

File metadata and controls

152 lines (111 loc) · 4.69 KB

Contributing to MnemeBrain Lite

Thank you for your interest in contributing! This guide will help you get started.

Development Setup

Prerequisites

  • Python 3.12+
  • uv (recommended) or pip

Getting Started

# Clone the repository
git clone git@github.com:mnemebrain/mnemebrain-lite.git
cd mnemebrain-lite

# Install dependencies (including dev extras)
uv sync --extra dev

# Install embedding providers (at least one required for /believe endpoint)

# Option A: Local embeddings (no API key needed)
uv pip install -e ".[embeddings]"

# Option B: OpenAI embeddings (requires OPENAI_API_KEY)
uv pip install -e ".[openai]"

# Option C: Everything
uv pip install -e ".[all]"

# Run all tests
uv run pytest tests/ -v

# Run only unit tests (fast, no external deps)
uv run pytest tests/unit/ -v

# Run integration tests (requires sentence-transformers model download)
uv run pytest tests/integration/ -v -m integration

# Run e2e tests (full API tests)
uv run pytest tests/e2e/ -v -m e2e

# Lint (ruff check + format)
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/

# Auto-fix lint issues
uv run ruff check --fix src/ tests/
uv run ruff format src/ tests/

# Test coverage
uv run pytest tests/ --cov=src/mnemebrain_core --cov-report=term-missing

# Coverage with HTML report
uv run pytest tests/ --cov=src/mnemebrain_core --cov-report=html
# open htmlcov/index.html

# Type check (requires pyright install)
uv run pip install pyright
uv run pyright src/

Project Structure

src/mnemebrain_core/
├── models.py          # Core data models (Belief, Evidence, TruthState)
├── engine.py          # Pure computation functions (truth state, confidence, decay)
├── store.py           # KuzuGraphStore — embedded graph database
├── memory.py          # BeliefMemory — the 4 core operations
├── working_memory.py  # WorkingMemoryFrame — active context for multi-step reasoning
├── providers/
│   ├── base.py        # Abstract EmbeddingProvider interface
│   └── embeddings/
│       ├── sentence_transformers.py  # Local embeddings (all-MiniLM-L6-v2)
│       └── openai.py                # OpenAI embeddings (text-embedding-3-small)
└── api/
    ├── app.py         # FastAPI application factory
    ├── routes.py      # REST endpoint handlers
    └── schemas.py     # Request/response Pydantic models

tests/
├── unit/              # Fast tests, no external dependencies
├── integration/       # Tests requiring Kuzu DB + embeddings
└── e2e/               # Full API endpoint tests

How to Contribute

Reporting Bugs

Open an issue using the Bug Report template. Include:

  • Steps to reproduce
  • Expected vs actual behavior
  • Python version and OS

Suggesting Features

Open an issue using the Feature Request template. Describe:

  • The problem you're solving
  • Your proposed approach
  • Alternatives you considered

Submitting Code

  1. Fork the repository
  2. Create a feature branch: git checkout -b feat/your-feature
  3. Write tests for your changes
  4. Ensure all tests pass: uv run pytest tests/ -v
  5. Run lint and format: uv run ruff check src/ tests/ && uv run ruff format --check src/ tests/
  6. Follow the code style (we use ruff for linting and formatting)
  7. Commit with conventional commits: feat(scope): description
  8. Push and open a Pull Request

Commit Convention

We use Conventional Commits:

Prefix Usage
feat New feature
fix Bug fix
docs Documentation only
test Adding or updating tests
refactor Code change that neither fixes a bug nor adds a feature
chore Maintenance tasks

Example: feat(memory): add batch believe operation

Code Guidelines

  • All public functions must have docstrings
  • New features must include tests
  • No # type: ignore or # noqa without justification
  • Evidence is append-only — never delete, only invalidate
  • Engine functions must be pure (no side effects, no mutations)

Architecture Principles

MnemeBrain Lite follows these core design principles:

  1. Belnap 4-valued logic — beliefs can be TRUE, FALSE, BOTH (contradiction), or NEITHER (insufficient evidence)
  2. Append-only evidence — evidence is never deleted, only invalidated via retract()
  3. Time decay — evidence weight decays based on belief type half-life
  4. Embedding dedup — similar claims are merged automatically via embedding similarity
  5. Pure computation — engine.py contains only pure functions; state lives in store.py

Questions?

Open an issue with the Question template, or start a discussion.