ethoryx 0.1.0__py3-none-any.whl

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/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/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/version.py

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

ethoryx-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+ethoryx/__init__.py,sha256=_Fc2fiINki2Q5zqXeaTDN8h4KFnu3T9qceS2i5xcr3k,1367
+ethoryx/client.py,sha256=aOUYZTYo1UV9I5wmhwlQme-Jxj9THMhpgpdJn5GhuGo,7040
+ethoryx/errors.py,sha256=7SsevVf449kWE2X-ri8CjC8iOTxnP6nByJ4SgMpm-uA,690
+ethoryx/version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+ethoryx-0.1.0.dist-info/METADATA,sha256=HZBj6tg7NHSQ6izexFwfDqG1qXHIcpTvrYBy9VpQgXE,3865
+ethoryx-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+ethoryx-0.1.0.dist-info/licenses/LICENSE,sha256=_mPHZcSJMyQfR7EAPi7QOr9BCZ5wSMgeI0PyiAwqZW8,1090
+ethoryx-0.1.0.dist-info/RECORD,,

ethoryx-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

ethoryx-0.1.0.dist-info/licenses/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.