Improved OPG allowance management methods

[adambalogh]

Summary

• Improve ensure_opg_approval with min_allowance/approve_amount params — only sends a tx when allowance drops below the minimum, and approves a
  configurable buffer amount (defaults to 2x) to reduce on-chain transactions across restarts
• Add wallet balance checks before approving (zero balance, insufficient balance, cap approval to balance)
• Extract _send_approve_tx helper and add logging

Test plan

• Unit tests updated and passing (114/114)
• Integration test with funded wallet on Base Sepolia

[Copilot]

Pull request overview

Updates the OPG Permit2 allowance/approval flow to reduce unnecessary on-chain approvals across restarts by introducing a minimum-allowance threshold, optional buffered approval amounts, and balance-aware approval behavior, and then propagates the new API through docs, examples, and tests.

Changes:

• Refactors ensure_opg_approval to use min_allowance/approve_amount, adds _send_approve_tx, balance checks, and logging.
• Updates unit/integration tests and various examples/tutorials to call the new API.
• Adjusts documentation to reflect updated behavior and related return types.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/opengradient/client/opg_token.py	Implements new allowance threshold + buffered approval logic, balance checks, helper extraction, logging.
src/opengradient/client/llm.py	Updates LLM.ensure_opg_approval signature/docs and delegates to updated token helper.
tests/opg_token_test.py	Reworks unit tests to cover new threshold/buffer/balance behaviors.
tests/llm_test.py	Updates import paths and removes now-obsolete ensure_opg_approval validation test.
tests/tee_connection_test.py	Refactors multi-patch() usage to parenthesized context manager form.
integrationtest/llm/test_llm_chat.py	Adds ERC-20 balanceOf ABI and waits for OPG balance visibility; updates approval call.
examples/llm_chat.py	Updates to min_allowance API.
examples/llm_chat_streaming.py	Updates to min_allowance API.
examples/llm_tool_calling.py	Updates to min_allowance API and adjusts wording.
examples/langchain_react_agent.py	Updates to min_allowance API and adjusts wording.
stresstest/llm.py	Updates to min_allowance API.
tutorials/01-verifiable-ai-agent.md	Updates tutorial text/code to min_allowance.
tutorials/02-streaming-multi-provider.md	Updates tutorial text/code to min_allowance.
tutorials/03-verified-tool-calling.md	Updates tutorial text/code to min_allowance.
README.md	Updates approval section to describe threshold-based behavior and new param name.
docs/opengradient/index.md	Updates example call to min_allowance.
docs/opengradient/client/index.md	Updates example call to min_allowance.
docs/opengradient/client/llm.md	Updates ensure_opg_approval docs/signature and semantics.
docs/opengradient/client/model_hub.md	Aligns documented return/exception types with current code.
docs/CLAUDE_SDK_USERS.md	Updates example call to min_allowance.
src/opengradient/__init__.py	Updates top-level example call to min_allowance.
src/opengradient/client/__init__.py	Updates package example call to min_allowance.
docs/opengradient/client/opg_token.md	Removes the opg_token doc page content (affects cross-links).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.