ark-opensource

Open Pydantic schemas for describing bioreactor run setup data.

ark-opensource provides a typed data structure for the scientific inputs that define an Ark run: vessel geometry, medium composition, gas transfer, headspace conditions, and process-control setpoints. The models are useful in scripts, notebooks, services, and partner integrations that need to validate or exchange run setup payloads while preserving explicit units and domain enums.

Installation

After publication:

pip install ark-opensource

From a local build artifact:

pip install dist/ark_opensource-0.1.0-py3-none-any.whl

Quick Start

from ark_opensource import RunSetup

setup = RunSetup.model_validate(
    {
        "bioreactor": {"bioreactor_name": "BRX-1", "manufacturer": "Ark"},
        "feed_liquids": {
            "feed": {"ph": 7.1, "osmolality": 300},
        },
        "dissolved_oxygen_control": None,
        "ph_control": None,
        "agitation_control": None,
        "headspace": {"headspace_pressure": 1.0, "gas_overlay": None},
    }
)

payload = setup.model_dump(mode="json")

Data Model

RunSetup is the root object. It groups the physical vessel, liquid feeds, gas environment, and optional control loops that define the initial state and operating policy for a run.

• bioreactor describes the hardware: reactor type, dimensions, impellers, spargers, shaker flasks, deep-well plates, and manufacturer metadata.
• feed_liquids maps liquid names to chemically defined media or feeds. Each liquid records pH, osmolality, sugars, amino acids, ions, buffers, metabolites, and tracer concentrations with explicit concentration units.
• headspace captures the gas-side environment: pressure, overlay gas composition, humidity, condenser efficiency, lid permeability, and time-based overlay schedules.
• dissolved_oxygen_control represents oxygen-control strategy, setpoints, PI gains, sparger dependencies, gas limits, and scheduled or conditional flow-rate changes.
• ph_control represents low-side and high-side pH correction using liquid additions or CO2 delivery, including controller gains, deadbands, setpoint schedules, and reagent composition.
• agitation_control describes mixing speed, orbital diameter, scheduled speed changes, scale-control alternatives, and DO-driven agitation constraints.

The schema uses Pydantic v2 for validation and serialization. Unit and option fields are represented as string enums so JSON payloads remain portable while still being checked against the supported scientific vocabulary.

Package Layout

• ark_opensource.RunSetup: the public root model.
• ark_opensource.jsonb_models: nested scientific data structures.
• ark_opensource.string_constants: units, options, and domain enums.
• Runtime dependency: pydantic>=2.10.6.

Development

Install the package in editable mode with the optional test dependency:

python -m pip install -e ".[dev]"

Run the test suite:

python -m pytest

Publishing

Before publishing a public release, confirm the version in pyproject.toml and build a wheel and source distribution from a clean checkout.

Built artifacts are written to dist/.

License

MIT. See LICENSE.