memvanta 0.8.3__tar.gz

memvanta-0.8.3/.clang-format

@@ -0,0 +1,19 @@
+BasedOnStyle: LLVM
+Language: Cpp
+Standard: c++20
+IndentWidth: 4
+ContinuationIndentWidth: 4
+ColumnLimit: 100
+BreakBeforeBraces: Attach
+AllowShortFunctionsOnASingleLine: Inline
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+AllowShortBlocksOnASingleLine: Never
+BinPackArguments: false
+BinPackParameters: false
+DerivePointerAlignment: false
+PointerAlignment: Left
+SortIncludes: CaseSensitive
+IncludeBlocks: Regroup
+NamespaceIndentation: None
+FixNamespaceComments: true

memvanta-0.8.3/.github/CODEOWNERS

@@ -0,0 +1,7 @@
+* @sauravsingla
+
+# Benchmark evidence and reproducibility-sensitive files
+/results/ @sauravsingla
+/docs/MEMORY_BENCHMARKING.md @sauravsingla
+/docs/BENCHMARK_CHECKLIST.md @sauravsingla
+/.github/workflows/ @sauravsingla

memvanta-0.8.3/.github/ISSUE_TEMPLATE/benchmark-reproduction.md

@@ -0,0 +1,67 @@
+---
+name: Benchmark reproduction
+description: Report an independent MemVanta memory benchmark reproduction
+title: "[reproduction] "
+labels: []
+assignees: []
+---
+
+## Result summary
+
+Briefly state whether your result confirms, narrows, or contradicts a published MemVanta memory result.
+
+## Hardware and operating system
+
+- CPU:
+- Physical cores / logical CPUs:
+- Total RAM:
+- Operating system:
+- Kernel:
+- Swap state:
+
+## Builds
+
+- MemVanta commit SHA:
+- Compiler and version:
+- Build flags/type:
+- Comparison runtime and commit SHA:
+- Comparison runtime build flags/type:
+
+## Model
+
+- Model name:
+- GGUF filename:
+- Quantization:
+- File size:
+- SHA-256:
+
+## Workload
+
+- Threads:
+- Context size:
+- Batch size:
+- KV-cache format:
+- Prompt tokens:
+- Generated tokens:
+- Warm-up runs:
+- Measured runs:
+
+## Peak-RSS results
+
+Include every measured run and the aggregate statistics. Attach or link raw output when possible.
+
+## Constrained-memory results
+
+If tested, list each cgroup-v2 `MemoryMax` ceiling and whether MemVanta and the comparison runtime completed or were OOM-killed. Confirm whether swap was disabled.
+
+## Throughput
+
+Report prompt-processing and token-generation throughput for transparency even when memory, rather than speed, is the focus.
+
+## Commands and raw evidence
+
+Paste exact commands or provide a repository/link containing the raw logs and machine-readable summary.
+
+## Deviations from the reference protocol
+
+Describe anything that differs from `docs/MEMORY_BENCHMARKING.md`.

memvanta-0.8.3/.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 5

memvanta-0.8.3/.github/pull_request_template.md

@@ -0,0 +1,42 @@
+## Summary
+
+Describe the change and why it is needed.
+
+## Change type
+
+- [ ] Runtime/code change
+- [ ] Benchmark/reproducibility change
+- [ ] Documentation only
+- [ ] CI/build change
+
+## Validation
+
+- [ ] Release build succeeds
+- [ ] `ctest` passes
+- [ ] Existing deterministic correctness checks pass
+- [ ] No benchmark number was changed without raw evidence
+
+## Performance / memory evidence
+
+If this PR changes runtime behavior, include before/after measurements using the same model, workload, threads, context, batch and KV-cache settings.
+
+- Peak RSS before:
+- Peak RSS after:
+- Prompt-processing throughput before/after:
+- Token-generation throughput before/after:
+- Model SHA-256:
+- MemVanta base/head commit SHAs:
+- Comparison-runtime commit SHA, if applicable:
+
+Attach or link raw outputs. Follow `docs/MEMORY_BENCHMARKING.md` and `docs/BENCHMARK_CHECKLIST.md` for publishable claims.
+
+## Claim discipline
+
+- [ ] Any memory claim is scoped to the tested model/workload/hardware
+- [ ] Throughput is reported transparently alongside memory results
+- [ ] Lowest successful cgroup ceiling is described as a tested boundary, not an exact RAM requirement
+- [ ] Contradictory or failed runs are retained and explained
+
+## Reviewer notes
+
+Call out anything that deserves extra scrutiny, especially benchmark methodology, correctness, numerical tolerance, or changes to `results/` and benchmark workflows.

