rost-io 0.1.0

Adapter layer for .rost — converts any data source to canonical JSON

rost-io — Adapter layer for .rost

rost-io converts messy real-world data sources into the canonical JSON contracts that the .rost compiler and solver consume.

Design principle

The .rost compiler only reads canonical JSON. It has no database drivers, no Excel parser, no API calls. rost-io is the adapter layer that handles all of that — exactly as described in DATA_IO.md (Hexagonal Architecture).

Excel / CSV / Parquet / PostgreSQL / MySQL / PDF
        │
        ▼
  rost-io adapter        ← this package
        │
        │   staff.json        (schema: rost/staff/v1)
        │   leave.json        (schema: rost/leave/v1)
        │   calendar.json     (schema: rost/calendar/v1)
        ▼
  rostc compiler  →  solver  →  solution.json

Installation

# Core only (CSV + JSON — no extra dependencies)
pip install rost-io

# With Parquet support (P1)
pip install "rost-io[parquet]"

# With database support — PostgreSQL + MySQL (P1)
pip install "rost-io[db]"

# With Excel support (P2)
pip install "rost-io[excel]"

# With pandas support (P2)
pip install "rost-io[pandas]"

# Everything
pip install "rost-io[all]"

Quick start

from rost_io import CsvAdapter, validate_staff

# Convert a CSV staff export to canonical staff.json
adapter = CsvAdapter("hr_export.csv", id_col="employee_id", tags_col="roles")
staff_json = adapter.to_staff_json()

# Validate against the canonical schema
validate_staff(staff_json)          # raises jsonschema.ValidationError if invalid

# Write for the compiler
import json
with open("staff.json", "w") as f:
    json.dump(staff_json, f, indent=2)

Canonical JSON schemas

File	Schema ID	Description
staff.json	rost/staff/v1	People + tags
leave.json	rost/leave/v1	Leave/absence entries
calendar.json	rost/calendar/v1	Date range + public holidays
solution.json	rost/solution/v1	Solver output (read-only for rost-io)

Adapters

Adapter	Priority	Extra dep
CsvAdapter	P0	none (stdlib)
JsonAdapter	P0	none
ParquetAdapter	P1	pyarrow
DatabaseAdapter	P1	sqlalchemy
ExcelAdapter	P2	openpyxl
PandasAdapter	P2	pandas