Metadata-Version: 2.4
Name: stargazer-bio
Version: 2026.10.28
Summary: Bioinformatics workflow orchestration on Flyte v2, with assets identified by their IPFS CID
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: flyte[tui]>=2.0.3
Requires-Dist: loguru>=0.7.3
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: psycopg[binary]<4,>=3.2
Requires-Dist: boto3<2,>=1.40
Requires-Dist: certifi>=2024.2.2
Provides-Extra: bio
Requires-Dist: scanpy>=1.12; extra == "bio"
Requires-Dist: anndata>=0.12.10; extra == "bio"
Requires-Dist: scikit-image>=0.26.0; extra == "bio"
Requires-Dist: igraph>=1.0.0; extra == "bio"
Requires-Dist: pooch>=1.9.0; extra == "bio"
Provides-Extra: notebook
Requires-Dist: marimo>=0.10.0; extra == "notebook"
Requires-Dist: stargazer-bio[bio]; extra == "notebook"
Provides-Extra: mcp
Requires-Dist: mcp[cli]<3,>=2.0; extra == "mcp"
Provides-Extra: docs
Requires-Dist: mkdocstrings[python]>=1.0.3; extra == "docs"
Provides-Extra: all
Requires-Dist: stargazer-bio[docs,mcp,notebook]; extra == "all"
Dynamic: license-file

<p align="center">
  <img src=".github/images/8-bit_stargazer_no-bg.jpg" alt="Stargazer" width="400">
</p>

# Stargazer

**The perpetual progress machine for computational biology**

---

Stargazer is an open-science initiative to broaden access to bioinformatics tools, foster collaboration, and align incentives in service of biomedical progress.

## Status: Alpha 🏗️
Collecting early feedback on direction and architecture. Try the quickstart!

## Quickstart

- `docker run -d -p 8080:8080 ghcr.io/stargazerbio/stargazer`
- Play around with the tutorial
- Open the terminal with <kbd>Ctrl</kbd>+<kbd>&#96;</kbd> and use claude code or opencode

Stargazer is an agent-first project - you'll need to login with your agent harness before interacting with the MCP server. Also, any other agent can pick it up if you run `uv run stargazer`. Finally, everything is just a Flyte workflow under the hood, feel free to start the container with `--entrypoint bash` and run any workflows or check out the [TUI](https://www.union.ai/docs/v2/flyte/user-guide/running-locally/#terminal-ui) from there.

Additional quickstart options and details are available in the [docs](https://docs.stargazer.bio/getting-started/).

## Why Stargazer?

Many researchers are experts in their specific niche; they have then become proficient bioinformaticians through necessity. On the other side of the spectrum, well-resourced organizations with their own bioinformatics and devops teams will each have their _specific_ way of running Nextflow pipelines on their Slurm cluster and organizing the filesystem. 

The backdrop to this fragmentation is the constant deluge of new data. Most of it is lucky to be analyzed in a meaningful way, let alone be re-analyzed in the context of new publications. While authors do their best to maintain access to the methods and data that produced their results, tools tend to go unmaintained and download links tend to grow stale. 

## Our Approach

Stargazer lowers the barrier to entry by placing an agent between the researcher and a set of proven workflows made of deeply composable tasks. The resulting executions run on declarative infrastructure against content-addressable data. Ask Stargazer to align WGS reads against GRCh38 using BWA-MEM2 and it will:

1. **Resolve the data** -- Hydrate references, indices, and read files from content-addressable storage using metadata queries instead of fragile file paths.
2. **Compose the workflow** -- Assemble the correct sequence of Flyte tasks or create new ones with strongly typed inputs/outputs, appropriate resources, and a container image with the necessary dependencies.
3. **Execute with full provenance** -- Run the workflow locally or on managed infrastructure with caching, reproducibility, and error-handling built in.
4. **Return actionable results** -- Deliver outputs to the same flexible and robust storage, to be investigated now or used at any point in the future.

## Architecture

### Interface - Chat Frontend
A familiar interface where researchers express intent. The LLM has access to a registry of Flyte tasks and workflows as well as an MCP server to interact with them. It understands their patterns, resource requirements and type signatures, allowing it to build novel modules for any requirement.

### Orchestrator - Flyte V2
[Flyte V2's](https://www.union.ai/docs/v2/flyte/user-guide/overview/) pure-Python and async-native orchestration engine does the heavy-lifting of each Stargazer execution. Everything runs in a container with task resource requirements and dependencies declared in-line. Tasks can be nested arbitrarily and executed async with standard Python patterns. Types are enforced at the task boundary and capture inputs and outputs with all necessary metadata.

### Storage - Content-Addressed Assets
Every file in Stargazer is content-addressable, inspired by [IPFS](https://docs.ipfs.tech/concepts/how-ipfs-works/). They are also self-describing via key-value metadata, inspired by [Pinata](https://pinata.cloud/blog/using-file-centric-architecture-to-build-simple-and-capable-apps/). Reproducibility becomes intrinsic as data is identified by an immutable, cryptographic commitment to its content. This powerful combination also means that workflows interact with data via composable queries, not their location.

## Execution Modes
Stargazer has a few execution modes to control exactly where data is processed and stored. The default is fully local compute and storage, with your files under `~/.stargazer`. By adding a PINATA_JWT env var, you can push and pull public assets from IPFS via Pinata. 

Stargazer is also hosted on [Union](https://www.union.ai/), where you can work on notebooks, workflows, and assets from your browser.

## Perpetual progress machine?
Never before has there been a greater opportunity to converge the fragmented landscape of bioinformatics tools and techniques. Frontier models enable integrating the plurality of inputs and contributions faster and more fairly than ever before. Stargazer doesn't aim to be yet another standard, but an organic substrate that evolves and responds to the needs of discovery in real-time.

The foundational patterns of this project [predate](https://www.youtube.com/watch?v=F7UUm78iito) the agentic development era, and they are a divergence from the norm. Stargazer aims to accommodate as many computational approaches, tools, and lines-of-inquiry as possible and has therefore made every attempt to be flexible and [open](LICENSE) with an opinionated core.

Within this framework, every user naturally becomes a contributor. My hope is that anyone who derives value from Stargazer will kindly let their reasoning, workflows, and results graduate into the public domain. In doing so, they will add momentum to the flywheel of perpetual progress.

> ⚠️ AI Use Disclaimer: If you're going to take the time to README, I'm going to take the time to WRITEIT. Every word of this README was typed out by a human. Additionally, every line of code was reviewed by a human and will continue to be. However, Stargazer is an AI-native project and we intend to leverage these impressive models where they shine while relying on human oversight and expertise to guide them.
