Metadata-Version: 2.5
Name: viva-catalog
Version: 0.1.0
Summary: Ecosystem ledger for the vivarium / process-bigraph workbench: the registry of repos + an aggregated artifact index.
Project-URL: Homepage, https://github.com/vivarium-collective/viva-catalog
Author: Vivarium Collective
License: MIT
Keywords: marketplace,process-bigraph,vivarium,workbench
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# viva-catalog

The **ecosystem ledger** for the [vivarium](https://github.com/vivarium-collective) /
[process-bigraph](https://github.com/vivarium-collective/process-bigraph) workbench.

It answers two questions for the [vivarium-workbench](https://github.com/vivarium-collective/vivarium-workbench)
Registry, so a workbench can browse the **whole ecosystem** — not just what's
installed locally — and offer **Install to use**:

| File | What it is |
|---|---|
| [`viva_catalog/modules.json`](viva_catalog/modules.json) | The registry of ecosystem repos — `name`, `source`, `description`, `tags`. **Generated** by discovering every public `vivarium-collective` repo with the `viva-marketplace` GitHub topic. |
| [`viva_catalog/ecosystem-index.json`](viva_catalog/ecosystem-index.json) | The aggregated **artifact index** — every repo's processes / steps / composites / studies / investigations (name + description + counts). Regenerated by CI. |

Previously the registry lived in `viva_superpowers/catalog/modules.json` (the
Claude-Code plugin). It moved here so the ledger is owned by a dedicated repo.

**Adding a repo?** Just add the **`viva-marketplace` GitHub topic** to your
public repo (`gh repo edit vivarium-collective/<repo> --add-topic
viva-marketplace`) — the nightly builder discovers it, refreshes `modules.json`,
and scans its source into the index. No PR needed. See
[CONTRIBUTING.md](CONTRIBUTING.md).

## How the index is built

`scripts/build_ecosystem_index.py` reads `modules.json` and, for each repo,
**shallow-clones it and scans the source** — no published dashboard required:

- **composites** — `@composite_generator(name=…, description=…)` decorators (AST)
  + any `*.composite.yaml` files
- **processes / steps** — top-level classes whose base ends in `Process` / `Step`
  (AST), described by a `description` class attribute or the class docstring
- **studies** — `**/studies/*/study.yaml` (name + objective/title)
- **investigations** — `**/investigations/*/investigation.yaml` (name + title)

This gives complete coverage across the ecosystem whether or not a repo publishes
a workbench dashboard. Repos that can't be cloned are still listed (empty
artifacts, `cloned: false`).

```bash
python scripts/build_ecosystem_index.py            # rebuild the index locally
python scripts/build_ecosystem_index.py --only Viva-munk,pbg-copasi   # subset
```

Needs `git` + `PyYAML`.

## Consuming the ledger

**Python** (viva-superpowers, vivarium-workbench):

```python
import viva_catalog
repos = viva_catalog.load_modules()          # the repo registry
index = viva_catalog.load_ecosystem_index()  # aggregated artifacts
```

**Over HTTP** (published to gh-pages, same-origin for any published workbench):

```
https://vivarium-collective.github.io/viva-catalog/modules.json
https://vivarium-collective.github.io/viva-catalog/ecosystem-index.json
```

## CI

[`.github/workflows/build-index.yml`](.github/workflows/build-index.yml) rebuilds
`ecosystem-index.json` daily (and on `modules.json` changes), commits it to `main`,
and publishes `modules.json` + the index to `gh-pages`.
