quantcost 0.2.0__tar.gz

quantcost-0.2.0/.dockerignore

@@ -0,0 +1,30 @@
+# Keep the build context small and hermetic. Anything the image genuinely needs
+# is COPY'd explicitly in the Dockerfile; anything generated is mounted at run
+# time via docker-compose.yml.
+
+.git
+.github
+.venv
+venv
+__pycache__
+**/__pycache__
+*.pyc
+.pytest_cache
+.ruff_cache
+.mypy_cache
+
+# Generated artifacts and measurements: mounted, never baked in. Baking them
+# would let a stale model or an old benchmark table ride along inside the image.
+artifacts/
+results/
+
+# Not part of the Linux container build.
+android/
+aihub/
+site/
+tests/
+
+*.onnx
+*.safetensors
+*.gguf
+.DS_Store

quantcost-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,23 @@
+<!--
+Submitting benchmark results? `quantcost submit` fills this in for you.
+If you ran it, you can delete this template — your numbers are already below.
+
+Submitting a code change instead? Delete this and describe the change.
+-->
+
+## Benchmark results
+
+- **CPU**:
+- **OS**:
+- **Model**:
+
+<!-- Paste the table `quantcost run` printed, or just leave the card file. -->
+
+### Checklist
+
+- [ ] The card was produced by `quantcost run` (not edited by hand)
+- [ ] The machine was reasonably idle — no "varied by more than 15%" warning
+- [ ] `results/community/` is the only directory this PR touches
+
+Numbers are never edited after the fact. If something looks wrong, re-run and
+submit the new card — a corrected measurement is welcome, a hand-tuned one is not.

quantcost-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,73 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # The default install must keep working on every Python it claims to
+        # support, including the newest — people run this on whatever they have.
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install (default deps only — no torch)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Ruff (lint)
+        run: ruff check .
+
+      - name: Ruff (format check)
+        run: ruff format --check .
+
+      - name: Pytest
+        run: pytest
+
+      - name: Assert the default install stays torch-free
+        # The whole contribution path depends on this: if importing the CLI ever
+        # drags in torch, a one-command benchmark becomes a multi-gigabyte one.
+        run: |
+          python - <<'PY'
+          import sys
+          import edgellm.cli  # noqa: F401
+          heavy = {m.split(".")[0] for m in sys.modules} & {
+              "torch", "transformers", "optimum", "datasets", "onnx", "matplotlib"
+          }
+          assert not heavy, f"CLI import pulled in heavy dependencies: {sorted(heavy)}"
+          print("CLI import is torch-free")
+          PY
+
+  validate-submitted-cards:
+    name: Validate result cards
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+
+      - name: Validate every card in results/community
+        run: python -m edgellm.validate results/community
+
+      - name: Confirm the leaderboard still builds from these cards
+        # Only that it *builds*. A contributor's PR adds a card and nothing else;
+        # regenerating LEADERBOARD.md is the merge job's responsibility, not theirs.
+        run: quantcost leaderboard --out /tmp/leaderboard.md --json-out /tmp/leaderboard.json

quantcost-0.2.0/.github/workflows/leaderboard.yml

@@ -0,0 +1,51 @@
+name: Rebuild leaderboard
+
+# Contributors submit a result card and nothing else. The leaderboard is a
+# generated artifact, so it is rebuilt here after a merge and committed back —
+# asking a first-time contributor to also regenerate a Markdown table is the
+# kind of friction that loses the submission.
+on:
+  push:
+    branches: [main]
+    paths:
+      - "results/community/**"
+      - "edgellm/leaderboard.py"
+      - "edgellm/validate.py"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: leaderboard
+  cancel-in-progress: false
+
+jobs:
+  rebuild:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+
+      - name: Rebuild from every submitted card
+        run: quantcost leaderboard
+
+      - name: Commit if it changed
+        run: |
+          if git diff --quiet -- results/LEADERBOARD.md site/leaderboard.json; then
+            echo "Leaderboard unchanged."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add results/LEADERBOARD.md site/leaderboard.json
+          git commit -m "Rebuild leaderboard from submitted cards"
+          git push

