Merge branch 'main' into ani/langchain-changes

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

Author: adambalogh

README.md

@@ -26,6 +26,17 @@ pip install opengradient
 
 **Note**: > **Windows users:** See the [Windows Installation Guide](./WINDOWS_INSTALL.md) for step-by-step setup instructions.
 
+### Claude Code Integration
+
+If you use [Claude Code](https://claude.ai/code), you can enhance your development experience with OpenGradient:
+
+- **CLAUDE.md context file**: Copy [docs/CLAUDE_SDK_USERS.md](docs/CLAUDE_SDK_USERS.md) to your project's `CLAUDE.md` to enable context-aware assistance with OpenGradient SDK development.
+
+- **Claude Code Plugin**: Install the [OpenGradient Claude Plugin](https://github.com/OpenGradient/claude-plugins) for skills, commands, and agents tailored to OpenGradient development. To install, run:
+  ```bash
+  claude plugin marketplace add https://github.com/OpenGradient/claude-plugins
+  ```
+
 ## Network Architecture
 
 OpenGradient operates two networks:
@@ -88,10 +99,10 @@ hub = og.ModelHub(email="you@example.com", password="...")
 
 ### OPG Token Approval
 
-Before making LLM requests, your wallet must approve OPG token spending via the [Permit2](https://github.com/Uniswap/permit2) protocol. Call this once (it's idempotent — no transaction is sent if the allowance already covers the requested amount):
+Before making LLM requests, your wallet must approve OPG token spending via the [Permit2](https://github.com/Uniswap/permit2) protocol. This only sends an on-chain transaction when the current allowance drops below the threshold:
 
 ```python
-llm.ensure_opg_approval(opg_amount=5)
+llm.ensure_opg_approval(min_allowance=5)
 ```
 
 See [Payment Settlement](#payment-settlement) for details on settlement modes.
@@ -324,10 +335,6 @@ For comprehensive documentation, API reference, and guides:
 - [API Reference](https://docs.opengradient.ai/api_reference/python_sdk/)
 - [Network Deployment](https://docs.opengradient.ai/learn/network/deployment.html)
 
-### Claude Code Integration
-
-If you use [Claude Code](https://claude.ai/code), copy [docs/CLAUDE_SDK_USERS.md](docs/CLAUDE_SDK_USERS.md) to your project's `CLAUDE.md` to enable context-aware assistance with OpenGradient SDK development.
-
 ## Model Hub
 
 Browse and discover AI models on the [OpenGradient Model Hub](https://hub.opengradient.ai/). The Hub provides:

docs/CLAUDE_SDK_USERS.md

@@ -21,8 +21,8 @@ import os
 # Create an LLM client
 llm = og.LLM(private_key=os.environ["OG_PRIVATE_KEY"])
 
-# One-time OPG token approval (idempotent — skips if allowance already sufficient)
-llm.ensure_opg_approval(opg_amount=0.1)
+# Ensure sufficient OPG allowance (only sends tx when below threshold)
+llm.ensure_opg_approval(min_allowance=0.1)
 
 # LLM Chat (TEE-verified with x402 payments, async)
 result = await llm.chat(

docs/opengradient/client/index.md

@@ -24,7 +24,7 @@ import opengradient as og
 
 # LLM inference (Base Sepolia OPG tokens)
 llm = og.LLM(private_key="0x...")
-llm.ensure_opg_approval(opg_amount=5)
+llm.ensure_opg_approval(min_allowance=5)
 result = await llm.chat(model=og.TEE_LLM.CLAUDE_HAIKU_4_5, messages=[...])
 
 # On-chain model inference (OpenGradient testnet gas tokens)

docs/opengradient/client/llm.md

@@ -22,36 +22,37 @@ All request methods (``chat``, ``completion``) are async.
 
 Before making LLM requests, ensure your wallet has approved sufficient
 OPG tokens for Permit2 spending by calling ``ensure_opg_approval``.
-This only sends an on-chain transaction when the current allowance is
-below the requested amount.
 
 #### Constructor
 
 ```python
 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 +126,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.
 
 ---
 
@@ -190,18 +191,30 @@ TextGenerationOutput: Generated text results including:
 #### `ensure_opg_approval()`
 
 ```python
-def ensure_opg_approval(self, opg_amount: float) ‑> [Permit2ApprovalResult](./opg_token)
+def ensure_opg_approval(
+    self,
+    min_allowance: float,
+    approve_amount: Optional[float] = None
+) ‑> [Permit2ApprovalResult](./opg_token)
 ```
-Ensure the Permit2 allowance for OPG is at least ``opg_amount``.
+Ensure the Permit2 allowance stays above a minimum threshold.
+
+Only sends a transaction when the current allowance drops below
+``min_allowance``. When approval is needed, approves ``approve_amount``
+(defaults to ``2 * min_allowance``) to create a buffer that survives
+multiple service restarts without re-approving.
+
+Best for backend servers that call this on startup::
 
-Checks the current Permit2 allowance for the wallet. If the allowance
-is already >= the requested amount, returns immediately without sending
-a transaction. Otherwise, sends an ERC-20 approve transaction.
+    llm.ensure_opg_approval(min_allowance=5.0, approve_amount=100.0)
 
 **Arguments**
 
-* **`opg_amount`**: Minimum number of OPG tokens required (e.g. ``0.1``
-        for 0.1 OPG). Must be at least 0.1 OPG.
+* **`min_allowance`**: The minimum acceptable allowance in OPG. Must be
+        at least 0.1 OPG.
+* **`approve_amount`**: The amount of OPG to approve when a transaction
+        is needed. Defaults to ``2 * min_allowance``. Must be
+        >= ``min_allowance``.
 
 **Returns**
 
@@ -211,5 +224,6 @@ Permit2ApprovalResult: Contains ``allowance_before``,
 
 **Raises**
 
-* **`ValueError`**: If the OPG amount is less than 0.1.
+* **`ValueError`**: If ``min_allowance`` is less than 0.1 or
+        ``approve_amount`` is less than ``min_allowance``.
 * **`RuntimeError`**: If the approval transaction fails.

docs/opengradient/client/model_hub.md

@@ -43,15 +43,16 @@ Create a new model with the given model_name and model_desc, and a specified ver
 
 * **`model_name (str)`**: The name of the model.
 * **`model_desc (str)`**: The description of the model.
-* **`version (str)`**: The version identifier (default is "1.00").
+* **`version (str)`**: A label used in the initial version notes (default is "1.00").
+* **`Note`**: the actual version string is assigned by the server.
 
 **Returns**
 
-dict: The server response containing model details.
+ModelRepository: Object containing the model name and server-assigned version string.
 
 **Raises**
 
-* **`CreateModelError`**: If the model creation fails.
+* **`RuntimeError`**: If the model creation fails.
 
 ---
 
@@ -125,7 +126,7 @@ Upload a model file to the server.
 
 **Returns**
 
-dict: The processed result.
+FileUploadResult: The processed result.
 
 **Raises**