Metadata-Version: 2.4
Name: rost-io
Version: 0.1.1
Summary: Adapter layer for .rost — converts any data source to canonical JSON
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: jsonschema>=4.0
Provides-Extra: csv
Provides-Extra: parquet
Requires-Dist: pyarrow>=13.0; extra == "parquet"
Provides-Extra: db
Requires-Dist: sqlalchemy>=2.0; extra == "db"
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1; extra == "excel"
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == "pandas"
Provides-Extra: llm
Requires-Dist: instructor>=1.0; extra == "llm"
Requires-Dist: openai>=1.0; extra == "llm"
Provides-Extra: all
Requires-Dist: pyarrow>=13.0; extra == "all"
Requires-Dist: sqlalchemy>=2.0; extra == "all"
Requires-Dist: openpyxl>=3.1; extra == "all"
Requires-Dist: pandas>=2.0; extra == "all"
Requires-Dist: instructor>=1.0; extra == "all"
Requires-Dist: openai>=1.0; extra == "all"

# 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

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

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