Python SDK

The Python SDK is the reference implementation of Zeq OS. It provides HulyaSync for local temporal synchronization and wraps the REST API for computation.

Installation

pip install zeq-os

Or from source:

cd sdk/python
pip install -e ".[dev]"

How it works

Free (no account needed):

• Browse all operator equations — they are standard physics formulas, fully public
• Read the framework formulas (Zeq Equation, KO42, HULYAS)
• Use HulyaSync locally for temporal synchronization and HulyaPulse modulation

Requires an account:

• Execute operators — computation runs on our servers
• Run the 7-Step Wizard — server-side physics processing
• All compute is billed; the framework knowledge is free

Authentication

Your equation IS your identity. Register once with any equation — the server stores only a hash of the evaluated result, never the equation string.

import requests

BASE = "http://localhost"  # your Zeq OS instance

# Register (first time)
r = requests.post(f"{BASE}/api/users/register", json={
    "displayName": "Alice",
    "equation": "x^2 + sin(y*pi) + phi"   # your key — memorise it
})
print(r.json())  # { "zid": "zeq-abc123", "token": "...", "displayName": "Alice" }

# Login (same equation = same identity, every time)
r = requests.post(f"{BASE}/api/users/login", json={
    "equation": "x^2 + sin(y*pi) + phi"
})
token = r.json()["token"]
headers = {"Authorization": f"Bearer {token}"}

Quick Start

import requests

BASE = "http://localhost"
headers = {"Authorization": "Bearer your-jwt-token"}

# 1. Browse operators — fully public, no token needed
ops = requests.get(f"{BASE}/api/zeq/operators").json()
for op in ops["operators"][:3]:
    print(f"{op['id']:6}  {op['name']:30}  {op['equation']}")
# QM1     Schrödinger Equation          iℏ ∂ψ/∂t = −ℏ²/2m ∂²ψ/∂x² + Vψ
# QM2     Born Rule                     P = |ψ|²
# NM18    Newton's Second Law           F = ma

# 2. Get current HulyaPulse phase — no token needed
phase = requests.get(f"{BASE}/api/zeq/phase").json()
print(f"Phase: {phase['phase']:.4f}   KO42: {phase['ko42']:.6f}   Zeqond: {phase['zeqond']}")

# 3. Execute a computation — requires account
result = requests.post(
    f"{BASE}/api/zeq/operators/execute?operator=NM21",
    headers=headers,
    json={"params": {"G": 6.674e-11, "m1": 5.97e24, "m2": 7.35e22, "r": 3.84e8}}
).json()
print(f"Gravitational force: {result['value']:.3e} N")

# 4. Run the 7-Step Wizard — requires account
state = requests.post(f"{BASE}/api/7step/run", headers=headers, json={
    "query": "gravitational time dilation near Earth",
    "operators": ["KO42", "GR37"],
    "mode": "basic"
}).json()
print(f"Operators: {state['selected_operators']}")
print(f"Master sum: {state['master_sum']:.6f}")
print(f"Precision:  {state['precision']}")

SDK Classes

ZeqSDK

Wraps POST /api/7step/run into a single call.

from zeq_os import ZeqSDK

sdk = ZeqSDK(token="your-jwt-token")
result = sdk.execute("gravitational time dilation at r=10km")

print(result.value)
print(result.operators)   # ["KO42", "GR37", ...]
print(result.precision)   # e.g. "0.08%"

ZeqondClock (HulyaSync)

Local temporal engine — runs entirely on your machine, no server call, no auth.

from zeq_os import ZeqondClock
import time

clock = ZeqondClock()

# Current Zeqond count (time unit, T = 0.777 s)
print(clock.current_zeqond())

# Phase within current Zeqond [0, 1)
print(clock.phase())

# Convert between Unix time and Zeqond time
print(clock.unix_to_zeqond(time.time()))
print(clock.zeqond_to_unix(clock.current_zeqond()))

# Zeq Equation modulation: R(t) = S(t) × [1 + α·sin(2πft)]
# f = 1.287 Hz, α = 0.00129
print(clock.modulate(9.80665))   # → 9.8066x (phase-dependent)

