aetherx-oracle 0.3.0__py3-none-any.whl

aetherx/__init__.py

@@ -0,0 +1,5 @@
+from aetherx.client import OracleClient, PortRisk
+
+__version__ = "0.3.0"
+
+__all__ = ["OracleClient", "PortRisk", "__version__"]

aetherx/client.py

@@ -0,0 +1,118 @@
+"""Aether-X Port Congestion Oracle - Python SDK client."""
+
+import asyncio
+from typing import List, Optional
+
+import requests
+from pydantic import BaseModel, Field
+
+DEFAULT_RAPIDAPI_HOST = "aether-x-port-congestion-oracle.p.rapidapi.com"
+RISK_ENDPOINT = "/v1/port-risk"
+
+
+class PortRisk(BaseModel):
+    """Predictive congestion signal for a single port."""
+
+    port_id: str = Field(..., description="UN/LOCODE do porto (ex: BRSSZ)")
+    port_name: str = Field(..., description="Nome do porto")
+    country: str = Field(..., description="País do porto")
+    congestion_score: float = Field(..., description="Score de congestão (0.0 a 1.0)")
+    eta_delay_days: float = Field(..., description="Atraso estimado de ETA em dias")
+    waiting_vessels: int = Field(..., description="Navios aguardando/ancorados")
+    freight_volatility_index: float = Field(..., description="Índice de volatilidade de frete")
+    updated_at: str = Field(..., description="Timestamp da última atualização")
+
+
+class OracleClient:
+    """Cliente para a API Aether-X Port Congestion Oracle (via RapidAPI).
+
+    Exemplo:
+        >>> from aetherx import OracleClient
+        >>> client = OracleClient(api_key="SUA_RAPIDAPI_KEY")
+        >>> risk = client.get_port_risk("BRSSZ")
+        >>> print(risk.congestion_score, risk.waiting_vessels)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        host: str = DEFAULT_RAPIDAPI_HOST,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key é obrigatória (sua chave da RapidAPI).")
+
+        self.api_key = api_key
+        self.host = host
+        self.base_url = (base_url or f"https://{host}").rstrip("/")
+        self.timeout = timeout
+
+    def get_port_risk(self, port_id: str) -> PortRisk:
+        """Retorna o sinal preditivo de congestão para um porto.
+
+        Args:
+            port_id: Código UN/LOCODE do porto (ex: "BRSSZ", "CNSHA").
+
+        Returns:
+            PortRisk com acesso direto via atributo.
+
+        Raises:
+            ValueError: se port_id for vazio.
+            requests.HTTPError: se a API retornar um status de erro.
+        """
+        url, headers, params = self._build_request(port_id)
+        response = requests.get(
+            url, headers=headers, params=params, timeout=self.timeout
+        )
+        response.raise_for_status()
+        return PortRisk.model_validate(response.json())
+
+    async def get_port_risk_async(self, port_id: str) -> PortRisk:
+        """Versão assíncrona de :meth:`get_port_risk` (requer o extra ``async``).
+
+        Uso:
+            >>> import asyncio
+            >>> client = OracleClient(api_key="SUA_RAPIDAPI_KEY")
+            >>> risk = asyncio.run(client.get_port_risk_async("BRSSZ"))
+
+        Instale com: ``pip install aetherx-oracle[async]``
+        """
+        try:
+            import httpx
+        except ImportError as exc:  # pragma: no cover - depende do ambiente
+            raise ImportError(
+                "httpx é necessário para métodos assíncronos. "
+                "Instale com: pip install aetherx-oracle[async]"
+            ) from exc
+
+        url, headers, params = self._build_request(port_id)
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.get(url, headers=headers, params=params)
+            response.raise_for_status()
+            return PortRisk.model_validate(response.json())
+
+    async def get_ports_risk_async(self, port_ids: List[str]) -> List[PortRisk]:
+        """Consulta vários portos em paralelo via ``asyncio.gather``.
+
+        Ideal para fundos quantitativos e bots que monitoram uma carteira de portos.
+        """
+        if not port_ids:
+            return []
+        return list(
+            await asyncio.gather(
+                *(self.get_port_risk_async(port_id) for port_id in port_ids)
+            )
+        )
+
+    def _build_request(self, port_id: str):
+        if not port_id:
+            raise ValueError("port_id é obrigatório (ex: 'BRSSZ').")
+
+        url = f"{self.base_url}{RISK_ENDPOINT}"
+        headers = {
+            "x-rapidapi-key": self.api_key,
+            "x-rapidapi-host": self.host,
+        }
+        params = {"port_id": port_id}
+        return url, headers, params

aetherx_oracle-0.3.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: aetherx-oracle
+Version: 0.3.0
+Summary: Python SDK for the Aether-X Port Congestion Oracle API
+Author: Aether-X Oracle Engine
+License: Proprietary - Machine-to-Machine Data Distribution
+Project-URL: Homepage, https://aether-x-oracle-production.up.railway.app
+Project-URL: Documentation, https://aether-x-oracle-production.up.railway.app/docs
+Project-URL: Terms, https://aether-x-oracle-production.up.railway.app/terms
+Keywords: port,congestion,oracle,logistics,shipping,quant,freight
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: async
+Requires-Dist: httpx>=0.24.0; extra == "async"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: responses>=0.23; extra == "test"
+Requires-Dist: httpx>=0.24.0; extra == "test"
+
+# aetherx-oracle
+
+SDK Python oficial para a **Aether-X Port Congestion Oracle API** — sinais preditivos de congestão portuária, atraso de ETA e volatilidade de frete para portos globais.
+
+## Instalação
+
+```bash
+pip install aetherx-oracle
+```
+
+## Uso rápido
+
+```python
+from aetherx import OracleClient
+
+client = OracleClient(api_key="SUA_RAPIDAPI_KEY")
+
+risk = client.get_port_risk("BRSSZ")
+
+print(risk.port_name)                 # Santos
+print(risk.country)                   # Brasil
+print(risk.congestion_score)          # 0.78
+print(risk.eta_delay_days)            # 1.6
+print(risk.waiting_vessels)           # 12
+print(risk.freight_volatility_index)  # 0.42
+print(risk.updated_at)                # 2026-09-17 15:46:53
+```
+
+## Campos retornados (`PortRisk`)
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `port_id` | `str` | UN/LOCODE do porto (ex: `BRSSZ`) |
+| `port_name` | `str` | Nome do porto |
+| `country` | `str` | País do porto |
+| `congestion_score` | `float` | Score de congestão (0.0 a 1.0) |
+| `eta_delay_days` | `float` | Atraso estimado de ETA em dias |
+| `waiting_vessels` | `int` | Navios aguardando/ancorados |
+| `freight_volatility_index` | `float` | Índice de volatilidade de frete |
+| `updated_at` | `str` | Timestamp da última atualização |
+
+## Configuração avançada
+
+```python
+client = OracleClient(
+    api_key="SUA_RAPIDAPI_KEY",
+    host="aether-x-port-congestion-oracle.p.rapidapi.com",  # default
+    timeout=30.0,                                            # segundos
+)
+```
+
+## Portos suportados
+
+Portos com dados de exemplo: `BRSSZ`, `BRRIO`, `CNSHA`, `CNNGB`, `SGSIN`, `NLRTM`, `USLAX`, `USNYC`, `DEHAM`, `MPTNG`, `AEDXB`, `KRPUS`, `GBLGP`, `ZACPT`, `MXZLO`.
+
+Portos não cadastrados retornam uma estimativa global (`country="Global"`).
+
+## Uso assíncrono (async)
+
+Para consultar múltiplos portos em paralelo (ideal para bots e fundos quantitativos). Requer o extra `async`:
+
+```bash
+pip install "aetherx-oracle[async]"
+```
+
+```python
+import asyncio
+from aetherx import OracleClient
+
+async def main():
+    client = OracleClient(api_key="SUA_RAPIDAPI_KEY")
+
+    # Um porto
+    risk = await client.get_port_risk_async("BRSSZ")
+    print(risk.congestion_score)
+
+    # Vários portos em paralelo
+    risks = await client.get_ports_risk_async(["BRSSZ", "CNSHA", "NLRTM"])
+    for r in risks:
+        print(r.port_id, r.congestion_score)
+
+asyncio.run(main())
+```
+
+## Termos de uso
+
+Os sinais são fornecidos "AS IS", sem garantia e **não constituem aconselhamento de investimento**. Consulte os [Termos de Serviço](https://aether-x-oracle-production.up.railway.app/terms).

aetherx_oracle-0.3.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+aetherx/__init__.py,sha256=Ikx1KnIHbPfXJGo9FDUAWbL5x-z0W1lqHU4Tu3wTZfQ,128
+aetherx/client.py,sha256=CuXph0_Jj_NRZnF33YcHiY0wN0E8EKen0TX_drFWfxs,4310
+aetherx_oracle-0.3.0.dist-info/METADATA,sha256=zmL21LONdFv3FNAwAOd1qFDw0rc079p0D-lOi7IADEc,3487
+aetherx_oracle-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+aetherx_oracle-0.3.0.dist-info/top_level.txt,sha256=jFkXoJMGdDpj1pdc3rxjTtlYDCBNCyzJklBUUrtdBbc,8
+aetherx_oracle-0.3.0.dist-info/RECORD,,

aetherx_oracle-0.3.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
+

aetherx_oracle-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+aetherx