toolplane-python-client 0.1.0__tar.gz

toolplane_python_client-0.1.0/.flake8

@@ -0,0 +1,14 @@
+[flake8]
+max-line-length = 88
+extend-ignore = E203,W503,D,ANN001,ANN002,ANN003,ANN101,ANN102,ANN201,ANN202,ANN204,ANN401,A001,A002,A003,A004,E501
+exclude =
+    .git,
+    __pycache__,
+    build,
+    dist,
+    toolplane/proto,
+    toolplane/toolkits,
+    toolplane.egg-info,
+    toolplane_python_client.egg-info
+per-file-ignores =
+    toolplane/__init__.py:F401

toolplane_python_client-0.1.0/.mypy-baseline

@@ -0,0 +1 @@
+1015

toolplane_python_client-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,83 @@
+# Python Client Architecture
+
+The Python client is the most complete SDK in the repository. It exposes both gRPC and HTTP facades, supports session management, remote invocation, streaming, and local tool-provider registration.
+
+## Module Graph
+
+```text
+toolplane/__init__.py
+  -> toolplane/toolplane_client.py
+  -> toolplane/provider_runtime.py
+    -> toolplane/core/*
+    -> toolplane/common/*
+    -> toolplane/interfaces/*
+  -> toolplane/toolplane_http_client.py
+    -> toolplane/http_core/*
+    -> toolplane/common/*
+```
+
+## Public Entry Points
+
+- `toolplane/__init__.py`: public export surface for both transport facades and shared types.
+- `toolplane/toolplane_client.py`: gRPC-first `Toolplane` facade.
+- `toolplane/toolplane_http_client.py`: HTTP-first `ToolplaneHTTP` facade.
+- `toolplane/provider_runtime.py`: explicit provider lifecycle surface shared by both transports.
+
+## Top-Level API Surface
+
+The two facades intentionally mirror each other closely.
+
+### `Toolplane`
+
+- Connection lifecycle: `connect()`, `disconnect()`, context-manager helpers.
+- Session lifecycle (consumer scope — portable across maintained SDKs): `create_session()`, `get_session()`, `list_sessions()`.
+- Session admin (admin scope — Python-only): `list_user_sessions()`, `bulk_delete_sessions()`, `get_session_stats()`, `invalidate_session()`.
+- Tool invocation (consumer scope): `invoke()`, `ainvoke()`, `stream()`, `astream()`, `get_available_tools()`, `get_request_status()`.
+- Provider runtime access: `provider_runtime()`.
+- Backward-compatible provider aliases: `tool()`, `start()`, `stop()`.
+
+### `ToolplaneHTTP`
+
+- Mirrors most of the gRPC facade and adds explicit `health()` for HTTP health probing.
+
+### `ProviderRuntime`
+
+- Provider lifecycle: `create_session()`, `attach_session()`, `managed_session_ids()`.
+- Tool registration: `register_tool()`, `tool()`.
+- Runtime control: `poll_once()`, `start_in_background()`, `run_forever()`, `stop()`.
+
+## Data Flow
+
+### Remote invocation
+
+1. User code creates an `Toolplane` or `ToolplaneHTTP` instance.
+2. The client establishes a connection and initializes session context.
+3. `invoke()` or `stream()` forwards the tool request through the relevant transport layer.
+4. Session and request helpers normalize the response into Python-friendly objects.
+
+### Provider mode
+
+1. User creates or reuses an explicit `ProviderRuntime` from an `Toolplane` or `ToolplaneHTTP` client.
+2. `ProviderRuntime.create_session()` or `ProviderRuntime.attach_session()` establishes machine ownership for the target session.
+3. User decorates local callables with `ProviderRuntime.tool()`.
+4. `ProviderRuntime.start_in_background()` or `ProviderRuntime.run_forever()` starts heartbeats and the provider poll loop.
+5. Registered Python callables execute locally and results are sent back to the server.
+
+## Key Folders
+
+| Path | Responsibility |
+| --- | --- |
+| `toolplane/core/` | gRPC-side connection, error, machine, request, session, and tool primitives |
+| `toolplane/http_core/` | HTTP-side connection and session implementations |
+| `toolplane/common/` | Shared configs, base managers, retries, validation, and cache helpers |
+| `toolplane/interfaces/` | Interface and protocol contracts for client modules |
+| `toolplane/toolkits/` | Toolkit-oriented helpers layered on top of the SDK |
+| `toolplane/utils/` | General utility helpers |
+| `toolplane/proto/` | Python protobuf outputs used by the gRPC facade |
+
+## Notes For Agents
+
+- When comparing SDK capability, use this client as the primary reference before checking Go or TypeScript.
+- Public behavior is concentrated in `toolplane_client.py` and `toolplane_http_client.py`; lower-level folders mostly exist to support those facades.
+- Provider execution is now explicit in `provider_runtime.py`; do not assume that `connect()` or consumer-side `create_session()` implies machine registration or background polling.
+- If a feature appears in one Python transport facade, check the other facade before assuming parity is missing.

