Metadata-Version: 2.5
Name: biotope
Version: 0.10.0
Summary: Curate Croissant descriptions of local data and build typed, provenance-tracked BioCypher knowledge graphs
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.github.io/biotope/
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
Keywords: biocypher,bioinformatics,croissant,data-integration,knowledge-graph,metadata,provenance
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
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Typing :: Typed
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
Requires-Dist: tomli>=1.1; python_version < '3.11'
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

Biotope builds knowledge graphs from local data. It uses [croissant-baker](https://pypi.org/project/croissant-baker/)
to describe sources, gives every described input a typed Python source package from
the reviewed Croissant metadata, and checks project-owned loaders, mappings and graph
pipelines. Builds export [BioCypher](https://biocypher.org/) files with provenance and
a record of the run.

[![PyPI](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/)
[![Documentation](https://github.com/biocypher/biotope/actions/workflows/docs_mkdocs.yaml/badge.svg)](https://biocypher.github.io/biotope/)
[![License](https://img.shields.io/pypi/l/biotope.svg)](LICENSE)

Biotope is under active development. The 0.10 release generates a complete source
inventory, reports source drift, and retires validation checks and the query
context; see the [migration guide](docs/migration.md).

## Install

Use Python 3.10–3.12. These commands use [uv](https://docs.astral.sh/uv/getting-started/installation/)
and a POSIX shell:

```bash
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python 'biotope[graph]>=0.10,<0.11'
source .venv/bin/activate
biotope --version
```

This installs the published croissant-baker dependency automatically. Graph type
checking also needs Node.js on `PATH`; alternatively, install `pyright[nodejs]`
in this environment. See [installation](docs/installation.md) for other setups.

## Build a graph

1. Initialize a metadata project with `biotope init my-kg`, then enter `my-kg`.
1. Describe selected local data with `biotope add <path>` and review the Croissant metadata.
1. Run `biotope graph scaffold`, then give every described input a source package with
   `biotope source generate <manifest> --out graph/sources`.
1. Select or exclude each source, then define the graph's schemas, loaders, topology,
   mappings and pipeline in Python.
1. Run `biotope graph check`, then `biotope graph build`, which writes `graph/build/`.
1. Review the exported values, descriptions and provenance against the research question,
   reading the sources themselves; checks establish structure, not scientific correctness.

The scaffold's README describes its layout. The [tutorial](docs/tutorial.md)
provides a complete synthetic project you can run immediately.

- [Typed graph guide](docs/mapping.md): source curation, authoring and review.
- [Commands](docs/commands.md): metadata, graph and version-control workflows.
- [Architecture](docs/architecture.md): responsibilities and execution boundaries.
- [Published documentation](https://biocypher.github.io/biotope/).

## Use with a coding agent

The repository includes a `biotope-croissant` skill for this workflow and a
`biocypher` skill for standalone BioCypher projects. Follow the
[agent setup guide](docs/plugin.md) for Claude Code, Cursor or Codex.
Skills guide the agent; install the Python package in the project environment too.

## Contribute

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, checks and release conventions.
Report reproducible problems through [GitHub issues](https://github.com/biocypher/biotope/issues).

Typed authoring and modular topology construction were informed by Paul Ka Po To's
`kg-build-system`. Biotope does not depend on that engine.

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