memvanta-0.8.3/.github/scripts/check_social_preview.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import struct
+import sys
+from html.parser import HTMLParser
+from pathlib import Path
+
+EXPECTED_IMAGE = "https://sauravsingla.github.io/MemVanta/social-card.png"
+EXPECTED_WIDTH = "1200"
+EXPECTED_HEIGHT = "630"
+
+
+class SocialParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__()
+        self.meta: dict[tuple[str, str], str] = {}
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag != "meta":
+            return
+        values = dict(attrs)
+        content = values.get("content")
+        if content is None:
+            return
+        if values.get("property"):
+            self.meta[("property", values["property"] or "")] = content
+        if values.get("name"):
+            self.meta[("name", values["name"] or "")] = content
+
+
+def check_png(path: Path, errors: list[str]) -> None:
+    if not path.exists():
+        errors.append(f"missing social preview image: {path}")
+        return
+    data = path.read_bytes()
+    if len(data) < 24 or data[:8] != b"\x89PNG\r\n\x1a\n":
+        errors.append(f"social preview is not a valid PNG: {path}")
+        return
+    width, height = struct.unpack(">II", data[16:24])
+    if (width, height) != (1200, 630):
+        errors.append(f"social preview must be 1200x630, found {width}x{height}")
+
+
+def main() -> None:
+    out = Path(sys.argv[1] if len(sys.argv) > 1 else "_site")
+    errors: list[str] = []
+    check_png(out / "social-card.png", errors)
+
+    pages = sorted(out.rglob("index.html"))
+    if not pages:
+        errors.append("no generated HTML pages found")
+
+    for page in pages:
+        parser = SocialParser()
+        parser.feed(page.read_text(encoding="utf-8"))
+        meta = parser.meta
+
+        required = {
+            ("property", "og:image"): EXPECTED_IMAGE,
+            ("property", "og:image:type"): "image/png",
+            ("property", "og:image:width"): EXPECTED_WIDTH,
+            ("property", "og:image:height"): EXPECTED_HEIGHT,
+            ("name", "twitter:card"): "summary_large_image",
+            ("name", "twitter:image"): EXPECTED_IMAGE,
+        }
+        for key, expected in required.items():
+            actual = meta.get(key)
+            if actual != expected:
+                errors.append(f"{page}: {key[1]} is {actual!r}, expected {expected!r}")
+
+        for key in (("property", "og:image:alt"), ("name", "twitter:image:alt")):
+            if not meta.get(key, "").strip():
+                errors.append(f"{page}: missing {key[1]}")
+
+    if errors:
+        for error in errors:
+            print(f"ERROR: {error}")
+        raise SystemExit(1)
+
+    print(f"Validated large social previews on {len(pages)} generated pages.")
+
+
+if __name__ == "__main__":
+    main()

memvanta-0.8.3/.github/workflows/cancel-obsolete-pr-runs.yml

