Metadata-Version: 2.4
Name: ark-opensource
Version: 0.1.0
Summary: Standalone Ark open-source Pydantic models
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.10.6
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

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

```bash
pip install ark-opensource
```

From a local build artifact:

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

## Quick Start

```python
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:

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

Run the test suite:

```bash
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`.
