Package Registry¶

Available since v0.9.5

The package registry subsystem lets users register pbg-<tool> packages and other process-bigraph compatible Python packages in the sms-api database. Once registered, the package’s Process and Step classes appear in the /compose/v1/processes?source=db and /compose/v1/steps?source=db endpoints, making them available alongside the core process-bigraph library’s built-in registry.

Concepts¶

Term	Meaning
Package	A pip-installable Python library containing Process or Step subclasses
Package registration	Storing a package’s metadata and compute outlines in the database
Compute outline	A description of a single Process or Step class (module, name, compute_type, inputs/outputs schema)
Audit	A dry-run check that a repo has the required `pyproject.toml`, `bigraph-schema` dependency, and `process-bigraph` dependency

Source modes¶

The /compose/v1/processes and /compose/v1/steps endpoints accept a ?source query parameter:

Source	Returns
`core`	Classes registered in the process-bigraph `core.link_registry` (in-memory)
`db`	Packages registered in the sms-api PostgreSQL database
`union` (default)	Both sources merged, deduplicated by `(module, name)`

CLI usage¶

List registered packages¶

uv run atlantis compose packages

Show a single package¶

uv run atlantis compose package-get 1

Audit a repo (dry run)¶

Check whether a local directory or GitHub URL meets package requirements:

uv run atlantis compose package-audit /path/to/pbg-tool-repo
uv run atlantis compose package-audit https://github.com/vivarium-collective/pbg-cobra

Register a package¶

Three modes:

# 1. From a local path (audits automatically)
uv run atlantis compose package-register /path/to/pbg-tool-repo

# 2. From a GitHub URL (audits automatically)
uv run atlantis compose package-register https://github.com/vivarium-collective/pbg-cobra

# 3. From an inline JSON outline (skip audit)
uv run atlantis compose package-register --from-file outline.json

The --no-audit flag skips the audit step and registers directly. The --ref flag specifies a git branch/tag/commit for URL registration.

REST API¶

Method	Endpoint	Description
`GET`	`/compose/v1/packages`	List all registered packages
`GET`	`/compose/v1/packages/{id}`	Get a single package by database ID
`POST`	`/compose/v1/packages/audit`	Dry-run audit of a repo without registering
`POST`	`/compose/v1/packages`	Register a package (repo URL, local path, or inline outline)
`GET`	`/compose/v1/processes?source=db`	List all registered processes from DB
`GET`	`/compose/v1/steps?source=db`	List all registered steps from DB

Register request format¶

{
  "kind": "repo_url",
  "url": "https://github.com/vivarium-collective/pbg-cobra",
  "ref": "main"
}

{
  "kind": "local_path",
  "path": "/path/to/pbg-tool-repo"
}

{
  "kind": "outline",
  "outline": {
    "package_type": "pypi",
    "name": "my-custom-pkg",
    "compute": [
      {
        "module": "my_pkg.processes",
        "name": "MyProcess",
        "compute_type": "process",
        "inputs": "{}",
        "outputs": "{}"
      }
    ]
  }
}

Auto-discovery from audit¶

When registering via repo_url or local_path, the system:

Clones (or resolves) the repository
Runs an audit: checks for pyproject.toml, bigraph-schema dependency, process-bigraph dependency
Scans Python source files for class X(Process) and class Y(Step) declarations
Auto-generates a compute outline from the discovered classes
Inserts the package into the database

This means any well-structured pbg-<tool> repo can be registered without manually writing a compute outline.

Duplicate detection¶

Registration is idempotent with respect to package name — if a package with the same name already exists in the database, the server returns 409 Conflict. To update a package, delete and re-register (no update-in-place endpoint yet).