mirrorcommons 0.1.0__tar.gz

mirrorcommons-0.1.0/LICENSE

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

mirrorcommons-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: mirrorcommons
+Version: 0.1.0
+Summary: CLI for Mirror Commons: create continuity manifests for external AI artifacts and publish reviewed community mirrors.
+Author: Mirror Commons
+License-Expression: MIT
+Project-URL: Homepage, https://mirrorcommons.com
+Project-URL: Source, https://github.com/Hashem-Al-Qurashi/mirrorcommons-cli
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: huggingface_hub>=0.30
+Provides-Extra: s3
+Requires-Dist: boto3>=1.35; extra == "s3"
+Dynamic: license-file
+
+# ArtifactGrid CLI
+
+`mirrorcommons` is the public-facing command alias for this package; `artifactgrid` remains available for continuity-report compatibility. The same CLI powers Mirror Commons publisher submissions and ArtifactGrid private continuity reports.
+
+This local-first CLI creates a private Consumer Continuity Report for a third-party public Hugging Face dependency. It can download an exact pinned revision or validate a snapshot you already hold. ArtifactGrid does not receive cloud credentials or host model weights.
+
+Supported V1 files are `.safetensors`, `.json`, `.md`, `.txt`, and `.model`, plus a root `LICENSE` file. If a root `LICENSE`, `LICENSE.md`, or `LICENSE.txt` is present, the manifest records its path and SHA-256 as a factual observation. This is not a legal review. Symlinks and unsupported formats are deliberately skipped; ArtifactGrid never loads model code or unsafe serialized formats.
+
+## Run locally
+
+```bash
+cd cli
+python3 -m pip install -e .
+artifactgrid inspect \
+  --source-url https://huggingface.co/owner/repository \
+  --revision <full-40-character-commit> \
+  --download
+```
+
+For a public Mirror Commons submission, use the identical command with the `mirrorcommons` alias:
+
+```bash
+mirrorcommons publish create --help
+```
+
+The local workflow needs no cloud-storage package. Install the optional S3 support only when using S3 or R2:
+
+```bash
+python3 -m pip install -e '.[s3]'
+```
+
+Use `--snapshot-dir ./snapshot` instead of `--download` when the customer has already retrieved the pinned snapshot.
+
+With `--download`, ArtifactGrid materializes ordinary files in a temporary directory so Hugging Face cache symlinks and local `.cache` metadata cannot enter the manifest. The CLI removes that temporary directory after `inspect` or `protect` finishes.
+
+Record whether the upstream public source currently resolves to the exact pinned commit. This uses Hugging Face's public API without a user token and does not download model weights:
+
+```bash
+artifactgrid source-check \
+  --source-url https://huggingface.co/owner/repository \
+  --revision <full-40-character-commit> \
+  --output ./source-observation.json
+```
+
+Create a customer-attested backup in a directory the customer controls:
+
+```bash
+artifactgrid protect \
+  --source-url https://huggingface.co/owner/repository \
+  --revision <full-40-character-commit> \
+  --download \
+  --backup-dir ./customer-backup \
+  --output ./continuity-manifest.json
+```
+
+`--output` is optional. It writes a portable copy of the same manifest kept with the customer backup.
+
+Or copy directly into customer-controlled R2/S3. The CLI uses the customer's standard local AWS credential chain or environment variables and never sends them to ArtifactGrid:
+
+```bash
+artifactgrid protect \
+  --source-url https://huggingface.co/owner/repository \
+  --revision <full-40-character-commit> \
+  --snapshot-dir ./snapshot \
+  --s3-bucket customer-ai-artifacts \
+  --s3-prefix artifactgrid/production-model \
+  --s3-endpoint-url https://<account-id>.r2.cloudflarestorage.com \
+  --output ./continuity-manifest.json
+```
+
+Verify a recovery copy:
+
+```bash
+artifactgrid verify \
+  --manifest ./customer-backup/artifactgrid-manifest.json \
+  --backup-dir ./customer-backup
+```
+
+With scoped read access, verify every protected S3/R2 object directly:
+
+```bash
+artifactgrid verify \
+  --manifest ./continuity-manifest.json \
+  --s3-bucket customer-ai-artifacts \
+  --s3-prefix artifactgrid/production-model \
+  --s3-endpoint-url https://<account-id>.r2.cloudflarestorage.com
+```
+
+Run a clean restore drill into an empty directory, then produce a private portable report:
+
+```bash
+artifactgrid restore \
+  --manifest ./customer-backup/artifactgrid-manifest.json \
+  --backup-dir ./customer-backup \
+  --restore-dir ./restore-drill
+
+artifactgrid report \
+  --manifest ./customer-backup/artifactgrid-manifest.json \
+  --backup-dir ./customer-backup \
+  --restore-result ./restore-drill/artifactgrid-restore-result.json \
+  --source-observation ./source-observation.json \
+  --output ./continuity-report.html
+```
+
+`--source-observation` is optional. When provided, ArtifactGrid accepts it only when it proves that the same repository and exact pinned revision were reachable at the recorded time.
+
+You can run the same clean recovery drill directly from customer-controlled R2/S3. The CLI first streams and checksum-verifies every declared object, then restores the allowlisted files into the empty destination and rechecks the restored copy:
+
+```bash
+artifactgrid restore \
+  --manifest ./continuity-manifest.json \
+  --s3-bucket customer-ai-artifacts \
+  --s3-prefix artifactgrid/production-model \
+  --s3-endpoint-url https://<account-id>.r2.cloudflarestorage.com \
+  --restore-dir ./restore-drill
+```
+
+Generate the private report directly from that same verified S3/R2 copy. Add `--restore-result ./restore-drill/artifactgrid-restore-result.json` after running the drill to include its outcome:
+
+```bash
+artifactgrid report \
+  --manifest ./continuity-manifest.json \
+  --s3-bucket customer-ai-artifacts \
+  --s3-prefix artifactgrid/production-model \
+  --s3-endpoint-url https://<account-id>.r2.cloudflarestorage.com \
+  --source-observation ./source-observation.json \
+  --output ./continuity-report.html
+```
+
+`customer_attested` means the CLI copied and immediately verified the listed files in customer-controlled storage. It is not an ArtifactGrid independently verified storage claim. A Consumer Continuity Report never asserts repository control, publisher ownership, or redistribution legality.
+
+## Commons publisher workflow
+
+The same control plane powers the web contributor workspace and the CLI. This CLI does not save a token; obtain a short-lived token from the configured production sign-in flow and supply it only through your current shell:
+
+```bash
+export ARTIFACTGRID_TOKEN='<short-lived-token>'
+
+artifactgrid publish create \
+  --slug acme-model \
+  --display-name 'Acme Model' \
+  --declared-license apache-2.0 \
+  --origin source_mirror \
+  --source-url https://huggingface.co/acme/model \
+  --revision <full-40-character-commit>
+
+artifactgrid publish source-challenge --draft <mirror-id>
+# Commit the returned JSON token to .artifactgrid/controller.json at that exact revision.
+artifactgrid publish verify-source --draft <mirror-id>
+
+artifactgrid publish inspect \
+  --snapshot-dir ./model \
+  --slug acme-model \
+  --origin source_mirror \
+  --source-control official_source_controller_verified \
+  --source-url https://huggingface.co/acme/model \
+  --revision <full-40-character-commit> \
+  --output ./publisher-mirror-manifest.json
+
+artifactgrid publish upload \
+  --draft <mirror-id> \
+  --manifest ./publisher-mirror-manifest.json \
+  --snapshot-dir ./model
+
+artifactgrid publish status --draft <mirror-id>
+```
+
+To propose a third-party model as a **community mirror**, use the same pinned source details but do not run a controller challenge. The resulting record truthfully says that upstream repository control is not claimed; it stays private until review decides whether it is eligible for the Commons.
+
+```bash
+artifactgrid publish create \
+  --slug community-model \
+  --display-name 'Community Model' \
+  --declared-license apache-2.0 \
+  --origin community_mirror \
+  --source-url https://huggingface.co/vendor/model \
+  --revision <full-40-character-commit>
+
+artifactgrid publish inspect \
+  --snapshot-dir ./model \
+  --slug community-model \
+  --origin community_mirror \
+  --source-control not_claimed \
+  --source-url https://huggingface.co/vendor/model \
+  --revision <full-40-character-commit> \
+  --output ./publisher-mirror-manifest.json
+```
+
+For original work, use `--origin original_creator_submission` and `--source-control not_applicable`, without a third-party source URL or revision. It is intentionally labeled as an original-creator submission, not as repository-controller verified.
+
+`publish upload` obtains only short-lived per-file R2 PUT URLs from ArtifactGrid, streams the declared files to its private staging prefix, and then submits the staging inventory for review. A completed upload becomes `review_required`; it is never automatically public.
+
+Configured reviewers use the same short-lived-token mechanism for the explicit two-step decision and publication action:
+
+```bash
+artifactgrid review decision --case <review-case-id> --decision approved
+artifactgrid review publish --mirror <mirror-id>
+```
+
+`review publish` copies an approved staged version server-side into the versioned public Commons prefix and writes its public manifest. Restricting or rejecting a review case never creates a public model page.

