Metadata-Version: 2.4
Name: refgenie
Version: 1.0.0a2
Summary: Reference genome asset manager
Keywords: bioinformatics,genomics,reference genome,genome assembly,sequence collections,seqcol,refget,GA4GH,asset management,reproducibility
Author: Nathan Sheffield, Vince Reuter, Michal Stolarczyk
License-Expression: BSD-2-Clause
License-File: LICENSE.txt
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Archiving :: Packaging
Requires-Dist: alembic>=1.20.1
Requires-Dist: cryptography>=50.0.2
Requires-Dist: gtars>=0.11.2
Requires-Dist: httpx2>=2.16.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: piper>=0.15.1
Requires-Dist: psycopg>=3.3.8
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: refget>=0.13.0
Requires-Dist: rich>=15.0.0
Requires-Dist: sqlmodel>=0.0.48
Requires-Dist: ubiquerg>=0.9.3
Requires-Dist: yacman>=1.0.0
Requires-Dist: pydantic-settings>=2.16.2
Requires-Dist: fastapi>=0.162.2 ; extra == 'dash'
Requires-Dist: uvicorn>=0.54.0 ; extra == 'dash'
Requires-Dist: mcp[cli]>=2.3.0 ; extra == 'mcp'
Requires-Dist: refgenie[dash] ; extra == 'server'
Requires-Dist: apscheduler>=3.11.3 ; extra == 'server'
Requires-Dist: mcp[cli]>=2.3.0 ; extra == 'server'
Requires-Dist: peppy>=0.40.8 ; extra == 'snakemake'
Requires-Dist: snakemake>=9.16.3,<9.17 ; extra == 'snakemake'
Requires-Python: >=3.11
Project-URL: Homepage, https://refgenie.org
Project-URL: Repository, https://github.com/refgenie/refgenie
Project-URL: Documentation, https://docs.refgenie.org/refgenie/
Project-URL: Issues, https://github.com/refgenie/refgenie/issues
Project-URL: Changelog, https://github.com/refgenie/refgenie/blob/master/CHANGELOG.md
Provides-Extra: dash
Provides-Extra: mcp
Provides-Extra: server
Provides-Extra: snakemake
Description-Content-Type: text/markdown

# Refgenie 1.0

