Metadata-Version: 2.5
Name: modeleum
Version: 0.2.23
Summary: The place for models — a Universal Model Standard registry and proxy
Project-URL: Homepage, https://modeleum.co
Project-URL: Repository, https://github.com/principean/Modeleum
Author: Bruno Sousa
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ai,models,registry,ums,universal-model-standard
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Archiving :: Mirroring
Requires-Python: >=3.11
Requires-Dist: anyio==4.14.2
Requires-Dist: certifi==2026.7.22
Requires-Dist: click==8.4.2
Requires-Dist: h11==0.16.0
Requires-Dist: httpcore==1.0.9
Requires-Dist: httpx==0.28.1
Requires-Dist: idna==3.18
Requires-Dist: pydantic-core==2.46.4
Requires-Dist: pydantic==2.13.4
Requires-Dist: typing-extensions==4.16.0
Provides-Extra: server
Requires-Dist: fastapi==0.136.1; extra == 'server'
Requires-Dist: starlette==1.6.0; extra == 'server'
Requires-Dist: uvicorn==0.47.0; extra == 'server'
Provides-Extra: test
Requires-Dist: fastapi==0.136.1; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Requires-Dist: starlette==1.6.0; extra == 'test'
Requires-Dist: uvicorn==0.47.0; extra == 'test'
Description-Content-Type: text/markdown

# Modeleum — the place for models

