Metadata-Version: 2.5
Name: modelspec-dev
Version: 0.1.1
Summary: A sourced model decision engine with an offline command-line interface
Project-URL: Homepage, https://modelspec.dev
Project-URL: Repository, https://github.com/turbobeest/modelspec
Project-URL: Documentation, https://github.com/turbobeest/modelspec/tree/main/docs
License-Expression: MIT
License-File: LICENSE
License-File: LICENSE-DATA
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: cryptography<46,>=43
Requires-Dist: falkordb>=1.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: jsonschema[format]>=4.23; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-xdist==3.8.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: researcher
Requires-Dist: anthropic>=0.39; extra == 'researcher'
Requires-Dist: beautifulsoup4>=4.12; extra == 'researcher'
Requires-Dist: celery>=5.4; extra == 'researcher'
Description-Content-Type: text/markdown

<p align="center">
<img width="2816" height="797" alt="modelspec" src="https://github.com/user-attachments/assets/1e344d67-605d-4577-8ea4-84148d5ae3d5" />
</p>

ModelSpec catalogs AI models as YAML+Markdown cards, exports them to versioned JSON on Cloudflare Pages ([modelspec.dev](https://modelspec.dev)), and ranks from that export — in the browser, or offline from a local snapshot. **No database is on the serving path.**

- Site: [modelspec.dev](https://modelspec.dev) · [decide](https://modelspec.dev/decide/) · [graph](https://modelspec.dev/graph/)
- CLI contract: [`docs/cli-contract.md`](docs/cli-contract.md)
- Current state: [`docs/handoff/current.md`](docs/handoff/current.md)
- Agent entry: [`AGENTS.md`](AGENTS.md)

## Quick start

```bash
pipx install modelspec-dev
modelspec snapshot fetch
modelspec offline rank coding --json
```

`snapshot fetch` is the only networked command. After that, rank and fit read the cache.

The supported interface is [`docs/cli-contract.md`](docs/cli-contract.md):

```
modelspec snapshot fetch [--origin URL]
modelspec snapshot status [--json]
modelspec offline rank <use-case> [...]
modelspec offline fit [<hardware-id>]
```

Graph commands (`stats`, `search`, `info`, `compare`, `rank`, `hardware`, …) need a local FalkorDB and are outside this contract.

## Serving path

```
models/*.md ──▶ pipeline/build.py ──▶ static JSON on Cloudflare Pages
                                      (modelspec.dev /api/*.json)
                                            │
CLI `snapshot fetch` ───────────────────────┘
Wizard / 3D graph read the same JSON in the browser.
```

FalkorDB is optional local graph exploration only. It is not required to rank, fit, or render the sites.

## Contribute

Read [`CONTRIBUTING.md`](CONTRIBUTING.md). Sign off commits (`git commit -s`) to certify the [`DCO`](DCO) — not a copyright assignment. Every fact carries a source and the date it was read; unknown means an empty field.

Cards live in `models/{provider}/{model-slug}.md`. Edit and open a PR.

## License

Two licences, because the code and the corpus want different things.

| Part | Licence |
| --- | --- |
| Code (everything outside the data directories) | MIT |
| Data (`models/`, `benchmarks/`, `hardware/`, `hosts/`) | CC BY-SA 4.0 |

The corpus is share-alike: build on it, including commercially, but if you redistribute it or a derivative, credit ModelSpec and publish yours under the same terms. The code is permissive so the CLI can go anywhere. Full text in [`LICENSE`](LICENSE) and [`LICENSE-DATA`](LICENSE-DATA).

Every card and page records the sources it draws on and the date each was read. Those sources keep their own licences.
