Skip to content

Contributing

Thank you for your interest in contributing to Mamba Agents!

Development Setup

Prerequisites

  • Python 3.12 or later
  • uv package manager

Clone and Install

# Clone the repository
git clone https://github.com/sequenzia/mamba-agents.git
cd mamba-agents

# Install dependencies
uv sync --group dev

# Verify installation
uv run pytest --version

Development Workflow

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=mamba_agents

# Run specific test file
uv run pytest tests/unit/test_config.py

# Run tests matching pattern
uv run pytest -k "test_agent"

Code Quality

# Format code
uv run ruff format

# Check formatting
uv run ruff format --check

# Lint code
uv run ruff check

# Auto-fix lint issues
uv run ruff check --fix

# Type checking (when configured)
uv run ty check

Documentation

# Install docs dependencies
uv sync --group docs

# Serve docs locally
uv run mkdocs serve

# Build docs
uv run mkdocs build

Code Standards

Python Style

  • Python 3.12+ features are welcome
  • Type annotations on all public APIs
  • Google-style docstrings for documentation
  • ruff for linting and formatting (line-length 100)

Example Docstring

def calculate_cost(tokens: int, model: str) -> float:
    """
    Calculate the cost for token usage.

    Args:
        tokens: Number of tokens used
        model: Model identifier (e.g., "gpt-4o")

    Returns:
        Estimated cost in USD

    Raises:
        ValueError: If model is not recognized

    Example:
        >>> calculate_cost(1000, "gpt-4o")
        0.0025
    """

Testing Guidelines

  • Use pytest for all tests
  • Use TestModel from pydantic-ai for deterministic testing
  • Block real model requests in tests (see conftest.py)
  • Use respx for HTTP mocking
  • Target 90% code coverage
from pydantic_ai.models.test import TestModel
from pydantic_ai import models

# Block real requests
models.ALLOW_MODEL_REQUESTS = False

def test_agent_with_test_model():
    agent = Agent(TestModel())
    result = agent.run_sync("Hello")
    assert result.output == "test response"

Commit Messages

Use Conventional Commits:

feat: add new compaction strategy
fix: handle empty message list
docs: update API reference
test: add workflow tests
refactor: simplify token counting

Pull Request Process

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/my-feature)
  3. Make your changes
  4. Add tests for new functionality
  5. Run tests and linting (uv run pytest && uv run ruff check)
  6. Commit with a descriptive message
  7. Push to your fork
  8. Open a pull request

PR Checklist

  • [ ] Tests pass (uv run pytest)
  • [ ] Linting passes (uv run ruff check)
  • [ ] Coverage maintained at 90%+
  • [ ] Documentation updated if needed
  • [ ] Commit messages follow conventions

Project Structure

src/mamba_agents/
├── agent/           # Core agent
├── config/          # Configuration
├── context/         # Context management
├── tokens/          # Token tracking
├── workflows/       # Workflow orchestration
├── tools/           # Built-in tools
├── mcp/             # MCP integration
├── backends/        # Model backends
├── observability/   # Logging/tracing
└── errors/          # Error handling

tests/
├── unit/            # Unit tests
├── integration/     # Integration tests
├── fixtures/        # Test fixtures
└── conftest.py      # Pytest configuration

docs/
├── getting-started/ # Getting started guides
├── user-guide/      # User guides
├── tutorials/       # Tutorials
├── concepts/        # Concept explanations
└── api/             # API reference

Getting Help

License

By contributing, you agree that your contributions will be licensed under the MIT License.