Merge branch 'main' into fix/opg-token-allowance-modelhub-firebase-refresh

Signed-off-by: kukac <adambalogh@users.noreply.github.com>

Author: adambalogh

.github/workflows/release.yml

@@ -44,6 +44,11 @@ jobs:
       - name: Run tests
         run: make test
 
+      - name: Run LLM integration tests
+        env:
+          PRIVATE_KEY: ${{ secrets.PRIVATE_KEY }}
+        run: make llm_integrationtest
+
   release:
     needs: [check, test]
     runs-on: ubuntu-latest

README.md

@@ -24,7 +24,7 @@ OpenGradient enables developers to build AI applications with verifiable executi
 pip install opengradient
 ```
 
-**Note**: Windows users should temporarily enable WSL during installation (fix in progress).
+**Note**: > **Windows users:** See the [Windows Installation Guide](./WINDOWS_INSTALL.md) for step-by-step setup instructions.
 
 ## Network Architecture
 

WINDOWS_INSTALL.md

@@ -0,0 +1,36 @@
+# Windows Installation Guide
+
+The `opengradient` package requires a C compiler
+to build its native dependencies. Windows does not
+have one by default.
+
+## Step 1 — Enable WSL
+
+Open PowerShell as Administrator and run:
+
+    wsl --install
+
+Restart your PC when prompted.
+
+## Step 2 — Install Python and uv inside WSL
+
+Open the Ubuntu app and run:
+
+    sudo apt update && sudo apt install -y python3 curl
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+    source $HOME/.local/bin/env
+
+## Step 3 — Install SDK
+
+    uv add opengradient
+
+## Step 4 — Verify
+
+    uv run python3 -c "import opengradient; print('Ready!')"
+
+## Common Errors
+
+- Visual C++ 14.0 required → Use WSL instead
+- wsl: command not found → Update Windows 10 to Build 19041+
+- WSL stuck → Enable Virtualization in BIOS
+- uv: command not found → Run: source $HOME/.local/bin/env

docs/opengradient/client/llm.md

@@ -31,27 +31,30 @@ below the requested amount.
 def __init__(
     private_key: str,
     rpc_url: str = 'https://ogevmdevnet.opengradient.ai',
-    tee_registry_address: str = '0x4e72238852f3c918f4E4e57AeC9280dDB0c80248',
-    llm_server_url: Optional[str] = None
+    tee_registry_address: str = '0x4e72238852f3c918f4E4e57AeC9280dDB0c80248'
 )
 ```
 
+#### Static methods
+
+---
+
+#### `from_url()`
+
+```python
+static def from_url(private_key: str, llm_server_url: str) ‑> `LLM`
+```
+**[Dev]** Create an LLM client with a hardcoded TEE endpoint URL.
+
+Intended for development and self-hosted TEE servers. TLS certificate
+verification is disabled because these servers typically use self-signed
+certificates. For production use, prefer the default constructor which
+resolves TEEs from the on-chain registry.
+
 **Arguments**
 
-* **`private_key (str)`**: Ethereum private key for signing x402 payments.
-* **`rpc_url (str)`**: RPC URL for the OpenGradient network. Used to fetch the
-        active TEE endpoint from the on-chain registry when ``llm_server_url``
-        is not provided.
-* **`tee_registry_address (str)`**: Address of the on-chain TEE registry contract.
-* **`llm_server_url (str, optional)`**: Bypass the registry and connect directly
-        to this TEE endpoint URL (e.g. ``"https://1.2.3.4"``). When set,
-        TLS certificate verification is disabled automatically because
-        self-hosted TEE servers typically use self-signed certificates.
-
-        .. warning::
-            Using ``llm_server_url`` disables TLS certificate verification,
-            which removes protection against man-in-the-middle attacks.
-            Only connect to servers you trust and over secure network paths.
+* **`private_key`**: Ethereum private key for signing x402 payments.
+* **`llm_server_url`**: The TEE endpoint URL (e.g. ``"https://1.2.3.4"``).
 
 #### Methods
 
@@ -125,7 +128,7 @@ Union[TextGenerationOutput, AsyncGenerator[StreamChunk, None]]:
 ```python
 async def close(self) ‑> None
 ```
-Close the underlying HTTP client.
+Cancel the background refresh loop and close the HTTP client.
 
 ---
 
@@ -200,8 +203,8 @@ a transaction. Otherwise, sends an ERC-20 approve transaction.
 
 **Arguments**
 
-* **`opg_amount`**: Minimum number of OPG tokens required (e.g. ``0.05``
-        for 0.05 OPG). Must be at least 0.05 OPG.
+* **`opg_amount`**: Minimum number of OPG tokens required (e.g. ``0.1``
+        for 0.1 OPG). Must be at least 0.1 OPG.
 
 **Returns**
 
@@ -211,5 +214,5 @@ Permit2ApprovalResult: Contains ``allowance_before``,
 
 **Raises**
 
-* **`ValueError`**: If the OPG amount is less than 0.05.
+* **`ValueError`**: If the OPG amount is less than 0.1.
 * **`RuntimeError`**: If the approval transaction fails.

docs/opengradient/client/tee_connection.md

