poelis-sdk 0.2.1__tar.gz → 0.3.0__tar.gz

{poelis_sdk-0.2.1 → poelis_sdk-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: poelis-sdk
-Version: 0.2.1
+Version: 0.3.0
 Summary: Official Python SDK for Poelis
 Project-URL: Homepage, https://poelis.com
 Project-URL: Source, https://github.com/PoelisTechnologies/poelis-python-sdk
@@ -60,6 +60,24 @@ export POELIS_ORG_ID=tenant_id_001
 ```
 
 
+### How authentication works
+
+The SDK does not talk to Auth0. It sends your API key directly to the Poelis backend for validation on every request.
+
+- Default headers sent by the SDK:
+
+  - `X-API-Key: <api_key>` (and `X-Poelis-Api-Key` as a compatibility alias)
+  - `Authorization: Api-Key <api_key>` (compatibility for gateways expecting Authorization-only)
+  - `X-Poelis-Org: <org_id>`
+
+You can opt into Bearer mode (legacy) by setting `POELIS_AUTH_MODE=bearer`, which will send:
+
+  - `Authorization: Bearer <api_key>`
+  - `X-Poelis-Org: <org_id>`
+
+The backend validates the API key against your organization, applies authorization and filtering, and returns data.
+
+
 ## Dot-path browser (Notebook UX)
 
 The SDK exposes a dot-path browser for easy exploration:
@@ -69,7 +87,7 @@ client.browser  # then use TAB to explore
 # client.browser.<workspace>.<product>.<item>.<child>.properties
 ```
 
-See the example notebook in `notebooks/try_poelis_sdk.ipynb` for an end-to-end walkthrough (authentication, listing workspaces/products/items, and simple search queries).
+See the example notebook in `notebooks/try_poelis_sdk.ipynb` for an end-to-end walkthrough (authentication, listing workspaces/products/items, and simple search queries). The client defaults to `https://api.poelis.ai` unless `POELIS_BASE_URL` is set.
 
 ## Requirements
 

{poelis_sdk-0.2.1 → poelis_sdk-0.3.0}/README.md

@@ -37,6 +37,24 @@ export POELIS_ORG_ID=tenant_id_001
 ```
 
 
+### How authentication works
+
+The SDK does not talk to Auth0. It sends your API key directly to the Poelis backend for validation on every request.
+
+- Default headers sent by the SDK:
+
+  - `X-API-Key: <api_key>` (and `X-Poelis-Api-Key` as a compatibility alias)
+  - `Authorization: Api-Key <api_key>` (compatibility for gateways expecting Authorization-only)
+  - `X-Poelis-Org: <org_id>`
+
+You can opt into Bearer mode (legacy) by setting `POELIS_AUTH_MODE=bearer`, which will send:
+
+  - `Authorization: Bearer <api_key>`
+  - `X-Poelis-Org: <org_id>`
+
+The backend validates the API key against your organization, applies authorization and filtering, and returns data.
+
+
 ## Dot-path browser (Notebook UX)
 
 The SDK exposes a dot-path browser for easy exploration:
@@ -46,7 +64,7 @@ client.browser  # then use TAB to explore
 # client.browser.<workspace>.<product>.<item>.<child>.properties
 ```
 
-See the example notebook in `notebooks/try_poelis_sdk.ipynb` for an end-to-end walkthrough (authentication, listing workspaces/products/items, and simple search queries).
+See the example notebook in `notebooks/try_poelis_sdk.ipynb` for an end-to-end walkthrough (authentication, listing workspaces/products/items, and simple search queries). The client defaults to `https://api.poelis.ai` unless `POELIS_BASE_URL` is set.
 
 ## Requirements
 

{poelis_sdk-0.2.1 → poelis_sdk-0.3.0}/notebooks/try_poelis_sdk.ipynb

@@ -68,7 +68,7 @@
    "source": [
     "## 2. Authentication Setup\n",
     "\n",
-    "Before you can use the SDK, you need to obtain your API credentials from the Poelis web interface.\n",
+    "Before you can use the SDK, obtain your API credentials from the Poelis web interface.\n",
     "\n",
     "### Getting Your Credentials\n",
     "\n",
@@ -97,23 +97,33 @@
     "\n",
     "There are two ways to initialize the Poelis client:\n",
     "\n",
-    "### Method 1: Direct Initialization (Simplified)\n",
-    "\n",
-    "```python\n",
-    "# Simple usage with defaults\n",
-    "client = PoelisClient(\n",
-    "    api_key=\"poelis_live_A1B2C3...\",\n",
-    "    org_id=\"tenant_id_001\"\n",
-    ")\n",
-    "```\n",
-    "\n",
+    "### Method 1: Direct Initialization (Simplified)\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Manual initialization (replace with your credentials)\n",
+    "poelis = PoelisClient(\n",
+    "    api_key=\"your_api_key_here\",\n",
+    "    org_id=\"your_org_id_here\"\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
     "### Method 2: From Environment Variables (Recommended)\n",
     "\n",
     "```python\n",
     "client = PoelisClient.from_env()\n",
     "```\n",
     "\n",
-    "This method automatically reads the `POELIS_API_KEY` and `POELIS_ORG_ID` environment variables.\n"
+    "This method automatically reads the `POELIS_API_KEY` and `POELIS_ORG_ID` environment variables."
    ]
   },
   {
@@ -128,19 +138,14 @@
     "\n",
     "try:\n",
     "    # Try to initialize from environment variables first\n",
-    "    client = PoelisClient.from_env()\n",
+    "    poelis = PoelisClient.from_env()\n",
     "    print(\"✅ Client initialized from environment variables\")\n",
     "    print(f\"Base URL: {client.base_url}\")\n",
     "    print(f\"Organization ID: {client.org_id}\")\n",
     "except ValueError as e:\n",
     "    print(f\"❌ Environment variables not set: {e}\")\n",
     "    print(\"Please set POELIS_API_KEY and POELIS_ORG_ID (POELIS_BASE_URL is optional)\")\n",
-    "    \n",
-    "# Fallback to manual initialization (replace with your credentials)\n",
-    "client = PoelisClient(\n",
-    "    api_key=\"your_api_key_here\",\n",
-    "    org_id=\"your_org_id_here\"\n",
-    ")\n"
+    "    \n"
    ]
   },
   {
@@ -171,7 +176,7 @@
     "from poelis_sdk import PoelisClient\n",
     "\n",
     "# 1) Create the client\n",
-    "client = PoelisClient(\n",
+    "poelis = PoelisClient(\n",
     "    api_key=\"YOUR_API_KEY\",\n",
     "    org_id=\"YOUR_ORG_ID\",\n",
     ")\n",
@@ -180,19 +185,41 @@
     "# - Type: client.browser. and press TAB to see workspaces\n",
     "# - Then: client.browser.<workspace>. and TAB to see products\n",
     "# - Then: client.browser.<workspace>.<product>. and TAB to see items\n",
-    "# - On an item, TAB shows child items and property keys\n",
-    "\n",
+    "# - On an item, TAB shows child items and property keys"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
     "# 3) Access a property’s value and category via dot paths\n",
     "# Example (replace names with your actual names shown by TAB):\n",
-    "workspace = client.browser.UH2_Workspace\n",
+    "workspace = poelis.browser.UH2_Workspace"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
     "val = workspace.LH2_Tank.cold_box.clv.mass.value\n",
     "cat = workspace.LH2_Tank.cold_box.clv.mass.category\n",
     "\n",
     "print(\"property value:\", val)\n",
-    "print(\"property category:\", cat)\n",
-    "\n",
+    "print(\"property category:\", cat)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
     "# 4) Go deeper into child items if needed (TAB will suggest only item/property names)\n",
-    "inner = client.browser.UH2_Workspace.LH2_Tank.inner_tank"
+    "inner = poelis.browser.UH2_Workspace.LH2_Tank.inner_tank"
    ]
   }
  ],