[![Run tests](https://github.com/refgenie/refgenie/actions/workflows/test.yaml/badge.svg)](https://github.com/refgenie/refgenie/actions/workflows/test.yaml)
[![PyPI](https://img.shields.io/pypi/v/refgenie.svg)](https://pypi.org/project/refgenie/)
[![Python versions](https://img.shields.io/pypi/pyversions/refgenie.svg)](https://pypi.org/project/refgenie/)
[![License: BSD-2-Clause](https://img.shields.io/badge/license-BSD--2--Clause-blue.svg)](https://github.com/refgenie/refgenie/blob/master/LICENSE.txt)

> ## ⚠️ This is an alpha release
>
> Refgenie 1.0 is an alpha. It works, but commands and data can still change,
> so pin the version in production pipelines (for example,
> `refgenie==1.0.0a2`). A future alpha may require you to rebuild your assets.
> Please do try it and
> [report what breaks](https://github.com/refgenie/refgenie/issues).

Refgenie is a reference genome asset manager. It organizes, builds, and serves
the reference genome files that bioinformatics workflows use, such as FASTA
files, aligner indexes, and annotations, and gives each one a stable identifier
you can resolve from a script.

## Features

- **Modular asset system**: manage different types of reference genome assets (FASTA, BWA index, etc.)
- **Content-addressed assets**: an asset's digest is derived from the files it contains
- **Seqcol genome identity**: genomes are identified by GA4GH refget sequence-collection digests
- **Database backend**: SQLite or PostgreSQL for asset metadata, with alembic migrations
- **Data channels**: register and sync asset classes and recipes from external sources
- **Server and web UI**: a REST API (with GA4GH DRS endpoints) and a local web UI
- **MCP server**: expose refgenie to LLM agents over the Model Context Protocol
- **Self-describing to agents**: every instance serves `/SKILL.md`, a capability
  doc that teaches an assistant this instance's HTTP API
- **Command-line interface**: build, seek, pull, push, and manage genome assets

## Installation

Refgenie 1.0 is a pre-release, so tell `pip` to accept it:

```bash
pip install "refgenie>=1.0.0a2"
```

Without the version, `pip install refgenie` installs the legacy 0.13 release.

### Optional extras

The base install gives you the CLI and the Python API. Everything else is an
extra:

| Extra | Install | What it enables | Adds |
| --- | --- | --- | --- |
| *(none)* | `pip install "refgenie>=1.0.0a2"` | CLI, Python API, building, pulling, staging | — |
| `dash` | `pip install "refgenie[dash]>=1.0.0a2"` | `refgenie dash`, the local web UI | fastapi, uvicorn |
| `server` | `pip install "refgenie[server]>=1.0.0a2"` | `refgenie serve`, the public REST API + DRS + `/mcp` endpoint (includes `dash` and `mcp`) | apscheduler, mcp |
| `mcp` | `pip install "refgenie[mcp]>=1.0.0a2"` | `refgenie-mcp`, the stdio MCP server for LLM agents | mcp |
| `snakemake` | `pip install "refgenie[snakemake]>=1.0.0a2"` | snakemake-based bulk asset building | snakemake, peppy |

Running `refgenie serve`, `refgenie dash`, or `refgenie-mcp` without its extra
prints which extra to install. PostgreSQL support is included in the base
install.

## Quick Start

```bash
pip install "refgenie>=1.0.0a2"
refgenie init                                # create the database; subscribe to api.refgenie.org
refgenie pull hg38/fasta_index               # about 12 KB: hg38's .fai and chrom sizes
refgenie seek hg38/fasta_index.chrom_sizes   # print the local path
```

`refgenie listr` lists everything you can pull, and `refgenie seek` gives your
pipelines a path that works on any machine.

### Build assets for your own genome

Building needs recipes from a data channel:

```bash
refgenie data-channel add refgenie https https://refgenie.github.io/refgenie-registry/index.yaml
refgenie data-channel sync refgenie --exists-ok
refgenie genome init --fasta genome.fa.gz --name genome_name   # also builds its fasta asset
refgenie build genome_name/bowtie2_index                       # needs bowtie2 installed
refgenie seek genome_name/fasta
```

`refgenie list` then prints something like:

```
                      Refgenie assets. Source: local
┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Aliases     ┃ Genome digest                    ┃ Asset group ┃ Asset   ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━┩
│ genome_name │ jthDpfNIgzM5AGJlOkRtfnky4rXMBIUP │ fasta       │ default │
└─────────────┴──────────────────────────────────┴─────────────┴─────────┘
```

## Environment variables

All are optional. Refgenie uses defaults under `~/.refgenie/` when they are unset.

| Variable | Default | Purpose |
| --- | --- | --- |
| `REFGENIE_HOME_PATH` | `~/.refgenie` | Root directory for refgenie files. Auto-created at first import. |
| `REFGENIE_DB_CONFIG_PATH` | `$REFGENIE_HOME_PATH/refgenie_db_config.yaml` | Path to the database connection YAML. |
| `REFGENIE_GENOME_FOLDER` | `$REFGENIE_HOME_PATH/genomes` | Where built asset files live. Auto-created on `refgenie init`. |
| `REFGENIE_GENOME_STAGE_FOLDER` | `$REFGENIE_HOME_PATH/archives` | Where staged/archived assets live before push. Auto-created on `refgenie init`. |
| `REFGENIE_SUBSCRIBE_DEFAULT_SERVER` | `true` | Whether `refgenie init` subscribes a new configuration to `https://api.refgenie.org`. |
| `REFGENIE_BRIDGE_MODE` | `read` | Localhost bridge policy for `refgenie dash`. `off` = no cross-origin access; `read` = allowlisted public origins may read `/ping`, `/v4`, `/v1/jobs`; `full` = additionally allows `POST /v1/actions/pull`. `refgenie dash --bridge` overrides it for one run. |
| `REFGENIE_BRIDGE_ORIGINS` | `https://refgenie.org` | Comma-separated exact origins the bridge admits. **Replaces** the default rather than appending. |
| `REFGENIE_BRIDGE_ORIGIN_REGEX` | unset | Origin regex, for SPA dev servers and preview deployments only. Wildcard-equivalent patterns are refused at startup. |
| `REFGENIE_BRIDGE_EXPOSE_PATHS` | `false` | Whether `/ping` may report the genome folder path. Off by default: a home-directory path leaks the OS username to every allowlisted origin. |
| `REFGENIE_WEB_DIST` | unset | Override the built web UI directory. Default is the packaged `refgenie/server/webui/`. |
| `REFGENIE_LOG_LEVEL` | `WARNING` | Python logging level. |
| `REFGENIE_ENCRYPTION_KEY` | (auto-generated, dev only) | Fernet key for encrypting credentials. **Set explicitly in production.** |
| `REFGENIE_DISABLE_PLUGINS` | unset | `1`/`true`/`all` turns off every plugin; a comma-separated list of plugin names turns off those. Wins over everything else. |
| `REFGENIE_SERVER_PLUGINS` | `false` | Run plugins in server mode (`refgenie serve`). Off by default; local mode and `refgenie dash` always run them. |
| `REFGENIE_CONTAINER_ENGINE` | `auto` | What runs a recipe's container image: `docker`, `apptainer`, or `auto` (Docker when its daemon answers, else Apptainer). |
| `REFGENIE_APPTAINER_CACHEDIR` | unset | Passed to Apptainer as `APPTAINER_CACHEDIR`, so image pulls land there instead of under `$HOME`. |

Upgrading from refgenie 0.x? See the [upgrade guide](https://docs.refgenie.org/refgenie/upgrade/).

## Usage

For a complete list of commands:

```bash
refgenie --help
```

Longer walkthroughs:

- [Documentation](https://docs.refgenie.org/refgenie/)
- [CLI reference](https://docs.refgenie.org/refgenie/refgenie-cli/)
- [Python tutorial](https://docs.refgenie.org/refgenie/refgenie_object/)

## Data Channels

Refgenie ships with no recipes or asset classes. A **data channel** is an index
of them that you register and sync; the canonical one is published by
[refgenie-registry](https://github.com/refgenie/refgenie-registry).

You need a data channel to *build* assets. To *pull* assets, `refgenie pull`
gets each asset's class from the server it pulls from.

```bash
# Add a data channel: <name> <type> <index url>
refgenie data-channel add refgenie https https://refgenie.github.io/refgenie-registry/index.yaml

# Sync its asset classes and recipes into your local database
refgenie data-channel sync refgenie --exists-ok

# See what you have
refgenie recipe list
refgenie asset-class list
```

> Recipes contain commands, and building an asset runs them. Only sync channels
> you trust.

## Server, dashboard, and MCP

```bash
# Local web UI (needs the 'dash' extra)
refgenie dash

# Public REST API, including GA4GH DRS endpoints and an /mcp endpoint
# (needs the 'server' extra)
refgenie serve --port 8000

# stdio MCP server for LLM agents (needs the 'mcp' or 'server' extra)
refgenie-mcp
```

With the server running, interactive API docs are at `/docs` and the OpenAPI
document is at `/openapi.json`. `/SKILL.md` is the same API written for an AI
assistant; both modes serve it. `refgenie serve` also serves an HTTP MCP
endpoint (Streamable HTTP transport) at `/mcp`.

`refgenie dash` and `refgenie serve` are the same application in two modes: the
same JSON API under `/v4`, the same web UI, and a local-only command surface
under `/v1` that only the dash has. The UI asks `/service-info` which mode it is
talking to and shows only what that mode can do. `refgenie dash` binds
`127.0.0.1` only; use `refgenie serve` for anything reachable over a network.

A wheel ships the built web UI. In a source checkout, build it once with
`npm --prefix frontend run build`. Until then the API works and `/` explains
what to run.

## Development

This project uses [uv](https://github.com/astral-sh/uv) for package management and [Task](https://taskfile.dev/) for development tasks. See [docs/refgenie/development.md](https://github.com/refgenie/refgenie/blob/master/docs/refgenie/development.md) for the full developer quickstart.

```bash
# Clone and install
git clone https://github.com/refgenie/refgenie.git
cd refgenie
uv sync

# Run tests
task test

# Format code
task reformat

# Run refgenie CLI
uv run refgenie <command>
```

## Contributing

Contributions are welcome. Please read
[CONTRIBUTING.md](https://github.com/refgenie/refgenie/blob/master/CONTRIBUTING.md)
for branch conventions, what a reviewable pull request looks like, and how to
run both test suites, and
[docs/refgenie/development.md](https://github.com/refgenie/refgenie/blob/master/docs/refgenie/development.md)
for the environment setup.

## License

Refgenie is released under the BSD 2-Clause License. See
[LICENSE.txt](https://github.com/refgenie/refgenie/blob/master/LICENSE.txt).

## Links

- [Source code](https://github.com/refgenie/refgenie)
- [Issue tracker](https://github.com/refgenie/refgenie/issues)
- [Changelog](https://github.com/refgenie/refgenie/blob/master/CHANGELOG.md)
- [Documentation](https://docs.refgenie.org/refgenie/)
- [Data channel registry](https://github.com/refgenie/refgenie-registry)
- [Upgrade guide](https://docs.refgenie.org/refgenie/upgrade/) (for refgenie 0.x users)