model-mirror-cli 0.2.0__tar.gz

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

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v7
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install locked dependencies
+        run: uv sync --locked --all-extras --dev
+      - name: Run test and coverage gate
+        run: |
+          uv run coverage run -m pytest -q
+          uv run coverage report -m
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b
+      - name: Build wheel and source distribution
+        run: uv build --no-sources
+      - name: Smoke-test wheel
+        run: uv run --isolated --no-project --with dist/*.whl tests/smoke_test.py
+      - name: Smoke-test source distribution
+        run: uv run --isolated --no-project --with dist/*.tar.gz tests/smoke_test.py

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

@@ -0,0 +1,47 @@
+name: Publish release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b
+      - name: Validate release tag
+        run: |
+          python scripts/check_release.py "$GITHUB_REF_NAME"
+          if [ "$(git cat-file -t "$GITHUB_REF_NAME")" != "tag" ]; then
+            echo "::error::release tag must be annotated"
+            exit 1
+          fi
+          git fetch --no-tags origin main:refs/remotes/origin/main
+          if ! git merge-base --is-ancestor "$(git rev-list -n 1 "$GITHUB_REF_NAME")" origin/main; then
+            echo "::error::release tag must point to a commit on main"
+            exit 1
+          fi
+      - name: Run test and coverage gate
+        run: |
+          uv sync --locked --all-extras --dev
+          uv run coverage run -m pytest -q
+          uv run coverage report -m
+      - name: Build wheel and source distribution
+        run: uv build --no-sources
+      - name: Smoke-test wheel
+        run: uv run --isolated --no-project --with dist/*.whl tests/smoke_test.py
+      - name: Smoke-test source distribution
+        run: uv run --isolated --no-project --with dist/*.tar.gz tests/smoke_test.py
+      - name: Publish to PyPI
+        run: uv publish

model_mirror_cli-0.2.0/.gitignore

@@ -0,0 +1,59 @@
+# Secrets and local configuration
+.env
+.env.*
+*.pem
+*.key
+*.token
+.model-mirror.yaml
+model-mirror.yaml
+.model-mirror/
+.verification
+.checksums
+.manifest
+
+# Model archives and large local state
+models/
+datasets/
+spaces/
+archives/
+downloads/
+.cache/
+cache/
+tmp/
+logs/
+*.safetensors
+*.bin
+*.pt
+*.pth
+*.ckpt
+*.gguf
+*.onnx
+*.msgpack
+*.h5
+*.incomplete
+SHA256SUMS
+MANIFEST.jsonl
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+
+# Test and tooling output
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS/editor noise
+.DS_Store
+Thumbs.db
+*~
+*.swp

model_mirror_cli-0.2.0/CONTRIBUTORS.md

@@ -0,0 +1,87 @@
+# Contributors
+
+This document holds implementation notes and development details. User-facing
+usage belongs in `README.md`.
+
+## Development
+
+```bash
+uv sync
+uv run coverage run -m pytest
+uv run coverage report -m
+```
+
+The test suite is expected to hold 100% statement and branch coverage. The
+coverage gate is enforced in `pyproject.toml`.
+
+## State Files
+
+Each mirrored repo owns its state inside the repo directory:
+
+- `.verification`: YAML status, timestamps, commit metadata, offline-only flag,
+  issues, repair paths
+- `.manifest`: versioned JSONL records with local size, mtime, SHA-256, and Git blob SHA-1
+- `.verification.lock`: advisory lock metadata while an operation is active
+- `.model-mirror/snapshot.json`: authoritative commit-pinned expected file list
+- `.model-mirror/torrent/coverage/`: atomic, resumable profile-specific piece
+  and Merkle hash coverage
+- `.model-mirror/torrent/publications/`: torrent artifacts, recovery records,
+  and durable publication/desired-seed state
+- `.model-mirror/torrent/fence.json`: the active commit update fence
+
+Deleting a model directory deletes its verification state with it. There is no
+global model state database.
+
+## Commit Handling
+
+Online operations resolve the requested revision to a concrete Hub commit before
+downloading or verifying. A clean local mirror is trusted for its resolved
+commit. If upstream moves, verification records `upstream_status: changed` but
+does not mutate local files. `repair --update` is the explicit command for
+moving to the new upstream commit recorded by verification.
+
+If upstream is unavailable, verification exits non-zero and preserves the local
+verification status when one already exists. `offline` sets `offline_only: true`
+for that repo, clears the upstream-unavailable issue, and makes future
+verification local-only until `online` clears the flag.
+
+## Checksums
+
+Manifest writes are incremental. After each file is hashed, `.manifest` is
+atomically rewritten with a schema/version header and one record per payload
+file. Each file is read once while both SHA-256 and Git blob SHA-1 are computed.
+Later runs skip files whose size, mtime, and hash fields match the manifest
+record. Downloads accumulate these hashes and any enabled torrent coverage
+while streaming into the destination's `.incomplete` file. This makes an
+interrupted download resumable without a mandatory second full-file hash pass.
+
+## Locking
+
+Mutating mirror, verification, repair, upgrade, and torrent control-plane
+transitions take an advisory lock on `.verification.lock` for the target repo.
+The first mirror operation writes `.verification` with `status: in_progress`
+before downloading. The seeder acquires the lock only for short reconciliation
+transitions, never for its lifetime. `list` does not block; it reports lock
+metadata when a repo is busy.
+
+## Hugging Face And Xet
+
+`model-mirror` uses `huggingface_hub` to resolve pinned metadata and transport
+URLs, then streams HTTP or Xet bytes into its own resumable hashing writer.
+Environment setup is derived from model-mirror config and is intentionally
+authoritative: if a config boolean is false, inherited Xet environment
+variables for that feature are removed before importing or using the transport.
+
+The conservative default is:
+
+- high-performance Xet mode off
+- range-get concurrency `1`
+- optional sequential reconstruction writes for HDD-backed archives
+
+This keeps the default path usable on lower-memory machines and lets power users
+tune throughput explicitly.
+
+## Design Documents
+
+- [Torrent Distribution And Archive Upgrade Requirements](docs/torrent-distribution-requirements.md)
+- [Torrent Backend Spike](docs/torrent-backend-spike.md)

model_mirror_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xlr8harder
+
+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.