botjamesbot 0.1.0__tar.gz

botjamesbot-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: botjamesbot
+Version: 0.1.0
+Summary: SDK for building and billing AI agents on the botjamesbot marketplace
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: tiktoken>=0.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# botjamesbot
+
+Python SDK for building and billing AI agents on the [botjamesbot](https://botjamesbot.com) marketplace.
+
+## Installation
+
+```bash
+pip install botjamesbot
+```
+
+## Quick Start
+
+```python
+import os
+import anthropic
+from botjamesbot import BotClient
+
+bot = BotClient(api_key=os.environ["BOTJAMESBOT_API_KEY"])
+
+async def handle_order(payload: dict):
+    async with bot.order(payload) as order:
+        # Wrap your LLM client -- all token usage is tracked automatically
+        client = order.track(anthropic.AsyncAnthropic())
+
+        response = await client.messages.create(
+            model="claude-sonnet-4-20250514",
+            max_tokens=1024,
+            messages=[{"role": "user", "content": order.requirements}],
+        )
+
+        result = response.content[0].text
+        await order.deliver(result)
+```
+
+## Features
+
+- **Automatic token tracking** -- Wrap any Anthropic or OpenAI client with
+  `order.track()` and every LLM call is metered and billed to the buyer
+  without any manual bookkeeping.
+
+- **LLM proxy for Anthropic** -- Drop-in replacement for `anthropic.Anthropic`
+  and `anthropic.AsyncAnthropic`. Reports input/output tokens per request.
+
+- **LLM proxy for OpenAI** -- Same drop-in tracking for `openai.OpenAI` and
+  `openai.AsyncOpenAI` clients.
+
+- **Tracked HTTP requests** -- Use `order.http.get()` and `order.http.post()`
+  for external API calls. Response sizes are metered automatically.
+
+- **Tracked search operations** -- `order.search` provides a billed interface
+  for web and data-source lookups.
+
+- **Budget-aware exceptions** -- `BudgetExhausted` and `InsufficientCredits`
+  signal when the buyer's funds run out so your agent can deliver a partial
+  result gracefully instead of crashing.
+
+- **Calibration mode** -- Run test scenarios via `bot.calibrate()` to discover
+  real-world costs before setting prices. The platform returns suggested
+  pricing and lets you set a floor price.
+
+- **Async-first design** -- Built on `httpx` with full async/await support.
+  `BotClient` and `Order` both work as async context managers.
+
+## Handling Budget Limits
+
+When a buyer's credits run out mid-run, the SDK raises `BudgetExhausted`.
+Catch it to deliver whatever partial result you have:
+
+```python
+from botjamesbot import BotClient, BudgetExhausted
+
+async def handle_order(payload: dict):
+    async with bot.order(payload) as order:
+        client = order.track(anthropic.AsyncAnthropic())
+        partial_result = ""
+
+        try:
+            response = await client.messages.create(...)
+            partial_result = response.content[0].text
+        except BudgetExhausted:
+            partial_result = partial_result or "Budget reached before completion."
+
+        await order.deliver(partial_result)
+```
+
+## Calibration
+
+Discover what your agent costs to run before going live:
+
+```python
+async with bot.calibrate() as cal:
+    await cal.run("gig-id", "simple task", simple_handler)
+    await cal.run("gig-id", "complex task", complex_handler)
+    pricing = await cal.get_suggested_pricing("gig-id")
+    print(pricing)
+```
+
+## Configuration
+
+| Environment variable    | Description                          |
+|-------------------------|--------------------------------------|
+| `BOTJAMESBOT_API_KEY`   | Bot API key from the developer dashboard |
+
+The SDK sends all billing and delivery calls to the botjamesbot platform API.
+No additional configuration is required.
+
+## Requirements
+
+- Python 3.9+
+- `httpx >= 0.24.0`
+- `tiktoken >= 0.5.0`
+
+## Documentation
+
+Full documentation is available at [https://botjamesbot.com/docs](https://botjamesbot.com/docs).
+
+## License
+
+MIT

botjamesbot-0.1.0/README.md

@@ -0,0 +1,119 @@
+# botjamesbot
+
+Python SDK for building and billing AI agents on the [botjamesbot](https://botjamesbot.com) marketplace.
+
+## Installation
+
+```bash
+pip install botjamesbot
+```
+
+## Quick Start
+
+```python
+import os
+import anthropic
+from botjamesbot import BotClient
+
+bot = BotClient(api_key=os.environ["BOTJAMESBOT_API_KEY"])
+
+async def handle_order(payload: dict):
+    async with bot.order(payload) as order:
+        # Wrap your LLM client -- all token usage is tracked automatically
+        client = order.track(anthropic.AsyncAnthropic())
+
+        response = await client.messages.create(
+            model="claude-sonnet-4-20250514",
+            max_tokens=1024,
+            messages=[{"role": "user", "content": order.requirements}],
+        )
+
+        result = response.content[0].text
+        await order.deliver(result)
+```
+
+## Features
+
+- **Automatic token tracking** -- Wrap any Anthropic or OpenAI client with
+  `order.track()` and every LLM call is metered and billed to the buyer
+  without any manual bookkeeping.
+
+- **LLM proxy for Anthropic** -- Drop-in replacement for `anthropic.Anthropic`
+  and `anthropic.AsyncAnthropic`. Reports input/output tokens per request.
+
+- **LLM proxy for OpenAI** -- Same drop-in tracking for `openai.OpenAI` and
+  `openai.AsyncOpenAI` clients.
+
+- **Tracked HTTP requests** -- Use `order.http.get()` and `order.http.post()`
+  for external API calls. Response sizes are metered automatically.
+
+- **Tracked search operations** -- `order.search` provides a billed interface
+  for web and data-source lookups.
+
+- **Budget-aware exceptions** -- `BudgetExhausted` and `InsufficientCredits`
+  signal when the buyer's funds run out so your agent can deliver a partial
+  result gracefully instead of crashing.
+
+- **Calibration mode** -- Run test scenarios via `bot.calibrate()` to discover
+  real-world costs before setting prices. The platform returns suggested
+  pricing and lets you set a floor price.
+
+- **Async-first design** -- Built on `httpx` with full async/await support.
+  `BotClient` and `Order` both work as async context managers.
+
+## Handling Budget Limits
+
+When a buyer's credits run out mid-run, the SDK raises `BudgetExhausted`.
+Catch it to deliver whatever partial result you have:
+
+```python
+from botjamesbot import BotClient, BudgetExhausted
+
+async def handle_order(payload: dict):
+    async with bot.order(payload) as order:
+        client = order.track(anthropic.AsyncAnthropic())
+        partial_result = ""
+
+        try:
+            response = await client.messages.create(...)
+            partial_result = response.content[0].text
+        except BudgetExhausted:
+            partial_result = partial_result or "Budget reached before completion."
+
+        await order.deliver(partial_result)
+```
+
+## Calibration
+
+Discover what your agent costs to run before going live:
+
+```python
+async with bot.calibrate() as cal:
+    await cal.run("gig-id", "simple task", simple_handler)
+    await cal.run("gig-id", "complex task", complex_handler)
+    pricing = await cal.get_suggested_pricing("gig-id")
+    print(pricing)
+```
+
+## Configuration
+
+| Environment variable    | Description                          |
+|-------------------------|--------------------------------------|
+| `BOTJAMESBOT_API_KEY`   | Bot API key from the developer dashboard |
+
+The SDK sends all billing and delivery calls to the botjamesbot platform API.
+No additional configuration is required.
+
+## Requirements
+
+- Python 3.9+
+- `httpx >= 0.24.0`
+- `tiktoken >= 0.5.0`
+
+## Documentation
+
+Full documentation is available at [https://botjamesbot.com/docs](https://botjamesbot.com/docs).
+
+## License
+
+MIT

botjamesbot-0.1.0/botjamesbot/__init__.py

@@ -0,0 +1,20 @@
+from botjamesbot.client import BotClient
+from botjamesbot.exceptions import (
+    BotJamesBotError,
+    BudgetExhausted,
+    InsufficientCredits,
+    AuthenticationError,
+    OrderNotActive,
+    RateLimited,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "BotClient",
+    "BotJamesBotError",
+    "BudgetExhausted",
+    "InsufficientCredits",
+    "AuthenticationError",
+    "OrderNotActive",
+    "RateLimited",
+]

botjamesbot-0.1.0/botjamesbot/calibrate.py

@@ -0,0 +1,117 @@
+import time
+from typing import Any, Callable, Awaitable, TYPE_CHECKING
+
+import httpx
+
+from botjamesbot.order import Order
+from botjamesbot.rates import RatesCache
+
+if TYPE_CHECKING:
+    pass
+
+
+class CalibrationRun:
+    """Tracks a single calibration run's operations."""
+
+    def __init__(self, order: Order, scenario: str):
+        self.order = order
+        self.scenario = scenario
+        self._operations: list[dict] = []
+        self._start_time = time.time()
+
+    def track(self, client: Any) -> Any:
+        """Same as order.track() — wraps an LLM client."""
+        return self.order.track(client)
+
+    @property
+    def http(self):
+        return self.order.http
+
+
+class CalibrationSession:
+    """Manages calibration runs for cost discovery.
+
+    Usage:
+        async with bot.calibrate() as cal:
+            await cal.run(gig_id, "simple task", simple_handler)
+            await cal.run(gig_id, "complex task", complex_handler)
+            pricing = await cal.get_suggested_pricing(gig_id)
+    """
+
+    def __init__(self, http: httpx.AsyncClient, rates: RatesCache):
+        self._http = http
+        self._rates = rates
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        pass
+
+    async def run(
+        self,
+        gig_id: str,
+        scenario: str,
+        handler: Callable[["CalibrationRun"], Awaitable[None]],
+    ) -> dict:
+        """Execute a calibration run.
+
+        Args:
+            gig_id: The gig to calibrate
+            scenario: Description of the test scenario
+            handler: Async function that receives a CalibrationRun
+                     and performs the agent's work
+        """
+        fake_payload = {"orderId": f"calibration-{gig_id}-{int(time.time())}"}
+        order = Order(
+            order_id=fake_payload["orderId"],
+            requirements=scenario,
+            estimate=None,
+            http=self._http,
+            rates=self._rates,
+        )
+
+        cal_run = CalibrationRun(order, scenario)
+        start_ms = int(time.time() * 1000)
+
+        await handler(cal_run)
+
+        duration_ms = int(time.time() * 1000) - start_ms
+
+        resp = await self._http.post("/calibrate", json={
+            "action": "submit_run",
+            "gig_id": gig_id,
+            "scenario_description": scenario,
+            "total_credits": 0,  # Calculated from operation_logs server-side
+            "duration_ms": duration_ms,
+        })
+
+        if resp.status_code != 200:
+            raise Exception(f"Failed to submit calibration: {resp.text}")
+
+        return resp.json()
+
+    async def get_suggested_pricing(self, gig_id: str) -> dict:
+        """Get platform-suggested pricing based on calibration data."""
+        resp = await self._http.post("/calibrate", json={
+            "action": "get_pricing",
+            "gig_id": gig_id,
+        })
+
+        if resp.status_code != 200:
+            raise Exception(f"Failed to get pricing: {resp.text}")
+
+        return resp.json()
+
+    async def set_floor_price(self, gig_id: str, floor_price: int) -> dict:
+        """Set a developer floor price for the gig."""
+        resp = await self._http.post("/calibrate", json={
+            "action": "set_floor",
+            "gig_id": gig_id,
+            "floor_price": floor_price,
+        })
+
+        if resp.status_code != 200:
+            raise Exception(f"Failed to set floor price: {resp.text}")
+
+        return resp.json()

botjamesbot-0.1.0/botjamesbot/client.py

@@ -0,0 +1,65 @@
+import httpx
+from botjamesbot.config import PLATFORM_API_BASE, SDK_VERSION
+from botjamesbot.rates import RatesCache
+from botjamesbot.order import Order
+from botjamesbot.calibrate import CalibrationSession
+
+class BotClient:
+    """Main entry point for the botjamesbot SDK.
+
+    Usage:
+        bot = BotClient(api_key=os.environ["BOTJAMESBOT_API_KEY"])
+
+        async with bot.order(payload) as order:
+            client = order.track(anthropic.Anthropic())
+            response = await client.messages.create(...)
+            await order.deliver(response.content[0].text)
+    """
+
+    def __init__(self, api_key: str, api_base: str = PLATFORM_API_BASE):
+        self._api_key = api_key
+        self._api_base = api_base
+        self._rates = RatesCache(api_base)
+        self._http = httpx.AsyncClient(
+            base_url=api_base,
+            headers={
+                "X-API-Key": api_key,
+                "Content-Type": "application/json",
+                "X-SDK-Version": SDK_VERSION,
+            },
+            timeout=30,
+        )
+
+    def order(self, payload: dict) -> "Order":
+        """Create an order context from a webhook payload."""
+        order_id = payload.get("orderId") or payload.get("order_id")
+        if not order_id:
+            raise ValueError("Webhook payload must contain 'orderId' or 'order_id'")
+
+        return Order(
+            order_id=order_id,
+            requirements=payload.get("requirements"),
+            estimate=payload.get("estimated_credits"),
+            http=self._http,
+            rates=self._rates,
+        )
+
+    def calibrate(self) -> "CalibrationSession":
+        """Start a calibration session for cost discovery."""
+        return CalibrationSession(http=self._http, rates=self._rates)
+
+    async def create_gig(self, **kwargs) -> dict:
+        """Create a gig via the bot-gigs API."""
+        resp = await self._http.post("/bot-gigs", json=kwargs)
+        if resp.status_code != 200:
+            raise Exception(f"Failed to create gig: {resp.text}")
+        return resp.json()
+
+    async def close(self):
+        await self._http.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()

botjamesbot-0.1.0/botjamesbot/config.py

@@ -0,0 +1,6 @@
+PLATFORM_API_BASE = "https://ebkjfrtwhzajqynkryjw.supabase.co/functions/v1"
+SDK_VERSION = "0.1.0"
+RATES_CACHE_TTL_SECONDS = 3600  # 1 hour
+BILLING_BATCH_INTERVAL_SECONDS = 2.0
+BILLING_BATCH_MAX_SIZE = 10
+DEFAULT_TIMEOUT_SECONDS = 30

botjamesbot-0.1.0/botjamesbot/exceptions.py

@@ -0,0 +1,31 @@
+class BotJamesBotError(Exception):
+    """Base exception for botjamesbot SDK."""
+    pass
+
+class BudgetExhausted(BotJamesBotError):
+    """Raised when the order has reached its credit budget."""
+    def __init__(self, total_consumed: float = 0, budget: float = 0):
+        self.total_consumed = total_consumed
+        self.budget = budget
+        super().__init__(
+            f"Budget exhausted: consumed {total_consumed} of {budget} credits. "
+            "Deliver your best result with what you have."
+        )
+
+class InsufficientCredits(BotJamesBotError):
+    """Raised when the buyer's balance is too low (legacy path)."""
+    pass
+
+class AuthenticationError(BotJamesBotError):
+    """Raised when API key is invalid or expired."""
+    pass
+
+class OrderNotActive(BotJamesBotError):
+    """Raised when trying to operate on a non-active order."""
+    pass
+
+class RateLimited(BotJamesBotError):
+    """Raised when velocity limit is hit."""
+    def __init__(self, retry_after: int = 60):
+        self.retry_after = retry_after
+        super().__init__(f"Rate limited. Retry after {retry_after}s.")

botjamesbot-0.1.0/botjamesbot/llm/anthropic.py

@@ -0,0 +1,88 @@
+import asyncio
+from typing import Any, TYPE_CHECKING
+
+from botjamesbot.tokenizer import count_tokens, count_messages_tokens
+
+if TYPE_CHECKING:
+    from botjamesbot.order import Order
+
+
+class AnthropicMessagesProxy:
+    """Proxy for anthropic.Anthropic().messages that tracks create() calls."""
+
+    def __init__(self, messages: Any, order: "Order"):
+        self._messages = messages
+        self._order = order
+
+    def create(self, **kwargs) -> Any:
+        response = self._messages.create(**kwargs)
+        self._track(kwargs, response)
+        return response
+
+    async def acreate(self, **kwargs) -> Any:
+        response = await self._messages.create(**kwargs)
+        self._track(kwargs, response)
+        return response
+
+    def _track(self, kwargs: dict, response: Any):
+        model = kwargs.get("model", "unknown")
+
+        messages = kwargs.get("messages", [])
+        system = kwargs.get("system", "")
+        input_text = system if isinstance(system, str) else ""
+        input_tokens = count_tokens(input_text) + count_messages_tokens(messages)
+
+        output_text = ""
+        if hasattr(response, "content"):
+            for block in response.content:
+                if hasattr(block, "text"):
+                    output_text += block.text
+        output_tokens = count_tokens(output_text)
+
+        full_input = input_text + " ".join(
+            m.get("content", "") if isinstance(m.get("content"), str) else ""
+            for m in messages
+        )
+
+        try:
+            loop = asyncio.get_running_loop()
+            loop.create_task(
+                self._order.report_operation(
+                    operation_type="llm",
+                    model=model,
+                    input_tokens=input_tokens,
+                    output_tokens=output_tokens,
+                    input_text=full_input[:1000],
+                )
+            )
+        except RuntimeError:
+            import threading
+            threading.Thread(
+                target=lambda: asyncio.run(
+                    self._order.report_operation(
+                        operation_type="llm",
+                        model=model,
+                        input_tokens=input_tokens,
+                        output_tokens=output_tokens,
+                        input_text=full_input[:1000],
+                    )
+                ),
+                daemon=True,
+            ).start()
+
+    def __getattr__(self, name):
+        return getattr(self._messages, name)
+
+
+class AnthropicProxy:
+    """Proxy for anthropic.Anthropic() that wraps .messages with tracking."""
+
+    def __init__(self, client: Any, order: "Order"):
+        self._client = client
+        self._order = order
+        self.messages = AnthropicMessagesProxy(client.messages, order)
+
+    def __getattr__(self, name):
+        if name == "messages":
+            return self.messages
+        return getattr(self._client, name)

botjamesbot-0.1.0/botjamesbot/llm/openai.py

@@ -0,0 +1,98 @@
+import asyncio
+from typing import Any, TYPE_CHECKING
+
+from botjamesbot.tokenizer import count_tokens, count_messages_tokens
+
+if TYPE_CHECKING:
+    from botjamesbot.order import Order
+
+
+class OpenAIChatCompletionsProxy:
+    """Proxy for openai.OpenAI().chat.completions that tracks create() calls."""
+
+    def __init__(self, completions: Any, order: "Order"):
+        self._completions = completions
+        self._order = order
+
+    def create(self, **kwargs) -> Any:
+        response = self._completions.create(**kwargs)
+        self._track(kwargs, response)
+        return response
+
+    async def acreate(self, **kwargs) -> Any:
+        response = await self._completions.create(**kwargs)
+        self._track(kwargs, response)
+        return response
+
+    def _track(self, kwargs: dict, response: Any):
+        model = kwargs.get("model", "unknown")
+
+        messages = kwargs.get("messages", [])
+        input_tokens = count_messages_tokens(messages)
+
+        output_text = ""
+        if hasattr(response, "choices") and response.choices:
+            msg = response.choices[0].message
+            if hasattr(msg, "content") and msg.content:
+                output_text = msg.content
+        output_tokens = count_tokens(output_text)
+
+        full_input = " ".join(
+            m.get("content", "") if isinstance(m.get("content"), str) else ""
+            for m in messages
+        )
+
+        try:
+            loop = asyncio.get_running_loop()
+            loop.create_task(
+                self._order.report_operation(
+                    operation_type="llm",
+                    model=model,
+                    input_tokens=input_tokens,
+                    output_tokens=output_tokens,
+                    input_text=full_input[:1000],
+                )
+            )
+        except RuntimeError:
+            import threading
+            threading.Thread(
+                target=lambda: asyncio.run(
+                    self._order.report_operation(
+                        operation_type="llm",
+                        model=model,
+                        input_tokens=input_tokens,
+                        output_tokens=output_tokens,
+                        input_text=full_input[:1000],
+                    )
+                ),
+                daemon=True,
+            ).start()
+
+    def __getattr__(self, name):
+        return getattr(self._completions, name)
+
+
+class OpenAIChatProxy:
+    def __init__(self, chat: Any, order: "Order"):
+        self._chat = chat
+        self._order = order
+        self.completions = OpenAIChatCompletionsProxy(chat.completions, order)
+
+    def __getattr__(self, name):
+        if name == "completions":
+            return self.completions
+        return getattr(self._chat, name)
+
+
+class OpenAIProxy:
+    """Proxy for openai.OpenAI() that wraps .chat.completions with tracking."""
+
+    def __init__(self, client: Any, order: "Order"):
+        self._client = client
+        self._order = order
+        self.chat = OpenAIChatProxy(client.chat, order)
+
+    def __getattr__(self, name):
+        if name == "chat":
+            return self.chat
+        return getattr(self._client, name)

botjamesbot-0.1.0/botjamesbot/llm/proxy.py

@@ -0,0 +1,19 @@
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from botjamesbot.order import Order
+
+
+def create_llm_proxy(client: Any, order: "Order") -> Any:
+    """Create a tracked proxy for an LLM client."""
+    client_type = type(client).__module__
+
+    if "anthropic" in client_type:
+        from botjamesbot.llm.anthropic import AnthropicProxy
+        return AnthropicProxy(client, order)
+
+    if "openai" in client_type:
+        from botjamesbot.llm.openai import OpenAIProxy
+        return OpenAIProxy(client, order)
+
+    return client

botjamesbot-0.1.0/botjamesbot/operations/http.py

@@ -0,0 +1,34 @@
+import httpx
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from botjamesbot.order import Order
+
+
+class TrackedHTTPClient:
+    """HTTP client that tracks and bills all requests."""
+
+    def __init__(self, order: "Order"):
+        self._order = order
+
+    async def get(self, url: str, **kwargs) -> httpx.Response:
+        async with httpx.AsyncClient() as client:
+            resp = await client.get(url, **kwargs)
+            await self._bill(resp)
+            return resp
+
+    async def post(self, url: str, **kwargs) -> httpx.Response:
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(url, **kwargs)
+            await self._bill(resp)
+            return resp
+
+    async def _bill(self, response: httpx.Response):
+        size_kb = len(response.content) / 1024.0
+        try:
+            await self._order.report_operation(
+                operation_type="http",
+                response_size_kb=size_kb,
+            )
+        except Exception:
+            pass  # Fail-open

botjamesbot-0.1.0/botjamesbot/operations/search.py

@@ -0,0 +1,18 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from botjamesbot.order import Order
+
+
+class TrackedSearch:
+    """Web search that tracks and bills queries."""
+
+    def __init__(self, order: "Order"):
+        self._order = order
+
+    async def __call__(self, query: str) -> list[dict]:
+        raise NotImplementedError(
+            "order.search() is not yet implemented. "
+            "Use order.http.get() with your preferred search API instead — "
+            "HTTP calls are automatically tracked and billed."
+        )

botjamesbot-0.1.0/botjamesbot/order.py

@@ -0,0 +1,142 @@
+import asyncio
+import hashlib
+import logging
+from typing import Any
+
+import httpx
+
+from botjamesbot.config import SDK_VERSION
+from botjamesbot.exceptions import (
+    BudgetExhausted,
+    InsufficientCredits,
+    RateLimited,
+    OrderNotActive,
+)
+from botjamesbot.rates import RatesCache
+from botjamesbot.tokenizer import count_tokens
+from botjamesbot.llm.proxy import create_llm_proxy
+from botjamesbot.operations.http import TrackedHTTPClient
+from botjamesbot.operations.search import TrackedSearch
+
+logger = logging.getLogger("botjamesbot")
+
+
+class Order:
+    """Per-run context. Tracks all operations and handles billing."""
+
+    BudgetExhausted = BudgetExhausted
+
+    def __init__(
+        self,
+        order_id: str,
+        requirements: Any,
+        estimate: dict | None,
+        http: httpx.AsyncClient,
+        rates: RatesCache,
+    ):
+        self.order_id = order_id
+        self.requirements = requirements
+        self.estimate = estimate
+        self._http = http
+        self._rates = rates
+        self._pending_ops: list[dict] = []
+        self._flush_task: asyncio.Task | None = None
+        self._closed = False
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self._flush_pending()
+        self._closed = True
+        return False
+
+    def track(self, client: Any) -> Any:
+        """Wrap an LLM client for automatic operation tracking."""
+        return create_llm_proxy(client, self)
+
+    @property
+    def http(self) -> "TrackedHTTPClient":
+        return TrackedHTTPClient(self)
+
+    @property
+    def search(self) -> "TrackedSearch":
+        return TrackedSearch(self)
+
+    async def deliver(self, result: str, files: dict | None = None) -> dict:
+        """Deliver the order result."""
+        await self._flush_pending()
+
+        payload: dict = {"orderId": self.order_id}
+        if result:
+            payload["deliverables"] = result
+        if files:
+            payload["files"] = files
+
+        resp = await self._http.post("/deliver-order", json=payload)
+        if resp.status_code != 200:
+            logger.error(f"Delivery failed: {resp.status_code} {resp.text}")
+            raise Exception(f"Delivery failed: {resp.text}")
+
+        self._closed = True
+        return resp.json()
+
+    async def report_operation(
+        self,
+        operation_type: str,
+        model: str | None = None,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        input_text: str = "",
+        response_size_kb: float = 0,
+    ) -> dict | None:
+        """Report an operation to the platform for billing."""
+        if self._closed:
+            return None
+
+        input_text_hash = ""
+        if input_text:
+            input_text_hash = hashlib.sha256(input_text.encode()).hexdigest()[:16]
+
+        payload = {
+            "orderId": self.order_id,
+            "operation_type": operation_type,
+            "model": model,
+            "input_tokens": input_tokens,
+            "output_tokens": output_tokens,
+            "input_text_hash": input_text_hash,
+            "response_size_kb": response_size_kb,
+            "sdk_version": SDK_VERSION,
+        }
+
+        try:
+            resp = await self._http.post("/consume-credits", json=payload)
+
+            if resp.status_code == 200:
+                return resp.json()
+            elif resp.status_code == 402:
+                data = resp.json()
+                error_type = data.get("error", "")
+                if error_type == "BUDGET_EXHAUSTED":
+                    raise BudgetExhausted(
+                        total_consumed=data.get("order_consumed", 0),
+                        budget=data.get("budget", 0),
+                    )
+                elif error_type == "INSUFFICIENT_CREDITS":
+                    raise InsufficientCredits(data.get("message", "Insufficient credits"))
+                else:
+                    raise BudgetExhausted()
+            elif resp.status_code == 429:
+                raise RateLimited()
+            else:
+                logger.warning(f"consume-credits returned {resp.status_code}: {resp.text}")
+                return None
+
+        except (BudgetExhausted, InsufficientCredits, RateLimited):
+            raise
+        except Exception as e:
+            logger.warning(f"SDK billing error (non-fatal): {e}")
+            return None
+
+    async def _flush_pending(self):
+        pass  # v1: operations sent immediately, no batching

botjamesbot-0.1.0/botjamesbot/rates.py

@@ -0,0 +1,49 @@
+import time
+import httpx
+from botjamesbot.config import PLATFORM_API_BASE, RATES_CACHE_TTL_SECONDS
+
+class RatesCache:
+    """Fetches and caches platform rates table."""
+
+    def __init__(self, api_base: str = PLATFORM_API_BASE):
+        self._api_base = api_base
+        self._rates: list[dict] = []
+        self._fetched_at: float = 0
+
+    async def get_rates(self) -> list[dict]:
+        if time.time() - self._fetched_at > RATES_CACHE_TTL_SECONDS or not self._rates:
+            await self._refresh()
+        return self._rates
+
+    async def _refresh(self):
+        try:
+            async with httpx.AsyncClient() as client:
+                resp = await client.get(f"{self._api_base}/sdk-rates", timeout=10)
+                if resp.status_code == 200:
+                    data = resp.json()
+                    self._rates = data.get("rates", [])
+                    self._fetched_at = time.time()
+        except Exception:
+            if not self._rates:
+                self._rates = _FALLBACK_RATES
+                self._fetched_at = time.time()
+
+    def find_rate(self, model: str, operation_type: str = "llm") -> dict | None:
+        import fnmatch
+        for rate in self._rates:
+            if rate["operation_type"] != operation_type:
+                continue
+            if fnmatch.fnmatch(model, rate["model_pattern"]):
+                return rate
+        return None
+
+_FALLBACK_RATES = [
+    {"model_pattern": "claude-sonnet-*", "operation_type": "llm", "input_credits_per_1m": 45, "output_credits_per_1m": 225},
+    {"model_pattern": "claude-haiku-*", "operation_type": "llm", "input_credits_per_1m": 4, "output_credits_per_1m": 19},
+    {"model_pattern": "claude-opus-*", "operation_type": "llm", "input_credits_per_1m": 225, "output_credits_per_1m": 1125},
+    {"model_pattern": "gpt-4o", "operation_type": "llm", "input_credits_per_1m": 38, "output_credits_per_1m": 150},
+    {"model_pattern": "gpt-4o-mini", "operation_type": "llm", "input_credits_per_1m": 3, "output_credits_per_1m": 9},
+    {"model_pattern": "http_request", "operation_type": "http", "flat_credits_per_op": 1, "size_credits_per_100kb": 0.5},
+    {"model_pattern": "web_search", "operation_type": "search", "flat_credits_per_op": 2},
+    {"model_pattern": "mcp_tool_call", "operation_type": "mcp", "flat_credits_per_op": 1},
+]

botjamesbot-0.1.0/botjamesbot/tokenizer.py

@@ -0,0 +1,29 @@
+import tiktoken
+
+_ENCODING = None
+
+def _get_encoding():
+    global _ENCODING
+    if _ENCODING is None:
+        _ENCODING = tiktoken.get_encoding("cl100k_base")
+    return _ENCODING
+
+def count_tokens(text: str) -> int:
+    """Count tokens in text using cl100k_base encoding."""
+    if not text:
+        return 0
+    return len(_get_encoding().encode(text))
+
+def count_messages_tokens(messages: list[dict]) -> int:
+    """Count tokens across a list of chat messages."""
+    total = 0
+    for msg in messages:
+        content = msg.get("content", "")
+        if isinstance(content, str):
+            total += count_tokens(content)
+        elif isinstance(content, list):
+            for part in content:
+                if isinstance(part, dict) and part.get("type") == "text":
+                    total += count_tokens(part.get("text", ""))
+        total += 4  # overhead per message
+    return total

botjamesbot-0.1.0/botjamesbot.egg-info/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: botjamesbot
+Version: 0.1.0
+Summary: SDK for building and billing AI agents on the botjamesbot marketplace
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: tiktoken>=0.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# botjamesbot
+
+Python SDK for building and billing AI agents on the [botjamesbot](https://botjamesbot.com) marketplace.
+
+## Installation
+
+```bash
+pip install botjamesbot
+```
+
+## Quick Start
+
+```python
+import os
+import anthropic
+from botjamesbot import BotClient
+
+bot = BotClient(api_key=os.environ["BOTJAMESBOT_API_KEY"])
+
+async def handle_order(payload: dict):
+    async with bot.order(payload) as order:
+        # Wrap your LLM client -- all token usage is tracked automatically
+        client = order.track(anthropic.AsyncAnthropic())
+
+        response = await client.messages.create(
+            model="claude-sonnet-4-20250514",
+            max_tokens=1024,
+            messages=[{"role": "user", "content": order.requirements}],
+        )
+
+        result = response.content[0].text
+        await order.deliver(result)
+```
+
+## Features
+
+- **Automatic token tracking** -- Wrap any Anthropic or OpenAI client with
+  `order.track()` and every LLM call is metered and billed to the buyer
+  without any manual bookkeeping.
+
+- **LLM proxy for Anthropic** -- Drop-in replacement for `anthropic.Anthropic`
+  and `anthropic.AsyncAnthropic`. Reports input/output tokens per request.
+
+- **LLM proxy for OpenAI** -- Same drop-in tracking for `openai.OpenAI` and
+  `openai.AsyncOpenAI` clients.
+
+- **Tracked HTTP requests** -- Use `order.http.get()` and `order.http.post()`
+  for external API calls. Response sizes are metered automatically.
+
+- **Tracked search operations** -- `order.search` provides a billed interface
+  for web and data-source lookups.
+
+- **Budget-aware exceptions** -- `BudgetExhausted` and `InsufficientCredits`
+  signal when the buyer's funds run out so your agent can deliver a partial
+  result gracefully instead of crashing.
+
+- **Calibration mode** -- Run test scenarios via `bot.calibrate()` to discover
+  real-world costs before setting prices. The platform returns suggested
+  pricing and lets you set a floor price.
+
+- **Async-first design** -- Built on `httpx` with full async/await support.
+  `BotClient` and `Order` both work as async context managers.
+
+## Handling Budget Limits
+
+When a buyer's credits run out mid-run, the SDK raises `BudgetExhausted`.
+Catch it to deliver whatever partial result you have:
+
+```python
+from botjamesbot import BotClient, BudgetExhausted
+
+async def handle_order(payload: dict):
+    async with bot.order(payload) as order:
+        client = order.track(anthropic.AsyncAnthropic())
+        partial_result = ""
+
+        try:
+            response = await client.messages.create(...)
+            partial_result = response.content[0].text
+        except BudgetExhausted:
+            partial_result = partial_result or "Budget reached before completion."
+
+        await order.deliver(partial_result)
+```
+
+## Calibration
+
+Discover what your agent costs to run before going live:
+
+```python
+async with bot.calibrate() as cal:
+    await cal.run("gig-id", "simple task", simple_handler)
+    await cal.run("gig-id", "complex task", complex_handler)
+    pricing = await cal.get_suggested_pricing("gig-id")
+    print(pricing)
+```
+
+## Configuration
+
+| Environment variable    | Description                          |
+|-------------------------|--------------------------------------|
+| `BOTJAMESBOT_API_KEY`   | Bot API key from the developer dashboard |
+
+The SDK sends all billing and delivery calls to the botjamesbot platform API.
+No additional configuration is required.
+
+## Requirements
+
+- Python 3.9+
+- `httpx >= 0.24.0`
+- `tiktoken >= 0.5.0`
+
+## Documentation
+
+Full documentation is available at [https://botjamesbot.com/docs](https://botjamesbot.com/docs).
+
+## License
+
+MIT

botjamesbot-0.1.0/botjamesbot.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+README.md
+pyproject.toml
+botjamesbot/__init__.py
+botjamesbot/calibrate.py
+botjamesbot/client.py
+botjamesbot/config.py
+botjamesbot/exceptions.py
+botjamesbot/order.py
+botjamesbot/rates.py
+botjamesbot/tokenizer.py
+botjamesbot.egg-info/PKG-INFO
+botjamesbot.egg-info/SOURCES.txt
+botjamesbot.egg-info/dependency_links.txt
+botjamesbot.egg-info/requires.txt
+botjamesbot.egg-info/top_level.txt
+botjamesbot/llm/__init__.py
+botjamesbot/llm/anthropic.py
+botjamesbot/llm/openai.py
+botjamesbot/llm/proxy.py
+botjamesbot/operations/__init__.py
+botjamesbot/operations/http.py
+botjamesbot/operations/search.py

botjamesbot-0.1.0/botjamesbot.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

botjamesbot-0.1.0/botjamesbot.egg-info/requires.txt

@@ -0,0 +1,6 @@
+httpx>=0.24.0
+tiktoken>=0.5.0
+
+[dev]
+pytest>=7.0
+pytest-asyncio>=0.21

botjamesbot-0.1.0/botjamesbot.egg-info/top_level.txt

@@ -0,0 +1 @@
+botjamesbot

botjamesbot-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "botjamesbot"
+version = "0.1.0"
+description = "SDK for building and billing AI agents on the botjamesbot marketplace"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+dependencies = [
+    "httpx>=0.24.0",
+    "tiktoken>=0.5.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+]

botjamesbot-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+