Metadata-Version: 2.4
Name: drip-sdk
Version: 1.2.1
Summary: Official Python SDK for Drip - usage-based billing infrastructure with on-chain settlement
Project-URL: Homepage, https://drip.dev
Project-URL: Documentation, https://docs.drip.dev
Project-URL: Repository, https://github.com/drip/sdk-python
Author-email: Drip <sdk@drip.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: api,billing,blockchain,drip,metered-billing,payments,sdk,usage-based
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: all
Requires-Dist: fastapi>=0.100.0; extra == 'all'
Requires-Dist: flask>=2.0.0; extra == 'all'
Requires-Dist: langchain-core>=0.1.0; extra == 'all'
Requires-Dist: starlette>=0.27.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: respx>=0.20.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
Requires-Dist: starlette>=0.27.0; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask>=2.0.0; extra == 'flask'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
Description-Content-Type: text/markdown

# Drip SDK (Python)

Drip is a Python SDK for **usage-based tracking and execution logging** in systems where spend is tied to computation — AI agents, APIs, batch jobs, and infra workloads.

This **Core SDK** is optimized for pilots: capture usage and run data first, add billing later.

**One line to start tracking:** `drip.track_usage(customer_id, meter, quantity)`

[![PyPI version](https://img.shields.io/pypi/v/drip-sdk.svg)](https://pypi.org/project/drip-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/drip-sdk.svg)](https://pypi.org/project/drip-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## 60-Second Quickstart (Core SDK)

### 1. Install

```bash
pip install drip-sdk
```

### 2. Set your API key

```bash
export DRIP_API_KEY=sk_test_...
```

### 3. Track usage (one line)

```python
from drip import drip

# Track usage - that's it
drip.track_usage(customer_id="cust_123", meter="api_calls", quantity=1)
```

The `drip` singleton reads `DRIP_API_KEY` from your environment automatically.

### Alternative: Explicit Configuration

```python
from drip import Drip

# Auto-reads DRIP_API_KEY from environment
client = Drip()

# Or pass config explicitly
client = Drip(api_key="sk_test_...")
```

### Full Example

```python
from drip import drip

# Verify connectivity
drip.ping()

# Record usage
drip.track_usage(
    customer_id="customer_123",
    meter="llm_tokens",
    quantity=842,
    metadata={"model": "gpt-4o-mini"}
)

# Record execution lifecycle
drip.record_run(
    customer_id="customer_123",
    workflow="research-agent",
    events=[
        {"event_type": "llm.call", "model": "gpt-4", "input_tokens": 500, "output_tokens": 1200},
        {"event_type": "tool.call", "name": "web-search", "duration": 1500},
    ],
    status="COMPLETED"
)

print("Usage + run recorded")
```

**Expected result:**
- No exceptions
- Events appear in the Drip dashboard within seconds

---

## Core Concepts

| Concept | Description |
|---------|-------------|
| `customer_id` | The entity you're attributing usage to |
| `meter` | What's being measured (tokens, calls, time, etc.) |
| `quantity` | Numeric usage value |
| `run` | A single request or job execution |

**Status values:** `PENDING` | `RUNNING` | `COMPLETED` | `FAILED`

**Event schema:** Payloads are schema-flexible. Drip stores events as structured JSON and does not enforce a fixed event taxonomy. CamelCase is accepted.

---

## Installation Options

```bash
pip install drip-sdk           # core only
pip install drip-sdk[fastapi]  # FastAPI helpers
pip install drip-sdk[flask]    # Flask helpers
pip install drip-sdk[all]      # everything
```

---

## SDK Variants

| Variant | Description |
|---------|-------------|
| **Core SDK** (recommended for pilots) | Usage tracking + execution logging only |
| **Full SDK** | Includes billing, balances, and workflows (for later stages) |

---

## Core SDK Methods

| Method | Description |
|--------|-------------|
| `ping()` | Verify API connection |
| `create_customer(params)` | Create a customer |
| `get_customer(customer_id)` | Get customer details |
| `list_customers(options)` | List all customers |
| `track_usage(params)` | Record metered usage |
| `record_run(params)` | Log complete agent run (simplified) |
| `start_run(params)` | Start execution trace |
| `emit_event(params)` | Log event within run |
| `emit_events_batch(params)` | Batch log events |
| `end_run(run_id, params)` | Complete execution trace |
| `get_run_timeline(run_id)` | Get execution timeline |

---

## Async Core SDK

```python
from drip.core import AsyncDrip

async with AsyncDrip(api_key="drip_sk_...") as client:
    await client.ping()

    await client.track_usage(
        customer_id="customer_123",
        meter="api_calls",
        quantity=1
    )

    result = await client.record_run(
        customer_id="customer_123",
        workflow="research-agent",
        events=[...],
        status="COMPLETED"
    )
```

---

## Who This Is For

- AI agents (token metering, tool calls, execution traces)
- API companies (per-request billing, endpoint attribution)
- RPC providers (multi-chain call tracking)
- Cloud/infra (compute seconds, storage, bandwidth)

---

## Full SDK (Billing, Webhooks, Integrations)

For billing, webhooks, middleware, and advanced features:

```python
from drip import Drip
```

See **[FULL_SDK.md](./FULL_SDK.md)** for complete documentation.

---

## Error Handling

```python
from drip import DripError, DripAPIError

try:
    result = client.track_usage(customer_id="customer_123", meter="api_calls", quantity=1)
except DripAPIError as e:
    print(f"API error {e.status_code}: {e.message}")
except DripError as e:
    print(f"Error: {e}")
```

---

## Requirements

- Python 3.10+
- httpx
- pydantic

## Links

- [Full SDK Documentation](./FULL_SDK.md)
- [API Documentation](https://drippay.dev/api-reference)
- [PyPI](https://pypi.org/project/drip-sdk/)

## License

MIT
