Metadata-Version: 2.4
Name: reservoirx-d
Version: 0.1.1
Summary: Python client for the ReservoirX-D API: directed degree-regular reservoir generation and measurement
Author: mahal95
License: MIT
Project-URL: Homepage, https://reservoirx-d.fly.dev
Project-URL: Documentation, https://reservoirx-d.fly.dev/docs
Keywords: reservoir-computing,echo-state-network,graph,benchmark,api-client
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: responses>=0.25; extra == "dev"

# ReservoirX-D Python Client

Official Python client for the [ReservoirX-D API](https://reservoirx-d.fly.dev) — directed, degree-regular reservoir generation with measured, not assumed, wiring effects.

```bash
pip install reservoirx-d
```

## Usage

```python
from reservoirx import ReservoirXClient

with ReservoirXClient() as client:
    result = client.compare(
        node_count=200, mean_degree=3, iterations=8,
        tasks=["memory_capacity", "delay_xor"],
        include_symmetrization_control=True,
    )
    print(result["summary"]["verdict"])
```

No credentials are needed for the public deployment. Through RapidAPI:

```python
client = ReservoirXClient(rapidapi_key="...", base_url="https://reservoirx-d.p.rapidapi.com")
```

## Methods

| Method | Endpoint |
| --- | --- |
| `generate()` | directed matrix with an exact degree sequence |
| `diagnose()` | structural metrics vs. two null models |
| `evaluate()` | score on memory capacity, parity, XOR, or NARMA-10 |
| `compare()` | paired regular vs skewed, Holm-corrected |
| `optimize()` | smallest non-inferior width, confirmed on held-out seeds |
| `claims()`, `tasks()`, `version()`, `health()` | metadata |

## Two response fields worth checking

`evaluate()` and `compare()` return `warnings`. Memory capacity is bounded by `max_lag`, so a saturated score cannot distinguish configurations — the server says so rather than letting you read a ceiling as a result.

`optimize()` returns `selection.metric_saturated`. When true, every width passed non-inferiority trivially and the recommended ratio means nothing. Raise `max_lag` and re-run.

## Errors

All exceptions derive from `APIError`, so `except APIError` catches everything.

```python
from reservoirx import APIError, RequestTimeout, ConnectionFailed, ValidationFailed
```

`RequestTimeout` and `ConnectionFailed` are worth retrying. `ValidationFailed` (HTTP 422) is not — it carries the server's own message, e.g. that `mean_degree=2.7` needs `wiring_scheme="near_regular"`.

The default timeout is 300s because `/compare` and `/optimize` run real simulations: eight seeds across four tasks is 64 reservoir runs.

## Changelog

### 0.1.1

- **Fixed:** timeouts and connection failures raised `UnboundLocalError` instead of `APIError`, because `e` was never bound in those handlers.
- **Fixed:** the package shipped the server's `models.py`, which imported a `config` module that was not included — `import reservoirx.models` raised `ModuleNotFoundError`, and it pulled in an undeclared pydantic dependency.
- **Fixed:** mutable default arguments (`null_models=[...]`, `tasks=[...]`) shared across calls.
- **Fixed:** package metadata listed a placeholder author and email.
- Added `RequestTimeout`, `ConnectionFailed`, `ValidationFailed` subclasses; errors now carry the server's message instead of a bare status line.
- `api_key` is optional; added RapidAPI header support.
- Context-manager support, injectable session, default timeout raised from 60s to 300s.

## License

MIT
