progtc 0.1.0__tar.gz

progtc-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Release
+
+on:
+  push:
+    tags:
+      # Publish on any tag starting with a `v`, e.g., v1.2.3
+      - v*
+
+jobs:
+  pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    # Environment and permissions trusted publishing.
+    environment:
+      # Create this environment in the GitHub repository under Settings -> Environments
+      name: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Install Python 3.13
+        run: uv python install 3.13
+      - name: Build
+        run: uv build
+      - name: Publish
+        run: uv publish

progtc-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

progtc-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

progtc-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: progtc
+Version: 0.1.0
+Summary: Add your description here
+Author-email: Callum Downie <70471360+calmdown13@users.noreply.github.com>
+Requires-Python: >=3.12
+Requires-Dist: httpx-sse>=0.4.3
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.12.5
+Provides-Extra: server
+Requires-Dist: fastapi>=0.123.10; extra == 'server'
+Requires-Dist: rich>=14.2.0; extra == 'server'
+Requires-Dist: typer>=0.20.0; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.38.0; extra == 'server'
+Description-Content-Type: text/markdown
+
+```
+    ██████╗ ██████╗  ██████╗  ██████╗ ████████╗ ██████╗
+    ██╔══██╗██╔══██╗██╔═══██╗██╔════╝ ╚══██╔══╝██╔════╝
+    ██████╔╝██████╔╝██║   ██║██║  ███╗   ██║   ██║     
+    ██╔═══╝ ██╔══██╗██║   ██║██║   ██║   ██║   ██║     
+    ██║     ██║  ██║╚██████╔╝╚██████╔╝   ██║   ╚██████╗
+    ╚═╝     ╚═╝  ╚═╝ ╚═════╝  ╚═════╝    ╚═╝    ╚═════╝
+                                               by capsa
+```
+
+**Programmatic Tool Calling** — Let LLM-generated code call your tools, even from inside a sandbox.
+
+---
+
+## The Problem
+
+You want an AI agent to write and execute Python code. Easy enough—spin up an [E2B](https://e2b.dev) sandbox and let it run. But what if that code needs to call your tools?
+
+The code runs inside a sandbox. Your tools live outside. There's no bridge.
+
+## The Solution
+
+**progtc** creates that bridge. It runs a lightweight server inside your sandbox that exposes your tools to the generated code. When the code calls a tool, the request streams back to your client, you execute it locally, and return the result—all transparently.
+
+
+## Installation
+
+```bash
+pip install progtc
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add progtc
+```
+
+## Quick Start
+
+### 1. Start the Server (inside your sandbox)
+
+```bash
+progtc serve --host 0.0.0.0 --port 8000 --api-key your-secret-key
+```
+
+### 2. Execute Code from Your Client
+
+```python
+from progtc import AsyncProgtcClient
+
+client = AsyncProgtcClient(
+    base_url="https://your-sandbox-url:8000",
+    api_key="your-secret-key",
+)
+
+# Define your tools as async functions
+async def get_weather(city: str, country: str) -> str:
+    # Your actual implementation
+    return f"Weather in {city}, {country}: Sunny, 22°C"
+
+async def search_database(query: str) -> list[dict]:
+    # Your actual implementation
+    return [{"id": 1, "name": "Result"}]
+
+# Execute LLM-generated code that uses your tools
+code = """
+from tools import get_weather
+
+weather = await get_weather("London", "UK")
+print(f"The weather is: {weather}")
+"""
+
+result = await client.execute_code(
+    code=code,
+    tool_call_handlers={
+        "get_weather": get_weather,
+        "search_database": search_database,
+    },
+)
+
+print(result.stdout)  # "The weather is: Weather in London, UK: Sunny, 22°C"
+```
+
+## How It Works
+
+1. **Your client** sends code + a list of available tool names to the progtc server
+2. **The server** executes the code in an isolated process, injecting a `tools` module
+3. **When code calls a tool**, the server streams the call back to your client via SSE
+4. **Your client** executes the tool locally and sends the result back
+5. **The server** resumes code execution with the result
+6. **Stdout/stderr** are captured and streamed back when execution completes
+
+## Code Requirements
+
+The LLM-generated code must:
+
+- **Import tools from the `tools` module**: `from tools import my_tool`
+- **Await all tool calls** (they're async)
+- **Use `print()` for output** — stdout/stderr are captured and returned
+
+```python
+from tools import get_weather, search_database
+import asyncio
+
+# Call tools like regular async functions
+weather, results = await asyncio.gather(
+    get_weather("Tokyo", "Japan"),
+    search_database("hotels"),
+)
+
+print(f"Weather: {weather}")
+print(f"Results: {results}")
+```
+
+> **Note:** The code runs in a top-level async context, so you can use `await` directly without defining an async function.
+
+## CLI Options
+
+```bash
+progtc serve [OPTIONS]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--host` | `127.0.0.1` | Host to bind to |
+| `--port` | `8000` | Port to bind to |
+| `--api-key` | (env: `PROGTC_API_KEY`) | API key for authentication |
+| `--tool-call-timeout` | `10.0` | Timeout for individual tool calls (seconds) |
+| `--code-execution-timeout` | `30.0` | Total timeout for code execution (seconds) |
+
+## Error Handling
+
+The client returns a discriminated union—either success or one of several error types:
+
+```python
+from progtc.types import MessageType
+
+result = await client.execute_code(code, tool_call_handlers)
+
+match result.type:
+    case MessageType.SUCCESS:
+        print(f"Stdout: {result.stdout}")
+        print(f"Stderr: {result.stderr}")
+    case MessageType.ERROR:
+        print(f"Error: {result.message}")
+        print(f"Code: {result.code}")  # compilation, runtime, timeout, etc.
+```
+
+Error codes:
+- `code_compilation_error` — Code failed to compile/exec
+- `code_runtime_error` — Exception raised during execution
+- `code_timeout_error` — Execution exceeded timeout
+
+## Example: E2B + pydantic-ai
+
+See [`examples/e2b-example/`](examples/e2b-example/) for a complete example using progtc with [E2B](https://e2b.dev) sandboxes and [pydantic-ai](https://ai.pydantic.dev) agents.
+
+The example demonstrates an AI agent that can execute Python code in a secure sandbox while calling tools defined in your application.
+
+## License
+
+MIT
+
+---
+
+<p align="center">
+  <b>Building AI agents?</b> We're hiring: <a href="https://capsa.ai/careers">capsa.ai/careers</a>
+</p>

progtc-0.1.0/README.md

@@ -0,0 +1,168 @@
+```
+    ██████╗ ██████╗  ██████╗  ██████╗ ████████╗ ██████╗
+    ██╔══██╗██╔══██╗██╔═══██╗██╔════╝ ╚══██╔══╝██╔════╝
+    ██████╔╝██████╔╝██║   ██║██║  ███╗   ██║   ██║     
+    ██╔═══╝ ██╔══██╗██║   ██║██║   ██║   ██║   ██║     
+    ██║     ██║  ██║╚██████╔╝╚██████╔╝   ██║   ╚██████╗
+    ╚═╝     ╚═╝  ╚═╝ ╚═════╝  ╚═════╝    ╚═╝    ╚═════╝
+                                               by capsa
+```
+
+**Programmatic Tool Calling** — Let LLM-generated code call your tools, even from inside a sandbox.
+
+---
+
+## The Problem
+
+You want an AI agent to write and execute Python code. Easy enough—spin up an [E2B](https://e2b.dev) sandbox and let it run. But what if that code needs to call your tools?
+
+The code runs inside a sandbox. Your tools live outside. There's no bridge.
+
+## The Solution
+
+**progtc** creates that bridge. It runs a lightweight server inside your sandbox that exposes your tools to the generated code. When the code calls a tool, the request streams back to your client, you execute it locally, and return the result—all transparently.
+
+
+## Installation
+
+```bash
+pip install progtc
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add progtc
+```
+
+## Quick Start
+
+### 1. Start the Server (inside your sandbox)
+
+```bash
+progtc serve --host 0.0.0.0 --port 8000 --api-key your-secret-key
+```
+
+### 2. Execute Code from Your Client
+
+```python
+from progtc import AsyncProgtcClient
+
+client = AsyncProgtcClient(
+    base_url="https://your-sandbox-url:8000",
+    api_key="your-secret-key",
+)
+
+# Define your tools as async functions
+async def get_weather(city: str, country: str) -> str:
+    # Your actual implementation
+    return f"Weather in {city}, {country}: Sunny, 22°C"
+
+async def search_database(query: str) -> list[dict]:
+    # Your actual implementation
+    return [{"id": 1, "name": "Result"}]
+
+# Execute LLM-generated code that uses your tools
+code = """
+from tools import get_weather
+
+weather = await get_weather("London", "UK")
+print(f"The weather is: {weather}")
+"""
+
+result = await client.execute_code(
+    code=code,
+    tool_call_handlers={
+        "get_weather": get_weather,
+        "search_database": search_database,
+    },
+)
+
+print(result.stdout)  # "The weather is: Weather in London, UK: Sunny, 22°C"
+```
+
+## How It Works
+
+1. **Your client** sends code + a list of available tool names to the progtc server
+2. **The server** executes the code in an isolated process, injecting a `tools` module
+3. **When code calls a tool**, the server streams the call back to your client via SSE
+4. **Your client** executes the tool locally and sends the result back
+5. **The server** resumes code execution with the result
+6. **Stdout/stderr** are captured and streamed back when execution completes
+
+## Code Requirements
+
+The LLM-generated code must:
+
+- **Import tools from the `tools` module**: `from tools import my_tool`
+- **Await all tool calls** (they're async)
+- **Use `print()` for output** — stdout/stderr are captured and returned
+
+```python
+from tools import get_weather, search_database
+import asyncio
+
+# Call tools like regular async functions
+weather, results = await asyncio.gather(
+    get_weather("Tokyo", "Japan"),
+    search_database("hotels"),
+)
+
+print(f"Weather: {weather}")
+print(f"Results: {results}")
+```
+
+> **Note:** The code runs in a top-level async context, so you can use `await` directly without defining an async function.
+
+## CLI Options
+
+```bash
+progtc serve [OPTIONS]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--host` | `127.0.0.1` | Host to bind to |
+| `--port` | `8000` | Port to bind to |
+| `--api-key` | (env: `PROGTC_API_KEY`) | API key for authentication |
+| `--tool-call-timeout` | `10.0` | Timeout for individual tool calls (seconds) |
+| `--code-execution-timeout` | `30.0` | Total timeout for code execution (seconds) |
+
+## Error Handling
+
+The client returns a discriminated union—either success or one of several error types:
+
+```python
+from progtc.types import MessageType
+
+result = await client.execute_code(code, tool_call_handlers)
+
+match result.type:
+    case MessageType.SUCCESS:
+        print(f"Stdout: {result.stdout}")
+        print(f"Stderr: {result.stderr}")
+    case MessageType.ERROR:
+        print(f"Error: {result.message}")
+        print(f"Code: {result.code}")  # compilation, runtime, timeout, etc.
+```
+
+Error codes:
+- `code_compilation_error` — Code failed to compile/exec
+- `code_runtime_error` — Exception raised during execution
+- `code_timeout_error` — Execution exceeded timeout
+
+## Example: E2B + pydantic-ai
+
+See [`examples/e2b-example/`](examples/e2b-example/) for a complete example using progtc with [E2B](https://e2b.dev) sandboxes and [pydantic-ai](https://ai.pydantic.dev) agents.
+
+The example demonstrates an AI agent that can execute Python code in a secure sandbox while calling tools defined in your application.
+
+## License
+
+MIT
+
+---
+
+<p align="center">
+  <b>Building AI agents?</b> We're hiring: <a href="https://capsa.ai/careers">capsa.ai/careers</a>
+</p>

progtc-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "progtc"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Callum Downie", email = "70471360+calmdown13@users.noreply.github.com" },
+]
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.12.5",
+    "httpx>=0.28.1",
+    "httpx-sse>=0.4.3",
+]
+
+[project.optional-dependencies]
+server = [
+    "fastapi>=0.123.10",
+    "rich>=14.2.0",
+    "typer>=0.20.0",
+    "uvicorn[standard]>=0.38.0",
+]
+
+[project.scripts]
+progtc = "progtc:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "progtc[server]",
+    "mypy>=1.19.0",
+    "pytest>=9.0.1",
+    "ruff>=0.14.8",
+    "pytest-asyncio>=1.3.0",
+]
+
+[tool.mypy]
+strict = true
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle
+    "F",   # Pyflakes
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "SIM", # flake8-simplify
+    "I",   # isort
+]
+ignore = ["B008"]
+
+[tool.pytest.ini_options]
+filterwarnings = [
+    "ignore:websockets.legacy is deprecated:DeprecationWarning",
+    "ignore:websockets.server.WebSocketServerProtocol is deprecated:DeprecationWarning",
+]

progtc-0.1.0/src/progtc/__init__.py

@@ -0,0 +1,4 @@
+from progtc.cli import main
+from progtc.client import AsyncProgtcClient
+
+__all__ = ["AsyncProgtcClient", "main"]

progtc-0.1.0/src/progtc/cli.py

@@ -0,0 +1,78 @@
+from typing import Annotated
+
+import typer
+import uvicorn
+from rich import print as rprint
+
+from progtc.server.config import server_config
+
+app = typer.Typer(
+    name="progtc",
+    help="progtc CLI",
+    add_completion=True,
+)
+
+
+@app.callback()
+def callback() -> None:
+    """Progtc - programmatic tool calling"""
+
+
+ARTWORK = """
+[bright_cyan]
+    ██████╗ ██████╗  ██████╗  ██████╗ ████████╗ ██████╗
+    ██╔══██╗██╔══██╗██╔═══██╗██╔════╝ ╚══██╔══╝██╔════╝
+    ██████╔╝██████╔╝██║   ██║██║  ███╗   ██║   ██║     
+    ██╔═══╝ ██╔══██╗██║   ██║██║   ██║   ██║   ██║     
+    ██║     ██║  ██║╚██████╔╝╚██████╔╝   ██║   ╚██████╗
+    ╚═╝     ╚═╝  ╚═╝ ╚═════╝  ╚═════╝    ╚═╝    ╚═════╝
+                                               by capsa[/bright_cyan]
+[dim]───────────────────────────────────────────────────────────[/dim]
+    [bright_white]Come build agents with us: https://capsa.ai/careers[/bright_white]
+[dim]───────────────────────────────────────────────────────────[/dim]
+"""
+
+
+@app.command()
+def serve(
+    host: Annotated[str, typer.Option(help="Host to bind to")] = "127.0.0.1",
+    port: Annotated[int, typer.Option(help="Port to bind to")] = 8000,
+    api_key: Annotated[
+        str | None,
+        typer.Option(
+            help=(
+                "API key for authentication (can also be set via "
+                "PROGTC_API_KEY env var)"
+            ),
+            envvar="PROGTC_API_KEY",
+        ),
+    ] = None,
+    tool_call_timeout: Annotated[
+        float,
+        typer.Option(help="Timeout for tool calls in seconds"),
+    ] = 10.0,
+    code_execution_timeout: Annotated[
+        float,
+        typer.Option(help="Timeout for code execution in seconds"),
+    ] = 30.0,
+) -> None:
+    if api_key:
+        server_config.api_key = api_key
+    server_config.tool_call_timeout = tool_call_timeout
+    server_config.code_execution_timeout = code_execution_timeout
+
+    rprint(ARTWORK)
+
+    uvicorn.run(
+        "progtc.server:app",
+        host=host,
+        port=port,
+    )
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

progtc-0.1.0/src/progtc/client.py

@@ -0,0 +1,61 @@
+from httpx import AsyncClient
+from httpx_sse import aconnect_sse
+from pydantic import TypeAdapter
+
+from progtc.types import (
+    ExecuteCodeError,
+    ExecuteCodeMessage,
+    ExecuteCodeSuccess,
+    ToolCall,
+    ToolHandler,
+)
+
+ExecuteCodeMessageAdapter = TypeAdapter[ExecuteCodeMessage](ExecuteCodeMessage)
+
+
+class AsyncProgtcClient:
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+    ):
+        self._base_url = base_url
+        self._api_key = api_key
+
+    async def execute_code(
+        self,
+        code: str,
+        tool_call_handlers: dict[str, ToolHandler],
+    ) -> ExecuteCodeSuccess | ExecuteCodeError:
+        async with (
+            AsyncClient(
+                base_url=self._base_url,
+                headers={"Authorization": f"Bearer {self._api_key}"},
+            ) as client,
+            aconnect_sse(
+                client,
+                "POST",
+                "/execute-code",
+                json={
+                    "tool_names": list(tool_call_handlers.keys()),
+                    "code": code,
+                },
+            ) as event_source,
+        ):
+            async for event in event_source.aiter_sse():
+                event_obj = ExecuteCodeMessageAdapter.validate_python(event.json())
+                if isinstance(event_obj, ToolCall):
+                    handler = tool_call_handlers[event_obj.tool_name]
+                    result = await handler(*event_obj.args, **event_obj.kwargs)
+                    await client.post(
+                        "/tool-results",
+                        json={
+                            "execution_id": event_obj.execution_id,
+                            "tool_call_id": event_obj.id,
+                            "result": result,
+                        },
+                    )
+                else:
+                    return event_obj
+
+        raise RuntimeError("Stream ended without result")

progtc-0.1.0/src/progtc/server/api.py

@@ -0,0 +1,63 @@
+import secrets
+import time
+from collections.abc import Generator
+
+from fastapi import Depends, FastAPI, HTTPException
+from fastapi.responses import StreamingResponse
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from progtc.server.code_execution_manager import CodeExecutionManager
+from progtc.server.config import server_config
+from progtc.types import (
+    CodeTimeoutError,
+    ExecuteCodeRequest,
+    ToolCallResult,
+)
+
+code_execution_manager = CodeExecutionManager()
+
+
+def authenticate(
+    credentials: HTTPAuthorizationCredentials = Depends(HTTPBearer()),
+) -> None:
+    if not secrets.compare_digest(credentials.credentials, server_config.api_key):
+        raise HTTPException(status_code=401, detail="Unauthorized")
+
+
+app = FastAPI(dependencies=[Depends(authenticate)])
+
+
+@app.post("/tool-results")
+def add_tool_result(tool_call_result: ToolCallResult) -> None:
+    code_execution_manager.send_tool_result(tool_call_result)
+
+
+@app.post("/execute-code")
+def execute_code(body: ExecuteCodeRequest) -> StreamingResponse:
+    def stream() -> Generator[str, None, None]:
+        with code_execution_manager.run(body.code, body.tool_names) as process:
+            t0 = time.monotonic()
+
+            # Yield tool calls to the client until the process
+            # is done or the timeout is reached
+            while (
+                not process.is_done()
+                and time.monotonic() - t0 < server_config.code_execution_timeout
+            ):
+                tool_call = process.next_tool_call()
+                if tool_call is None:
+                    continue
+                yield f"data: {tool_call.model_dump_json()}\n\n"
+
+            # Yield the final result to the client.
+            if process.is_done():
+                result = process.result()
+            else:
+                result = CodeTimeoutError(
+                    message="Code execution timed out",
+                    stdout="",
+                    stderr="",
+                )
+            yield f"data: {result.model_dump_json()}\n\n"
+
+    return StreamingResponse(stream(), media_type="text/event-stream")