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
Meta

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.

Skills only: copy the folder(s) you need from 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:

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

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:

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):

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.

Worked example: tutorial — 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 ecosystem: curated Croissant → typed Python graph projects, with metadata version control.

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 and the command overview.

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.