quantcost-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,89 @@
+name: Release to PyPI
+
+# Publishes on a version tag. Uses PyPI Trusted Publishing (OIDC), so there is no
+# API token stored in this repository at all.
+#
+# One-time setup on PyPI, before the first tag. The project does not exist yet,
+# so this is the *pending* publisher form, not the per-project settings page:
+#   https://pypi.org/manage/account/publishing/
+#     PyPI Project Name: quantcost
+#     Owner:             vijay-kapse
+#     Repository name:   EdgeLLM        (the repo, not the package)
+#     Workflow name:     release.yml
+#     Environment name:  pypi           (required - this job declares it)
+#
+# Then:  git tag v0.2.0 && git push origin v0.2.0
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Verify the eval corpus is inside the wheel
+        # A wheel missing the pinned corpus installs fine and then fails the hash
+        # check on first use, so this is checked before anything is published.
+        run: |
+          python - <<'PY'
+          import glob, zipfile
+          wheel = sorted(glob.glob("dist/*.whl"))[-1]
+          names = zipfile.ZipFile(wheel).namelist()
+          assert "edgellm/data/eval_wikitext2.txt" in names, f"corpus missing from {wheel}"
+          print(f"{wheel}: corpus bundled")
+          PY
+
+      - name: Check the tag matches the packaged version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          python - <<'PY'
+          import glob, os, re
+          tag = os.environ["GITHUB_REF_NAME"].lstrip("v")
+          wheel = os.path.basename(sorted(glob.glob("dist/*.whl"))[-1])
+          version = re.match(r"quantcost-([^-]+)-", wheel).group(1)
+          assert version == tag, f"tag {tag!r} does not match built version {version!r}"
+          print(f"tag and version agree: {version}")
+          PY
+
+      - name: Smoke-test the built wheel in a clean environment
+        run: |
+          python -m venv /tmp/smoke
+          /tmp/smoke/bin/pip install --quiet dist/*.whl
+          /tmp/smoke/bin/quantcost --help > /dev/null
+          /tmp/smoke/bin/python -c "
+          import sys, edgellm.cli
+          heavy = {m.split('.')[0] for m in sys.modules} & {'torch', 'transformers'}
+          assert not heavy, heavy
+          print('wheel installs clean and imports torch-free')
+          "
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write    # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

quantcost-0.2.0/.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Project artifacts (models, exports, quantized weights are large — never commit)
+artifacts/
+*.onnx
+*.onnx_data
+*.gguf
+*.bin
+*.safetensors
+hf_cache/
+.cache/
+
+# Results: commit curated tables/charts, ignore bulky raw dumps
+results/raw/
+
+# C++ build
+cpp/build/
+kernels/build/
+*.o
+*.obj
+
+# Android
+android/.gradle/
+android/build/
+android/app/build/
+android/local.properties
+android/.idea/
+*.apk
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

quantcost-0.2.0/.mailmap

@@ -0,0 +1,11 @@
+# Canonical identity for every commit in this repository.
+# All of these are the same author; git split them across machines,
+# GitHub noreply addresses, university accounts and assistant tooling.
+Vijay Kapse <vijayskofficial@gmail.com> <118760102+vijay-kapse@users.noreply.github.com>
+Vijay Kapse <vijayskofficial@gmail.com> <vijay-kapse@users.noreply.github.com>
+Vijay Kapse <vijayskofficial@gmail.com> <vj@Vijays-MacBook-Air.local>
+Vijay Kapse <vijayskofficial@gmail.com> <vsk@Vijays-MacBook-Pro.local>
+Vijay Kapse <vijayskofficial@gmail.com> <vkapse@binghamton.edu>
+Vijay Kapse <vijayskofficial@gmail.com> <21f1000202@ds.study.iitm.ac.in>
+Vijay Kapse <vijayskofficial@gmail.com> <noreply@anthropic.com>
+Vijay Kapse <vijayskofficial@gmail.com> Vijay Suryakant Kapse <vijayskofficial@gmail.com>

quantcost-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing
+
+## Submitting benchmark results
+
+This is the most useful thing you can contribute, and it takes about two minutes.
+
+```bash
+pip install quantcost
+quantcost run
+quantcost submit
+```
+
+`submit` validates the card, forks this repo, commits your result and opens the
+pull request. If you do not have the [GitHub CLI](https://cli.github.com)
+installed it prints a prefilled link instead, so you are never stuck.
+
+### What makes a good submission
+
+- **An idle machine.** Close the browser and the build you have running. If the
+  report prints a *"varied by more than 15%"* warning, re-run before submitting.
+- **Default settings.** `quantcost run` with no flags produces a card that
+  is comparable with everyone else's. Non-default runs are still accepted and
+  listed — they just are not ranked, because a 64-token run and a 32-token run
+  do not measure the same thing.
+- **Leave `--threads` alone** unless you are deliberately investigating it. The
+  default pins ONNX Runtime to your machine's *performance* cores, and the card
+  records how that was determined (`thread_policy`). This matters more than it
+  sounds: on a heterogeneous CPU one thread scheduled onto an efficiency core
+  gates the whole parallel region. Measured on an Apple M4 (4 performance + 6
+  efficiency), pinning all ten physical cores cost int8 66% of its throughput
+  and doubled run-to-run spread, while barely moving fp32. A card run across
+  both tiers is measuring something different from everyone else's.
+- **Interesting hardware especially welcome.** Raspberry Pi, old ThinkPads,
+  Snapdragon laptops, bare-metal ARM servers, anything unusual. The point of the
+  leaderboard is the *spread* across real machines, not the top of the list.
+
+### What gets rejected, and why
+
+CI runs `python -m edgellm.validate results/community` on every PR. It rejects
+cards that are internally inconsistent (throughput that disagrees with the
+latency and token count it claims), scored against a modified eval corpus, run
+with an unpinned thread count, or carrying identifying information about your
+machine. The intent is to keep the leaderboard comparable, not to accuse anyone:
+if your card is rejected, the message says what to fix, and re-running almost
+always fixes it.
+
+Results are reviewed, not blindly trusted. Nothing here can prove a number came
+from real silicon — but every input is pinned (model revision, artifact bytes,
+corpus hash, prompt hash, token budget), so anyone can re-run the exact
+configuration recorded in your card and compare.
+
+### Privacy
+
+A card contains your CPU model string, architecture, core count, RAM rounded to
+the nearest gigabyte, OS name and release, and version strings. It does **not**
+contain your hostname, username, file paths, IP or MAC address, or any machine
+identifier. `edgellm/card.py::fingerprint` is the only function that reads your
+machine, so you can check that claim in one place. The `--name` flag is optional
+and the only thing that attaches an identity to a submission.
+
+## Code changes
+
+```bash
+pip install -e ".[dev]"
+ruff check . && ruff format --check . && pytest
+```
+
+Adding the quantization/export path (PyTorch, Optimum, ONNX) needs the extra:
+
+```bash
+pip install -e ".[dev,quantize]"
+```
+
+Keep the default install torch-free. CI asserts that importing the CLI pulls in
+no heavy dependency, because the contribution flow above depends on a fast
+install. If you need torch, import it inside the function that uses it.

quantcost-0.2.0/Dockerfile

@@ -0,0 +1,119 @@
+# syntax=docker/dockerfile:1.7
+#
+# EdgeLLM container image.
+#
+# Builds both native binaries against a pinned ONNX Runtime release, then ships
+# them alongside the Python pipeline in a slim runtime image:
+#
+#   edgellm_infer  - C++17 harness, KV-cache greedy decode via the ORT C++ API
+#   int8_gemm      - scalar vs. hand-vectorized INT8 GEMM microbenchmark
+#
+# The image is architecture-aware. On arm64 the kernel compiles the ARM NEON
+# SDOT path; on amd64 it compiles the AVX2 path. That is deliberate: running the
+# same image on an Apple Silicon host and on an x86 cloud instance produces two
+# genuinely different SIMD backends to compare, rather than one emulated number.
+#
+# Build:
+#   docker build -t edgellm .
+#   docker build -t edgellm --build-arg ORT_VERSION=1.20.1 .
+#
+# See docker-compose.yml for the pipeline / inference / benchmark entry points.
+
+ARG UBUNTU_VERSION=22.04
+ARG PYTHON_VERSION=3.11
+
+# ---------------------------------------------------------------- builder ----
+FROM ubuntu:${UBUNTU_VERSION} AS builder
+
+# Pinned rather than "latest": benchmark numbers are only comparable across runs
+# if the inference runtime is held fixed.
+ARG ORT_VERSION=1.22.0
+ARG TARGETARCH
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential \
+        cmake \
+        ca-certificates \
+        curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# ONNX Runtime publishes prebuilt Linux archives as x64 / aarch64; Docker's
+# TARGETARCH is amd64 / arm64. Translate, with a uname fallback for the legacy
+# (non-BuildKit) builder where TARGETARCH is not populated.
+RUN set -eux; \
+    arch="${TARGETARCH:-}"; \
+    if [ -z "${arch}" ]; then \
+        case "$(uname -m)" in \
+            x86_64)         arch=amd64 ;; \
+            aarch64|arm64)  arch=arm64 ;; \
+        esac; \
+    fi; \
+    case "${arch}" in \
+        amd64) ort_arch=x64 ;; \
+        arm64) ort_arch=aarch64 ;; \
+        *) echo "unsupported architecture: '${arch}'" >&2; exit 1 ;; \
+    esac; \
+    url="https://github.com/microsoft/onnxruntime/releases/download/v${ORT_VERSION}/onnxruntime-linux-${ort_arch}-${ORT_VERSION}.tgz"; \
+    echo "fetching ${url}"; \
+    curl -fsSL -o /tmp/ort.tgz "${url}"; \
+    mkdir -p /opt/onnxruntime; \
+    tar -xzf /tmp/ort.tgz -C /opt/onnxruntime --strip-components=1; \
+    rm /tmp/ort.tgz; \
+    test -f /opt/onnxruntime/include/onnxruntime_cxx_api.h; \
+    test -e /opt/onnxruntime/lib/libonnxruntime.so
+
+# cpp/CMakeLists.txt resolves ONNX Runtime from ORT_HOME (its documented escape
+# hatch for non-Homebrew hosts), so no CMake changes are needed to build here.
+ENV ORT_HOME=/opt/onnxruntime
+
+WORKDIR /src
+COPY cpp/ cpp/
+COPY kernels/ kernels/
+
+RUN cmake -S cpp -B build/cpp -DCMAKE_BUILD_TYPE=Release \
+    && cmake --build build/cpp -j "$(nproc)"
+
+RUN cmake -S kernels -B build/kernels -DCMAKE_BUILD_TYPE=Release \
+    && cmake --build build/kernels -j "$(nproc)"
+
+# ---------------------------------------------------------------- runtime ----
+FROM python:${PYTHON_VERSION}-slim-bookworm AS runtime
+
+# libgomp is ONNX Runtime's OpenMP dependency; without it the .so fails to load.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        libgomp1 \
+        ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /opt/onnxruntime/lib/ /opt/onnxruntime/lib/
+COPY --from=builder /src/build/cpp/edgellm_infer   /usr/local/bin/edgellm_infer
+COPY --from=builder /src/build/kernels/int8_gemm   /usr/local/bin/int8_gemm
+
+ENV LD_LIBRARY_PATH=/opt/onnxruntime/lib \
+    PYTHONUNBUFFERED=1 \
+    HF_HOME=/cache/huggingface
+
+WORKDIR /app
+
+# Dependency metadata first so the (slow) install layer caches independently of
+# source edits. hatchling reads README.md at build time, so it has to come too.
+COPY pyproject.toml README.md ./
+COPY edgellm/ edgellm/
+
+# CPU-only torch on x86 avoids pulling ~2.5 GB of CUDA wheels that this image
+# has no GPU to use. The CPU index has no aarch64 wheels, so arm64 takes the
+# ordinary PyPI build, which is already CPU-only.
+RUN set -eux; \
+    case "$(uname -m)" in \
+        x86_64) pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu ;; \
+        *)      pip install --no-cache-dir torch ;; \
+    esac; \
+    pip install --no-cache-dir ".[onnx,eval,report]"
+
+COPY configs/ configs/
+COPY scripts/ scripts/
+
+# Written to by the pipeline; compose mounts host directories over both.
+RUN mkdir -p /app/artifacts /app/results /cache/huggingface
+
+CMD ["edgellm", "--help"]

quantcost-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vijay Kapse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.