# KO42 Metric Tensioner — mandatory in all computations
print(clock.ko42_automatic())    # α · sin(2π × 1.287 × t)

# Daemon tick string
print(clock.daemon_tick())
# [Zeq OS Daemon] Zeqond ticked — phase ≈ 0.421 — HulyaPulse 1.287 Hz synced

OperatorRegistry

Browse operators locally (reads public API; no auth needed for equations).

from zeq_os import OperatorRegistry

registry = OperatorRegistry()

# Get any operator — equation is fully public
op = registry.get("QM1")
print(op.name)      # "Schrödinger Equation"
print(op.equation)  # "iℏ ∂ψ/∂t = −ℏ²/2m ∂²ψ/∂x² + Vψ"
print(op.category)  # "quantum_mechanics"

# Browse by domain
qm_ops  = registry.by_domain("quantum_mechanics")   # QM1–QM17
nm_ops  = registry.by_domain("newtonian_mechanics")  # NM18–NM30
gr_ops  = registry.by_domain("general_relativity")   # GR31–GR41

Framework Equations

These formulas are the published foundation of Zeq OS (Zenodo paper):

Zeq Equation

R(t) = S(t) × [1 + α × sin(2π × 1.287 × t)]

f = 1.287 Hz    (HulyaPulse frequency)
T = 0.777 s     (Zeqond — one period)
α = 0.00129     (modulation depth)

Averaging R(t) over one Zeqond recovers S(t) exactly — backwards-compatible with standard physics.

KO42 Metric Tensioner

KO42.1 (Automatic): ds² = g_μν dx^μ dx^ν + α sin(2π × 1.287 × t) dt²
KO42.2 (Manual):    ds² = g_μν dx^μ dx^ν + β sin(2π × 1.287 × t) dt²

KO42 is the Prime Directive — mandatory in every Zeq OS computation.

HULYAS Master Equation

□(φ) − μ²(r)φ − λφ³ − exp(−φ/φ_c)
  + φ₄₂ × Σ(Cₖ(φ)) = T^μ_μ + βF·F + J_ext

The 7-Step Protocol

Step	Name	What happens
1	PRIME DIRECTIVE	KO42 Metric Tensioner is applied — mandatory
2	OPERATOR LIMIT	Select 1–3 additional operators (total ≤ 4 including KO42)
3	SCALE PRINCIPLE	Match operators to the correct physics domain
4	PRECISION	Target ≤ 0.1% mean error
5	COMPILE	Assemble the Master Equation from selected operators
6	EXECUTE	Run with HulyaPulse modulation
7	VERIFY	Confirm precision. Troubleshoot if target not met.

# Via REST API
state = requests.post(f"{BASE}/api/7step/run", headers=headers, json={
    "query": "photon energy at 5e14 Hz",
    "operators": ["KO42", "QM10"],
    "mode": "basic"          # "basic" | "advanced" | "mathematical_state"
}).json()

# Parse a query to discover suggested operators
parsed = requests.post(f"{BASE}/api/7step/parse", headers=headers, json={
    "query": "orbital velocity of ISS at 408 km"
}).json()
print(parsed["detected_domains"])     # ["celestial_mechanics", "newtonian"]
print(parsed["suggested_operators"])  # ["KO42", "CM6", "NM18"]

REST API Reference

Method	Endpoint	Auth	Description
POST	/api/users/register	—	Register with equation
POST	/api/users/login	—	Login, receive JWT
GET	/api/users/me	Required	Current user + subscription
GET	/api/zeq/phase	—	Live HulyaPulse phase + KO42
GET	/api/zeq/operators	—	All operators with equations (public)
GET	/api/zeq/operators/:id	—	Single operator with equation
POST	/api/zeq/operators/execute?operator=ID	Required	Execute operator (billed)
POST	/api/7step/run	Required	7-Step Wizard (billed)
POST	/api/7step/parse	Required	Parse query → domains + operators
POST	/api/7step/strict	Required	Strict protocol with full validation
GET	/api/zeq/state	Required	Full live computational state
POST	/api/zeq/phrase-to-equation	Required	NLP phrase → math equation
GET	/api/health	—	Service health

Testing

cd sdk/python
pytest tests/ -v