Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
72 lines (55 loc) · 1.87 KB

CONTRIBUTING.md

File metadata and controls

72 lines (55 loc) · 1.87 KB
Raw

Contributing to Marvin

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

Development Setup

  1. Clone the repo

    git clone https://github.com/r0k3/marvin.git
cd marvin

  2. Install Python 3.12+

  3. Install uv — a fast Python package manager

  4. Install dependencies

    uv sync

  5. Full stack (optional) — starts NATS, Ollama, MCP Gateway, and Brain Worker:

    docker compose up -d

Running Tests

uv run pytest

Tests live in the tests/ directory.

Code Style

Marvin uses ruff for linting and formatting.

uv run ruff check .
uv run ruff format .

Project Structure

src/marvin/         # Core library
├── server.py       # MCP Gateway (FastMCP)
├── service.py      # Business logic layer
├── vault.py        # Obsidian vault management
├── git.py          # Git integration
├── index.py        # Hybrid search index (sqlite-vec + FTS5)
├── embeddings.py   # Local ONNX embeddings (fastembed)
├── broker.py       # NATS message broker
├── worker.py       # Brain Worker daemon
├── consolidation.py # Computational sleep engine
├── extraction.py   # Entity extraction (langextract)
├── models.py       # Pydantic data models
├── config.py       # Configuration (pydantic-settings)
└── skill.md        # Agent skill instructions
tests/              # Pytest test suite
docs/               # MkDocs documentation
examples/           # Example vaults showcasing memory types

Pull Requests

  1. Fork the repo and create a feature branch
  2. Ensure tests pass (uv run pytest)
  3. Follow existing code style (uv run ruff check .)
  4. Write clear commit messages
  5. Open a pull request with a description of your changes