biosim 0.0.1__tar.gz

biosim-0.0.1/.gitignore

@@ -0,0 +1,25 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+node_modules/
+.venv/
+dist/
+build/
+src/biosim/simui/_frontend/dist/
+
+.DS_Store
+
+# SimUI UI build outputs
+packages/simui-ui/dist-static/
+
+# Commit the built library artifacts so npm can install @biosim/simui-ui from a git SHA.
+!packages/simui-ui/dist/
+!packages/simui-ui/dist/**

biosim-0.0.1/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BioSimulant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

biosim-0.0.1/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: biosim
+Version: 0.0.1
+Summary: Core simulation library for Biosimulant
+Project-URL: Documentation, https://github.com/Biosimulant/biosim#readme
+Project-URL: Issues, https://github.com/Biosimulant/biosim/issues
+Project-URL: Source, https://github.com/Biosimulant/biosim
+Author-email: Demi <bjaiye1@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.26
+Provides-Extra: all
+Requires-Dist: fastapi<1,>=0.110; extra == 'all'
+Requires-Dist: pytest-cov>=4; extra == 'all'
+Requires-Dist: pytest>=7; extra == 'all'
+Requires-Dist: pyyaml>=6; extra == 'all'
+Requires-Dist: tomli>=2; (python_version < '3.11') and extra == 'all'
+Requires-Dist: uvicorn>=0.23; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Requires-Dist: tomli>=2; (python_version < '3.11') and extra == 'dev'
+Provides-Extra: ui
+Requires-Dist: fastapi<1,>=0.110; extra == 'ui'
+Requires-Dist: uvicorn>=0.23; extra == 'ui'
+Description-Content-Type: text/markdown
+
+# biosim
+
+[![PyPI - Version](https://img.shields.io/pypi/v/biosim.svg)](https://pypi.org/project/biosim)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/biosim.svg)](https://pypi.org/project/biosim)
+
+Composable simulation runtime + UI layer for orchestrating runnable biomodules.
+
+---
+
+## Executive Summary & System Goals
+
+### Vision
+
+Provide a small, stable composition layer for simulations: wire reusable components ("biomodules") into a `BioWorld`, run them with a single orchestration contract, and visualize/debug runs via a lightweight web UI (SimUI). Biomodules are self-contained Python packages that can wrap external simulators internally (SBML/NeuroML/CellML/etc.) without a separate adapter layer.
+
+### Core Mission
+
+- Compose simulations from reusable, interoperable biomodules.
+- Make "run + visualize + share a config" the default workflow (local-first; hosted later).
+- Keep the runtime small and predictable while letting biomodules embed their own simulator/tooling.
+
+### Primary Users
+
+- Developers and researchers who need composable simulation workflows and fast iteration.
+- Near-term beachhead: neuroscience demos (single neuron + small E/I microcircuits) with strong visuals and reproducible configs.
+
+---
+
+## Installation
+
+Preferred (pinned GitHub ref):
+
+```console
+pip install "biosim @ git+https://github.com/<org>/biosim.git@<ref>"
+```
+
+Alternative (package index):
+
+```console
+pip install biosim
+```
+
+## Publishing to PyPI
+
+This repository publishes to PyPI using GitHub Trusted Publishing.
+
+Release workflow:
+
+1. Update `src/biosim/__about__.py` with a new version (example: `0.0.2`).
+2. Commit and push the version bump to `main`.
+3. Create and push a matching tag (`v0.0.2`).
+4. Verify GitHub Actions `Publish to PyPI` finishes successfully.
+
+Manual commands:
+
+```bash
+git add src/biosim/__about__.py
+git commit -m "Bump version to 0.0.2"
+git push origin main
+git tag v0.0.2
+git push origin v0.0.2
+```
+
+Automation script:
+
+```bash
+bash scripts/release_pypi.sh
+```
+
+- This reads the version from `src/biosim/__about__.py`, requires a clean git tree, pushes `main`, then creates and pushes `v<version>`.
+- You can also pass an explicit version: `bash scripts/release_pypi.sh 0.0.2`.
+- Use `--no-push` to only create the local tag: `bash scripts/release_pypi.sh --no-push`.
+
+## Examples
+
+- See `examples/` for quick-start scripts. Try:
+
+```bash
+pip install -e .
+python examples/basic_usage.py
+```
+
+For advanced curated demos (neuro/ecology), wiring configs, and model-pack templates, see the companion repo:
+
+- https://github.com/Biosimulant/models
+
+### Quick Start: BioWorld
+
+Minimal usage:
+
+```python
+import biosim
+from biosim import BioSignal, SignalMetadata
+
+class Counter(biosim.BioModule):
+    min_dt = 0.1
+
+    def __init__(self):
+        self.value = 0
+
+    def reset(self) -> None:
+        self.value = 0
+
+    def advance_to(self, t: float) -> None:
+        self.value += 1
+
+    def get_outputs(self):
+        source = getattr(self, "_world_name", "counter")
+        return {
+            "count": BioSignal(
+                source=source,
+                name="count",
+                value=self.value,
+                time=0.0,
+                metadata=SignalMetadata(units="1", description="tick counter"),
+            )
+        }
+
+world = biosim.BioWorld()
+world.add_biomodule("counter", Counter())
+world.run(duration=1.0, tick_dt=0.1)
+```
+
+### Visuals from Modules
+
+Modules may optionally expose web-native visuals via `visualize()`, returning a dict or list of dicts with keys `render` and `data`. The world can collect them without any transport layer:
+
+```python
+class MyModule(biosim.BioModule):
+    min_dt = 0.1
+
+    def advance_to(self, t: float) -> None:
+        return
+
+    def get_outputs(self):
+        return {}
+
+    def visualize(self):
+        return {
+            "render": "timeseries",
+            "data": {"series": [{"name": "s", "points": [[0.0, 1.0]]}]},
+        }
+
+world = biosim.BioWorld()
+world.add_biomodule("module", MyModule())
+world.run(duration=0.1, tick_dt=0.1)
+print(world.collect_visuals())  # [{"module": "module", "visuals": [...]}]
+```
+
+See `examples/visuals_demo.py` for a minimal end-to-end example.
+
+## SimUI (Python-Declared UI)
+
+SimUI lets you build and launch a small web UI entirely from Python (similar to Gradio's ergonomics), backed by FastAPI and a prebuilt React SPA that renders visuals from JSON. The frontend uses Server-Sent Events (SSE) for real-time updates.
+
+- User usage (no Node/npm required):
+  - Install UI extras: `pip install -e '.[ui]'`
+  - Try the demo: `python examples/ui_demo.py` then open `http://127.0.0.1:7860/ui/`.
+  - From your own code:
+
+    ```python
+    from biosim.simui import Interface, Number, Button, EventLog, VisualsPanel
+    world = biosim.BioWorld()
+    ui = Interface(
+        world,
+        controls=[Number("duration", 10), Number("tick_dt", 0.1), Button("Run")],
+        outputs=[EventLog(), VisualsPanel()],
+    )
+    ui.launch()
+    ```
+
+  - The UI provides endpoints under `/ui/api/...`:
+    - `GET /api/spec` – UI layout (controls, outputs, modules)
+    - `POST /api/run` – Start a simulation run
+    - `GET /api/status` – Runner status (running/paused/error)
+    - `GET /api/state` – Full state (status + last step + modules)
+    - `GET /api/events` – Buffered world events (`?since_id=&limit=`)
+    - `GET /api/visuals` – Collected module visuals
+    - `GET /api/snapshot` – Full snapshot (status + visuals + events)
+    - `GET /api/stream` – SSE endpoint for real-time event streaming
+    - `POST /api/pause` – Pause running simulation
+    - `POST /api/resume` – Resume paused simulation
+    - `POST /api/reset` – Stop, reset, and clear buffers
+    - **Editor sub-API** (`/api/editor/...`): visual config editor for loading, saving, validating, and applying YAML wiring configs as node graphs. Endpoints include `modules`, `current`, `config`, `apply`, `validate`, `layout`, `to-yaml`, `from-yaml`, and `files`.
+
+Per-run resets for clean visuals
+- On each `Run`, the backend clears its event buffer and calls `reset()` on modules if they implement it.
+- The frontend clears visuals/events before posting `/api/run`.
+- To avoid overlapping charts across runs, add `reset()` to modules that accumulate history (e.g., time series points).
+
+- Maintainer flow (building the frontend SPA):
+  - Edit the React/Vite app under `src/biosim/simui/_frontend/`.
+  - Build via Python: `python -m biosim.simui.build` (requires Node/npm). This writes `src/biosim/simui/static/app.js`.
+  - Alternatively: `bash scripts/build_simui_frontend.sh`.
+  - Packaging includes `src/biosim/simui/static/**`, so end users never need npm.
+
+- CI packaging (recommended): run the frontend build before `python -m build` so wheels/sdists ship the bundled assets.
+
+Troubleshooting:
+- If you see `SimUI static bundle missing at .../static/app.js`, build the frontend with `python -m biosim.simui.build` (requires Node/npm) before launching. End users installing a release wheel won't see this.
+
+### SimUI Design Notes
+- Transport: SSE (Server-Sent Events). The SPA connects to `/api/stream` for real-time updates. Polling endpoints (`/api/status`, `/api/visuals`, `/api/events`) remain available for fallback/debugging.
+- Events API: `/api/events?since_id=<int>&limit=<int>` returns `{ events, next_since_id }` where `events` are appended world events and `next_since_id` is the cursor for subsequent calls.
+- VisualSpec types supported now:
+  - `timeseries`: `data = { "series": [{ "name": str, "points": [[x, y], ...] }, ...] }`
+  - `bar`: `data = { "items": [{ "label": str, "value": number }, ...] }`
+  - `table`: `data = { "columns": [..], "rows": [[..], ...] }` or `data = { "items": [{...}, ...] }`
+  - `image`: `data = { "src": str, "alt"?: str, "width"?: number, "height"?: number }`
+  - `scatter`: scatter plot data
+  - `heatmap`: matrix/heatmap data
+  - `graph`: placeholder renderer shows counts + JSON; richer graph lib can be added later
+  - `custom:<type>`: custom renderer namespace for user-defined types
+  - unknown types: rendered as JSON fallback
+- VisualSpec may also include an optional `description` (string) for hover text or captions.
+
+## Terminology
+
+Understanding the core concepts is essential for working with biosim effectively.
+
+| Term | Description |
+|------|-------------|
+| **BioWorld** | Runtime container that orchestrates multi-rate biomodules, routes signals, and publishes lifecycle events. |
+| **BioModule** | Pluggable unit of behavior with local state. Implements the runnable contract (`setup/reset/advance_to/...`). |
+| **BioSignal** | Typed, versioned data payload exchanged between modules via named ports. |
+| **WorldEvent** | Runtime events emitted by the BioWorld (`STARTED`, `TICK`, `FINISHED`, etc.). |
+| **Wiring** | Module connection graph. Defined programmatically, via `WiringBuilder`, or loaded from YAML/TOML configs. |
+| **VisualSpec** | JSON structure returned by `module.visualize()` with `render` type and `data` payload. |
+
+### Event Lifecycle
+
+Every simulation follows this sequence:
+```
+STARTED -> TICK (xN) -> FINISHED
+```
+
+`PAUSED`, `RESUMED`, `STOPPED`, and `ERROR` may also be emitted depending on runtime control flow.
+
+## License
+
+MIT. See `LICENSE.txt`.

biosim-0.0.1/README.md

@@ -0,0 +1,241 @@
+# biosim
+
+[![PyPI - Version](https://img.shields.io/pypi/v/biosim.svg)](https://pypi.org/project/biosim)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/biosim.svg)](https://pypi.org/project/biosim)
+
+Composable simulation runtime + UI layer for orchestrating runnable biomodules.
+
+---
+
+## Executive Summary & System Goals
+
+### Vision
+
+Provide a small, stable composition layer for simulations: wire reusable components ("biomodules") into a `BioWorld`, run them with a single orchestration contract, and visualize/debug runs via a lightweight web UI (SimUI). Biomodules are self-contained Python packages that can wrap external simulators internally (SBML/NeuroML/CellML/etc.) without a separate adapter layer.
+
+### Core Mission
+
+- Compose simulations from reusable, interoperable biomodules.
+- Make "run + visualize + share a config" the default workflow (local-first; hosted later).
+- Keep the runtime small and predictable while letting biomodules embed their own simulator/tooling.
+
+### Primary Users
+
+- Developers and researchers who need composable simulation workflows and fast iteration.
+- Near-term beachhead: neuroscience demos (single neuron + small E/I microcircuits) with strong visuals and reproducible configs.
+
+---
+
+## Installation
+
+Preferred (pinned GitHub ref):
+
+```console
+pip install "biosim @ git+https://github.com/<org>/biosim.git@<ref>"
+```
+
+Alternative (package index):
+
+```console
+pip install biosim
+```
+
+## Publishing to PyPI
+
+This repository publishes to PyPI using GitHub Trusted Publishing.
+
+Release workflow:
+
+1. Update `src/biosim/__about__.py` with a new version (example: `0.0.2`).
+2. Commit and push the version bump to `main`.
+3. Create and push a matching tag (`v0.0.2`).
+4. Verify GitHub Actions `Publish to PyPI` finishes successfully.
+
+Manual commands:
+
+```bash
+git add src/biosim/__about__.py
+git commit -m "Bump version to 0.0.2"
+git push origin main
+git tag v0.0.2
+git push origin v0.0.2
+```
+
+Automation script:
+
+```bash
+bash scripts/release_pypi.sh
+```
+
+- This reads the version from `src/biosim/__about__.py`, requires a clean git tree, pushes `main`, then creates and pushes `v<version>`.
+- You can also pass an explicit version: `bash scripts/release_pypi.sh 0.0.2`.
+- Use `--no-push` to only create the local tag: `bash scripts/release_pypi.sh --no-push`.
+
+## Examples
+
+- See `examples/` for quick-start scripts. Try:
+
+```bash
+pip install -e .
+python examples/basic_usage.py
+```
+
+For advanced curated demos (neuro/ecology), wiring configs, and model-pack templates, see the companion repo:
+
+- https://github.com/Biosimulant/models
+
+### Quick Start: BioWorld
+
+Minimal usage:
+
+```python
+import biosim
+from biosim import BioSignal, SignalMetadata
+
+class Counter(biosim.BioModule):
+    min_dt = 0.1
+
+    def __init__(self):
+        self.value = 0
+
+    def reset(self) -> None:
+        self.value = 0
+
+    def advance_to(self, t: float) -> None:
+        self.value += 1
+
+    def get_outputs(self):
+        source = getattr(self, "_world_name", "counter")
+        return {
+            "count": BioSignal(
+                source=source,
+                name="count",
+                value=self.value,
+                time=0.0,
+                metadata=SignalMetadata(units="1", description="tick counter"),
+            )
+        }
+
+world = biosim.BioWorld()
+world.add_biomodule("counter", Counter())
+world.run(duration=1.0, tick_dt=0.1)
+```
+
+### Visuals from Modules
+
+Modules may optionally expose web-native visuals via `visualize()`, returning a dict or list of dicts with keys `render` and `data`. The world can collect them without any transport layer:
+
+```python
+class MyModule(biosim.BioModule):
+    min_dt = 0.1
+
+    def advance_to(self, t: float) -> None:
+        return
+
+    def get_outputs(self):
+        return {}
+
+    def visualize(self):
+        return {
+            "render": "timeseries",
+            "data": {"series": [{"name": "s", "points": [[0.0, 1.0]]}]},
+        }
+
+world = biosim.BioWorld()
+world.add_biomodule("module", MyModule())
+world.run(duration=0.1, tick_dt=0.1)
+print(world.collect_visuals())  # [{"module": "module", "visuals": [...]}]
+```
+
+See `examples/visuals_demo.py` for a minimal end-to-end example.
+
+## SimUI (Python-Declared UI)
+
+SimUI lets you build and launch a small web UI entirely from Python (similar to Gradio's ergonomics), backed by FastAPI and a prebuilt React SPA that renders visuals from JSON. The frontend uses Server-Sent Events (SSE) for real-time updates.
+
+- User usage (no Node/npm required):
+  - Install UI extras: `pip install -e '.[ui]'`
+  - Try the demo: `python examples/ui_demo.py` then open `http://127.0.0.1:7860/ui/`.
+  - From your own code:
+
+    ```python
+    from biosim.simui import Interface, Number, Button, EventLog, VisualsPanel
+    world = biosim.BioWorld()
+    ui = Interface(
+        world,
+        controls=[Number("duration", 10), Number("tick_dt", 0.1), Button("Run")],
+        outputs=[EventLog(), VisualsPanel()],
+    )
+    ui.launch()
+    ```
+
+  - The UI provides endpoints under `/ui/api/...`:
+    - `GET /api/spec` – UI layout (controls, outputs, modules)
+    - `POST /api/run` – Start a simulation run
+    - `GET /api/status` – Runner status (running/paused/error)
+    - `GET /api/state` – Full state (status + last step + modules)
+    - `GET /api/events` – Buffered world events (`?since_id=&limit=`)
+    - `GET /api/visuals` – Collected module visuals
+    - `GET /api/snapshot` – Full snapshot (status + visuals + events)
+    - `GET /api/stream` – SSE endpoint for real-time event streaming
+    - `POST /api/pause` – Pause running simulation
+    - `POST /api/resume` – Resume paused simulation
+    - `POST /api/reset` – Stop, reset, and clear buffers
+    - **Editor sub-API** (`/api/editor/...`): visual config editor for loading, saving, validating, and applying YAML wiring configs as node graphs. Endpoints include `modules`, `current`, `config`, `apply`, `validate`, `layout`, `to-yaml`, `from-yaml`, and `files`.
+
+Per-run resets for clean visuals
+- On each `Run`, the backend clears its event buffer and calls `reset()` on modules if they implement it.
+- The frontend clears visuals/events before posting `/api/run`.
+- To avoid overlapping charts across runs, add `reset()` to modules that accumulate history (e.g., time series points).
+
+- Maintainer flow (building the frontend SPA):
+  - Edit the React/Vite app under `src/biosim/simui/_frontend/`.
+  - Build via Python: `python -m biosim.simui.build` (requires Node/npm). This writes `src/biosim/simui/static/app.js`.
+  - Alternatively: `bash scripts/build_simui_frontend.sh`.
+  - Packaging includes `src/biosim/simui/static/**`, so end users never need npm.
+
+- CI packaging (recommended): run the frontend build before `python -m build` so wheels/sdists ship the bundled assets.
+
+Troubleshooting:
+- If you see `SimUI static bundle missing at .../static/app.js`, build the frontend with `python -m biosim.simui.build` (requires Node/npm) before launching. End users installing a release wheel won't see this.
+
+### SimUI Design Notes
+- Transport: SSE (Server-Sent Events). The SPA connects to `/api/stream` for real-time updates. Polling endpoints (`/api/status`, `/api/visuals`, `/api/events`) remain available for fallback/debugging.
+- Events API: `/api/events?since_id=<int>&limit=<int>` returns `{ events, next_since_id }` where `events` are appended world events and `next_since_id` is the cursor for subsequent calls.
+- VisualSpec types supported now:
+  - `timeseries`: `data = { "series": [{ "name": str, "points": [[x, y], ...] }, ...] }`
+  - `bar`: `data = { "items": [{ "label": str, "value": number }, ...] }`
+  - `table`: `data = { "columns": [..], "rows": [[..], ...] }` or `data = { "items": [{...}, ...] }`
+  - `image`: `data = { "src": str, "alt"?: str, "width"?: number, "height"?: number }`
+  - `scatter`: scatter plot data
+  - `heatmap`: matrix/heatmap data
+  - `graph`: placeholder renderer shows counts + JSON; richer graph lib can be added later
+  - `custom:<type>`: custom renderer namespace for user-defined types
+  - unknown types: rendered as JSON fallback
+- VisualSpec may also include an optional `description` (string) for hover text or captions.
+
+## Terminology
+
+Understanding the core concepts is essential for working with biosim effectively.
+
+| Term | Description |
+|------|-------------|
+| **BioWorld** | Runtime container that orchestrates multi-rate biomodules, routes signals, and publishes lifecycle events. |
+| **BioModule** | Pluggable unit of behavior with local state. Implements the runnable contract (`setup/reset/advance_to/...`). |
+| **BioSignal** | Typed, versioned data payload exchanged between modules via named ports. |
+| **WorldEvent** | Runtime events emitted by the BioWorld (`STARTED`, `TICK`, `FINISHED`, etc.). |
+| **Wiring** | Module connection graph. Defined programmatically, via `WiringBuilder`, or loaded from YAML/TOML configs. |
+| **VisualSpec** | JSON structure returned by `module.visualize()` with `render` type and `data` payload. |
+
+### Event Lifecycle
+
+Every simulation follows this sequence:
+```
+STARTED -> TICK (xN) -> FINISHED
+```
+
+`PAUSED`, `RESUMED`, `STOPPED`, and `ERROR` may also be emitted depending on runtime control flow.
+
+## License
+
+MIT. See `LICENSE.txt`.

biosim-0.0.1/docs/PUBLIC_INTERNAL_BOUNDARY.md

@@ -0,0 +1,20 @@
+# Public/Internal Boundary
+
+`bio-sim` is a public OSS repository.
+
+## Allowed (public)
+- Runtime/library source code
+- Technical design docs and API contracts
+- Testing strategy and quality docs
+- Example models/templates intended for public use
+
+## Not allowed (internal only)
+- Business cases, pricing, GTM, investor/fundraising content
+- Competitive strategy and commercial forecasts
+- Internal operating procedures and non-public incident reports
+- Secrets, service-account keys, credentials, tokens
+
+## Enforcement
+- CI blocks commits containing common business-sensitive terms in docs.
+- CI blocks commits containing detected secrets.
+- Internal planning docs are stored in `biosim-platform`.

biosim-0.0.1/docs/README.md

@@ -0,0 +1,30 @@
+# biosim Documentation
+
+Welcome to the biosim documentation. This guide explains the core concepts, APIs, and practical wiring patterns for building modular biological simulations.
+
+## Contents
+
+- [Overview](overview.md): high-level architecture, core concepts (BioWorld, BioModule, BioSignal, SimUI)
+- [Quickstart](quickstart.md): install, run, and explore
+- API:
+  - [BioWorld](bioworld.md): orchestrator, events, run control (pause/resume/stop), signal routing
+  - [BioModule](biomodule.md): module interface, lifecycle, port metadata, visualization
+  - [Wiring](wiring.md): WiringBuilder, `build_from_spec`, and YAML/TOML loaders
+  - [Configuration](config.md): how to write wiring files
+- [Example: Eye → LGN → SC pipeline](brain_pipeline.md)
+- [Neuro packs](neuro.md): computational neuroscience modules (Izhikevich, Hodgkin-Huxley, Poisson input, synapses, monitors) — lives in the companion [`models`](https://github.com/Biosimulant/models) repo
+- [Plugin Development](plugin-development.md): creating and distributing custom biomodules
+
+See the files in this folder for a textbook-style walkthrough with code and concrete data examples.
+
+## SimUI
+
+The biosim core includes a lightweight web UI (SimUI) for running and visualizing simulations. See the [README](../README.md#simui-python-declared-ui) for:
+- Python-declared interface API
+- Full REST + SSE endpoint reference
+- Config editor sub-API for visual wiring editing
+- VisualSpec render types (timeseries, bar, table, image, scatter, heatmap, graph, custom)
+
+## Building a single PDF
+- Requirements: `pandoc` and a LaTeX engine (e.g., TeX Live)
+- Status: planned (no `scripts/build_pdf.sh` in this repo yet)

biosim-0.0.1/docs/biomodule.md

@@ -0,0 +1,63 @@
+# API: BioModule
+
+BioModule encapsulates behavior with local state. It:
+- Implements a runnable contract (`setup/reset/advance_to/...`).
+- Receives inputs via `set_inputs(...)` and emits outputs via `get_outputs()`.
+- Optionally declares connection ports for validation via `inputs()` and `outputs()`.
+
+Signature (selected)
+```python
+class BioModule:
+    min_dt: float  # required positive value (seconds by default), defaults to 0.0
+
+    def setup(self, config: Optional[Dict[str, Any]] = None) -> None: ...
+    def reset(self) -> None: ...
+    def advance_to(self, t: float) -> None: ...       # abstract
+    def set_inputs(self, signals: Dict[str, BioSignal]) -> None: ...
+    def get_outputs(self) -> Dict[str, BioSignal]: ... # abstract
+    def get_state(self) -> Dict[str, Any]: ...
+    def next_due_time(self, now: float) -> float: ...  # returns now + min_dt by default
+    def inputs(self) -> Set[str]: ...
+    def outputs(self) -> Set[str]: ...
+    def input_schemas(self) -> Dict[str, Any]: ...     # optional, for future tooling
+    def output_schemas(self) -> Dict[str, Any]: ...    # optional, for future tooling
+    def visualize(self) -> Optional[VisualSpec | List[VisualSpec]]: ...
+```
+
+Notes:
+- `advance_to` and `get_outputs` are abstract (must be implemented).
+- `setup` receives an optional config dict (per-module section from the world config), not the BioWorld instance.
+- `next_due_time` returns `float` (not Optional); default implementation is `now + min_dt`.
+- `input_schemas`/`output_schemas` return port-name-to-schema mappings; currently unused but reserved for future validation.
+- `visualize` returns a VisualSpec dict or list of dicts for browser rendering (see README VisualSpec types).
+
+Example with local state
+```python
+class Eye(biosim.BioModule):
+    min_dt = 0.01
+
+    def __init__(self):
+        self.photons_seen = 0
+
+    def outputs(self):
+        return {"visual_stream"}
+
+    def advance_to(self, t: float) -> None:
+        self.photons_seen += 1
+
+    def get_outputs(self):
+        source = getattr(self, "_world_name", "eye")
+        return {
+            "visual_stream": biosim.BioSignal(
+                source=source,
+                name="visual_stream",
+                value={"count": self.photons_seen},
+                time=0.0,
+                metadata=biosim.SignalMetadata(units="1"),
+            )
+        }
+```
+
+Typical values at runtime
+- `t` -> current world time (float)
+- `self.photons_seen` after two ticks -> `2`