Metadata-Version: 2.5
Name: gravi-model-client
Version: 0.6.0
Summary: Python client for Gravitate's Demand & Supply optimization models
Project-URL: Homepage, https://gravitate.energy
Project-URL: Repository, https://github.com/gravitate-energy/demand-only-model
Author-email: Gravitate Energy <engineering@gravitate.energy>
License: Proprietary
Keywords: api-client,demand-model,optimization,supply-model
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: pyhumps>=3.8.0
Description-Content-Type: text/markdown

# gravi-model-client

Python client for Gravitate's demand and supply optimization models.

## Installation

```bash
pip install gravi-model-client
```

## Usage

```python
from gravi_model_client import GraviModelClient, ModelRunRequest, OptimizationInput

async with GraviModelClient(api_key="your-api-key", base_url="https://...") as client:
    # Health check
    await client.health_check()

    # Run demand model (synchronous)
    result = await client.run_demand_model(request)

    # Run TSD (supply) model (synchronous)
    result = await client.run_tsd_model(optimization)
```

### Async (queue-based) models: VRP and OSA

VRP (tank wagon turn) and OSA (order-based supply) runs are queued and processed
by a worker. `run_vrp_model` / `run_osa_model` handle the whole queue → poll →
fetch lifecycle and block until the result is ready:

```python
from gravi_model_client import GraviModelClient, VrpModelRunRequest, OsaInput

async with GraviModelClient(api_key="your-api-key") as client:
    vrp_result = await client.run_vrp_model(vrp_request)   # -> VrpModelResultResponse
    osa_result = await client.run_osa_model(osa_input)     # -> OsaAPIResponse
```

They raise `ModelRunError` if the run fails or is cancelled, and `ModelRunTimeout`
if it doesn't finish within `timeout` (default 300s; tune `poll_interval` too).

For fire-and-forget / webhook workflows, use the primitives instead: `queue_vrp_model`
returns a job id, `get_job_status` / `get_osa_job_status` return a `JobStatus`, and
`get_vrp_model_run_response` / `get_osa_model_run_response` fetch the finished result.

## Models

This package is the single source of truth for all pydantic models used by both
the client and the server. Import models directly:

```python
from gravi_model_client.demand import ModelRunRequest, StoreRequest, TankRequest, VolumeRange
from gravi_model_client.tsd import OptimizationInput, Directive, Site, Tank
```
