Installation¶

Requirements¶

Python 3.11+
A running Hippo instance (v0.3.1+)
(Optional) A running Canon instance (v0.1+) for artifact resolution

Install¶

pip install cappella

For SQL adapter support (PostgreSQL, MySQL, SQLite):

pip install cappella[sql]

For development and testing:

pip install cappella[dev]

Verify Installation¶

cappella --version
cappella --help

Configure¶

Create a cappella.yaml configuration file. At minimum you need a Hippo connection:

hippo:
  url: "http://localhost:8001"
  token: "${HIPPO_TOKEN}"

See the Quick Start for a minimal working example, or the User Guide for the full configuration reference.

Run as a Service¶

cappella serve --config cappella.yaml

The REST API will be available at http://localhost:8000 by default.

Run as a CLI Tool¶

All Cappella operations are also available as CLI commands without starting a server:

cappella ingest <adapter_name> --config cappella.yaml
cappella resolve --entity-type GeneCounts --criteria "donor.diagnosis=CTE" --config cappella.yaml
cappella status --config cappella.yaml
cappella --help

Verify Connection¶

cappella status --config cappella.yaml

Expected output:

{
  "cappella_version": "0.1.0",
  "hippo": {"status": "ok", "version": "0.3.1"},
  "canon": {"status": "ok", "version": "0.2.0"},
  "adapters": {}
}