aethex 0.1.0__py3-none-any.whl

aethex/__init__.py

@@ -0,0 +1,51 @@
+"""
+Aethex Python SDK.
+
+Quick start:
+
+    from aethex import AethexClient
+
+    client = AethexClient(api_key="aex_live_...")
+
+    verdict = client.cyber.analyze(events=[
+        {"type": "failed_login"},
+        {"type": "successful_login", "suspicious": True},
+        {"type": "privilege_escalation", "suspicious": True},
+    ])
+
+    print(verdict["final_severity"])
+
+Three product domains: cyber, finance, llm.
+Account operations on client.account.
+
+Full docs: https://github.com/aethexa1/aethexai
+"""
+
+from ._version import __version__
+
+from .client import AethexClient
+
+from .exceptions import (
+    AethexError,
+    AethexAuthError,
+    AethexConnectionError,
+    AethexNotFoundError,
+    AethexPermissionError,
+    AethexRateLimitError,
+    AethexServerError,
+    AethexValidationError,
+)
+
+
+__all__ = [
+    "__version__",
+    "AethexClient",
+    "AethexError",
+    "AethexAuthError",
+    "AethexConnectionError",
+    "AethexNotFoundError",
+    "AethexPermissionError",
+    "AethexRateLimitError",
+    "AethexServerError",
+    "AethexValidationError",
+]

aethex/_version.py

@@ -0,0 +1,15 @@
+"""
+Aethex Python SDK — single source of truth for version number.
+
+Imported by setup.py / pyproject.toml at build time, and by
+aethex/__init__.py at runtime so customers can introspect the
+SDK version they have installed (`aethex.__version__`).
+
+Bump on every PyPI release. Pre-1.0 follows 0.x.y where:
+  - x bumps for breaking changes (rare pre-1.0)
+  - y bumps for new features and bug fixes
+
+Post-1.0 we'll switch to strict semver.
+"""
+
+__version__ = "0.1.0"

aethex/client.py

