llm4agents-sdk 2.0.0__tar.gz

llm4agents_sdk-2.0.0/.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install hatchling
+        run: pip install hatchling
+      - name: Build
+        run: python -m hatchling build
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

llm4agents_sdk-2.0.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+*.pyc

llm4agents_sdk-2.0.0/.serena/.gitignore

@@ -0,0 +1,2 @@
+/cache
+/project.local.yml

llm4agents_sdk-2.0.0/.serena/memories/project/commands.md

@@ -0,0 +1,44 @@
+# Project Commands
+
+## Setup
+```bash
+cd /home/soho/gitlab-repos/proxy-llm/llm4agents-sdk-python
+source .venv/bin/activate
+```
+
+## Testing
+```bash
+# Full test suite
+pytest tests/ -v
+
+# Single test file
+pytest tests/test_client.py -v
+
+# Single test by name
+pytest tests/test_client.py::test_client_creates -v
+
+# With asyncio info
+pytest --tb=short
+```
+
+## Code Quality
+```bash
+# Type checking (if mypy available)
+mypy llm4agents --strict
+
+# Linting (if ruff/flake8 available)
+# Check project docs for configured linters
+```
+
+## Installation
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+```
+
+## Git Workflow
+```bash
+git add <files>
+git commit -m "type: description"
+git push origin <branch>
+```

llm4agents_sdk-2.0.0/.serena/memories/project/overview.md

@@ -0,0 +1,41 @@
+# llm4agents-sdk-python Project Overview
+
+## Purpose
+Python SDK for llm4agents.com — gasless AI agent infrastructure. Provides client library for interacting with the LLM4Agents API.
+
+## Tech Stack
+- **Language:** Python 3.10+
+- **HTTP:** httpx (async with HTTP/2)
+- **Web3:** eth-account (for wallet signing)
+- **Testing:** pytest, pytest-asyncio, respx (HTTP mocking)
+- **Build:** hatchling
+
+## Architecture Overview
+- **Entry Point:** `llm4agents/client.py` - Main LLM4AgentsClient facade
+- **Transport:** `llm4agents/transport/` - HTTP and MCP transports
+- **Modules:**
+  - `llm4agents/chat/` - Chat completions and conversations
+  - `llm4agents/wallets/` - Wallet management
+  - `llm4agents/transfer/` - Token transfers with signing
+  - `llm4agents/tools/` - MCP tool integrations (scraper, search, image)
+- **Error Handling:** `llm4agents/errors.py` - Typed error codes and mapping
+
+## Module Structure
+- All async-first design (httpx AsyncClient)
+- Type hints throughout
+- Namespace pattern for client submodules (e.g., client.chat, client.wallets)
+- Conversation factory pattern for interactive chat
+- Tool call support with callback hooks
+
+## Key Files to Know
+- `llm4agents/__init__.py` - Package exports (currently empty)
+- `llm4agents/types.py` - Type re-exports (to be created)
+- `llm4agents/client.py` - Main client facade (to be created)
+- Tests in `tests/` with structure matching source modules
+
+## Code Style
+- Type hints required on all functions
+- Use dataclass with frozen=True for immutable types
+- Async/await for I/O operations
+- Error handling via LLM4AgentsError with typed codes
+- Namespace classes for logical grouping

llm4agents_sdk-2.0.0/.serena/memories/tasks/task-9-client-implementation.md

@@ -0,0 +1,39 @@
+# Task 9: Client Facade & Package Exports - COMPLETED
+
+## Files Created/Modified
+1. **llm4agents/client.py** - Main LLM4AgentsClient facade class
+   - Initializes HTTP and MCP transports
+   - Creates namespace objects (chat, wallets, transfer, tools, models)
+   - _ChatNamespace: completions property + conversation() factory method
+   - _ModelsNamespace: list() async method for models
+   
+2. **llm4agents/types.py** - Re-export all public types
+   - Imports from errors, wallets.types, transfer.types, chat.types, chat.conversation
+   - Single source of truth for SDK public API types
+   
+3. **llm4agents/__init__.py** - Package entry point
+   - Exports: LLM4AgentsClient, LLM4AgentsError, ErrorCode
+   - Clean public API surface
+   
+4. **tests/test_client.py** - Client unit tests
+   - test_client_creates: checks all namespaces exist
+   - test_chat_namespace: verifies chat.completions and chat.conversation
+   - test_conversation_factory: confirms Conversation factory pattern works
+   - test_error_is_exported: verifies error is exported
+   - test_custom_base_url: tests custom base URL configuration
+
+## Test Results
+- All 5 new tests pass
+- Full test suite: 44/44 tests pass
+- No regressions introduced
+
+## Commit
+- Hash: f0bac1c
+- Message: "feat: add client facade and package exports"
+
+## Architecture Notes
+- Client uses dependency injection pattern: HttpTransport + McpTransport passed to submodules
+- Namespace pattern for logical grouping (chat, wallets, transfer, tools, models)
+- Conversation uses factory pattern via chat.conversation(opts)
+- Default timeouts: 30s for HTTP, 60s for MCP
+- Default base URLs are configurable at client init time

llm4agents_sdk-2.0.0/.serena/project.local.yml

@@ -0,0 +1,5 @@
+# This file allows you to locally override settings in project.yml for development purposes.
+#
+# Use the same keys as in project.yml here. Any setting you specify will override the corresponding
+# setting in project.yml, allowing you to customise the configuration for your local development environment
+# without affecting the project configuration in project.yml (which is intended to be versioned).

llm4agents_sdk-2.0.0/.serena/project.yml

@@ -0,0 +1,127 @@
+# the name by which the project can be referenced within Serena
+project_name: "llm4agents-sdk-python"
+
+
+# list of languages for which language servers are started; choose from:
+#   al                  ansible             bash                clojure             cpp
+#   cpp_ccls            crystal             csharp              csharp_omnisharp    dart
+#   elixir              elm                 erlang              fortran             fsharp
+#   go                  groovy              haskell             haxe                hlsl
+#   java                json                julia               kotlin              lean4
+#   lua                 luau                markdown            matlab              msl
+#   nix                 ocaml               pascal              perl                php
+#   php_phpactor        powershell          python              python_jedi         python_ty
+#   r                   rego                ruby                ruby_solargraph     rust
+#   scala               solidity            swift               systemverilog       terraform
+#   toml                typescript          typescript_vts      vue                 yaml
+#   zig
+#   (This list may be outdated. For the current list, see values of Language enum here:
+#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
+#   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+#   - For Free Pascal/Lazarus, use pascal
+# Special requirements:
+#   Some languages require additional setup/installations.
+#   See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages:
+- python
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: "utf-8"
+
+# line ending convention to use when writing source files.
+# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
+# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
+line_ending:
+
+# The language backend to use for this project.
+# If not set, the global setting from serena_config.yml is used.
+# Valid values: LSP, JetBrains
+# Note: the backend is fixed at startup. If a project with a different backend
+# is activated post-init, an error will be returned.
+language_backend:
+
+# whether to use project's .gitignore files to ignore files
+ignore_all_files_in_gitignore: true
+
+# advanced configuration option allowing to configure language server-specific options.
+# Maps the language key to the options.
+# Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available.
+# No documentation on options means no options are available.
+ls_specific_settings: {}
+
+# list of additional paths to ignore in this project.
+# Same syntax as gitignore, so you can use * and **.
+# Note: global ignored_paths from serena_config.yml are also applied additively.
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude.
+# This extends the existing exclusions (e.g. from the global configuration)
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+excluded_tools: []
+
+# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
+# This extends the existing inclusions (e.g. from the global configuration).
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+included_optional_tools: []
+
+# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
+# This cannot be combined with non-empty excluded_tools or included_optional_tools.
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+fixed_tools: []
+
+# list of mode names to that are always to be included in the set of active modes
+# The full set of modes to be activated is base_modes + default_modes.
+# If the setting is undefined, the base_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this setting overrides the global configuration.
+# Set this to [] to disable base modes for this project.
+# Set this to a list of mode names to always include the respective modes for this project.
+base_modes:
+
+# list of mode names that are to be activated by default, overriding the setting in the global configuration.
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# If the setting is undefined/empty, the default_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
+# Therefore, you can set this to [] if you do not want the default modes defined in the global config to apply
+# for this project.
+# This setting can, in turn, be overridden by CLI parameters (--mode).
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+default_modes:
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+# time budget (seconds) per tool call for the retrieval of additional symbol information
+# such as docstrings or parameter information.
+# This overrides the corresponding setting in the global configuration; see the documentation there.
+# If null or missing, use the setting from the global configuration.
+symbol_info_budget:
+
+# list of regex patterns which, when matched, mark a memory entry as read‑only.
+# Extends the list from the global configuration, merging the two lists.
+read_only_memory_patterns: []
+
+# list of regex patterns for memories to completely ignore.
+# Matching memories will not appear in list_memories or activate_project output
+# and cannot be accessed via read_memory or write_memory.
+# To access ignored memory files, use the read_file tool on the raw file path.
+# Extends the list from the global configuration, merging the two lists.
+# Example: ["_archive/.*", "_episodes/.*"]
+ignored_memory_patterns: []
+
+# list of mode names to be activated additionally for this project, e.g. ["query-projects"]
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+added_modes:

llm4agents_sdk-2.0.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: llm4agents-sdk
+Version: 2.0.0
+Summary: Python SDK for llm4agents.com — gasless AI agent infrastructure
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: eth-account>=0.13.0
+Requires-Dist: httpx[http2]>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# llm4agents-sdk
+
+Python SDK for [llm4agents.com](https://llm4agents.com) — gasless AI agent infrastructure.
+
+## Install
+
+pip install llm4agents-sdk
+
+## Quick start
+
+```python
+import asyncio
+from llm4agents import LLM4AgentsClient
+
+async def main():
+    client = LLM4AgentsClient(api_key="sk-proxy-...")
+    conv = client.chat.conversation({"model": "openai/gpt-4o"})
+    result = await conv.say("Hello!")
+    print(result.content)
+
+asyncio.run(main())
+```
+
+## Version
+
+This SDK tracks the TypeScript SDK. Version parity is maintained via CONTRACT.md in the TS SDK repo.

llm4agents_sdk-2.0.0/README.md

@@ -0,0 +1,26 @@
+# llm4agents-sdk
+
+Python SDK for [llm4agents.com](https://llm4agents.com) — gasless AI agent infrastructure.
+
+## Install
+
+pip install llm4agents-sdk
+
+## Quick start
+
+```python
+import asyncio
+from llm4agents import LLM4AgentsClient
+
+async def main():
+    client = LLM4AgentsClient(api_key="sk-proxy-...")
+    conv = client.chat.conversation({"model": "openai/gpt-4o"})
+    result = await conv.say("Hello!")
+    print(result.content)
+
+asyncio.run(main())
+```
+
+## Version
+
+This SDK tracks the TypeScript SDK. Version parity is maintained via CONTRACT.md in the TS SDK repo.

llm4agents_sdk-2.0.0/llm4agents/__init__.py

@@ -0,0 +1,4 @@
+from llm4agents.client import LLM4AgentsClient
+from llm4agents.errors import LLM4AgentsError, ErrorCode
+
+__all__ = ["LLM4AgentsClient", "LLM4AgentsError", "ErrorCode"]

llm4agents_sdk-2.0.0/llm4agents/chat/completions.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+from collections.abc import AsyncIterator
+from typing import Any
+from llm4agents.transport.http import HttpTransport
+from llm4agents.chat.types import ChatResponse, StreamChunk
+
+
+class ChatCompletions:
+    def __init__(self, http: HttpTransport) -> None:
+        self._http = http
+
+    async def create(
+        self, params: dict[str, Any]
+    ) -> ChatResponse | AsyncIterator[StreamChunk]:
+        if params.get("stream"):
+            raw_stream = await self._http.post_stream("/v1/chat/completions", params)
+            return self._wrap_stream(raw_stream)
+        data = await self._http.post("/v1/chat/completions", params)
+        return ChatResponse.from_dict(data)
+
+    async def _wrap_stream(
+        self, raw: AsyncIterator[Any]
+    ) -> AsyncIterator[StreamChunk]:
+        async for chunk in raw:
+            yield StreamChunk.from_dict(chunk)

llm4agents_sdk-2.0.0/llm4agents/chat/conversation.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+import json
+from dataclasses import dataclass
+from typing import Any, Callable
+from llm4agents.transport.http import HttpTransport
+from llm4agents.chat.types import ChatMessage
+from llm4agents.errors import LLM4AgentsError
+
+
+@dataclass(frozen=True)
+class ConversationResponse:
+    content: str
+    tool_calls: list[dict[str, Any]]
+    usage: dict[str, int]
+
+
+class Conversation:
+    def __init__(self, http: HttpTransport, opts: dict[str, Any]) -> None:
+        self._http = http
+        self._model: str = opts["model"]
+        self._system: str | None = opts.get("system")
+        self._tools = opts.get("tools")
+        self._on_tool_call: Callable[[str, Any], bool] | None = opts.get("on_tool_call")
+        self._on_tool_result: Callable[[str, Any], None] | None = opts.get("on_tool_result")
+        self._max_tool_rounds: int = opts.get("max_tool_rounds", 10)
+        self._history: list[ChatMessage] = list(opts.get("history", []))
+        self._tool_rounds: int = 0
+
+    @property
+    def messages(self) -> list[ChatMessage]:
+        return list(self._history)
+
+    def clear(self) -> None:
+        self._history.clear()
+        self._tool_rounds = 0
+
+    def fork(self) -> Conversation:
+        opts: dict[str, Any] = {
+            "model": self._model,
+            "max_tool_rounds": self._max_tool_rounds,
+            "history": list(self._history),
+        }
+        if self._system is not None:
+            opts["system"] = self._system
+        if self._tools is not None:
+            opts["tools"] = self._tools
+        if self._on_tool_call is not None:
+            opts["on_tool_call"] = self._on_tool_call
+        if self._on_tool_result is not None:
+            opts["on_tool_result"] = self._on_tool_result
+        return Conversation(self._http, opts)
+
+    def _check_tool_limit(self) -> None:
+        if self._tool_rounds >= self._max_tool_rounds:
+            raise LLM4AgentsError(
+                f"Tool loop limit reached ({self._max_tool_rounds})",
+                "tool_loop_limit",
+                None,
+                None,
+            )
+
+    async def say(self, message: str) -> ConversationResponse:
+        self._history.append(
+            {"role": "user", "content": message, "tool_calls": None, "tool_call_id": None}
+        )
+
+        all_tool_calls: list[dict[str, Any]] = []
+        final_usage: dict[str, int] = {}
+
+        while True:
+            params: dict[str, Any] = {
+                "model": self._model,
+                "messages": self._build_messages(),
+            }
+            if self._tools is not None:
+                if not self._tools.definitions:
+                    await self._tools.fetch_definitions()
+                params["tools"] = self._tools.definitions
+
+            data = await self._http.post("/v1/chat/completions", params)
+            choice = data["choices"][0]
+            msg: ChatMessage = choice["message"]
+            usage: dict[str, int] = data.get("usage") or {}
+            final_usage = usage
+            finish_reason: str = choice.get("finish_reason", "stop")
+
+            self._history.append(msg)
+
+            raw_tool_calls: list[dict[str, Any]] = msg.get("tool_calls") or []
+
+            if not raw_tool_calls or finish_reason == "stop":
+                return ConversationResponse(
+                    content=msg.get("content") or "",
+                    tool_calls=all_tool_calls,
+                    usage=final_usage,
+                )
+
+            self._check_tool_limit()
+            self._tool_rounds += 1
+
+            for tc in raw_tool_calls:
+                fn = tc["function"]
+                name: str = fn["name"]
+                try:
+                    args = json.loads(fn.get("arguments") or "{}")
+                except json.JSONDecodeError:
+                    args = {}
+
+                if self._on_tool_call is not None:
+                    should_continue = self._on_tool_call(name, args)
+                    if not should_continue:
+                        return ConversationResponse(
+                            content="",
+                            tool_calls=all_tool_calls,
+                            usage=final_usage,
+                        )
+
+                result = await self._tools.call(name, args)
+
+                if self._on_tool_result is not None:
+                    self._on_tool_result(name, result)
+
+                all_tool_calls.append({"name": name, "args": args, "result": result})
+                self._history.append({
+                    "role": "tool",
+                    "content": result.text,
+                    "tool_calls": None,
+                    "tool_call_id": tc.get("id"),
+                })
+
+    def _build_messages(self) -> list[ChatMessage]:
+        if self._system:
+            return [
+                {"role": "system", "content": self._system, "tool_calls": None, "tool_call_id": None},
+                *self._history,
+            ]
+        return list(self._history)

llm4agents_sdk-2.0.0/llm4agents/chat/types.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Any, TypedDict
+
+
+class ChatMessage(TypedDict, total=False):
+    role: str
+    content: str | None
+    tool_calls: list[Any] | None
+    tool_call_id: str | None
+
+
+@dataclass(frozen=True)
+class ChatResponse:
+    id: str
+    choices: tuple[dict[str, Any], ...]
+    usage: dict[str, int]
+    model: str
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> ChatResponse:
+        return cls(
+            id=d["id"],
+            choices=tuple(d.get("choices", [])),
+            usage=d.get("usage") or {},
+            model=d.get("model", ""),
+        )
+
+
+@dataclass(frozen=True)
+class StreamChunk:
+    id: str
+    choices: tuple[dict[str, Any], ...]
+    usage: dict[str, int] | None
+    model: str | None
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> StreamChunk:
+        return cls(
+            id=d["id"],
+            choices=tuple(d.get("choices", [])),
+            usage=d.get("usage"),
+            model=d.get("model"),
+        )

llm4agents_sdk-2.0.0/llm4agents/client.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Any
+from llm4agents.transport.http import HttpTransport
+from llm4agents.transport.mcp import McpTransport
+from llm4agents.chat.completions import ChatCompletions
+from llm4agents.chat.conversation import Conversation
+from llm4agents.wallets.wallets import Wallets
+from llm4agents.transfer.transfer import Transfer
+from llm4agents.tools.tools import Tools
+
+_DEFAULT_BASE_URL = "https://api.llm4agents.com"
+_DEFAULT_MCP_URL = "https://mcp.llm4agents.com/mcp"
+_DEFAULT_TIMEOUT = 30.0
+_MCP_TIMEOUT = 60.0
+
+
+@dataclass(frozen=True)
+class ModelListResult:
+    models: list[dict[str, Any]]
+    request_id: str | None
+
+
+class _ChatNamespace:
+    def __init__(self, completions: ChatCompletions, http: HttpTransport) -> None:
+        self.completions = completions
+        self._http = http
+
+    def conversation(self, opts: dict[str, Any]) -> Conversation:
+        return Conversation(self._http, opts)
+
+
+class _ModelsNamespace:
+    def __init__(self, http: HttpTransport) -> None:
+        self._http = http
+
+    async def list(self, search: str | None = None) -> ModelListResult:
+        params: dict[str, str] | None = {"search": search} if search else None
+        data = await self._http.get("/api/v1/models/", params=params)
+        return ModelListResult(
+            models=data.get("models", []),
+            request_id=data.get("requestId"),
+        )
+
+
+class LLM4AgentsClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        mcp_url: str = _DEFAULT_MCP_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self._http = HttpTransport(base_url, api_key, timeout)
+        mcp = McpTransport(mcp_url, api_key, _MCP_TIMEOUT)
+
+        completions = ChatCompletions(self._http)
+        self.chat = _ChatNamespace(completions, self._http)
+        self.wallets = Wallets(self._http)
+        self.transfer = Transfer(self._http)
+        self.tools = Tools(mcp)
+        self.models = _ModelsNamespace(self._http)