toolplane_python_client-0.1.0/Dockerfile

@@ -0,0 +1,35 @@
+# Use the official Ubuntu base image
+FROM ubuntu:latest
+
+# Set the working directory
+WORKDIR /app
+
+# Install Python and pip
+RUN apt-get update && apt-get install -y \
+    python3 \
+    python3-pip \
+    python3-venv \
+    && apt-get clean
+
+# Create a virtual environment
+RUN python3 -m venv /app/venv
+
+# Activate the virtual environment and install the wheel file
+COPY dist/toolplane-0.1.0-py3-none-any.whl /app/toolplane-0.1.0-py3-none-any.whl
+RUN /app/venv/bin/pip install --no-cache-dir /app/toolplane-0.1.0-py3-none-any.whl
+
+# Copy the requirements.txt file into the container
+COPY requirements.txt /app/requirements.txt
+RUN /app/venv/bin/pip install --no-cache-dir -r /app/requirements.txt
+
+# Copy the example.py script into container
+COPY example.py /app/example.py
+
+# Set up the folder to be mounted as root
+VOLUME /root
+
+# Ensure the container runs as root
+USER root
+
+# Run the example.py script using the virtual environment
+CMD ["sh", "-c", "cd /root && /app/venv/bin/python /app/example.py \"$SESSION_ID\" \"$USER_ID\" \"$API_KEY\""]

toolplane_python_client-0.1.0/MANUAL.md

