Metadata-Version: 2.4
Name: umarise-huggingface
Version: 0.2.0
Summary: Anchor every HuggingFace upload to Bitcoin. Async, with reconciliation ledger.
Author-email: Umarise <partners@umarise.com>
License-Expression: Unlicense
Project-URL: Homepage, https://umarise.com
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: umarise-core-sdk>=1.1.0
Requires-Dist: huggingface-hub>=0.20

# umarise-huggingface

**Anchor every HuggingFace upload to Bitcoin. Automatically.**

`umarise-huggingface` intercepts `upload_file()` and `upload_folder()` to automatically compute a local SHA-256 hash and anchor it to Bitcoin via the Umarise Core API. No files are transmitted — only the hash.

## Install

```bash
pip install umarise-huggingface
export UMARISE_API_KEY=um_your_key_here
```

## Usage

### Option 1: Auto-anchor (recommended)

```python
import umarise_huggingface
from huggingface_hub import HfApi

umarise_huggingface.enable()

api = HfApi()
api.upload_file(
    path_or_fileobj="model.safetensors",
    path_in_repo="model.safetensors",
    repo_id="your-org/your-model",
)
# [umarise] ✓ Anchored your-org/your-model:model.safetensors → origin_id: abc123...
```

### Option 2: With transformers push_to_hub

```python
import umarise_huggingface
umarise_huggingface.enable()

# Works automatically with any push_to_hub call
model.push_to_hub("your-org/your-model")
tokenizer.push_to_hub("your-org/your-model")
# Each file is automatically anchored
```

### Option 3: Explicit

```python
from umarise_huggingface import anchor_file, anchor_folder

# Single file
origin_id = anchor_file("model.safetensors")

# Entire directory
results = anchor_folder("./model_output/", pattern="*.safetensors")
```

## What happens

1. You upload via HuggingFace Hub — upload proceeds normally
2. SHA-256 is computed **locally** — bytes never leave your machine
3. Hash is submitted to Umarise Core API → anchored to Bitcoin
4. `origin_id` is printed to stderr
5. Within ~2 hours, proof is confirmed on the Bitcoin blockchain

## What this proves

- ✓ This exact model/dataset existed no later than time T
- ✓ The artifact was not modified after anchoring
- ✓ Anyone can verify — no Umarise account needed

## Verify

```bash
# Get the hash of your file
shasum -a 256 model.safetensors

# Verify against Umarise
curl -s https://core.umarise.com/v1-core-verify \
  -H 'Content-Type: application/json' \
  -d '{"hash":"sha256:YOUR_HASH"}' | python3 -m json.tool
```

Or visit [verify-anchoring.org](https://verify-anchoring.org)

## Design principles

- **Never breaks your pipeline** — if anchoring fails, uploads continue normally
- **Zero storage** — only the SHA-256 hash is sent to Umarise
- **Vault-independent** — HuggingFace stores the data, Umarise stores the proof
- **Independently verifiable** — no Umarise account needed to verify

## Links

- [Umarise](https://umarise.com)
- [API Reference](https://umarise.com/api-reference)
- [Anchoring Specification](https://anchoring-spec.org)
- [umarise-wandb](https://pypi.org/project/umarise-wandb/)
- [umarise-mlflow](https://pypi.org/project/umarise-mlflow/)

## License

[Unlicense](https://unlicense.org) — public domain.