@@ -0,0 +1,69 @@
+name: Cancel Obsolete PR Runs
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, reopened, synchronize]
+
+permissions:
+  actions: write
+  contents: read
+
+# This workflow is intentionally the only central cancellation hook. It avoids
+# copying concurrency blocks into every benchmark workflow while preserving all
+# current-head evidence and every non-PR/push run.
+concurrency:
+  group: cancel-obsolete-pr-runs-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  cancel-obsolete:
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Cancel queued or running jobs from older commits on this PR branch
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const branch = context.payload.pull_request.head.ref;
+            const currentSha = context.payload.pull_request.head.sha;
+            const currentRunId = context.runId;
+            const statuses = new Set(['queued', 'in_progress', 'waiting', 'requested', 'pending']);
+            let cancelled = 0;
+
+            for (let page = 1; page <= 10; page++) {
+              const { data } = await github.rest.actions.listWorkflowRunsForRepo({
+                owner,
+                repo,
+                branch,
+                event: 'pull_request',
+                per_page: 100,
+                page,
+              });
+              if (data.workflow_runs.length === 0) break;
+
+              for (const run of data.workflow_runs) {
+                if (run.id === currentRunId || run.head_sha === currentSha) continue;
+                if (!statuses.has(run.status)) continue;
+                core.info(`Cancelling stale run ${run.id} (${run.name}) at ${run.head_sha}`);
+                try {
+                  await github.rest.actions.cancelWorkflowRun({ owner, repo, run_id: run.id });
+                  cancelled++;
+                } catch (error) {
+                  // A run may finish between listing and cancellation. Only ignore
+                  // that normal race; surface permission/API failures.
+                  if (error.status === 409) {
+                    core.info(`Run ${run.id} already completed while cancelling`);
+                  } else {
+                    throw error;
+                  }
+                }
+              }
+              if (data.workflow_runs.length < 100) break;
+            }
+            core.summary.addHeading('Obsolete PR run cleanup');
+            core.summary.addRaw(`Cancelled ${cancelled} stale queued/running run(s) for ${branch}.`);
+            await core.summary.write();

memvanta-0.8.3/.github/workflows/ci.yml