@@ -0,0 +1,391 @@
+# Toolplane Python Client Documentation
+
+> **This is the advanced API reference.** If you are new to Toolplane, start with the canonical first-touch path in `README.md` and the example walkthrough in `README_EXAMPLES.md`. Come back here for detailed constructor parameters, method signatures, and configuration options.
+
+This manual documents the Python SDK as the primary maintained client for the Toolplane control plane. The maintained story is gRPC control-plane execution first, with `ToolplaneHTTP` available as a compatibility gateway surface over the same session, machine, request, and task flows.
+
+## Overview
+
+This documentation covers the Modular Remote Procedure Call (Toolplane) Python client implementation. The client allows you to interact with Toolplane servers to register tools, manage sessions, and execute distributed functions.
+
+## Architecture
+
+The Toolplane Python client is organized into several key components:
+
+- **Core Components**: Connection management, machine management, tool management, and request handling
+- **Session Management**: Handles multiple session contexts
+- **HTTP Client Alternative**: Provides HTTP-based communication as an alternative to gRPC
+
+## Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+## Quick Start Example
+
+```python
+from toolplane.toolplane_client import Toolplane
+
+# Initialize client
+client = Toolplane(
+    server_host="localhost",
+    server_port=9001,
+    user_id="user-456",
+    api_key="your-api-key",
+)
+client.connect()
+
+# Provider side: create a machine-backed session and register tools through
+# the explicit provider runtime (tools are session-scoped).
+provider = client.provider_runtime()
+session = provider.create_session(user_id="user-456", name="demo")
+
+
+@provider.tool(session_id=session.session_id, name="echo_tool")
+def echo_tool(input_str: str) -> str:
+    return f"Echo: {input_str}"
+
+
+provider.start_in_background()
+
+# Consumer side: invoke in the same session and get the tool's result value.
+result = client.invoke("echo_tool", session.session_id, input_str="Hello World")
+print(result)
+
+# Stop the background poll/heartbeat loop when done.
+provider.stop()
+```
+
+## Core Classes
+
+### Toolplane (Main Client)
+
+The main Toolplane client class that manages connections, sessions, and tools.
+
+#### Constructor Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `server_host` | str | Hostname of the Toolplane server |
+| `server_port` | int | Port of the Toolplane server |
+| `session_ids` | List[str] | List of session IDs to manage |
+| `api_key` | Optional[str] | API key for authentication |
+| `user_id` | Optional[str] | User identifier |
+| `session_name` | Optional[str] | Name for the session |
+| `session_description` | Optional[str] | Description of the session |
+| `session_namespace` | Optional[str] | Namespace for the session |
+| `heartbeat_interval` | int | Interval for heartbeat messages (seconds) |
+| `max_workers` | int | Maximum number of worker threads |
+| `request_timeout` | int | Request timeout in seconds |
+| `poll_interval` | float | Interval for polling requests (seconds) |
+| `max_retries` | int | Maximum number of retry attempts for connection failures |
+| `retry_base_delay` | float | Initial delay between retries (seconds) |
+| `retry_max_delay` | float | Maximum delay between retries (seconds) |
+| `retry_backoff_factor` | float | Exponential backoff factor |
+
+#### Methods
+
+##### `connect() -> bool`
+Establishes connection to the Toolplane server.
+
+##### `disconnect() -> None`
+Closes connection to the Toolplane server.
+
+##### `create_session(session_id: Optional[str] = None, user_id: Optional[str] = None, name: Optional[str] = None, description: Optional[str] = None, namespace: Optional[str] = None, register_machine: bool = False) -> SessionContext`
+Creates a new session on the server.
+
+##### `get_session(session_id: str) -> Optional[SessionContext]`
+Retrieves a session context by ID.
+
+##### `list_sessions() -> List[SessionContext]`
+Lists all active session contexts.
+
+##### `tool(session_id: str, name: Optional[str] = None, description: Optional[str] = None, stream: bool = False, tags: Optional[List[str]] = None) -> Callable[[Callable], Callable]`
+Decorator to register a tool for a session.
+
+##### `invoke(tool_name: str, session_id: str, timeout_seconds: int = 0, wait_timeout: Optional[int] = None, **params) -> Any`
+Invokes a tool in a session synchronously and returns the tool's result
+value. `timeout_seconds` sets the request's absolute per-attempt timeout
+on the wire; `wait_timeout` bounds the local wait (default:
+timeout_seconds + 15, else 60). A lapsed wait raises
+`ToolplaneTimeoutError` carrying the request ID.
+
+##### `ainvoke(tool_name: str, session_id: str, **params) -> str`
+Invokes a tool asynchronously.
+
+##### `stream(tool_name: str, callback: Callable[[Any, bool], None], session_id: str, **params) -> List[Any]`
+Streams tool execution results.
+
+##### `astream(tool_name: str, callback: Callable[[Any, bool], None], session_id: str, **params) -> List[Any]`
+Awaitable stream: runs the blocking stream loop in a worker thread and
+resolves with the collected chunks.
+
+##### `get_available_tools(session_id: str) -> Dict[str, Any]`
+Gets available tools for a session.
+
+##### `get_request_status(session_id: str, request_id: str) -> Dict[str, Any]`
+Gets status of a request (arguments are session_id first, then request_id).
+
+##### `start() -> None`
+Starts the client and begins polling for requests.
+
+##### `stop() -> None`
+Stops the client and cleans up resources.
+
+### ToolplaneHTTP (HTTP Client Alternative)
+
+An HTTP-based alternative to the gRPC client.
+
+#### Constructor Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `server_host` | str | Hostname of the Toolplane server |
+| `server_port` | int | Port of the Toolplane server |
+| `session_ids` | List[str] | List of session IDs to manage |
+| `api_key` | Optional[str] | API key for authentication |
+| `user_id` | Optional[str] | User identifier |
+| `session_name` | Optional[str] | Name for the session |
+| `session_description` | Optional[str] | Description of the session |
+| `session_namespace` | Optional[str] | Namespace for the session |
+| `max_buffer_size` | int | Maximum buffer size for HTTP requests |
+| `max_retries` | int | Maximum number of retry attempts |
+| `request_timeout` | int | Request timeout in seconds |
+| `retry_backoff_ms` | int | Initial backoff time for retries (milliseconds) |
+| `heartbeat_interval` | int | Interval for heartbeat messages (seconds) |
+| `max_workers` | int | Maximum number of worker threads |
+| `poll_interval` | float | Interval for polling requests (seconds) |
+
+#### Methods
+
+Same as Toolplane client with the same signatures and functionality.
+
+## Session Management
+
+### SessionContext
+
+Represents a session context with its own tools and machine registration.
+
+#### Methods
+
+##### `register_machine() -> bool`
+Registers a machine for this session.
+
+##### `register_tool(name: str, func: Callable, schema: Optional[Dict] = None, description: Optional[str] = None, stream: bool = False, tags: Optional[List[str]] = None) -> None`
+Registers a tool for this session.
+
+##### `invoke(tool_name: str, timeout_seconds: int = 0, wait_timeout: Optional[int] = None, **params) -> Any`
+Invokes a tool in this session synchronously and returns the tool's result value.
+
+##### `ainvoke(tool_name: str, **params) -> str`
+Invokes a tool asynchronously.
+
+##### `stream(tool_name: str, callback: Callable[[Any, bool], None], **params)`
+Streams tool execution.
+
+##### `get_available_tools() -> Dict[str, Any]`
+Gets available tools for this session.
+
+##### `get_request_status(request_id: str) -> Dict[str, Any]`
+Gets status of a request.
+
+## Tool Registration
+
+Tools are registered using the `@client.tool` decorator:
+
+```python
+@client.tool("session-123", name="my_tool", description="A sample tool")
+def my_tool(param1: str, param2: int) -> str:
+    return f"Processed {param1} with {param2}"
+```
+
+### Tool Registration Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `session_id` | str | ID of the session to register the tool for |
+| `name` | Optional[str] | Tool name (defaults to function name) |
+| `description` | Optional[str] | Tool description |
+| `stream` | bool | Whether tool supports streaming |
+| `tags` | Optional[List[str]] | Tags for categorizing the tool |
+
+## Error Handling
+
+The client raises `ToolplaneError` for most operation failures and `ConnectionError` for connection-related issues.
+
+## Type Safety
+
+All public APIs are fully typed with proper type annotations to enable:
+- Better IDE support (autocomplete, error detection)
+- Static type checking with tools like `mypy`
+- Self-documenting code
+
+## Retry Logic
+
+Both Toolplane clients now include comprehensive retry logic to handle transient failures:
+
+### gRPC Client Retry Configuration
+
+```python
+# Example with custom retry configuration
+client = Toolplane(
+    server_host="localhost",
+    server_port=80,
+    max_retries=5,
+    retry_base_delay=2.0,
+    retry_max_delay=120.0,
+    retry_backoff_factor=3.0
+)
+```
+
+### HTTP Client Retry Configuration
+
+```python
+# Example with custom retry configuration
+client = ToolplaneHTTP(
+    server_host="localhost",
+    server_port=8080,
+    max_retries=5,
+    retry_backoff_ms=500
+)
+```
+
+### Retry Features
+
+1. **Exponential Backoff**: Delays increase exponentially with each retry attempt
+2. **Jitter**: Random variation to prevent thundering herds
+3. **Configurable Limits**: Users can tune retry behavior to their needs
+4. **Smart Error Detection**: Retries only on retryable errors (UNAVAILABLE, DEADLINE_EXCEEDED, etc.)
+5. **Connection State Tracking**: Monitor connection health and recovery attempts
+
+### Retry Parameters
+
+| Parameter | Default Value | Description |
+|-----------|---------------|-------------|
+| `max_retries` | 3 | Maximum retry attempts |
+| `retry_base_delay` | 1.0 seconds | Initial delay between retries |
+| `retry_max_delay` | 60.0 seconds | Maximum delay between retries |
+| `retry_backoff_factor` | 2.0 | Exponential backoff factor |
+| `retry_backoff_ms` | 250 milliseconds | HTTP client initial backoff |
+
+## Usage Examples
+
+### Basic Usage
+
+```python
+from toolplane.toolplane_client import Toolplane
+
+# Initialize client
+client = Toolplane(
+    server_host="localhost",
+    server_port=80,
+    session_ids=["session-123"],
+    user_id="user-456",
+    api_key="your-api-key"
+)
+
+# Connect to server
+client.connect()
+
+# Register tools
+@client.tool("session-123", name="echo")
+def echo(input_str: str) -> str:
+    return f"Echo: {input_str}"
+
+# Start client
+client.start()
+```
+
+### Asynchronous Tool Invocation
+
+```python
+# Invoke tool asynchronously
+request_id = client.ainvoke("echo", session_id="session-123", input_str="Hello World")
+print(f"Request ID: {request_id}")
+```
+
+### Streaming Tool Execution
+
+```python
+def callback(chunk, is_final):
+    print(f"Chunk: {chunk}")
+
+# Stream tool execution
+chunks = client.stream("echo", callback, session_id="session-123", input_str="Hello World")
+print(f"Final result: {chunks}")
+```
+
+## Configuration
+
+### Environment Variables
+
+The client supports configuration through environment variables:
+- `TOOLPLANE_SERVER_HOST` - Server hostname
+- `TOOLPLANE_SERVER_PORT` - Server port
+- `TOOLPLANE_API_KEY` - API key for authentication
+- `TOOLPLANE_USER_ID` - User identifier
+
+### Configuration Priority
+
+1. Explicit constructor parameters
+2. Environment variables
+3. Default values
+
+## Performance Considerations
+
+- Uses thread pools for concurrent request handling
+- Configurable worker count for heavy workloads
+- Efficient connection reuse
+- Heartbeat mechanism for connection liveness
+
+## Troubleshooting
+
+### Connection Issues
+
+If you encounter connection problems:
+1. Verify server address and port
+2. Check network connectivity
+3. Ensure the server is running
+4. Confirm credentials are valid
+
+### Timeout Issues
+
+If operations timeout:
+1. Increase `request_timeout` parameter
+2. Check server performance
+3. Monitor network latency
+
+## Development Guidelines
+
+### Code Style
+
+- Follow PEP 8 guidelines
+- Use descriptive variable names
+- Include comprehensive docstrings
+- Maintain type safety with proper annotations
+
+### Testing
+
+Write unit tests for all public APIs:
+- Test connection establishment
+- Test tool registration
+- Test invocation scenarios
+- Test error conditions
+
+## Future Enhancements
+
+### Planned Features
+
+1. **Automatic Reconnection**: Built-in reconnection logic with exponential backoff
+2. **Enhanced Logging**: More detailed logging for debugging
+3. **Improved Retry Logic**: More sophisticated retry mechanisms
+4. **Better Session Management**: Enhanced session lifecycle handling
+5. **Async/Await Support**: Native async/await patterns for Python 3.7+
+
+## Contributing
+
+1. Fork the repository
+2. Create feature branch
+3. Write tests for new functionality
+4. Submit pull request with clear description