paperclip-sdk 0.6.1

Public Python SDK for calling remote functions, with sync and async clients.

paperclip-sdk

Python SDK for calling server-hosted Paperclip tools from scripts, workers, web apps, and async services.

Use it when you want to keep business logic, pricing rules, private workflows, or customer-specific functionality on the server while calling it from Python through a small client.

Install

poetry add paperclip-sdk

or

pip install paperclip-sdk

Authentication

The SDK reads the API key from LEASEKEY_API_KEY by default:

export LEASEKEY_API_KEY="your-api-key"

The default base URL is https://leasekey.org. For self-hosted or local servers, pass a custom base_url.

Quickstart

Sync

from paperclip_sdk import Paperclip

with Paperclip() as paperclip:
    result = paperclip.tools.core.hello_world(name="Ada")
    print(result)

Async

import asyncio

from paperclip_sdk import AsyncPaperclip


async def main() -> None:
    async with AsyncPaperclip() as paperclip:
        result = await paperclip.tools.core.hello_world(name="Ada")
        print(result)


asyncio.run(main())

Tool access styles

The SDK supports three equivalent ways to call the same tool.

Sync

from paperclip_sdk import Paperclip

with Paperclip() as paperclip:
    print(paperclip.tools.core.hello_world(name="Ada"))
    print(paperclip.core.hello_world(name="Ada"))
    print(paperclip["core.hello_world"](name="Ada"))

Async

import asyncio

from paperclip_sdk import AsyncPaperclip


async def main() -> None:
    async with AsyncPaperclip() as paperclip:
        print(await paperclip.tools.core.hello_world(name="Ada"))
        print(await paperclip.core.hello_world(name="Ada"))
        print(await paperclip["core.hello_world"](name="Ada"))


asyncio.run(main())

Use a specific server

Sync

from paperclip_sdk import Paperclip

with Paperclip(
    base_url="http://127.0.0.1:8889",
    api_key="your-api-key",
) as paperclip:
    result = paperclip.tools.core.hello_world(name="Ada")
    print(result)

Async

import asyncio

from paperclip_sdk import AsyncPaperclip


async def main() -> None:
    async with AsyncPaperclip(
        base_url="http://127.0.0.1:8889",
        api_key="your-api-key",
    ) as paperclip:
        result = await paperclip.tools.core.hello_world(name="Ada")
        print(result)


asyncio.run(main())

Discover available tools

Use paperclip.list_tools() for the flat tool list or paperclip.manifest() for the full manifest payload.

Sync

from paperclip_sdk import Paperclip

with Paperclip() as paperclip:
    print(paperclip.list_tools())

Async

import asyncio

from paperclip_sdk import AsyncPaperclip


async def main() -> None:
    async with AsyncPaperclip() as paperclip:
        print(await paperclip.list_tools())


asyncio.run(main())

Error handling

By default, the SDK uses suppress_errors=True.

That means failed calls can return None instead of raising immediately, and the captured failure is available in last_error.

Sync

from paperclip_sdk import Paperclip

with Paperclip(suppress_errors=True) as paperclip:
    result = paperclip.tools.core.hello_world(name="Ada")

    if result is None:
        print("Call failed:", paperclip.last_error)

Async

import asyncio

from paperclip_sdk import AsyncPaperclip


async def main() -> None:
    async with AsyncPaperclip(suppress_errors=True) as paperclip:
        result = await paperclip.tools.core.hello_world(name="Ada")

        if result is None:
            print("Call failed:", paperclip.last_error)


asyncio.run(main())

To raise failures immediately, disable suppressed errors:

Sync

from paperclip_sdk import Paperclip

with Paperclip(suppress_errors=False) as paperclip:
    result = paperclip.tools.core.hello_world(name="Ada")
    print(result)

Async

import asyncio

from paperclip_sdk import AsyncPaperclip


async def main() -> None:
    async with AsyncPaperclip(suppress_errors=False) as paperclip:
        result = await paperclip.tools.core.hello_world(name="Ada")
        print(result)


asyncio.run(main())

Debug logging

from paperclip_sdk import Paperclip

with Paperclip(
    base_url="http://127.0.0.1:8889",
    debug=True,
    log_server_meta=True,
) as paperclip:
    result = paperclip.tools.core.hello_world(name="Ada")
    print(result)

Notes

• Tools can be accessed as paperclip.tools.<namespace>.<name>(...)
• Masked namespace access is also supported: paperclip.<namespace>.<name>(...)
• Flat concrete tool access is also supported: paperclip["<namespace>.<name>"](...)
• Registered tools can be discovered with paperclip.list_tools()
• The full manifest is available with paperclip.manifest()
• The default base URL is https://leasekey.org
• The SDK automatically sends User-Agent: paperclip-sdk/<version>
• The SDK also sends X-Leasekey-SDK-Version: <version>
• Built-in retry behavior covers retryable transport failures and these HTTP statuses: 408, 425, 429, 502, 503, 504