@@ -0,0 +1,348 @@
+"""
+Aethex Python SDK — main client.
+
+Provides AethexClient: a unified interface to all three product
+domains (cyber, finance, llm) plus account-level operations
+(audit export, loss matrix, webhooks).
+
+Usage:
+    from aethex import AethexClient
+
+    client = AethexClient(api_key="aex_live_...")
+
+    # Cyber analysis
+    verdict = client.cyber.analyze(events=[
+        {"type": "failed_login"},
+        {"type": "successful_login", "suspicious": True},
+        {"type": "privilege_escalation", "suspicious": True},
+    ])
+    print(verdict["final_severity"])  # e.g. "CRITICAL"
+
+    # Finance analysis
+    verdict = client.finance.analyze(events=[
+        {"type": "ofac_full_match", "suspicious": True},
+        {"type": "sanctioned_geography_routing", "suspicious": True},
+    ])
+
+    # LLM safety analysis
+    verdict = client.llm.analyze(events=[
+        {"type": "external_document_retrieval"},
+        {"type": "instruction_override_detected", "suspicious": True},
+        {"type": "tool_use_data_exfiltration", "suspicious": True},
+    ])
+
+Implementation notes:
+  - Pure stdlib HTTP (urllib). No external dependencies. Customers
+    don't need to pip install requests just to use Aethex.
+  - One client instance is thread-safe for read-only attribute access
+    but should be created once and reused, not constructed per call.
+  - Default timeout: 30 seconds. Configurable per client or per call.
+  - All API errors map to typed exceptions in aethex.exceptions.
+"""
+
+import json
+from typing import Any, Dict, List, Optional
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from ._version  import __version__
+from .exceptions import (
+    AethexAuthError,
+    AethexConnectionError,
+    AethexError,
+    AethexNotFoundError,
+    AethexPermissionError,
+    AethexRateLimitError,
+    AethexServerError,
+    AethexValidationError,
+)
+
+
+# ─── defaults ──────────────────────────────────────────────
+
+DEFAULT_BASE_URL = "https://aethex-api-1yqe.onrender.com"
+DEFAULT_TIMEOUT  = 30
+USER_AGENT       = f"aethex-python/{__version__}"
+
+
+# ─── http core ─────────────────────────────────────────────
+
+def _raise_for_status(status: int, body: str) -> None:
+    """Map an HTTP status code to a typed AethexError."""
+    if status == 401:
+        raise AethexAuthError(
+            "API key invalid, missing, or revoked.",
+            status_code=status, response=body,
+        )
+    if status == 403:
+        raise AethexPermissionError(
+            "API key not scoped for this product domain.",
+            status_code=status, response=body,
+        )
+    if status == 404:
+        raise AethexNotFoundError(
+            "Resource not found.",
+            status_code=status, response=body,
+        )
+    if status == 429:
+        raise AethexRateLimitError(
+            "Rate limit exceeded.",
+            status_code=status, response=body,
+        )
+    if status == 400 or 405 <= status < 500:
+        raise AethexValidationError(
+            f"Request rejected ({status}): {body[:200]}",
+            status_code=status, response=body,
+        )
+    if 500 <= status < 600:
+        raise AethexServerError(
+            f"Aethex server error ({status}).",
+            status_code=status, response=body,
+        )
+    # Other unexpected status -- still surface it.
+    raise AethexError(
+        f"Unexpected HTTP {status}: {body[:200]}",
+        status_code=status, response=body,
+    )
+
+
+# ─── client ────────────────────────────────────────────────
+
+class AethexClient:
+    """
+    Main entry point for the Aethex SDK.
+
+    Args:
+        api_key:   your aex_live_... key (required)
+        base_url:  override the API endpoint (defaults to production)
+        timeout:   per-request timeout in seconds (default 30)
+    """
+
+    def __init__(
+        self,
+        api_key:  str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout:  int = DEFAULT_TIMEOUT,
+    ):
+        if not api_key or not isinstance(api_key, str):
+            raise ValueError("api_key must be a non-empty string")
+        if not api_key.startswith("aex_"):
+            raise ValueError(
+                "api_key has invalid format (expected to start with 'aex_')"
+            )
+
+        self._api_key  = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout  = timeout
+
+        # Sub-clients for each product domain
+        self.cyber   = _CyberAPI(self)
+        self.finance = _FinanceAPI(self)
+        self.llm     = _LLMAPI(self)
+
+        # Account-level operations
+        self.account = _AccountAPI(self)
+
+    # ─── internal HTTP ────────────────────────────────────
+
+    def _request(
+        self,
+        method:   str,
+        path:     str,
+        body:     Optional[Dict[str, Any]] = None,
+        timeout:  Optional[int]            = None,
+    ) -> Dict[str, Any]:
+        """
+        Internal HTTP helper. Customers should not call this directly --
+        use the typed methods on cyber/finance/llm/account instead.
+        """
+        url     = self._base_url + path
+        timeout = timeout or self._timeout
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "User-Agent":    USER_AGENT,
+            "Accept":        "application/json",
+        }
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        req = Request(url, data=data, method=method, headers=headers)
+
+        try:
+            with urlopen(req, timeout=timeout) as resp:
+                response_body = resp.read().decode("utf-8")
+                if resp.status >= 400:
+                    _raise_for_status(resp.status, response_body)
+                return json.loads(response_body) if response_body else {}
+        except HTTPError as e:
+            response_body = ""
+            try:
+                response_body = e.read().decode("utf-8", errors="replace")
+            except Exception:
+                pass
+            _raise_for_status(e.code, response_body)
+            raise  # _raise_for_status always raises, but keep type checker happy
+        except URLError as e:
+            raise AethexConnectionError(
+                f"Network error reaching Aethex: {e.reason}"
+            ) from e
+        except Exception as e:
+            if isinstance(e, AethexError):
+                raise
+            raise AethexConnectionError(
+                f"Unexpected SDK error: {type(e).__name__}: {e}"
+            ) from e
+
+    # ─── repr ─────────────────────────────────────────────
+
+    def __repr__(self) -> str:
+        # Don't leak the API key in repr.
+        suffix = self._api_key[-4:] if self._api_key else "????"
+        return f"AethexClient(api_key=aex_live_***{suffix}, base_url={self._base_url!r})"
+
+
+# ─── sub-clients ───────────────────────────────────────────
+
+class _DomainAPI:
+    """Shared base for cyber/finance/llm domain sub-clients."""
+
+    _path = ""  # subclass override
+
+    def __init__(self, client: AethexClient):
+        self._client = client
+
+    def analyze(
+        self,
+        events:     List[Dict[str, Any]],
+        session_id: Optional[str]       = None,
+        timestamp:  Optional[str]       = None,
+        frames:     Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Run a sequence of events through Aethex's 10 ancient engines.
+
+        Args:
+            events:     list of {"type": "...", "suspicious": bool} dicts
+            session_id: optional client-supplied session identifier
+            timestamp:  optional ISO 8601 timestamp (defaults to now)
+            frames:     optional list of perspective frames
+
+        Returns:
+            verdict dict containing final_severity, final_confidence,
+            engines (per-engine outputs), nyaya reasoning chain,
+            chakravyuha layers, and recommended action.
+        """
+        body: Dict[str, Any] = {"events": events}
+        if session_id is not None: body["session_id"] = session_id
+        if timestamp  is not None: body["timestamp"]  = timestamp
+        if frames     is not None: body["frames"]     = frames
+
+        return self._client._request("POST", f"{self._path}/analyze", body=body)
+
+
+class _CyberAPI(_DomainAPI):
+    """Cyber threat analysis. Use for SOC alerts, intrusion patterns, insider threats."""
+    _path = "/api/cyber"
+
+
+class _FinanceAPI(_DomainAPI):
+    """Financial fraud / AML / sanctions analysis."""
+    _path = "/api/finance"
+
+
+class _LLMAPI(_DomainAPI):
+    """LLM agent safety analysis. Translates LLM event types to engine vocabulary."""
+    _path = "/api/llm"
+
+    def vocabulary(self) -> Dict[str, Any]:
+        """
+        Return the canonical LLM event-type -> cyber-vocabulary
+        mapping. Useful for understanding which LLM events Aethex
+        recognizes and what their engine-level equivalents are.
+        """
+        return self._client._request("GET", "/api/llm/vocabulary")
+
+
+class _AccountAPI:
+    """Account-level operations: audit export, loss matrix, webhooks."""
+
+    def __init__(self, client: AethexClient):
+        self._client = client
+
+    # --- audit ---
+
+    def export_audit(
+        self,
+        format: str          = "json",
+        from_:  Optional[str] = None,
+        to:     Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Export the calling key's audit log.
+
+        Args:
+            format: "json" (default) or "csv"
+            from_:  ISO 8601 start (e.g. "2026-01-01")
+            to:     ISO 8601 end
+        """
+        params = []
+        if format: params.append(f"format={format}")
+        if from_:  params.append(f"from={from_}")
+        if to:     params.append(f"to={to}")
+        path = "/api/audit/export" + ("?" + "&".join(params) if params else "")
+        return self._client._request("GET", path)
+
+    # --- loss matrix ---
+
+    def get_loss_matrix(self) -> Dict[str, Any]:
+        """Return the calling key's current loss matrix."""
+        return self._client._request("GET", "/api/keys/me/loss-matrix")
+
+    def replace_loss_matrix(self, matrix: Dict[str, float]) -> Dict[str, Any]:
+        """Replace the entire loss matrix with the supplied dict."""
+        return self._client._request(
+            "PUT", "/api/keys/me/loss-matrix", body={"matrix": matrix},
+        )
+
+    def patch_loss_matrix(self, matrix: Dict[str, float]) -> Dict[str, Any]:
+        """Merge the supplied entries into the existing loss matrix."""
+        return self._client._request(
+            "PATCH", "/api/keys/me/loss-matrix", body={"matrix": matrix},
+        )
+
+    # --- webhooks ---
+
+    def list_webhooks(self) -> List[Dict[str, Any]]:
+        """List webhooks registered to the calling key."""
+        return self._client._request("GET", "/api/keys/me/webhooks")
+
+    def create_webhook(
+        self,
+        url:       str,
+        threshold: str = "CRITICAL",
+        name:      str = "default",
+    ) -> Dict[str, Any]:
+        """
+        Register a new webhook. The plaintext secret is returned ONCE
+        in the response. Save it immediately -- it is not retrievable
+        afterwards.
+        """
+        return self._client._request(
+            "POST", "/api/keys/me/webhooks",
+            body={"url": url, "threshold": threshold, "name": name},
+        )
+
+    def delete_webhook(self, webhook_id: int) -> Dict[str, Any]:
+        """Delete a webhook by id."""
+        return self._client._request(
+            "DELETE", f"/api/keys/me/webhooks/{webhook_id}",
+        )
+
+    def list_deliveries(self, webhook_id: int, limit: int = 50) -> List[Dict[str, Any]]:
+        """List recent delivery attempts for a webhook."""
+        return self._client._request(
+            "GET",
+            f"/api/keys/me/webhooks/{webhook_id}/deliveries?limit={limit}",
+        )

aethex/exceptions.py

@@ -0,0 +1,71 @@
+"""
+Aethex SDK — exception hierarchy.
+
+Customers catch these in their integration code. The hierarchy
+lets them either catch broadly (every Aethex error) or narrowly
+(only auth, only rate-limit, etc).
+
+  AethexError                       -- root; catch this for any SDK error
+    AethexAuthError                 -- 401: bad / missing / revoked API key
+    AethexPermissionError           -- 403: key not scoped for this product
+    AethexNotFoundError             -- 404: resource doesn't exist
+    AethexRateLimitError            -- 429: over rate limit
+    AethexValidationError           -- 400: malformed request
+    AethexServerError               -- 5xx: Aethex side broke
+    AethexConnectionError           -- network failure, timeout, DNS, SSL
+"""
+
+from typing import Optional
+
+
+class AethexError(Exception):
+    """
+    Base class for every error this SDK raises.
+    Carries the HTTP status code (if applicable) and the response
+    body returned by the Aethex API for debugging.
+    """
+
+    def __init__(
+        self,
+        message:     str,
+        status_code: Optional[int]  = None,
+        response:    Optional[str]  = None,
+    ):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response    = response
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}("
+            f"message={str(self)!r}, "
+            f"status_code={self.status_code!r})"
+        )
+
+
+class AethexAuthError(AethexError):
+    """401 — API key missing, malformed, or revoked."""
+
+
+class AethexPermissionError(AethexError):
+    """403 — API key valid but not scoped for the requested product."""
+
+
+class AethexNotFoundError(AethexError):
+    """404 — resource (webhook, audit entry, etc) does not exist."""
+
+
+class AethexRateLimitError(AethexError):
+    """429 — over the per-key rate limit. Customer should back off."""
+
+
+class AethexValidationError(AethexError):
+    """400 — request body malformed (bad event types, missing fields)."""
+
+
+class AethexServerError(AethexError):
+    """5xx — Aethex side broke. Retry may help."""
+
+
+class AethexConnectionError(AethexError):
+    """Network-layer failure: timeout, DNS error, SSL error, connection refused."""