Modeleum is a definitive online registry of AI models, built on the
[Universal Model Standard](https://modeleum.co/standard) that the Principeum
ecosystem is defining. It records what a model *is* as a set of immutable, linked,
content-addressed facts, and it serves those facts to Principeum applications such
as Geminal and Agenteum through one vendor-neutral contract.

Modeleum exists so that the record of what models exist, and the bytes behind
them, do not depend on any one company staying in business or staying open. It
is not commercial. The record is meant to be available to everyone.

The beta is the registry for open models: open licences, ungated, bytes held
for anyone. Models under other terms stay where their publishers put them.

Modeleum is an independent registry and cache. It is not affiliated with,
endorsed by, or sponsored by Hugging Face, Inc. or any model publisher; model
names and licences are those of their publishers.

Modeleum begins as a **proxy**. Holding every model's weights is not a starting
position anyone can afford, so Modeleum holds UMS documents for everything it
knows about and holds bytes only for what people actually pull. The first request for
an artifact is served as the bytes arrive and a copy is kept if it verifies, so
every request after it is served locally. Nothing is held that nobody asked for,
nothing is fetched twice, and storage grows with usage rather than with the
size of the catalogue.

## What it does today

- **Registry.** Immutable put/get of all six UMS document kinds, addressable by
  document ID and by the RFC 8785 canonical digest of the payload. Withdrawal is
  a projection over retained history, not a delete.
- **Import.** Resolves a Hugging Face repository revision into a `ModelDescriptor`,
  one `ArtifactManifest` per serialisation format, and — only where the source
  task maps to an exact signature — a `CapabilityManifest`.
- **Bulk import.** Discovers repositories by author, search, task, or library and
  imports them as a durable background job with progress and cancellation. One
  bad repository is counted and named, never fatal to the run.
- **Catalogue search.** Text, filters, facets, and cursor pagination over every
  model the registry knows.
- **Capability negotiation.** Finds capabilities by exact typed signature and
  returns routes pinned to the digest of every document the decision used.
- **Byte proxy.** Serves artifact bytes by digest, counts demand, and mirrors what
  demand justifies. Mirrored bytes are verified against their descriptor before
  anything is stored or served.

Modeleum states **UMS conformance level 5, Offering**. It deliberately does not
claim level 6: it stores and reports qualification evidence and applies a
caller-supplied policy filter, but it does not verify attestation envelopes, so it
never presents a report as authenticated. See
[`src/modeleum/conformance.py`](src/modeleum/conformance.py).

## Quick start

```bash
python -m venv .venv && . .venv/bin/activate && pip install -e '.[server]'
```

The base install gives the UMS types, the registry, the client, and the CLI. The
`server` extra adds the HTTP service — a consumer that only wants to talk to a
Modeleum instance does not need to install a web server to do it.

Reads are public; writes need a key. Mint one first:

```bash
modeleum keys create --name laptop --scope write
```

Populate a catalogue, then browse it:

```bash
modeleum bulk-import --author sentence-transformers --limit 25
```

```bash
modeleum browse --operation compare --format safetensors
```

Import one model and ask what it can do:

```bash
modeleum import sentence-transformers/all-MiniLM-L6-v2
```

```bash
modeleum negotiate --operation compare --input text --input text --output score_set
```

Or run the whole thing as one container, the way it will be hosted:

```bash
docker compose up
```

That builds the site, installs the service, and serves both on port 8000 with
the registry on a named volume. Put a Hugging Face token in `.env` first if you
have one. Without Docker, run the service with the browse interface, on one
port:

```bash
cd web && npm install && npm run build && cd .. && modeleum serve --web
```

Then open `http://127.0.0.1:8000`. Drop `--web` for the API alone. `GET /v1` returns the conformance
statement; `GET /v1/schema` returns the normative UMS schema.

## Getting a model

The user-facing commands need no local registry, only a directory:

```bash
pipx install modeleum
modeleum resolve BAAI/bge-small-en-v1.5
modeleum pull BAAI/bge-small-en-v1.5 --dest ./bge --lock
modeleum verify ./bge
modeleum install --lock ./bge/modeleum.lock --dest ./elsewhere
```

Every file lands only after its digest matches. `--lock` writes
`modeleum.lock`, which `install` reproduces byte for byte without re-resolving
a name, and `verify` re-hashes what is on disk against it. The commands talk to
`https://modeleum.co` unless `--registry` or `MODELEUM_REGISTRY` says
otherwise; repeat `--registry` to name mirrors. See
[the guide](docs/guide/records-and-bytes.md).

## One call for everything

An application that knows a model's name needs exactly one request:

```bash
curl "http://127.0.0.1:8000/v1/resolve?name=BAAI/bge-small-en-v1.5"
```

That accepts a `urn:modeleum:…` URI, `namespace/name`, or
`source:namespace/name`, each optionally with `@revision`, and returns the
descriptor, every typed capability signature, every artifact variant with file
digests, provider offerings, qualification evidence, and the revision list.

## Consuming it from Python

```python
from modeleum import ModeleumClient

with ModeleumClient("http://127.0.0.1:8000", api_key="mk_...") as modeleum:
    route = modeleum.negotiate(
        "compare", inputs=["text", "text"], outputs=["score_set"]
    ).one()
    safetensors = next(a for a in route.artifacts if a["format"] == "safetensors")
    modeleum.download_artifact_set(safetensors["digest"], "./weights")
```

Documents come back as validated UMS objects, artifact bytes are verified before
they land, and server errors arrive as the server's own exception types. See
[the clients area](docs/dev/clients/README.md).

## Verification

```bash
python -m pytest -q
```

The default suite is fully offline; the Hugging Face adapter runs against a
recorded revision. Tests marked `live` hit the real API and catch upstream shape
changes a fixture cannot:

```bash
python -m pytest -q -m live
```

Check stored bytes against their digests and rebuild every derived index:

```bash
modeleum fsck
```

## Layout

| Path | Owns |
| --- | --- |
| [`src/modeleum/ums/`](src/modeleum/ums/) | UMS 1.1 reference implementation. The standard, never Modeleum policy. |
| [`src/modeleum/canonical.py`](src/modeleum/canonical.py) | RFC 8785 canonicalisation and content addressing. |
| [`src/modeleum/registry/`](src/modeleum/registry/) | Immutable document store, derived indexes, usage and blob accounting. |
| [`src/modeleum/sources/`](src/modeleum/sources/) | Upstream adapters and the bounded, allowlisted HTTP client. |
| [`src/modeleum/proxy/`](src/modeleum/proxy/) | Capability negotiation and the artifact byte proxy. |
| [`src/modeleum/api/`](src/modeleum/api/) | FastAPI surface. |
| [`web/`](web/README.md) | The public browse interface: React, Vite, TypeScript. |

## Documentation

- [Trying the prototype](docs/prototype.md) — the end-to-end path, start to
  finish.

- [HTTP API](docs/api.md) — endpoint reference.
- [Registry and proxy profile](docs/registry-profile.md) — Modeleum's exact
  behaviour under the UMS registry/proxy profile, including what it refuses to
  claim. This is the consumer contract.
- [Universal Model Standard 1.1](https://modeleum.co/standard) — the
  specification these records follow, at `docs/universal-model-standard.md` in
  this tree and authored here as of 1.1.
- [Development documentation](docs/dev/README.md) — the per-area development
  source of truth: [architecture](docs/dev/architecture.md),
  [decision log](docs/dev/decision-log.md),
  [project decisions](docs/dev/project-decisions.md), and the
  [roadmap](docs/dev/release-quality/roadmap.md).

Agents working on this repository start at [`AGENTS.md`](AGENTS.md).

## Licensing

Apache-2.0. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).

Apache rather than MIT because Modeleum is infrastructure for an open
specification: implementers need an explicit patent grant, not silence on the
subject. It also matches every standard UMS interoperates with — OCI, SPDX,
CycloneDX, in-toto, MLflow, KServe. The reasoning is in
[the project decisions](docs/dev/project-decisions.md).

The Universal Model Standard is licensed Apache-2.0 by its authors, scoped to the
standard rather than to the application it was authored in. This repository
redistributes that copy under the same terms.
