aetherx-oracle 0.3.0__tar.gz

aetherx_oracle-0.3.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,87 @@
+# 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/aetherx/__init__.py

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

aetherx_oracle-0.3.0/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/aetherx_oracle.egg-info/PKG-INFO

@@ -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/aetherx_oracle.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+aetherx/__init__.py
+aetherx/client.py
+aetherx_oracle.egg-info/PKG-INFO
+aetherx_oracle.egg-info/SOURCES.txt
+aetherx_oracle.egg-info/dependency_links.txt
+aetherx_oracle.egg-info/requires.txt
+aetherx_oracle.egg-info/top_level.txt
+tests/test_sdk.py

aetherx_oracle-0.3.0/aetherx_oracle.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aetherx_oracle-0.3.0/aetherx_oracle.egg-info/requires.txt

@@ -0,0 +1,10 @@
+requests>=2.25.0
+pydantic>=2.0.0
+
+[async]
+httpx>=0.24.0
+
+[test]
+pytest>=7.0
+responses>=0.23
+httpx>=0.24.0

aetherx_oracle-0.3.0/aetherx_oracle.egg-info/top_level.txt

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

aetherx_oracle-0.3.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aetherx-oracle"
+version = "0.3.0"
+description = "Python SDK for the Aether-X Port Congestion Oracle API"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "Proprietary - Machine-to-Machine Data Distribution" }
+authors = [{ name = "Aether-X Oracle Engine" }]
+keywords = ["port", "congestion", "oracle", "logistics", "shipping", "quant", "freight"]
+dependencies = [
+    "requests>=2.25.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+async = ["httpx>=0.24.0"]
+test = ["pytest>=7.0", "responses>=0.23", "httpx>=0.24.0"]
+
+[project.urls]
+Homepage = "https://aether-x-oracle-production.up.railway.app"
+Documentation = "https://aether-x-oracle-production.up.railway.app/docs"
+Terms = "https://aether-x-oracle-production.up.railway.app/terms"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["aetherx*"]

aetherx_oracle-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aetherx_oracle-0.3.0/tests/test_sdk.py

@@ -0,0 +1,144 @@
+import asyncio
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+import httpx
+import pytest
+import requests
+import responses
+
+from aetherx import OracleClient, PortRisk
+
+HOST = "aether-x-port-congestion-oracle.p.rapidapi.com"
+URL = f"https://{HOST}/v1/port-risk"
+
+SAMPLE = {
+    "port_id": "BRSSZ",
+    "port_name": "Santos",
+    "country": "Brasil",
+    "congestion_score": 0.78,
+    "eta_delay_days": 1.6,
+    "waiting_vessels": 12,
+    "freight_volatility_index": 0.42,
+    "updated_at": "2026-09-17 15:46:53",
+}
+
+FALLBACK = {
+    "port_id": "ZZZ99",
+    "port_name": "Unknown Port (Global Estimate)",
+    "country": "Global",
+    "congestion_score": 0.45,
+    "eta_delay_days": 1.0,
+    "waiting_vessels": 6,
+    "freight_volatility_index": 0.35,
+    "updated_at": "2026-09-17 15:47:19",
+}
+
+
+def make_client() -> OracleClient:
+    return OracleClient(api_key="test-key")
+
+
+def test_empty_api_key_raises():
+    with pytest.raises(ValueError):
+        OracleClient(api_key="")
+
+
+def test_empty_port_id_raises():
+    with pytest.raises(ValueError):
+        make_client().get_port_risk("")
+
+
+@responses.activate
+def test_get_port_risk_parses_response():
+    responses.add(responses.GET, URL, json=SAMPLE, status=200)
+
+    risk = make_client().get_port_risk("BRSSZ")
+
+    assert isinstance(risk, PortRisk)
+    assert risk.port_id == "BRSSZ"
+    assert risk.port_name == "Santos"
+    assert risk.country == "Brasil"
+    assert risk.congestion_score == 0.78
+    assert risk.eta_delay_days == 1.6
+    assert risk.waiting_vessels == 12
+    assert risk.freight_volatility_index == 0.42
+    assert risk.updated_at == "2026-09-17 15:46:53"
+
+
+@responses.activate
+def test_sends_rapidapi_headers_and_query_param():
+    responses.add(responses.GET, URL, json=SAMPLE, status=200)
+
+    make_client().get_port_risk("BRSSZ")
+
+    request = responses.calls[0].request
+    assert request.headers["x-rapidapi-key"] == "test-key"
+    assert request.headers["x-rapidapi-host"] == HOST
+    assert "port_id=BRSSZ" in request.url
+
+
+@responses.activate
+def test_fallback_payload_parses():
+    responses.add(responses.GET, URL, json=FALLBACK, status=200)
+
+    risk = make_client().get_port_risk("ZZZ99")
+
+    assert risk.country == "Global"
+    assert risk.congestion_score == 0.45
+    assert risk.waiting_vessels == 6
+
+
+@responses.activate
+def test_http_error_is_raised():
+    responses.add(responses.GET, URL, json={"detail": "boom"}, status=500)
+
+    with pytest.raises(requests.HTTPError):
+        make_client().get_port_risk("BRSSZ")
+
+
+def _patch_httpx(monkeypatch, handler):
+    real_async_client = httpx.AsyncClient
+    transport = httpx.MockTransport(handler)
+
+    def factory(*args, **kwargs):
+        kwargs["transport"] = transport
+        return real_async_client(*args, **kwargs)
+
+    monkeypatch.setattr(httpx, "AsyncClient", factory)
+
+
+def test_get_port_risk_async_parses(monkeypatch):
+    def handler(request):
+        assert request.headers["x-rapidapi-key"] == "test-key"
+        assert request.headers["x-rapidapi-host"] == HOST
+        return httpx.Response(200, json=SAMPLE)
+
+    _patch_httpx(monkeypatch, handler)
+
+    risk = asyncio.run(make_client().get_port_risk_async("BRSSZ"))
+
+    assert risk.port_name == "Santos"
+    assert risk.waiting_vessels == 12
+
+
+def test_get_ports_risk_async_gathers_multiple(monkeypatch):
+    def handler(request):
+        port_id = dict(request.url.params)["port_id"]
+        payload = {**SAMPLE, "port_id": port_id, "port_name": f"Port {port_id}"}
+        return httpx.Response(200, json=payload)
+
+    _patch_httpx(monkeypatch, handler)
+
+    results = asyncio.run(
+        make_client().get_ports_risk_async(["BRSSZ", "CNSHA", "NLRTM"])
+    )
+
+    assert len(results) == 3
+    assert [r.port_id for r in results] == ["BRSSZ", "CNSHA", "NLRTM"]
+
+
+def test_get_ports_risk_async_empty_list():
+    assert asyncio.run(make_client().get_ports_risk_async([])) == []