@@ -0,0 +1,218 @@
+name: Build and Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  linux:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    strategy:
+      fail-fast: false
+      matrix:
+        build_type: [Release, Debug]
+
+    name: linux-${{ matrix.build_type }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Verify canonical README benchmark
+        if: matrix.build_type == 'Release'
+        run: python3 scripts/sync_headline_benchmark.py --check
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y build-essential cmake ninja-build clang-format
+
+      - name: Enforce clang-format across C++ tree
+        if: matrix.build_type == 'Release'
+        run: |
+          find src include tests benchmarks -type f \( -name '*.cpp' -o -name '*.hpp' \) -print0 \
+            | xargs -0 clang-format --dry-run --Werror
+          clang-format --dry-run --Werror tools_gguf_inspect.cpp tools_tokenize.cpp
+
+      - name: Configure
+        run: cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=${{ matrix.build_type }}
+
+      - name: Build
+        run: cmake --build build -j "$(nproc)"
+
+      - name: Test
+        run: ctest --test-dir build --output-on-failure
+
+  portable-linux:
+    name: linux-Release-portable-runtime-dispatch
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y build-essential cmake ninja-build
+
+      - name: Configure without -march=native
+        run: >-
+          cmake -S . -B build-portable -G Ninja
+          -DCMAKE_BUILD_TYPE=Release
+          -DMEMVANTA_NATIVE=OFF
+
+      - name: Build portable binary
+        run: cmake --build build-portable -j "$(nproc)"
+
+      - name: Test portable runtime-dispatch build
+        run: ctest --test-dir build-portable --output-on-failure
+
+      - name: Verify installable runtime layout
+        shell: bash
+        run: |
+          set -euo pipefail
+          prefix="${PWD}/install-root"
+          cmake --install build-portable --prefix "${prefix}"
+          test -x "${prefix}/bin/memvanta"
+          test -x "${prefix}/bin/memvanta_real"
+          test -x "${prefix}/bin/memvanta_tokenize"
+          test -x "${prefix}/bin/memvanta_gguf_inspect"
+          test -f "${prefix}/share/doc/memvanta_cpu/README.md"
+          test -f "${prefix}/share/doc/memvanta_cpu/LICENSE"
+          test -f "${prefix}/share/doc/memvanta_cpu/CITATION.cff"
+
+  arm64-qemu:
+    name: arm64-Release-NEON-capable-cross
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install ARM64 toolchain and emulator
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            cmake ninja-build qemu-user \
+            gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
+
+      - name: Configure ARMv8 SIMD build
+        run: >-
+          cmake -S . -B build-arm64 -G Ninja
+          -DCMAKE_BUILD_TYPE=Release
+          -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/aarch64-linux-gnu.cmake
+          -DCMAKE_CXX_FLAGS="-march=armv8-a+simd"
+          -DMEMVANTA_NATIVE=OFF
+          -DMEMVANTA_ENABLE_IPO=OFF
+          -DCMAKE_DISABLE_FIND_PACKAGE_OpenMP=TRUE
+
+      - name: Build ARM64 targets
+        run: cmake --build build-arm64 -j "$(nproc)"
+
+      - name: Run portable correctness tests under QEMU
+        run: >-
+          ctest --test-dir build-arm64 --output-on-failure
+          -E memvanta_concurrency_stress_tests
+
+  sanitizers:
+    name: clang-ASan-UBSan
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      CC: clang
+      CXX: clang++
+      ASAN_OPTIONS: detect_leaks=1:halt_on_error=1
+      UBSAN_OPTIONS: print_stacktrace=1:halt_on_error=1
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y clang cmake ninja-build
+
+      - name: Configure with AddressSanitizer and UBSan
+        run: >-
+          cmake -S . -B build-sanitize -G Ninja
+          -DCMAKE_BUILD_TYPE=Debug
+          -DMEMVANTA_NATIVE=OFF
+          -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer"
+          -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address,undefined"
+
+      - name: Build
+        run: cmake --build build-sanitize -j "$(nproc)"
+
+      - name: Test under sanitizers
+        run: ctest --test-dir build-sanitize --output-on-failure
+
+      - name: Build GGUF fuzz target
+        run: |
+          cmake -S . -B build-fuzz -G Ninja -DMEMVANTA_NATIVE=OFF -DMEMVANTA_BUILD_FUZZER=ON
+          cmake --build build-fuzz --target memvanta_gguf_fuzz -j "$(nproc)"
+
+      - name: GGUF fuzz smoke
+        run: ./build-fuzz/memvanta_gguf_fuzz -runs=1000 -max_len=16384
+
+  thread-sanitizer:
+    name: clang-TSan
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      CC: clang
+      CXX: clang++
+      TSAN_OPTIONS: halt_on_error=1:second_deadlock_stack=1
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y clang cmake ninja-build
+
+      - name: Configure with ThreadSanitizer
+        run: >-
+          cmake -S . -B build-tsan -G Ninja
+          -DCMAKE_BUILD_TYPE=Debug
+          -DMEMVANTA_NATIVE=OFF
+          -DCMAKE_DISABLE_FIND_PACKAGE_OpenMP=TRUE
+          -DCMAKE_CXX_FLAGS="-fsanitize=thread -fno-omit-frame-pointer"
+          -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=thread"
+
+      - name: Build
+        run: cmake --build build-tsan -j "$(nproc)"
+
+      - name: Test under ThreadSanitizer
+        run: ctest --test-dir build-tsan --output-on-failure
+
+  macos:
+    name: macOS-Clang
+    runs-on: macos-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Configure
+        run: cmake -S . -B build-macos -DCMAKE_BUILD_TYPE=Release -DMEMVANTA_NATIVE=OFF
+
+      - name: Build
+        run: cmake --build build-macos -j 3
+
+      - name: Test
+        run: ctest --test-dir build-macos --output-on-failure