Best Practices for Developing with Colibri: A Complete Guide to Contributing

Always preserve the dependency-free CPU path, develop against the dev branch, and run make check before submitting PRs to ensure your changes meet the project's stability standards.

Colibri is a lightweight, dependency-free inference engine written in C with a thin Python wrapper. Whether you are optimizing CUDA kernels or extending the CLI, following the established best practices for developing with Colibri ensures your contributions remain portable and maintainable. This guide covers the essential workflows, testing requirements, and coding standards defined in the repository's CONTRIBUTING.md and source tree.

Understand the Architecture: C Engine vs. Python Wrapper

Colibri maintains a strict separation between its high-performance backend and user-facing interface.

• Engine (C): Located in the c/ directory, this layer handles high-performance model execution with optional CUDA and Vulkan support. The key entry point is c/coli, which is invoked via the Python wrapper.
• Python Wrapper: Provides the user-friendly coli CLI and library import (import colibri). Key files include colibri/cli.py for the console script entry point and colibri/__init__.py, which exposes the package __version__.

This two-layer design ensures that the core engine remains dependency-free while the Python layer handles convenience features.

Preserve the Dependency-Free CPU Path

The default build must remain dependency-free and runnable on any CPU without CUDA, Vulkan, or external Python packages.

If you introduce features requiring extra libraries, isolate that code behind compile-time or runtime flags. This ensures the plain-CPU build remains untouched and stable.

"Keep changes focused and preserve Colibri's dependency-free default CPU path." — CONTRIBUTING.md

Follow the Branch Workflow

The repository uses a two-branch strategy to maintain stability.

• main: Contains stable code that always passes the token-exact oracle test.
• dev: The integration branch where all development occurs.

Always open pull requests against dev. Reviewed PRs land there first, and only after validation does the maintainer fast-forward dev into main.

"Open your PR against dev. Reviewed PRs land there first …" — CONTRIBUTING.md

Run Automated Checks Before Pushing

Validate your changes using the repository's lightweight test harness.

# Run the portable CPU build, C unit tests, and Python std-lib tests

make check

This command does not download models or require CUDA, making it safe for rapid iteration.

For GPU-specific changes, additionally run:

make -C c cuda-test CUDA_ARCH=native

"CUDA changes should additionally be checked on a CUDA-capable Linux host." — CONTRIBUTING.md

Maintain Reproducible Builds

All builds are driven by the Makefile in the repository root. When adding new source files to the C engine, update c/Makefile to list them in the appropriate build target.

This guarantees that make check produces a clean, warning-free compilation across different environments.

Extend the CLI Responsibly

The public CLI (coli) is a thin wrapper around the engine script. Keep the wrapper minimal by delegating to c/coli via runpy.run_path:

# colibri/cli.py – entry point for the `coli` console script

import os
import sys
import runpy

def main():
    engine_dir = os.path.join(os.path.dirname(__file__), "..", "c")
    coli_script = os.path.join(engine_dir, "coli")
    sys.path.insert(0, engine_dir)
    sys.argv[0] = coli_script
    runpy.run_path(coli_script, run_name="__main__")

This pattern ensures that pip install colibri-engine creates a working coli command without requiring users to modify their PATH.

Adhere to Code Style and Linting

The repository enforces strict formatting standards for both languages.

• C Code: Follow the .clang-format file and run clang-tidy via make check.
• Python Code: Adhere to PEP-8 standards validated by flake8.

Running make check before committing catches style violations early and prevents CI failures.

Benchmark Responsibly

Performance changes require reproducible evidence. Include a benchmark report detailing:

• Commit hash and hardware specifications
• Exact command line used
• Warm-up policy and run count
• Median throughput results

Place this documentation in docs/benchmarks.md or a new markdown file under docs/.

"Benchmark reports should include the commit, exact commands, hardware and storage details, warm-up policy, run count, and median throughput." — CONTRIBUTING.md

Summary

Following these best practices for developing with Colibri maintains the codebase's portability and performance:

• Guard optional dependencies behind flags to preserve the default CPU path.
• Develop on dev and target it for all pull requests.
• Run make check locally before pushing; add GPU tests for CUDA/Vulkan changes.
• Update c/Makefile when adding source files to ensure reproducible builds.
• Keep the Python wrapper thin by delegating to c/coli via runpy.
• Follow linting rules enforced by clang-tidy and flake8.
• Document benchmarks with full hardware and methodology details in docs/.

Frequently Asked Questions

Should I develop on the main or dev branch?

Always develop on the dev branch. The main branch contains stable, production-ready code that has passed all validation tests. Open your pull requests against dev, where maintainers review and integrate changes before promoting them to main.

How do I test CUDA changes without breaking the CPU build?

Isolate CUDA-specific code behind compile-time flags or runtime checks. Run make check to verify the CPU build remains intact, then execute make -C c cuda-test CUDA_ARCH=native on a CUDA-capable machine to validate GPU functionality. This ensures the dependency-free default path stays functional for all users.

What should I include in a performance benchmark report?

Include the exact commit hash, hardware specifications (CPU, GPU, storage), the precise command line executed, your warm-up policy, the number of runs performed, and the median throughput. Place this report in docs/benchmarks.md so other developers can reproduce your results.

How do I add a new command-line option to the Colibri CLI?

Add new flags to colibri/cli.py using argparse, then forward unknown arguments to the C engine via runpy.run_path. Set environment variables for flags the engine needs to read directly. Keep the wrapper minimal and delegate actual processing to c/coli rather than implementing logic in Python.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}