mirrorcommons-0.1.0/README.md

@@ -0,0 +1,200 @@
+# ArtifactGrid CLI
+
+`mirrorcommons` is the public-facing command alias for this package; `artifactgrid` remains available for continuity-report compatibility. The same CLI powers Mirror Commons publisher submissions and ArtifactGrid private continuity reports.
+
+This local-first CLI creates a private Consumer Continuity Report for a third-party public Hugging Face dependency. It can download an exact pinned revision or validate a snapshot you already hold. ArtifactGrid does not receive cloud credentials or host model weights.
+
+Supported V1 files are `.safetensors`, `.json`, `.md`, `.txt`, and `.model`, plus a root `LICENSE` file. If a root `LICENSE`, `LICENSE.md`, or `LICENSE.txt` is present, the manifest records its path and SHA-256 as a factual observation. This is not a legal review. Symlinks and unsupported formats are deliberately skipped; ArtifactGrid never loads model code or unsafe serialized formats.
+
+## Run locally
+
+```bash
+cd cli
+python3 -m pip install -e .
+artifactgrid inspect \
+  --source-url https://huggingface.co/owner/repository \
+  --revision <full-40-character-commit> \
+  --download
+```
+
+For a public Mirror Commons submission, use the identical command with the `mirrorcommons` alias:
+
+```bash
+mirrorcommons publish create --help
+```
+
+The local workflow needs no cloud-storage package. Install the optional S3 support only when using S3 or R2:
+
+```bash
+python3 -m pip install -e '.[s3]'
+```
+
+Use `--snapshot-dir ./snapshot` instead of `--download` when the customer has already retrieved the pinned snapshot.
+
+With `--download`, ArtifactGrid materializes ordinary files in a temporary directory so Hugging Face cache symlinks and local `.cache` metadata cannot enter the manifest. The CLI removes that temporary directory after `inspect` or `protect` finishes.
+
+Record whether the upstream public source currently resolves to the exact pinned commit. This uses Hugging Face's public API without a user token and does not download model weights:
+
+```bash
+artifactgrid source-check \
+  --source-url https://huggingface.co/owner/repository \
+  --revision <full-40-character-commit> \
+  --output ./source-observation.json
+```
+
+Create a customer-attested backup in a directory the customer controls:
+
+```bash
+artifactgrid protect \
+  --source-url https://huggingface.co/owner/repository \
+  --revision <full-40-character-commit> \
+  --download \
+  --backup-dir ./customer-backup \
+  --output ./continuity-manifest.json
+```
+
+`--output` is optional. It writes a portable copy of the same manifest kept with the customer backup.
+
+Or copy directly into customer-controlled R2/S3. The CLI uses the customer's standard local AWS credential chain or environment variables and never sends them to ArtifactGrid:
+
+```bash
+artifactgrid protect \
+  --source-url https://huggingface.co/owner/repository \
+  --revision <full-40-character-commit> \
+  --snapshot-dir ./snapshot \
+  --s3-bucket customer-ai-artifacts \
+  --s3-prefix artifactgrid/production-model \
+  --s3-endpoint-url https://<account-id>.r2.cloudflarestorage.com \
+  --output ./continuity-manifest.json
+```
+
+Verify a recovery copy:
+
+```bash
+artifactgrid verify \
+  --manifest ./customer-backup/artifactgrid-manifest.json \
+  --backup-dir ./customer-backup
+```
+
+With scoped read access, verify every protected S3/R2 object directly:
+
+```bash
+artifactgrid verify \
+  --manifest ./continuity-manifest.json \
+  --s3-bucket customer-ai-artifacts \
+  --s3-prefix artifactgrid/production-model \
+  --s3-endpoint-url https://<account-id>.r2.cloudflarestorage.com
+```
+
+Run a clean restore drill into an empty directory, then produce a private portable report:
+
+```bash
+artifactgrid restore \
+  --manifest ./customer-backup/artifactgrid-manifest.json \
+  --backup-dir ./customer-backup \
+  --restore-dir ./restore-drill
+
+artifactgrid report \
+  --manifest ./customer-backup/artifactgrid-manifest.json \
+  --backup-dir ./customer-backup \
+  --restore-result ./restore-drill/artifactgrid-restore-result.json \
+  --source-observation ./source-observation.json \
+  --output ./continuity-report.html
+```
+
+`--source-observation` is optional. When provided, ArtifactGrid accepts it only when it proves that the same repository and exact pinned revision were reachable at the recorded time.
+
+You can run the same clean recovery drill directly from customer-controlled R2/S3. The CLI first streams and checksum-verifies every declared object, then restores the allowlisted files into the empty destination and rechecks the restored copy:
+
+```bash
+artifactgrid restore \
+  --manifest ./continuity-manifest.json \
+  --s3-bucket customer-ai-artifacts \
+  --s3-prefix artifactgrid/production-model \
+  --s3-endpoint-url https://<account-id>.r2.cloudflarestorage.com \
+  --restore-dir ./restore-drill
+```
+
+Generate the private report directly from that same verified S3/R2 copy. Add `--restore-result ./restore-drill/artifactgrid-restore-result.json` after running the drill to include its outcome:
+
+```bash
+artifactgrid report \
+  --manifest ./continuity-manifest.json \
+  --s3-bucket customer-ai-artifacts \
+  --s3-prefix artifactgrid/production-model \
+  --s3-endpoint-url https://<account-id>.r2.cloudflarestorage.com \
+  --source-observation ./source-observation.json \
+  --output ./continuity-report.html
+```
+
+`customer_attested` means the CLI copied and immediately verified the listed files in customer-controlled storage. It is not an ArtifactGrid independently verified storage claim. A Consumer Continuity Report never asserts repository control, publisher ownership, or redistribution legality.
+
+## Commons publisher workflow
+
+The same control plane powers the web contributor workspace and the CLI. This CLI does not save a token; obtain a short-lived token from the configured production sign-in flow and supply it only through your current shell:
+
+```bash
+export ARTIFACTGRID_TOKEN='<short-lived-token>'
+
+artifactgrid publish create \
+  --slug acme-model \
+  --display-name 'Acme Model' \
+  --declared-license apache-2.0 \
+  --origin source_mirror \
+  --source-url https://huggingface.co/acme/model \
+  --revision <full-40-character-commit>
+
+artifactgrid publish source-challenge --draft <mirror-id>
+# Commit the returned JSON token to .artifactgrid/controller.json at that exact revision.
+artifactgrid publish verify-source --draft <mirror-id>
+
+artifactgrid publish inspect \
+  --snapshot-dir ./model \
+  --slug acme-model \
+  --origin source_mirror \
+  --source-control official_source_controller_verified \
+  --source-url https://huggingface.co/acme/model \
+  --revision <full-40-character-commit> \
+  --output ./publisher-mirror-manifest.json
+
+artifactgrid publish upload \
+  --draft <mirror-id> \
+  --manifest ./publisher-mirror-manifest.json \
+  --snapshot-dir ./model
+
+artifactgrid publish status --draft <mirror-id>
+```
+
+To propose a third-party model as a **community mirror**, use the same pinned source details but do not run a controller challenge. The resulting record truthfully says that upstream repository control is not claimed; it stays private until review decides whether it is eligible for the Commons.
+
+```bash
+artifactgrid publish create \
+  --slug community-model \
+  --display-name 'Community Model' \
+  --declared-license apache-2.0 \
+  --origin community_mirror \
+  --source-url https://huggingface.co/vendor/model \
+  --revision <full-40-character-commit>
+
+artifactgrid publish inspect \
+  --snapshot-dir ./model \
+  --slug community-model \
+  --origin community_mirror \
+  --source-control not_claimed \
+  --source-url https://huggingface.co/vendor/model \
+  --revision <full-40-character-commit> \
+  --output ./publisher-mirror-manifest.json
+```
+
+For original work, use `--origin original_creator_submission` and `--source-control not_applicable`, without a third-party source URL or revision. It is intentionally labeled as an original-creator submission, not as repository-controller verified.
+
+`publish upload` obtains only short-lived per-file R2 PUT URLs from ArtifactGrid, streams the declared files to its private staging prefix, and then submits the staging inventory for review. A completed upload becomes `review_required`; it is never automatically public.
+
+Configured reviewers use the same short-lived-token mechanism for the explicit two-step decision and publication action:
+
+```bash
+artifactgrid review decision --case <review-case-id> --decision approved
+artifactgrid review publish --mirror <mirror-id>
+```
+
+`review publish` copies an approved staged version server-side into the versioned public Commons prefix and writes its public manifest. Restricting or rejecting a review case never creates a public model page.

mirrorcommons-0.1.0/artifactgrid/__init__.py

@@ -0,0 +1,3 @@
+"""ArtifactGrid continuity manifest tools."""
+
+__version__ = "0.1.0"