Metadata-Version: 2.5
Name: biotope
Version: 0.9.0
Summary: CLI integration for BioCypher ecosystem packages
Project-URL: Homepage, https://github.com/biocypher/biotope
Project-URL: Source Code, https://github.com/biocypher/biotope
Project-URL: Bug Tracker, https://github.com/biocypher/biotope/issues
Project-URL: Documentation, https://biocypher.org
Project-URL: Download, https://pypi.org/project/biotope/#files
Author-email: Sebastian Lobentanzer <sebastian.lobentanzer@gmail.com>, Vladislav Samoilov <vladislav.samoilov@gmail.com>
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: <3.13,>=3.10
Requires-Dist: click>=8.1.8
Requires-Dist: croissant-baker<1,>=0.5
Requires-Dist: mlcroissant<2,>=1.0.13
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.32.0
Requires-Dist: rich>=13.9.4
Provides-Extra: dev
Requires-Dist: mike>=2.1.3; extra == 'dev'
Requires-Dist: mkdocs-material>=9.6.20; extra == 'dev'
Requires-Dist: mkdocstrings-python>=1.16.10; extra == 'dev'
Requires-Dist: pre-commit>=4.1.0; extra == 'dev'
Requires-Dist: pytest<9.0.0,>=8.3.5; extra == 'dev'
Provides-Extra: graph
Requires-Dist: biocypher<0.18,>=0.17; extra == 'graph'
Requires-Dist: pyright<2,>=1.1.400; extra == 'graph'
Description-Content-Type: text/markdown

# biotope

Describe local data with croissant-baker, define a purpose and target schema, and maintain typed Python mappings and project-owned graph pipelines with version-controlled metadata. Biotope validates selected builds and writes BioCypher files. **Best used with a coding agent:** install the plugin, describe what you want the graph to answer, and let the agent run the pipeline.

|         |                                                                                                                                                                                                                                                                                                                                              |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Package | [![Latest PyPI Version](https://img.shields.io/pypi/v/biotope.svg)](https://pypi.org/project/biotope/) [![Python](https://img.shields.io/pypi/pyversions/biotope.svg)](https://pypi.org/project/biotope/) [![Docs](https://github.com/biocypher/biotope/actions/workflows/docs_mkdocs.yaml/badge.svg)](https://biocypher.github.io/biotope/) |
| Meta    | [![Apache 2.0](https://img.shields.io/pypi/l/biotope.svg)](LICENSE) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)                                                                                                         |

> **Pre-alpha.** CLI flags and APIs will change. The plugin skills are the most stable onboarding path.

## Install the plugin

Pick your agent harness. All paths use this repo: [github.com/biocypher/biotope](https://github.com/biocypher/biotope).

| Harness         | Setup                                                                                                                                    |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Claude Code** | `/plugin marketplace add biocypher/biotope` then `/plugin install biotope@biotope`                                                       |
| **Cursor**      | [Add a team marketplace](https://cursor.com/docs/plugins#add-a-team-marketplace) → import `biocypher/biotope`                            |
| **Codex**       | [Add a marketplace from the CLI](https://developers.openai.com/codex/plugins/build#add-a-marketplace-from-the-cli) pointing at this repo |

**Skills only:** copy the folder(s) you need from [`skills/`](skills/) into your project — e.g. `.cursor/skills/`, `.claude/skills/`. Start with `biotope-croissant`; add `biocypher` for a standalone BioCypher project.

## Use it

The plugin ships two skills:

| Skill                 | Use when                                                              |
| --------------------- | --------------------------------------------------------------------- |
| **biotope-croissant** | Curated sources, Python mappings and selected BioCypher file builds   |
| **biocypher**         | A standalone BioCypher project: adapters, schema config, Neo4j import |

You do not need to learn the CLI first. In chat, invoke a skill (e.g. `/biotope-croissant`) or just ask:

> *What does biotope do? I want to build a graph from my data.*

The agent reads the skill contract and runs `biotope` commands for you.

**Reference:** [biocypher.github.io/biotope](https://biocypher.github.io/biotope/)

## CLI (manual / scripting)

If you prefer the terminal or need CI, install the package in your environment.
For this unreleased integration, use both local checkouts in the same environment:

```bash
uv venv .venv
uv pip install --python .venv/bin/python -e ../croissant-baker -e '.[graph]'
source .venv/bin/activate
```

Published-release installation options (the updated baker release is still required):

```bash
uvx biotope init my-kg    # no install — ephemeral venv for scaffolding
pipx install biotope      # global install
uv add biotope              # inside a uv-managed project
```

Graph authoring starts with `biotope graph scaffold`, which creates `graph/`.
Initialization and baking do not create or execute a graph.

Typical flow: `init` → `add` → `graph scaffold` → `source generate` → Python authoring → `graph check` → `graph build`. Use `graph metagraph` to view topology independently, or `graph quality` to execute and assess without export. Command overview: [docs/commands.md](docs/commands.md).

**Worked example:** [tutorial](docs/tutorial.md) — one Croissant description, one source package per record set, joined with typed mappings, provenance and BioCypher output.

## For developers

biotope is a CLI for the [BioCypher](https://biocypher.org/) ecosystem: curated Croissant → typed Python graph projects, with metadata version control.

| Layer           | Module                | Role                                                                         |
| --------------- | --------------------- | ---------------------------------------------------------------------------- |
| Project & VCS   | `biotope.commands.*`  | `init`, `add`, `commit`, `status`, `log`, `push`, `pull` — metadata workflow |
| Source metadata | `biotope.croissant.*` | Metadata models and payload-free inspection                                  |

Agent contract lives in `skills/` (not `AGENTS.md`). `biotope.graph` exposes the typed contracts; CLI verbs wrap generation, checking and explicit execution. See [how biotope works](https://biocypher.github.io/biotope/architecture/) and the [command overview](https://biocypher.github.io/biotope/commands/).

```bash
uv sync --extra dev --extra graph
node --version
uv run python -m pyright --version
uv run pyright
uv run pytest
uv run ruff check biotope tests
```

Typed authoring, topology organization and modular construction were informed by Paul Ka Po To's `kg-build-system`. This implementation uses ordinary Python and does not copy, vendor or depend on that engine.

## Copyright

Copyright © 2025–2026 BioCypher Team. [Apache 2.0](./LICENSE).
