<!-- Source: https://docs.biosimulant.com/references/library -->

# Python API reference

The supported public Python surface for the `biosimulant` runtime. Use this
section to choose the right interface, then follow the linked reference pages
for lifecycle and data-contract details.

**Info:**

  Looking for step-by-step instructions? See the [How-To Guides](/how-to) for task-oriented walkthroughs like creating a BioModule, composing simulations, and packaging models.

## Installation

```bash
pip install "biosimulant>=0.0.20"
```

The compatibility `ui` extra is still accepted but no longer required for
Local lab UI:

```bash
pip install "biosimulant @ git+https://github.com/Biosimulant/biosim.git@<ref>"
biosimulant labs serve ./my-lab
```

For curated model packs, see the companion repo: [github.com/Biosimulant/models](https://github.com/Biosimulant/models)

## Choose an interface

### Local runtime

Use the open-source runtime to build and run simulations on your machine or in
your own CI:

```python
from biosimulant import BioWorld
from biosimulant.hub import HubComposition

world = BioWorld()
composition = HubComposition(world, lab_root="./lab")
```

`BioWorld` and `BioModule` are the core local composition interface.
`HubComposition` explicitly resolves exact, lockfile-pinned Hub Labs into that
same local world; it never turns a Python import into a network request.

- [BioWorld API](/references/library/bioworld-api)
- [BioModule API](/references/library/biomodule-api)
- [HubComposition API](/references/library/hub-composition-api)

### Managed Hub API

Use `Client` or `AsyncClient` only when you intentionally want to submit an
accessible, versioned Hub Lab as a durable managed run:

```python
from biosimulant import Client

with Client() as client:
    result = client.run("owner/lab@1.0.0", inputs={})
```

Managed execution is separate from `BioWorld.run()` and requires an API key.
See the [Developer API](/developer-api) for `Client`, `AsyncClient`, durable
runs, result artifacts, errors, and webhooks.

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                       BioWorld                               │
│           (Orchestrator + Event Queue)                       │
│                                                              │
│  Events: STARTED → TICK* → FINISHED                          │
└─────────────────────────────┬───────────────────────────────┘
                              │
         ┌────────────────────┼────────────────────┐
         │                    │                    │
         ▼                    ▼                    ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   BioModule     │  │   BioModule     │  │   BioModule     │
│  (Neuron Pop)   │  │  (Monitor)      │  │  (Metabolism)   │
│                 │  │                 │  │                 │
│ in: current     │  │ in: spikes      │  │ in: params      │
│ out: spikes     │──│                 │  │ out: species    │
└─────────────────┘  └─────────────────┘  └─────────────────┘
         │                                         │
         └─────────────── BioSignals ──────────────┘
```

## API Reference

- [BioModule API](/references/library/biomodule-api): Base interface for all composable simulation components.
- [BioWorld API](/references/library/bioworld-api): Central orchestrator: lifecycle, events, scheduling.
- [WiringBuilder API](/references/library/wiring-api): Declarative composition: add modules and connect ports.
- [BioSignal & Metadata](/references/library/signals): Message passing between modules.
- [HubComposition API](/references/library/hub-composition-api): Resolve exact, lockfile-pinned Hub Labs into a local world.
- [Supported Python API surface](/references/library/python-api): Exhaustive index of supported root imports.

## Schemas

- [model.yaml Schema](/references/library/model-manifest): BioModule manifest format reference.
- [lab.yaml Schema](/references/library/lab-manifest): Composed simulation manifest format reference.

## Tools & Extensions

- [Visualization Contract](/references/library/visualization): Standard format for module visualization output.
- [Domain Packs](/references/library/domain-packs): Pre-built modules for neuroscience and ecology.
- [Labs Serve UI](/references/library/labs-serve): bundled local web UI for runnable labs.