ethoryx 0.1.0__tar.gz

ethoryx-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Build / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

ethoryx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ethoryx Research (Tesfaye Dereje)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ethoryx-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: ethoryx
+Version: 0.1.0
+Summary: Official Python client for the Ethoryx prime-generation API (RSA, FHE, zk-SNARK, and NTT primes).
+Project-URL: Homepage, https://ethoryx.io
+Project-URL: Documentation, https://ethoryx.io/docs
+Project-URL: Source, https://github.com/Teshgty/ethoryx-python
+Project-URL: API Status, https://api.ethoryx.io/v1/status
+Author-email: Ethoryx Research <research@ethoryx.io>
+License: MIT
+License-File: LICENSE
+Keywords: cryptography,ethoryx,fhe,ntt,number-theory,prime,primes,rsa,zk-snark
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.20
+Description-Content-Type: text/markdown
+
+# ethoryx
+
+Official Python client for the [Ethoryx](https://ethoryx.io) prime-generation API —
+structurally-guided primes for **RSA, FHE, zk-SNARKs, and NTT**, backed by the Ethoryx
+C/GMP core. Fewer Miller–Rabin tests, fewer candidates, same cryptographic strength.
+
+- API: `https://api.ethoryx.io` · [Docs](https://ethoryx.io/docs) · [Status](https://api.ethoryx.io/v1/status)
+
+## Install
+
+```bash
+pip install ethoryx
+```
+
+## Quick start
+
+```python
+import ethoryx
+
+client = ethoryx.Client(api_key="tg_your_key")   # or set ETHORYX_API_KEY
+
+# Generate primes
+prime = client.generate(bits=2048)
+rsa   = client.generate_rsa(bits=2048)
+pair  = client.generate_rsa_pair(bits=2048)      # matched (p, q)
+ntt   = client.generate_ntt(bits=256)
+fhe   = client.generate_fhe(bits=2048)           # Starter tier or above
+
+# Public endpoints — no API key required
+ethoryx.verify(999983)                           # {"is_prime": true, ...}
+ethoryx.optimize_next(prime=999983, gap=6)       # next-prime prediction
+ethoryx.status()                                 # version, benchmarks
+```
+
+Get a free key (100 calls/month) at <https://ethoryx.io/register>.
+
+## Authentication
+
+Pass your key to the client, or set it once in the environment:
+
+```bash
+export ETHORYX_API_KEY="tg_your_key"
+```
+
+```python
+client = ethoryx.Client()                 # picks up ETHORYX_API_KEY
+```
+
+The public endpoints (`verify`, `optimize_next`, `predict_gap`, `status`) work without a
+key. Everything under `generate*` and `account*` requires one.
+
+## API
+
+| Method | Endpoint | Auth |
+|--------|----------|------|
+| `client.generate(bits=, method=)` | `GET /v1/generate` | 🔑 |
+| `client.generate_rsa(bits=)` | `GET /v1/generate/rsa` | 🔑 |
+| `client.generate_rsa_pair(bits=)` | `GET /v1/generate/rsa-pair` | 🔑 |
+| `client.generate_ntt(bits=)` | `GET /v1/generate/ntt` | 🔑 |
+| `client.generate_fhe(bits=)` | `GET /v1/generate/fhe` | 🔑 Starter+ |
+| `client.generate_ecc(bits=)` | `GET /v1/generate/ecc` | 🔑 |
+| `client.verify(n)` | `GET /v1/verify` | public |
+| `client.optimize_next(prime=, gap=)` | `GET /v1/optimize/next` | public |
+| `client.predict_gap(...)` | `GET /v1/predict/gap` | public |
+| `client.account()` | `GET /v1/account` | 🔑 |
+| `client.usage_history()` | `GET /v1/usage/history` | 🔑 |
+| `client.status()` | `GET /v1/status` | public |
+
+Every method returns the parsed JSON response as a `dict`.
+
+## Errors
+
+```python
+from ethoryx import EthoryxError, AuthError, RateLimitError, APIError
+
+try:
+    client.generate(bits=2048)
+except AuthError:
+    ...        # missing/invalid key, or tier too low (401/403)
+except RateLimitError:
+    ...        # 429 — back off and retry
+except APIError as e:
+    print(e.status, e.response)
+except EthoryxError:
+    ...        # network/other
+```
+
+## License
+
+MIT © Ethoryx Research

ethoryx-0.1.0/README.md

@@ -0,0 +1,90 @@
+# ethoryx
+
+Official Python client for the [Ethoryx](https://ethoryx.io) prime-generation API —
+structurally-guided primes for **RSA, FHE, zk-SNARKs, and NTT**, backed by the Ethoryx
+C/GMP core. Fewer Miller–Rabin tests, fewer candidates, same cryptographic strength.
+
+- API: `https://api.ethoryx.io` · [Docs](https://ethoryx.io/docs) · [Status](https://api.ethoryx.io/v1/status)
+
+## Install
+
+```bash
+pip install ethoryx
+```
+
+## Quick start
+
+```python
+import ethoryx
+
+client = ethoryx.Client(api_key="tg_your_key")   # or set ETHORYX_API_KEY
+
+# Generate primes
+prime = client.generate(bits=2048)
+rsa   = client.generate_rsa(bits=2048)
+pair  = client.generate_rsa_pair(bits=2048)      # matched (p, q)
+ntt   = client.generate_ntt(bits=256)
+fhe   = client.generate_fhe(bits=2048)           # Starter tier or above
+
+# Public endpoints — no API key required
+ethoryx.verify(999983)                           # {"is_prime": true, ...}
+ethoryx.optimize_next(prime=999983, gap=6)       # next-prime prediction
+ethoryx.status()                                 # version, benchmarks
+```
+
+Get a free key (100 calls/month) at <https://ethoryx.io/register>.
+
+## Authentication
+
+Pass your key to the client, or set it once in the environment:
+
+```bash
+export ETHORYX_API_KEY="tg_your_key"
+```
+
+```python
+client = ethoryx.Client()                 # picks up ETHORYX_API_KEY
+```
+
+The public endpoints (`verify`, `optimize_next`, `predict_gap`, `status`) work without a
+key. Everything under `generate*` and `account*` requires one.
+
+## API
+
+| Method | Endpoint | Auth |
+|--------|----------|------|
+| `client.generate(bits=, method=)` | `GET /v1/generate` | 🔑 |
+| `client.generate_rsa(bits=)` | `GET /v1/generate/rsa` | 🔑 |
+| `client.generate_rsa_pair(bits=)` | `GET /v1/generate/rsa-pair` | 🔑 |
+| `client.generate_ntt(bits=)` | `GET /v1/generate/ntt` | 🔑 |
+| `client.generate_fhe(bits=)` | `GET /v1/generate/fhe` | 🔑 Starter+ |
+| `client.generate_ecc(bits=)` | `GET /v1/generate/ecc` | 🔑 |
+| `client.verify(n)` | `GET /v1/verify` | public |
+| `client.optimize_next(prime=, gap=)` | `GET /v1/optimize/next` | public |
+| `client.predict_gap(...)` | `GET /v1/predict/gap` | public |
+| `client.account()` | `GET /v1/account` | 🔑 |
+| `client.usage_history()` | `GET /v1/usage/history` | 🔑 |
+| `client.status()` | `GET /v1/status` | public |
+
+Every method returns the parsed JSON response as a `dict`.
+
+## Errors
+
+```python
+from ethoryx import EthoryxError, AuthError, RateLimitError, APIError
+
+try:
+    client.generate(bits=2048)
+except AuthError:
+    ...        # missing/invalid key, or tier too low (401/403)
+except RateLimitError:
+    ...        # 429 — back off and retry
+except APIError as e:
+    print(e.status, e.response)
+except EthoryxError:
+    ...        # network/other
+```
+
+## License
+
+MIT © Ethoryx Research

ethoryx-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ethoryx"
+description = "Official Python client for the Ethoryx prime-generation API (RSA, FHE, zk-SNARK, and NTT primes)."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Ethoryx Research", email = "research@ethoryx.io" }]
+keywords = ["ethoryx", "prime", "rsa", "fhe", "zk-snark", "cryptography", "ntt", "number-theory", "primes"]
+dependencies = ["requests>=2.20"]
+dynamic = ["version"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Security :: Cryptography",
+  "Topic :: Scientific/Engineering :: Mathematics",
+]
+
+[project.urls]
+Homepage = "https://ethoryx.io"
+Documentation = "https://ethoryx.io/docs"
+Source = "https://github.com/Teshgty/ethoryx-python"
+"API Status" = "https://api.ethoryx.io/v1/status"
+
+[tool.hatch.version]
+path = "src/ethoryx/version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ethoryx"]

ethoryx-0.1.0/src/ethoryx/__init__.py

@@ -0,0 +1,57 @@
+"""
+Ethoryx — official Python client for the Ethoryx prime-generation API.
+
+    import ethoryx
+
+    client = ethoryx.Client(api_key="tg_...")   # or set ETHORYX_API_KEY
+    prime = client.generate(bits=2048)
+    rsa   = client.generate_rsa(bits=2048)
+
+    # Public endpoints need no key:
+    ethoryx.verify(999983)
+    ethoryx.status()
+
+Docs: https://ethoryx.io/docs
+"""
+from .client import DEFAULT_BASE_URL, Client
+from .errors import APIError, AuthError, EthoryxError, RateLimitError
+from .version import __version__
+
+__all__ = [
+    "Client",
+    "DEFAULT_BASE_URL",
+    "EthoryxError",
+    "APIError",
+    "AuthError",
+    "RateLimitError",
+    "status",
+    "verify",
+    "optimize_next",
+    "predict_gap",
+    "__version__",
+]
+
+
+def _public():
+    """A keyless client for the free/public endpoints."""
+    return Client(api_key=None)
+
+
+def status():
+    """API status, version, and benchmarks (public)."""
+    return _public().status()
+
+
+def verify(n):
+    """Check whether ``n`` is prime (public)."""
+    return _public().verify(n)
+
+
+def optimize_next(prime=None, gap=None, **params):
+    """Predict the next prime from the last prime + preceding gap (public)."""
+    return _public().optimize_next(prime=prime, gap=gap, **params)
+
+
+def predict_gap(**params):
+    """Predict the gap to the next prime (public)."""
+    return _public().predict_gap(**params)

ethoryx-0.1.0/src/ethoryx/client.py

@@ -0,0 +1,155 @@
+"""
+Ethoryx API client.
+
+A thin, well-behaved wrapper over the Ethoryx prime-generation API
+(https://api.ethoryx.io). Every method returns the parsed JSON response as a
+dict; failures raise a typed :class:`~ethoryx.errors.EthoryxError`.
+
+    import ethoryx
+    client = ethoryx.Client(api_key="tg_...")      # or set ETHORYX_API_KEY
+    prime = client.generate(bits=2048)
+"""
+import os
+
+import requests
+
+from .errors import APIError, AuthError, EthoryxError, RateLimitError
+from .version import __version__
+
+DEFAULT_BASE_URL = "https://api.ethoryx.io"
+
+__all__ = ["Client", "DEFAULT_BASE_URL"]
+
+
+class Client:
+    """Client for the Ethoryx API.
+
+    Args:
+        api_key: Your ``tg_...`` API key. Falls back to the ``ETHORYX_API_KEY``
+            environment variable. Not required for the public endpoints
+            (:meth:`verify`, :meth:`optimize_next`, :meth:`predict_gap`,
+            :meth:`status`).
+        base_url: Override the API host (default ``https://api.ethoryx.io``).
+        timeout: Per-request timeout in seconds (default 30).
+        session: An optional pre-configured ``requests.Session``.
+    """
+
+    def __init__(self, api_key=None, base_url=DEFAULT_BASE_URL, timeout=30, session=None):
+        self.api_key = api_key or os.environ.get("ETHORYX_API_KEY")
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = session or requests.Session()
+        self._session.headers.setdefault("User-Agent", "ethoryx-python/%s" % __version__)
+
+    # ── transport ────────────────────────────────────────────────────────────
+    def _request(self, method, path, params=None, json=None, auth=True):
+        headers = {}
+        if self.api_key:                       # always send the key when we have one
+            headers["X-API-Key"] = self.api_key
+        elif auth:                             # required but absent → fail clearly
+            raise AuthError(
+                "No API key. Pass api_key= or set ETHORYX_API_KEY. "
+                "Get one at https://ethoryx.io/register"
+            )
+        try:
+            resp = self._session.request(
+                method, self.base_url + path, params=params, json=json,
+                headers=headers, timeout=self.timeout,
+            )
+        except requests.RequestException as exc:
+            raise EthoryxError("request to %s failed: %s" % (path, exc)) from exc
+        return self._handle(resp)
+
+    @staticmethod
+    def _handle(resp):
+        try:
+            data = resp.json()
+        except ValueError:
+            data = {"error": resp.text}
+        if resp.status_code >= 400:
+            msg = (data.get("error") or data.get("message") or resp.reason
+                   if isinstance(data, dict) else resp.reason)
+            if resp.status_code in (401, 403):
+                raise AuthError(msg, status=resp.status_code, response=data)
+            if resp.status_code == 429:
+                raise RateLimitError(msg, status=resp.status_code, response=data)
+            raise APIError(msg, status=resp.status_code, response=data)
+        return data
+
+    def _get(self, path, params=None, auth=True):
+        return self._request("GET", path, params=params, auth=auth)
+
+    def _post(self, path, json=None, auth=True):
+        return self._request("POST", path, json=json, auth=auth)
+
+    # ── prime generation (X-API-Key required) ────────────────────────────────
+    def generate(self, bits=2048, method=None, **params):
+        """Generate a prime of ``bits`` bits. ``GET /v1/generate``."""
+        q = {"bits": bits, **params}
+        if method is not None:
+            q["method"] = method
+        return self._get("/v1/generate", q)
+
+    def generate_rsa(self, bits=2048, **params):
+        """Generate an RSA-suitable prime. ``GET /v1/generate/rsa``."""
+        return self._get("/v1/generate/rsa", {"bits": bits, **params})
+
+    def generate_rsa_pair(self, bits=2048, **params):
+        """Generate a matched RSA prime pair (p, q). ``GET /v1/generate/rsa-pair``."""
+        return self._get("/v1/generate/rsa-pair", {"bits": bits, **params})
+
+    def generate_ntt(self, bits=256, **params):
+        """Generate an NTT-friendly prime. ``GET /v1/generate/ntt``."""
+        return self._get("/v1/generate/ntt", {"bits": bits, **params})
+
+    def generate_fhe(self, bits=None, **params):
+        """Generate an FHE-suitable prime. ``GET /v1/generate/fhe`` (Starter tier+)."""
+        q = dict(params)
+        if bits is not None:
+            q["bits"] = bits
+        return self._get("/v1/generate/fhe", q)
+
+    def generate_ecc(self, bits=None, **params):
+        """Generate an ECC-suitable prime. ``GET /v1/generate/ecc``."""
+        q = dict(params)
+        if bits is not None:
+            q["bits"] = bits
+        return self._get("/v1/generate/ecc", q)
+
+    # ── optimization / prediction (free, public) ─────────────────────────────
+    def optimize_next(self, prime=None, gap=None, **params):
+        """Predict the next prime from the last prime + preceding gap.
+        ``GET /v1/optimize/next`` — free and public."""
+        q = dict(params)
+        if prime is not None:
+            q["prime"] = prime
+        if gap is not None:
+            q["gap"] = gap
+        return self._get("/v1/optimize/next", q, auth=False)
+
+    def predict_gap(self, **params):
+        """Predict the gap to the next prime. ``GET /v1/predict/gap``."""
+        return self._get("/v1/predict/gap", params, auth=False)
+
+    # ── verification (public) ────────────────────────────────────────────────
+    def verify(self, n):
+        """Check whether ``n`` is prime. ``GET /v1/verify`` — public, no key."""
+        return self._get("/v1/verify", {"n": str(n)}, auth=False)
+
+    # ── account ──────────────────────────────────────────────────────────────
+    def account(self):
+        """Your account, tier, and quota. ``GET /v1/account``."""
+        return self._get("/v1/account")
+
+    def account_profile(self):
+        """Account profile details. ``GET /v1/account/profile``."""
+        return self._get("/v1/account/profile")
+
+    def usage_history(self):
+        """Your recent API usage. ``GET /v1/usage/history``."""
+        return self._get("/v1/usage/history")
+
+    # ── status (public) ──────────────────────────────────────────────────────
+    def status(self):
+        """API status, version, and benchmarks. ``GET /v1/status`` — public."""
+        return self._get("/v1/status", auth=False)

ethoryx-0.1.0/src/ethoryx/errors.py

@@ -0,0 +1,22 @@
+"""Exceptions raised by the Ethoryx client."""
+
+
+class EthoryxError(Exception):
+    """Base class for all Ethoryx client errors."""
+
+    def __init__(self, message, status=None, response=None):
+        super().__init__(message)
+        self.status = status          # HTTP status code, when available
+        self.response = response      # parsed JSON body, when available
+
+
+class APIError(EthoryxError):
+    """The API returned a 4xx/5xx that isn't auth or rate-limit related."""
+
+
+class AuthError(EthoryxError):
+    """Missing/invalid API key, or the endpoint needs a higher tier (401/403)."""
+
+
+class RateLimitError(EthoryxError):
+    """Too many requests (429). Back off and retry."""

ethoryx-0.1.0/src/ethoryx/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

ethoryx-0.1.0/tests/test_client.py

@@ -0,0 +1,82 @@
+"""Offline tests — a fake session verifies URL/params/headers without any network."""
+import json
+
+import pytest
+
+import ethoryx
+from ethoryx import AuthError, RateLimitError, APIError
+
+
+class _Resp:
+    def __init__(self, status=200, body=None, text=""):
+        self.status_code = status
+        self._body = body
+        self.text = text
+        self.reason = "err"
+
+    def json(self):
+        if self._body is None:
+            raise ValueError("no json")
+        return self._body
+
+
+class _FakeSession:
+    """Records the last request and returns a queued response."""
+
+    def __init__(self, resp):
+        self.headers = {}
+        self.resp = resp
+        self.calls = []
+
+    def request(self, method, url, params=None, json=None, headers=None, timeout=None):
+        self.calls.append(dict(method=method, url=url, params=params,
+                               json=json, headers=headers))
+        return self.resp
+
+
+def _client(resp, **kw):
+    sess = _FakeSession(resp)
+    c = ethoryx.Client(session=sess, **kw)
+    return c, sess
+
+
+def test_generate_builds_url_and_sends_key():
+    c, s = _client(_Resp(body={"prime": "123"}), api_key="tg_test")
+    out = c.generate(bits=2048, method="standard")
+    assert out == {"prime": "123"}
+    call = s.calls[-1]
+    assert call["method"] == "GET"
+    assert call["url"].endswith("/v1/generate")
+    assert call["params"] == {"bits": 2048, "method": "standard"}
+    assert call["headers"]["X-API-Key"] == "tg_test"
+
+
+def test_authed_endpoint_without_key_raises():
+    c, _ = _client(_Resp(body={}))            # no api_key
+    with pytest.raises(AuthError):
+        c.generate(bits=512)
+
+
+def test_public_endpoint_needs_no_key():
+    c, s = _client(_Resp(body={"is_prime": True}))
+    assert c.verify(999983) == {"is_prime": True}
+    assert s.calls[-1]["params"] == {"n": "999983"}
+    assert "X-API-Key" not in s.calls[-1]["headers"]
+
+
+def test_error_mapping():
+    c, _ = _client(_Resp(status=429, body={"error": "slow down"}), api_key="tg")
+    with pytest.raises(RateLimitError):
+        c.generate()
+
+    c2, _ = _client(_Resp(status=403, body={"error": "tier too low"}), api_key="tg")
+    with pytest.raises(AuthError):
+        c2.generate_fhe(bits=2048)
+
+    c3, _ = _client(_Resp(status=500, body={"error": "boom"}), api_key="tg")
+    with pytest.raises(APIError):
+        c3.generate()
+
+
+def test_module_version():
+    assert isinstance(ethoryx.__version__, str) and ethoryx.__version__