Matheel

Matheel is a Python package and CLI for source-code similarity. It combines semantic embeddings, lexical similarity, chunking, preprocessing, and code evaluation metrics in one workflow.

Installation

Matheel supports Python 3.10 to 3.13.

Recommended install:

pip install "matheel[all]"

For a lightweight install without optional semantic, chunking, metrics, and Gradio dependencies:

pip install matheel

Installation options are covered in the usage guide.

Quick Start

Create a tiny archive and compare it with the CLI:

python - <<'PY'
from zipfile import ZipFile

with ZipFile("sample_pairs.zip", "w") as archive:
    archive.writestr("a.py", "def add(a, b):\n    return a + b\n")
    archive.writestr("b.py", "def add(x, y):\n    return x + y\n")
    archive.writestr("c.py", "def sub(a, b):\n    return a - b\n")
PY

matheel compare sample_pairs.zip \
  --feature-weight levenshtein=1.0 \
  --num 10

Or score a pair directly from Python:

from matheel.similarity import calculate_similarity

score = calculate_similarity(
    "def add(a, b):\n    return a + b\n",
    "def add(x, y):\n    return x + y\n",
    feature_weights={"levenshtein": 1.0},
)
print(round(score, 4))

See the usage guide for semantic models, archives, comparison suites, custom algorithms, chunking, preprocessing, visualization, leaderboards, and code metrics.

Links

• Documentation: fahadebrahim.github.io/matheel
• Choosing metrics: similarity guide
• Public plagiarism benchmark: definition and reproduction recipe, results and scope
• Hugging Face Space demo: buelfhood/matheel-framework
• Core workflows Colab notebook: Open in Colab
• Dataset workflows Colab notebook: Open in Colab
• Custom algorithms Colab notebook: Open in Colab
• Gradio Colab notebook: Open in Colab
• Visualization and leaderboard Colab notebook: Open in Colab
• Examples folder: examples/
• Development: development docs

Development

Contributor setup, tests, linting, package checks, and release preparation are documented in the development docs.

License

This project is licensed under the MIT License.