# Zeq Python SDK

Two Python modules for interacting with Zeq OS:

| File | Purpose | Network? |
|------|---------|----------|
| `zeq_client.py` | Thin HTTP wrapper around `https://zeq.dev/api/zeq/compute` — normalises inputs to natural units, posts the request, denormalises the response. Use this for production integrations. | yes |
| `hulyas_framework.py` | Offline HULYAS mathematical framework v1.287 Hz — the full 42-operator Kinematic Operator spectrum, KO42.1/KO42.2 metric tensioners, master equation ODE integrator, autotune-until-pass, strict validator. Use this for local experimentation, teaching, and verification. | no (stdlib + numpy/scipy/matplotlib) |

Both modules are released under the licence that applies to the rest of this repository (see `LICENSE` at the repo root).

## Install

Clone the repo or copy the files directly. No package manager entry is required — the modules are single-file and have no sub-package structure.

```bash
# Optional: the offline framework uses numpy, scipy, matplotlib for plotting
pip install numpy scipy matplotlib requests
```

## Quickstart — `zeq_client.py`

```python
from zeq_client import ZeqClient

client = ZeqClient(token="zeq_ak_...")  # Bearer token from the Zeq dashboard
result = client.compute(
    operator_id="NM21",
    inputs={"m1": 5.972e24, "m2": 7.342e22, "r": 3.844e8},
)
print(result["value"], result["unit"])  # → 1.98049e+20 N   (Earth-Moon gravity)
```

The wrapper also exposes `client.prove()` for the `/api/zeq/prove` endpoint,
and returns the full `zeqProof` HMAC, `compliance` envelope, and `cko` block
alongside the numeric result.

## Quickstart — `hulyas_framework.py`

```python
from hulyas_framework import run_master_experiment

# Free-fall from 1 m, 5 seconds, KO42.1 automatic tensioner
cko = run_master_experiment(
    "Compute free-fall displacement from 1 m over 5 seconds",
    alpha=1.0,       # KO42.1 automatic tensioner weight
    beta=0.0,        # KO42.2 manual tensioner (off)
    t_max=5.0,
    dt=0.01,
)
print(cko)
```

For strict ≤0.1 % validation and autotune:

```python
from hulyas_framework import autotune_until_pass
cko = autotune_until_pass("Simple harmonic motion with k=200, m=0.5")
```

See the file's inline documentation for the full list of 42 Kinematic Operators
and the 7-step wizard protocol it implements.

## What is what

- `zeq_client.py` — small, focused, stateless, used in production applications.
- `hulyas_framework.py` — large, opinionated, pedagogical; it is the original
  1047-line reference implementation authored by Hammoudeh Zeq and Aydan Zeq
  and is intended as the canonical offline analogue of the online `/api/zeq/*`
  surfaces. Both modules share the same 1.287 Hz HulyaPulse and 0.777 s Zeqond.

## Temporal alignment

Both modules use the canonical Zeq OS constants:

- `f_H` = **1.287 Hz** (HulyaPulse)
- `τ_z` = **0.777 s** (Zeqond)
- `α_K` = **0.00129** (modulation coefficient)
- NIST CODATA 2018 physical constants

## Compliance

The online API (`zeq_client.py` path) returns an FDA 21 CFR Part 11 / ISO 27001
/ GDPR Art. 30-aligned compliance envelope and a SHA-256 `zeqProof` HMAC on
every response. The offline framework (`hulyas_framework.py`) emits the same
CKO (Computational Kernel Output) block locally for reproducibility but does
not sign it — sign via the online API when regulatory evidence is required.

## Reference

- Zeq Paper DOI: https://10.5281/zenodo.18158152
- Zeq OS framework paper DOI: https://10.5281/zenodo.15825138
- API documentation: https://zeq.dev/sdk