clervo-sdk 0.1.0__tar.gz

clervo_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.1
+Name: clervo-sdk
+Version: 0.1.0
+Summary: Clervo x402 Gateway SDK
+License: MIT
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.24
+Description-Content-Type: text/markdown
+
+# clervo
+
+Python SDK for the [Clervo x402 Gateway](https://api.clervo.dev).
+
+23 AI models. 8 free. Pay per call in USDC on Solana. No API keys.
+
+## Install
+
+```bash
+pip install clervo
+```
+
+## Quick start
+
+```python
+from clervo import Clervo
+
+client = Clervo()
+
+# Free call — no wallet needed
+text = client.chat("groq/llama-3.1-8b-instant", "Explain recursion in 2 sentences")
+print(text)
+
+# List models
+models = client.models()
+free = client.free_models()
+print(f"{len(free)} free models available")
+```
+
+## Free models
+
+No payment, no wallet, no signup:
+
+| Model | Speed | Best for |
+|-------|-------|----------|
+| `groq/llama-3.1-8b-instant` | 170ms | Fast responses |
+| `groq/llama-3.3-70b` | 800ms | Strong general |
+| `sambanova/deepseek-v3.2` | 1.6s | Reasoning |
+| `sambanova/llama-3.3-70b` | 1.5s | General |
+| `hcn/qwen3.6-35b` | 0.9s | Fast small |
+| `hcn/step-3.7-flash` | 3s | Reasoning |
+| `hcn/deepseek-v4-pro` | 9s | Deep reasoning |
+| `hcn/auto` | 3s | Auto-routed |
+
+## Paid models (10-20% cheaper than BlockRun)
+
+```python
+from clervo import Clervo, PaymentRequired
+
+client = Clervo()
+
+try:
+    text = client.chat("tongkhokr/claude-opus-5", "Review this code...")
+except PaymentRequired:
+    print("Fund a Solana wallet with USDC for paid models")
+```
+
+| Model | Price/req |
+|-------|-----------|
+| `tongkhokr/claude-haiku-4.5` | $0.002 |
+| `tongkhokr/claude-sonnet-5` | $0.015 |
+| `tongkhokr/claude-opus-5` | $0.084 |
+| `quickai/gpt-5.4-mini` | $0.005 |
+| `quickai/gpt-5.5` | $0.035 |
+
+## API
+
+### `Clervo(api_url=None, timeout=30.0)`
+
+| Param | Default | Description |
+|-------|---------|-------------|
+| `api_url` | `https://api.clervo.dev` | API base URL |
+| `timeout` | `30.0` | Request timeout seconds |
+
+### `client.chat(model, message, *, system=None, max_tokens=1024)`
+
+Simple chat. Returns the text response.
+
+### `client.chat_completion(model, messages, *, max_tokens=1024, response_format=None)`
+
+Full OpenAI-compatible chat completion. Returns the full response dict.
+
+### `client.models()`
+
+List all available models.
+
+### `client.free_models()`
+
+List only free models.
+
+### `client.operation(operation_id)`
+
+Look up an operation by ID.
+
+## OpenAI drop-in
+
+Since Clervo is OpenAI-compatible:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="https://api.clervo.dev/v1",
+    api_key="unused"  # no key needed for free models
+)
+
+response = client.chat.completions.create(
+    model="groq/llama-3.1-8b-instant",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+print(response.choices[0].message.content)
+```
+
+## Links
+
+- API: https://api.clervo.dev
+- Models: https://api.clervo.dev/v1/models
+- Quickstart: https://api.clervo.dev/quickstart.md
+- TypeScript SDK: https://npmjs.com/package/@clervo/sdk
+- MCP: https://npmjs.com/package/@clervo/mcp

clervo_sdk-0.1.0/README.md

@@ -0,0 +1,120 @@
+# clervo
+
+Python SDK for the [Clervo x402 Gateway](https://api.clervo.dev).
+
+23 AI models. 8 free. Pay per call in USDC on Solana. No API keys.
+
+## Install
+
+```bash
+pip install clervo
+```
+
+## Quick start
+
+```python
+from clervo import Clervo
+
+client = Clervo()
+
+# Free call — no wallet needed
+text = client.chat("groq/llama-3.1-8b-instant", "Explain recursion in 2 sentences")
+print(text)
+
+# List models
+models = client.models()
+free = client.free_models()
+print(f"{len(free)} free models available")
+```
+
+## Free models
+
+No payment, no wallet, no signup:
+
+| Model | Speed | Best for |
+|-------|-------|----------|
+| `groq/llama-3.1-8b-instant` | 170ms | Fast responses |
+| `groq/llama-3.3-70b` | 800ms | Strong general |
+| `sambanova/deepseek-v3.2` | 1.6s | Reasoning |
+| `sambanova/llama-3.3-70b` | 1.5s | General |
+| `hcn/qwen3.6-35b` | 0.9s | Fast small |
+| `hcn/step-3.7-flash` | 3s | Reasoning |
+| `hcn/deepseek-v4-pro` | 9s | Deep reasoning |
+| `hcn/auto` | 3s | Auto-routed |
+
+## Paid models (10-20% cheaper than BlockRun)
+
+```python
+from clervo import Clervo, PaymentRequired
+
+client = Clervo()
+
+try:
+    text = client.chat("tongkhokr/claude-opus-5", "Review this code...")
+except PaymentRequired:
+    print("Fund a Solana wallet with USDC for paid models")
+```
+
+| Model | Price/req |
+|-------|-----------|
+| `tongkhokr/claude-haiku-4.5` | $0.002 |
+| `tongkhokr/claude-sonnet-5` | $0.015 |
+| `tongkhokr/claude-opus-5` | $0.084 |
+| `quickai/gpt-5.4-mini` | $0.005 |
+| `quickai/gpt-5.5` | $0.035 |
+
+## API
+
+### `Clervo(api_url=None, timeout=30.0)`
+
+| Param | Default | Description |
+|-------|---------|-------------|
+| `api_url` | `https://api.clervo.dev` | API base URL |
+| `timeout` | `30.0` | Request timeout seconds |
+
+### `client.chat(model, message, *, system=None, max_tokens=1024)`
+
+Simple chat. Returns the text response.
+
+### `client.chat_completion(model, messages, *, max_tokens=1024, response_format=None)`
+
+Full OpenAI-compatible chat completion. Returns the full response dict.
+
+### `client.models()`
+
+List all available models.
+
+### `client.free_models()`
+
+List only free models.
+
+### `client.operation(operation_id)`
+
+Look up an operation by ID.
+
+## OpenAI drop-in
+
+Since Clervo is OpenAI-compatible:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="https://api.clervo.dev/v1",
+    api_key="unused"  # no key needed for free models
+)
+
+response = client.chat.completions.create(
+    model="groq/llama-3.1-8b-instant",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+print(response.choices[0].message.content)
+```
+
+## Links
+
+- API: https://api.clervo.dev
+- Models: https://api.clervo.dev/v1/models
+- Quickstart: https://api.clervo.dev/quickstart.md
+- TypeScript SDK: https://npmjs.com/package/@clervo/sdk
+- MCP: https://npmjs.com/package/@clervo/mcp

clervo_sdk-0.1.0/clervo/__init__.py

@@ -0,0 +1,17 @@
+"""
+Clervo x402 Gateway SDK
+
+23 AI models. 8 free. Pay per call in USDC on Solana.
+
+Usage:
+    from clervo import Clervo
+
+    client = Clervo()
+    response = client.chat("groq/llama-3.1-8b-instant", "Hello!")
+    print(response)
+"""
+
+from clervo.client import Clervo
+
+__all__ = ["Clervo"]
+__version__ = "0.1.0"

clervo_sdk-0.1.0/clervo/client.py

@@ -0,0 +1,155 @@
+"""Clervo x402 Gateway client."""
+
+import os
+import uuid
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+DEFAULT_API = "https://api.clervo.dev"
+
+
+class ClervoError(Exception):
+    """Base exception for Clervo SDK errors."""
+
+    def __init__(self, message: str, status: int = 0, code: str = ""):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+
+class PaymentRequired(ClervoError):
+    """Raised when a paid model is called without payment."""
+
+    pass
+
+
+class Clervo:
+    """Clervo x402 Gateway client.
+
+    Args:
+        api_url: Base URL for the Clervo API. Defaults to CLERVO_API_URL env or https://api.clervo.dev.
+        timeout: Request timeout in seconds. Default 30.
+
+    Example:
+        >>> from clervo import Clervo
+        >>> client = Clervo()
+        >>> text = client.chat("groq/llama-3.1-8b-instant", "Hello!")
+        >>> print(text)
+    """
+
+    def __init__(self, api_url: Optional[str] = None, timeout: float = 30.0):
+        self._api_url = api_url or os.environ.get("CLERVO_API_URL", DEFAULT_API)
+        self._client = httpx.Client(base_url=self._api_url, timeout=timeout)
+
+    def chat(
+        self,
+        model: str,
+        message: str,
+        *,
+        system: Optional[str] = None,
+        max_tokens: int = 1024,
+    ) -> str:
+        """Simple chat — returns just the text response.
+
+        Args:
+            model: Model ID (e.g. "groq/llama-3.1-8b-instant").
+            message: User message.
+            system: Optional system prompt.
+            max_tokens: Max output tokens.
+
+        Returns:
+            The assistant's text response.
+
+        Raises:
+            PaymentRequired: If model requires x402 payment.
+            ClervoError: On API errors.
+        """
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": message})
+
+        result = self.chat_completion(model, messages, max_tokens=max_tokens)
+        return result["choices"][0]["message"]["content"]
+
+    def chat_completion(
+        self,
+        model: str,
+        messages: List[Dict[str, str]],
+        *,
+        max_tokens: int = 1024,
+        response_format: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Full OpenAI-compatible chat completion.
+
+        Args:
+            model: Model ID.
+            messages: List of message dicts with 'role' and 'content'.
+            max_tokens: Max output tokens.
+            response_format: Optional response format spec.
+
+        Returns:
+            Full completion response dict (OpenAI-compatible).
+        """
+        body: Dict[str, Any] = {
+            "model": model,
+            "messages": messages,
+            "max_completion_tokens": max_tokens,
+        }
+        if response_format:
+            body["response_format"] = response_format
+
+        r = self._client.post(
+            "/v1/chat/completions",
+            json=body,
+            headers={
+                "idempotency-key": str(uuid.uuid4()),
+            },
+        )
+
+        if r.status_code == 402:
+            raise PaymentRequired(
+                f'Payment required for model "{model}". Use a free model or fund a wallet.',
+                status=402,
+                code="PAYMENT_REQUIRED",
+            )
+
+        if r.status_code != 200:
+            data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
+            raise ClervoError(
+                data.get("error", {}).get("message", f"API error: {r.status_code}"),
+                status=r.status_code,
+                code=data.get("error", {}).get("code", "API_ERROR"),
+            )
+
+        result = r.json()
+        result["_operation_id"] = r.headers.get("x-clervo-operation-id")
+        result["_replay"] = r.headers.get("x-idempotent-replay") == "true"
+        return result
+
+    def models(self) -> List[Dict[str, Any]]:
+        """List all available models."""
+        r = self._client.get("/v1/models")
+        return r.json().get("data", [])
+
+    def free_models(self) -> List[Dict[str, Any]]:
+        """List only free models (no payment needed)."""
+        return [m for m in self.models() if m.get("lifecycle") == "free_beta"]
+
+    def operation(self, operation_id: str) -> Optional[Dict[str, Any]]:
+        """Get operation status/receipt."""
+        r = self._client.get(f"/v1/operations/{operation_id}")
+        if r.status_code == 404:
+            return None
+        return r.json()
+
+    def close(self):
+        """Close the HTTP client."""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()

clervo_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "clervo"
+version = "0.1.0"
+description = "Clervo x402 Gateway SDK — 23 AI models, 8 free. Pay per call in USDC."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+keywords = ["clervo", "x402", "ai", "claude", "gpt", "deepseek", "llm", "usdc", "solana", "openai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://clervo.dev"
+API = "https://api.clervo.dev"
+Documentation = "https://api.clervo.dev/quickstart.md"
+Repository = "https://github.com/clervo/clervo-python"