{poelis_sdk-0.2.1 → poelis_sdk-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "poelis-sdk"
-version = "0.2.1"
+version = "0.3.0"
 description = "Official Python SDK for Poelis"
 readme = "README.md"
 requires-python = ">=3.11"

{poelis_sdk-0.2.1 → poelis_sdk-0.3.0}/src/poelis_sdk/_transport.py

@@ -1,12 +1,12 @@
 from __future__ import annotations
 
 from typing import Any, Dict, Mapping, Optional
+import os
 import time
 import random
 import httpx
 
 from .exceptions import ClientError, HTTPError, NotFoundError, RateLimitError, ServerError, UnauthorizedError
-from .auth0 import Auth0TokenManager
 
 """HTTP transport abstraction for the Poelis SDK.
 
@@ -29,7 +29,7 @@ class Transport:
 
         Args:
             base_url: Base API URL.
-            api_key: API key for Auth0 authentication.
+            api_key: API key provided by backend to authenticate requests.
             org_id: Organization id for tenant scoping.
             timeout_seconds: Request timeout in seconds.
         """
@@ -38,18 +38,32 @@ class Transport:
         self._api_key = api_key
         self._org_id = org_id
         self._timeout = timeout_seconds
+        # Auth mode is intentionally read from environment to keep the public
+        # constructor signature stable for tests and backwards-compatibility.
+        # Supported values:
+        # - "bearer" (default): Authorization: Bearer <api_key>
+        # - "api_key": X-API-Key/X-Poelis-Api-Key headers with no Authorization
+        self._auth_mode = os.environ.get("POELIS_AUTH_MODE", "api_key").strip().lower()
         
-        # Initialize Auth0 token manager
-        self._auth0_manager = Auth0TokenManager(api_key, org_id, base_url)
 
     def _headers(self, extra: Optional[Mapping[str, str]] = None) -> Dict[str, str]:
         headers: Dict[str, str] = {
             "Accept": "application/json",
             "Content-Type": "application/json",
         }
-        # Get fresh JWT token from Auth0
-        token = self._auth0_manager.get_token()
-        headers["Authorization"] = f"Bearer {token}"
+        # Resolve auth mode with a safe fallback in case tests monkeypatch __init__
+        auth_mode = getattr(self, "_auth_mode", None) or os.environ.get("POELIS_AUTH_MODE", "api_key").strip().lower()
+        if auth_mode == "api_key":
+            # Some staging environments expect an API key header and reject Bearer
+            # Include common header variants for compatibility; backend may accept either.
+            headers["X-API-Key"] = self._api_key
+            headers["X-Poelis-Api-Key"] = self._api_key
+            # Additionally include Authorization with Api-Key scheme for services
+            # that only read credentials from Authorization.
+            headers["Authorization"] = f"Api-Key {self._api_key}"
+        else:
+            # Default: send API key as Bearer token
+            headers["Authorization"] = f"Bearer {self._api_key}"
         headers["X-Poelis-Org"] = self._org_id
         if extra:
             headers.update(dict(extra))

{poelis_sdk-0.2.1 → poelis_sdk-0.3.0}/src/poelis_sdk/browser.py

@@ -56,6 +56,10 @@ class _Node:
         self._load_children()
         return [child._name or "" for child in self._children_cache.values()]
 
+    def names(self) -> List[str]:
+        """Public: return display names of children at this level."""
+        return self._names()
+
     def _suggest(self) -> List[str]:
         """Return suggested attribute names for interactive usage.
 
@@ -249,10 +253,22 @@ class Browser:
         """Return display names of root-level children (workspaces)."""
         return self._root._names()
 
+    def names(self) -> List[str]:
+        """Public: return display names of root-level children (workspaces)."""
+        return self._root._names()
+
     # keep suggest internal so it doesn't appear in help/dir
     def _suggest(self) -> List[str]:
         return self._root._suggest()
 
+    def suggest(self) -> List[str]:
+        """Return curated attribute suggestions at the current root level.
+
+        This mirrors the internal `_suggest` used for interactive completion,
+        but is exposed publicly for tests and programmatic usage.
+        """
+        return self._root._suggest()
+
 
 def _safe_key(name: str) -> str:
     """Convert arbitrary display name to a safe attribute key (letters/digits/_)."""

{poelis_sdk-0.2.1 → poelis_sdk-0.3.0}/src/poelis_sdk/client.py

@@ -31,7 +31,7 @@ class ClientConfig(BaseModel):
         timeout_seconds: Request timeout in seconds.
     """
 
-    base_url: HttpUrl = Field(default="https://poelis-be-py-753618215333.europe-west1.run.app")
+    base_url: HttpUrl = Field(default="https://api.poelis.ai")
     api_key: str = Field(min_length=1)
     org_id: str = Field(min_length=1)
     timeout_seconds: float = 30.0
@@ -45,7 +45,7 @@ class PoelisClient:
     resource accessors to unblock incremental development.
     """
 
-    def __init__(self, api_key: str, org_id: str, base_url: str = "https://poelis-be-py-753618215333.europe-west1.run.app", timeout_seconds: float = 30.0) -> None:
+    def __init__(self, api_key: str, org_id: str, base_url: str = "https://api.poelis.ai", timeout_seconds: float = 30.0) -> None:
         """Initialize the client with API endpoint and credentials.
 
         Args:
@@ -90,7 +90,7 @@ class PoelisClient:
         - POELIS_ORG_ID
         """
 
-        base_url = os.environ.get("POELIS_BASE_URL", "https://poelis-be-py-753618215333.europe-west1.run.app")
+        base_url = os.environ.get("POELIS_BASE_URL", "https://api.poelis.ai")
         api_key = os.environ.get("POELIS_API_KEY")
         org_id = os.environ.get("POELIS_ORG_ID")
 

{poelis_sdk-0.2.1 → poelis_sdk-0.3.0}/src/tests/test_client_basic.py

@@ -34,7 +34,7 @@ def test_client_default_base_url() -> None:
 
 
 def test_client_api_key_headers(monkeypatch: "MonkeyPatch") -> None:
-    """When api_key and org_id are provided, use ApiKey and X-Poelis-Org headers."""
+    """When api_key and org_id are provided, use API key and X-Poelis-Org headers by default."""
 
     import httpx
     from poelis_sdk.client import Transport as _T
@@ -62,7 +62,8 @@ def test_client_api_key_headers(monkeypatch: "MonkeyPatch") -> None:
         # trigger a request to test headers
         client._transport.get("/health")
         assert t.last is not None
-        assert t.last.headers.get("Authorization") == "ApiKey poelis_live_abc"
+        assert t.last.headers.get("X-API-Key") == "poelis_live_abc" or t.last.headers.get("X-Poelis-Api-Key") == "poelis_live_abc"
+        assert t.last.headers.get("Authorization") == "Api-Key poelis_live_abc"
         assert t.last.headers.get("X-Poelis-Org") == "tenant_x"
     finally:
         _T.__init__ = orig  # type: ignore[assignment]

{poelis_sdk-0.2.1 → poelis_sdk-0.3.0}/src/tests/test_transport_and_products.py

@@ -46,7 +46,7 @@ class _MockTransport(httpx.BaseTransport):
 
 
 def test_auth_header_and_pagination(monkeypatch: "MonkeyPatch") -> None:
-    """Verify Authorization header exists and pagination iterates over all pages."""
+    """Verify auth headers exist and pagination iterates over all pages."""
 
     client = PoelisClient(base_url="http://example.com", api_key="k", org_id="o")
 
@@ -72,7 +72,9 @@ def test_auth_header_and_pagination(monkeypatch: "MonkeyPatch") -> None:
         # Check headers on first request
         assert mt.requests, "no requests captured"
         first = mt.requests[0]
-        assert first.headers.get("Authorization") == "ApiKey k"
+        # Default auth mode is API key headers and Authorization: Api-Key
+        assert first.headers.get("X-API-Key") == "k" or first.headers.get("X-Poelis-Api-Key") == "k"
+        assert first.headers.get("Authorization") == "Api-Key k"
         assert first.headers.get("Accept") == "application/json"
     finally:
         _T.__init__ = _orig_init  # type: ignore[assignment]

{poelis_sdk-0.2.1 → poelis_sdk-0.3.0}/tests/test_browser_navigation.py

@@ -6,6 +6,7 @@ These tests avoid reliance on IPython and focus on programmatic APIs.
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any, Dict
+import json
 
 import httpx
 
@@ -22,7 +23,7 @@ class _MockTransport(httpx.BaseTransport):
     def handle_request(self, request: httpx.Request) -> httpx.Response:  # type: ignore[override]
         self.requests.append(request)
         if request.method == "POST" and request.url.path == "/v1/graphql":
-            payload = request.json()  # type: ignore[no-untyped-call]
+            payload = json.loads(request.content.decode("utf-8"))
             query: str = payload.get("query", "")
             vars: Dict[str, Any] = payload.get("variables", {})
 
@@ -77,15 +78,6 @@ def _client_with_graphql_mock(t: httpx.BaseTransport) -> PoelisClient:
         self._org_id = org_id
         self._timeout = timeout_seconds
 
-        # minimal stubs for headers used by transport
-        class _Auth0:
-            def __init__(self) -> None:
-                pass
-
-            def get_token(self) -> str:
-                return "tok"
-
-        self._auth0_manager = _Auth0()
 
     orig = _T.__init__
     _T.__init__ = _init  # type: ignore[assignment]

{poelis_sdk-0.2.1 → poelis_sdk-0.3.0}/uv.lock

@@ -538,7 +538,7 @@ wheels = [
 
 [[package]]
 name = "poelis-sdk"
-version = "0.2.1"
+version = "0.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "build" },

poelis_sdk-0.2.1/src/poelis_sdk/auth0.py

@@ -1,87 +0,0 @@
-"""Auth0 Client Credentials flow for SDK authentication.
-
-This module handles automatic JWT token acquisition using Auth0 Client Credentials
-flow when users provide API keys. The API key serves as the client_id, and we
-derive the client_secret and audience from the API key format.
-"""
-
-from __future__ import annotations
-
-import time
-from typing import Optional
-
-import httpx
-
-
-class Auth0TokenManager:
-    """Manages Auth0 JWT tokens using Client Credentials flow.
-    
-    Automatically acquires and refreshes tokens based on API keys.
-    """
-    
-    def __init__(self, api_key: str, org_id: str, base_url: str) -> None:
-        """Initialize token manager.
-        
-        Args:
-            api_key: API key from webapp (used as client_id)
-            org_id: Organization ID for audience
-            base_url: Base URL to derive Auth0 domain and audience
-        """
-        self.api_key = api_key
-        self.org_id = org_id
-        self.base_url = base_url
-        
-        # Extract Auth0 domain from API key format
-        # Format: poelis_live_org_dev_<client_id>
-        parts = api_key.split('_')
-        if len(parts) >= 4 and parts[0] == 'poelis' and parts[1] == 'live' and parts[2] == 'org' and parts[3] == 'dev':
-            # For now, use the Machine to Machine application credentials
-            # TODO: Parse client_id from API key when webapp generates proper format
-            self.client_id = "XcSLURURuQNEVvX2PF5DplNhTY6YCT4C"  # Machine to Machine app
-            self.client_secret = "TM_Fv8FsfAaqvODf7ayyE_LrZM2KbbpdtLIIMqkIZwFXfKYLdOFcO2qmyO0v970-"
-        else:
-            raise ValueError("Invalid API key format. Expected: poelis_live_org_dev_<client_id>")
-        
-        # Derive Auth0 domain and audience
-        self.auth0_domain = "poelis-prod.eu.auth0.com" 
-        self.audience = "poelis-auth-api"  # Use the API identifier, not the GCP URL
-        
-        self._token: Optional[str] = None
-        self._expires_at: float = 0
-    
-    def get_token(self) -> str:
-        """Get valid JWT token, refreshing if needed.
-        
-        Returns:
-            str: JWT token for Authorization header
-        """
-        if self._token and time.time() < self._expires_at - 60:  # Refresh 1min early
-            return self._token
-        
-        return self._refresh_token()
-    
-    def _refresh_token(self) -> str:
-        """Acquire new JWT token from Auth0.
-        
-        Returns:
-            str: Fresh JWT token
-        """
-        token_url = f"https://{self.auth0_domain}/oauth/token"
-        
-        data = {
-            "client_id": self.client_id,
-            "client_secret": self.client_secret,
-            "audience": self.audience,
-            "grant_type": "client_credentials"
-        }
-        
-        with httpx.Client() as client:
-            response = client.post(token_url, data=data)
-            response.raise_for_status()
-            
-            token_data = response.json()
-            self._token = token_data["access_token"]
-            expires_in = token_data.get("expires_in", 3600)
-            self._expires_at = time.time() + expires_in
-            
-            return self._token