@@ -0,0 +1,202 @@
+---
+outline: [2,4]
+---
+
+[opengradient](../index) / [client](./index) / tee_connection
+
+# Package opengradient.client.tee_connection
+
+Manages the lifecycle of a connection to a TEE endpoint.
+
+## Classes
+
+### `ActiveTEE`
+
+Snapshot of the currently connected TEE.
+
+#### Constructor
+
+```python
+def __init__(
+    endpoint: str,
+    http_client: `x402HttpxClient`,
+    tee_id: Optional[str],
+    payment_address: Optional[str]
+)
+```
+
+#### Methods
+
+---
+
+#### `metadata()`
+
+```python
+def metadata(self) ‑> Dict
+```
+Return TEE metadata dict for decorating responses.
+
+#### Variables
+
+* static `endpoint` : str
+* static `http_client` : `x402HttpxClient`
+* static `payment_address` : Optional[str]
+* static `tee_id` : Optional[str]
+
+### `RegistryTEEConnection`
+
+TEE connection resolved from the on-chain registry.
+
+Handles TLS certificate pinning, background health checks, and automatic
+failover when the current TEE becomes unavailable.
+
+#### Constructor
+
+```python
+def __init__(x402_client: `x402Client`, registry: [TEERegistry](./tee_registry))
+```
+
+**Arguments**
+
+* **`x402_client`**: Configured x402 payment client for creating HTTP clients.
+* **`registry`**: TEERegistry for looking up active TEEs.
+
+#### Methods
+
+---
+
+#### `close()`
+
+```python
+async def close(self) ‑> None
+```
+Cancel the background refresh loop and close the HTTP client.
+
+---
+
+#### `ensure_refresh_loop()`
+
+```python
+def ensure_refresh_loop(self) ‑> None
+```
+Start the background TEE refresh loop if not already running.
+
+Called lazily from async request methods since ``__init__`` is synchronous.
+
+---
+
+#### `get()`
+
+```python
+def get(self) ‑> `ActiveTEE`
+```
+Return a snapshot of the current TEE connection.
+
+---
+
+#### `reconnect()`
+
+```python
+async def reconnect(self) ‑> None
+```
+Connect to a new TEE from the registry and rebuild the HTTP client.
+
+### `StaticTEEConnection`
+
+TEE connection with a hardcoded endpoint URL.
+
+No registry lookup, no background refresh. TLS certificate verification
+is disabled because self-hosted TEE servers typically use self-signed certs.
+
+#### Constructor
+
+```python
+def __init__(x402_client: `x402Client`, endpoint: str)
+```
+
+**Arguments**
+
+* **`x402_client`**: Configured x402 payment client for creating HTTP clients.
+* **`endpoint`**: The TEE endpoint URL to connect to.
+
+#### Methods
+
+---
+
+#### `close()`
+
+```python
+async def close(self) ‑> None
+```
+Close the HTTP client.
+
+---
+
+#### `ensure_refresh_loop()`
+
+```python
+def ensure_refresh_loop(self) ‑> None
+```
+No-op — static connections don't refresh.
+
+---
+
+#### `get()`
+
+```python
+def get(self) ‑> `ActiveTEE`
+```
+Return a snapshot of the current TEE connection.
+
+---
+
+#### `reconnect()`
+
+```python
+async def reconnect(self) ‑> None
+```
+Rebuild the HTTP client (same endpoint).
+
+### `TEEConnectionInterface`
+
+Interface for TEE connection implementations.
+
+#### Constructor
+
+```python
+def __init__(*args, **kwargs)
+```
+
+#### Methods
+
+---
+
+#### `close()`
+
+```python
+async def close(self) ‑> None
+```
+
+---
+
+#### `ensure_refresh_loop()`
+
+```python
+def ensure_refresh_loop(self) ‑> None
+```
+
+---
+
+#### `get()`
+
+```python
+def get(self) ‑> `ActiveTEE`
+```
+
+---
+
+#### `reconnect()`
+
+```python
+async def reconnect(self) ‑> None
+```

docs/opengradient/index.md

@@ -6,7 +6,7 @@ opengradient
 
 # Package opengradient
 
-**Version: 0.9.0**
+**Version: 0.9.3**
 
 OpenGradient Python SDK for decentralized AI inference with end-to-end verification.
 

integrationtest/llm/test_llm_chat.py

@@ -23,7 +23,7 @@
 ]
 
 # Amount of OPG tokens to fund the test account with
-OPG_FUND_AMOUNT = 0.05
+OPG_FUND_AMOUNT = 0.1
 # Amount of ETH to fund the test account with (for gas)
 ETH_FUND_AMOUNT = 0.0001
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "opengradient"
-version = "0.9.1"
+version = "0.9.3"
 description = "Python SDK for OpenGradient decentralized model management & inference services"
 authors = [{name = "OpenGradient", email = "adam@vannalabs.ai"}]
 readme = "README.md"
@@ -27,7 +27,7 @@ dependencies = [
     "langchain>=0.3.7",
     "openai>=1.58.1",
     "pydantic>=2.9.2",
-    "og-x402==0.0.1.dev2"
+    "og-x402==0.0.1.dev4"
 ]
 
 [project.optional-dependencies]

src/opengradient/client/_utils.py

@@ -49,6 +49,9 @@ def run_with_retry(
     """
     effective_retries = max_retries if max_retries is not None else DEFAULT_MAX_RETRY
 
+    if effective_retries < 1:
+        raise ValueError(f"max_retries must be at least 1, got {effective_retries}")
+
     for attempt in range(effective_retries):
         try:
             return txn_function()
@@ -62,3 +65,5 @@ def run_with_retry(
                 continue
 
             raise
+
+    raise RuntimeError(f"run_with_retry exhausted {effective_retries} attempts without returning or raising")