Metadata-Version: 2.5
Name: shdwsdk
Version: 0.1.0
Summary: Non-blocking Scope 3 AI carbon telemetry and AI-BOM discovery for OpenAI, Anthropic, Gemini and LiteLLM.
Project-URL: Homepage, https://www.shdwsdk.ai
Project-URL: Documentation, https://www.shdwsdk.ai/docs
Author: SHDWsdk
License: MIT
Keywords: ai,ai-bom,anthropic,carbon,litellm,openai,scope-3,telemetry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Provides-Extra: test
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# shdwsdk (Python)

Non-blocking AI carbon telemetry for OpenAI, Anthropic, Gemini and anything routed through LiteLLM.
Reports model names and token counts only. It never sends prompts or completions, and it never raises into your application.
Energy and carbon are computed server-side with the EcoLogits methodology.

```bash
pip install shdwsdk
export SHDW_API_KEY=shdw_live_...
```

## Instrument a client

```python
import shdwsdk
from openai import OpenAI

shdwsdk.init()                      # reads SHDW_API_KEY; optional grid_region="eu-north-1"
client = shdwsdk.instrument(OpenAI())   # also Anthropic(), AsyncOpenAI(), AsyncAnthropic()

client.chat.completions.create(model="gpt-5.4-mini", messages=[...])
```

## Per-customer Scope 3 statements

Tag calls with **your** customer's account id (pseudonymous, never an email).
SHDWsdk then produces an emissions statement per customer for their supplier reporting.

```python
with shdwsdk.customer(request.account_id):
    client.messages.create(model="claude-sonnet-5-5", ...)
```

`customer()` uses `contextvars`, so it is safe with threads and asyncio.

## LiteLLM

```python
import litellm
from shdwsdk.integrations.litellm import ShdwLiteLLMLogger
litellm.callbacks = [ShdwLiteLLMLogger()]
litellm.completion(model="anthropic/claude-haiku-5-5", messages=[...],
                   metadata={"shdw_customer_ref": "acme-corp"})
```

LiteLLM proxy (`config.yaml`):

```yaml
litellm_settings:
  callbacks: shdwsdk.integrations.litellm.proxy_handler_instance
```

## Short-lived processes

Events are sent from a background thread every 5 seconds and at exit. In serverless functions call `shdwsdk.get_client().flush()` before returning.
