Metadata-Version: 2.5
Name: strataq
Version: 0.1.0
Summary: Computational framework for stochastic strategic interaction: QRE, potential and non-potential games, entropy-regularised response, non-equilibrium strategic dynamics.
Project-URL: Repository, https://github.com/SharathSPhD/sage
Author: Sharath Sathish
License-Expression: Apache-2.0
Keywords: game-theory,jax,non-equilibrium,quantal-response-equilibrium,thermodynamics
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: equinox>=0.11
Requires-Dist: hydra-core>=1.3
Requires-Dist: jax>=0.4.30
Requires-Dist: lineax>=0.0.6
Requires-Dist: numpy>=1.26
Requires-Dist: omegaconf>=2.3
Requires-Dist: optax>=0.2
Requires-Dist: optimistix>=0.0.9
Requires-Dist: polars>=1.0
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic>=2.7
Provides-Extra: all
Requires-Dist: datasets>=2.19; extra == 'all'
Requires-Dist: huggingface-hub>=0.23; extra == 'all'
Requires-Dist: matplotlib>=3.8; extra == 'all'
Requires-Dist: numpyro>=0.15; extra == 'all'
Requires-Dist: pyblp>=1.1; extra == 'all'
Requires-Dist: pygambit>=16.2; extra == 'all'
Provides-Extra: bayes
Requires-Dist: numpyro>=0.15; extra == 'bayes'
Provides-Extra: blp
Requires-Dist: pyblp>=1.1; extra == 'blp'
Provides-Extra: dreamprice
Requires-Dist: datasets>=2.19; extra == 'dreamprice'
Requires-Dist: huggingface-hub>=0.23; extra == 'dreamprice'
Provides-Extra: gambit
Requires-Dist: pygambit>=16.2; extra == 'gambit'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.8; extra == 'viz'
Description-Content-Type: text/markdown

# strataq

**Thermodynamic instruments for strategic systems.** Quantal-response
equilibria, potential/harmonic game decomposition, entropy-regularised
response, and non-equilibrium strategic dynamics — in JAX, with a
plain-numpy toolkit on top.

Some strategic systems settle (landscapes); some circulate forever
(whirlpools). From the outside they can look identical. strataq is a set of
calibrated meters that tell them apart — from a payoff matrix if you have
one, from measured responses or a raw time series if you don't.

```python
import strataq.toolkit as tk
```

## Three questions, one call each

**Is my system a landscape or a whirlpool?** — from any measured
cross-response matrix (e.g. cost pass-through between two firms):

```python
read = tk.reciprocity_read([[1.07, 0.003], [0.0005, 0.97]])
read.r  # 0.0011 — this is the actual Dominick's grocery reading
read.verdict  # "reciprocal (landscape-like): ..."
read.warnings  # the honesty notes travel with the number
```

**Is my time series irreversibly driven?** — the instrument that found the
diurnal loop in day-ahead electricity prices:

```python
verdict = tk.irreversibility_test(weekly_prices)  # any scalar series, ≥ a few hundred points
verdict.detected, verdict.p_value  # vs a reversible null with matched persistence
```

**How payoff-sensitive are my agents?** — a Bayesian posterior over the
logit rationality λ from observed choice frequencies:

```python
est = tk.estimate_rationality([u1, u2], counts=[[412, 95, 493], [301, 402, 297]])
est.mean, (est.ci_low, est.ci_high)  # calibrated 95% interval
est.warnings  # flags flat likelihoods instead of quoting noise
```

And for a game you can write down, the full dashboard:

```python
tk.game_thermo([u1, u2], lam=1.5)  # harmonic fraction α, reciprocity ℛ, dissipation
```

## The full library

Under the facade: three QRE solvers (damped fixed-point, mirror descent,
arclength branch tracer, pygambit-validated), the Hodge potential/harmonic
decomposition, equilibrium response matrices χ = (I − SB)⁻¹S, exact Glauber
dynamics with currents and entropy production, trajectory estimators (KLD,
certified TUR bounds), Hatano–Sasa quench thermodynamics, surrogate nulls,
Bayesian estimation with an EFE experiment-selection loop, and domain
plugins (Colonel Blotto, traffic networks, electricity markets, retail
pricing).

Every claim the library makes is backed by a gated unit with an adversarial
review on record, and every number regenerates from fixed seeds
(`make reproduce` in the [SAGE monorepo](https://github.com/SharathSPhD/sage)).
The interactive companion lives at
[sage-labs.vercel.app](https://sage-labs.vercel.app).

## Install

```bash
pip install strataq        # once published; until then (pip ≥ 21.1):
pip install "strataq @ git+https://github.com/SharathSPhD/sage.git#subdirectory=packages/strataq"
```

Python ≥ 3.11. CPU JAX by default; float64 is enabled by the library.

`import strataq` — never `import sage` (SageMath owns that name).

## License

Apache-2.0. Dominick's-derived artifacts carry CC-BY-NC-4.0 (see
`strataq.domains.pricing`).