aethex-0.1.0.dist-info/METADATA

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: aethex
+Version: 0.1.0
+Summary: Official Python SDK for Aethex — multi-domain AI threat verification (cyber, finance, LLM safety) with explainable reasoning chains.
+Author-email: Aethex <lizsanchez@aethexai.net>
+License: MIT
+Project-URL: Homepage, https://github.com/aethexa1/aethexai
+Project-URL: Documentation, https://github.com/aethexa1/aethexai/tree/main/docs
+Project-URL: Repository, https://github.com/aethexa1/aethexai
+Project-URL: Issues, https://github.com/aethexa1/aethexai/issues
+Keywords: ai-safety,threat-detection,llm-safety,cybersecurity,fraud-detection,aml,fatf,mitre-attack,explainable-ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+
+# Aethex Python SDK
+
+Official Python client for [Aethex](https://github.com/aethexa1/aethexai) —
+a multi-domain AI threat verification API with explainable reasoning chains.
+
+Aethex runs threat events through 10 deterministic reasoning engines and
+returns a verdict with severity, confidence, and a traceable reasoning
+chain. Same engines work across three product domains:
+
+- **Cyber** — SOC alerts, intrusion patterns, insider threats
+- **Finance** — AML, sanctions screening, FATF typologies
+- **LLM safety** — agent failure modes, prompt injection, tool-use exfiltration
+
+Verdicts are deterministic. Same input produces the same output every
+time, with the same audit trail. This is the core differentiator vs
+LLM-only detection systems.
+
+## Install
+
+```bash
+pip install aethex
+```
+
+No external dependencies. Pure stdlib (urllib, json).
+
+## Quick start
+
+```python
+from aethex import AethexClient
+
+client = AethexClient(api_key="aex_live_...")
+
+# Cyber threat analysis
+verdict = client.cyber.analyze(events=[
+    {"type": "failed_login"},
+    {"type": "failed_login"},
+    {"type": "successful_login", "suspicious": True},
+    {"type": "privilege_escalation", "suspicious": True},
+    {"type": "lateral_movement", "suspicious": True},
+])
+
+print(verdict["final_severity"])    # CRITICAL
+print(verdict["final_confidence"])  # 0.92
+print(verdict["verdict"])           # human-readable summary
+```
+
+## Three product domains
+
+```python
+# Cyber
+client.cyber.analyze(events=[...])
+
+# Finance (AML / sanctions / fraud)
+client.finance.analyze(events=[
+    {"type": "ofac_full_match", "suspicious": True},
+    {"type": "sanctioned_geography_routing", "suspicious": True},
+])
+
+# LLM safety
+client.llm.analyze(events=[
+    {"type": "external_document_retrieval"},
+    {"type": "instruction_override_detected", "suspicious": True},
+    {"type": "tool_use_data_exfiltration", "suspicious": True},
+])
+
+# Discover the canonical LLM event vocabulary
+mapping = client.llm.vocabulary()
+```
+
+## Account operations
+
+```python
+# Audit log export (compliance)
+audit = client.account.export_audit(format="json", from_="2026-01-01")
+
+# Customer-tunable severity weighting
+client.account.replace_loss_matrix({
+    "failed_login":      0.5,   # downweight noisy events
+    "external_transfer": 5.0,   # upweight critical events
+})
+
+# Webhooks for real-time alerts
+webhook = client.account.create_webhook(
+    url="https://your-app.com/aethex-webhook",
+    threshold="CRITICAL",
+)
+# Save webhook["secret"] now -- it's shown only once.
+
+deliveries = client.account.list_deliveries(webhook["id"])
+```
+
+## Error handling
+
+```python
+from aethex import (
+    AethexAuthError,
+    AethexRateLimitError,
+    AethexValidationError,
+    AethexConnectionError,
+    AethexError,
+)
+
+try:
+    verdict = client.cyber.analyze(events=[...])
+except AethexAuthError:
+    # 401 — bad / missing / revoked API key
+    ...
+except AethexRateLimitError:
+    # 429 — back off and retry
+    ...
+except AethexValidationError as e:
+    # 400 — request body malformed
+    print(e.response)
+except AethexConnectionError:
+    # network / timeout / DNS / SSL
+    ...
+except AethexError:
+    # catch-all for anything Aethex-related
+    ...
+```
+
+## What you get back
+
+Every `analyze` call returns a verdict dict with:
+
+- `final_severity` — `LOW` / `MEDIUM` / `HIGH` / `CRITICAL`
+- `final_confidence` — 0.0 to 1.0
+- `verdict` — human-readable summary
+- `action` — recommended operational response
+- `engines` — per-engine outputs from all 10 reasoning engines
+- `nyaya` — the formal reasoning chain that produced the verdict
+- `chakravyuha` — defense-in-depth layers breached
+- `disagreement` — when engines disagree, the system surfaces uncertainty
+  rather than producing false confidence
+
+See the [API documentation](https://github.com/aethexa1/aethexai)
+for the full verdict shape.
+
+## Configuration
+
+```python
+client = AethexClient(
+    api_key="aex_live_...",
+    base_url="https://aethex-api-1yqe.onrender.com",  # default
+    timeout=30,                                       # seconds
+)
+```
+
+## Status
+
+Alpha. APIs are stabilizing. Breaking changes possible until 1.0.
+
+## License
+
+MIT. See LICENSE for details.
+
+---
+
+Built by Aethex. Questions: open an issue at the
+[GitHub repo](https://github.com/aethexa1/aethexai/issues).

aethex-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+aethex/__init__.py,sha256=tClu2EPjtkU5oxDjCWSmPNx3LPTBLookib6VkalY63o,1060
+aethex/_version.py,sha256=qLVCe9Pq4w9YtTvXGkK-5M-YLI3POEYf0_oy78UaEdc,465
+aethex/client.py,sha256=4fvszcu3jt98IWIZGtxZzmyjOHH09rFyyHHRYVHZv8Y,12354
+aethex/exceptions.py,sha256=4x4JMGk3G5_JfnPOhb7ThILjHXCQ3vkm1-SbB6GbwsI,2233
+aethex-0.1.0.dist-info/METADATA,sha256=6W9TsOtnmbg9kzKmHhycYJcCIq9rwBbR5dqL2YyGtbA,5865
+aethex-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+aethex-0.1.0.dist-info/top_level.txt,sha256=eZHPcDAoPcEcBzMeQcgMdB05fMmcS-9g7JjUxG_i9VY,7
+aethex-0.1.0.dist-info/RECORD,,

aethex-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

aethex-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+aethex