Skip to content

Contributing to AdaptShot

Thank you for your interest in contributing to AdaptShot. This document outlines how to contribute code, documentation, or feedback in a way that aligns with our mission: building trustworthy, CPU-first few-shot vision AI for resource-constrained environments.

🎯 Our Guiding Principles

  1. Truth over hype: We document what works, what doesn't, and why. No exaggerated claims.
  2. CPU-first by default: All new features must run on CPU with <250MB RAM unless explicitly marked as optional GPU extras.
  3. Human-in-the-loop by design: Contributions should enhance transparency, calibration, or feedback routing—not obscure them.
  4. Open and reproducible: Every benchmark, test, and result must be reproducible with pytest, mypy, and our benchmark harnesses.

🛠️ Getting Started

Prerequisites

  • Python ≥ 3.9
  • Git
  • Virtual environment tool (venv, virtualenv, or conda)

Setup

# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/adaptshot.git
cd adaptshot

# 2. Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 3. Install development dependencies
pip install -e ".[dev]"

# 4. Install pre-commit hooks (optional but recommended)
pre-commit install

Verify Your Setup

# Run tests
pytest tests/ -v

# Run type checking
mypy src/adaptshot --strict

# Run linting
ruff check src/adaptshot tests/

# Run smoke benchmark
python -m benchmarks.run_benchmark --smoke-test
All commands should pass before submitting a pull request.

📦 Project Structure

adaptshot/
├── src/adaptshot/          # Core library code
│   ├── config/             # Configuration dataclasses
│   ├── core/               # Inference engine (extractor, similarity, calibration, ACT, learner)
│   ├── training/           # Continual learning (feedback_router, finetune, up_ugf)
│   ├── ui/                 # Gradio interface for pilots
│   └── utils/              # Determinism, I/O helpers
├── benchmarks/             # Reproducible evaluation scripts
├── tests/                  # Unit and integration tests
├── docs/                   # Documentation source (MkDocs)
├── pyproject.toml          # Build config, dependencies, tool settings
├── README.md               # Project overview
├── CONTRIBUTING.md         # This file
├── CODE_OF_CONDUCT.md      # Community standards
└── CHANGELOG.md            # Version history

🧪 Testing Guidelines

  • All new code must include unit tests in tests/ using pytest.
  • Type hints are required on all public functions and classes (mypy --strict enforced).
  • Benchmarks must be deterministic: Use set_deterministic_seed() and verify with verify_determinism().
  • CPU-first validation: New features must pass benchmarks on CPU unless explicitly marked GPU-only.

Example test structure: 

# tests/test_new_module.py
import pytest
from src.adaptshot.new_module import NewComponent

def test_new_component_basic():
    comp = NewComponent(param=42)
    result = comp.run()
    assert result is not None
    assert isinstance(result, ExpectedType)

📝 Code Style

  • Formatting: Ruff auto-formatter (ruff check --fix)
  • Imports: Standard library → third-party → local (sorted alphabetically)
  • Docstrings: Google-style for public APIs; concise one-liners for private helpers
  • Line length: ≤100 characters
  • Logging: Use logging.getLogger(__name__) instead of print() for library code

🔄 Contribution Workflow

  1. Create a feature branch: git checkout -b feat/your-feature-name
  2. Make changes: Follow testing and style guidelines above
  3. Run full validation: 
    pytest tests/ -v
mypy src/adaptshot --strict
ruff check src/adaptshot tests/
python -m benchmarks.run_benchmark --smoke-test
  4. Commit with clear messages: 
    git commit -m "feat: add conformal prediction stub to CalibrationEngine"
git commit -m "test: add unit tests for UP-UGF pruning logic"
  5. Push and open a Pull Request:
  6. Link to relevant issue or discussion
  7. Describe what changed and why
  8. Include benchmark diffs if performance/calibration affected
  9. Add [WIP] prefix if work is incomplete

🗣️ Communication

  • Discussions: Use GitHub Discussions for questions, ideas, and RFCs
  • Issues: Report bugs or request features via GitHub Issues
  • WhatsApp: Join our community WhatsApp group for real-time discussion
  • Security: Report vulnerabilities privately to johnson2006christopher@gmail.com
  • Code of Conduct: All interactions follow our Code of Conduct

📚 Documentation

  • API docs: Auto-generated from docstrings via MkDocs + mkdocstrings
  • Tutorials: Jupyter notebooks in docs/tutorials/ with executable examples
  • Examples: Minimal runnable scripts in docs/examples/

To preview docs locally: 

pip install mkdocs mkdocstrings[python] mkdocs-material
mkdocs serve
# Visit http://localhost:8000

🚫 What We Don't Accept

  • Features that require GPU by default without a CPU fallback
  • Undocumented public APIs or missing type hints
  • Benchmarks that aren't reproducible with --seed 42
  • Marketing language or unsubstantiated performance claims
  • Code that violates our CPU-first, <250MB RAM constraint for core functionality

🙏 Thank You

Every contribution—code, docs, testing, or feedback—helps make trustworthy AI accessible to more people. We review all PRs within 7 days and provide constructive feedback.

If you're unsure where to start, look for issues labeled good first issue or open a Discussion to propose an idea.

— The AdaptShot Maintainers

Created by Johnson Christopher Hassan
Connect on LinkedIn
Project: github.com/johnson2006christopher/adaptshot