shdwsdk 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,59 @@
1
+ # Dependencies
2
+ node_modules/
3
+ .pnp
4
+ .pnp.js
5
+
6
+ # Build outputs
7
+ dist/
8
+ build/
9
+ out/
10
+ *.tsbuildinfo
11
+
12
+ # Environment variables (NEVER commit secrets)
13
+ .env
14
+ .env.local
15
+ .env.development.local
16
+ .env.test.local
17
+ .env.production.local
18
+ .env.*
19
+ !.env.example
20
+
21
+ # Supabase local development & temp files
22
+ supabase/.branches
23
+ supabase/.temp
24
+ .supabase/
25
+
26
+ # Logs & runtime data
27
+ logs
28
+ *.log
29
+ npm-debug.log*
30
+ yarn-debug.log*
31
+ yarn-error.log*
32
+ pnpm-debug.log*
33
+ lerna-debug.log*
34
+
35
+ # Caches
36
+ .cache/
37
+ .vite/
38
+ .turbo/
39
+ .eslintcache
40
+ .parcel-cache
41
+
42
+ # Editor & OS directories
43
+ .vscode/*
44
+ !.vscode/extensions.json
45
+ .idea
46
+ .DS_Store
47
+ Thumbs.db
48
+ *.suo
49
+ *.ntvs*
50
+ *.njsproj
51
+ *.sln
52
+ *.sw?
53
+
54
+ # Testing & coverage
55
+ coverage/
56
+ .nyc_output
57
+ __pycache__/
58
+ .pytest_cache/
59
+ *.egg-info/
shdwsdk-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,72 @@
1
+ Metadata-Version: 2.5
2
+ Name: shdwsdk
3
+ Version: 0.1.0
4
+ Summary: Non-blocking Scope 3 AI carbon telemetry and AI-BOM discovery for OpenAI, Anthropic, Gemini and LiteLLM.
5
+ Project-URL: Homepage, https://www.shdwsdk.ai
6
+ Project-URL: Documentation, https://www.shdwsdk.ai/docs
7
+ Author: SHDWsdk
8
+ License: MIT
9
+ Keywords: ai,ai-bom,anthropic,carbon,litellm,openai,scope-3,telemetry
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Operating System :: OS Independent
12
+ Classifier: Programming Language :: Python :: 3
13
+ Requires-Python: >=3.9
14
+ Provides-Extra: test
15
+ Requires-Dist: pytest>=8; extra == 'test'
16
+ Description-Content-Type: text/markdown
17
+
18
+ # shdwsdk (Python)
19
+
20
+ Non-blocking AI carbon telemetry for OpenAI, Anthropic, Gemini and anything routed through LiteLLM.
21
+ Reports model names and token counts only. It never sends prompts or completions, and it never raises into your application.
22
+ Energy and carbon are computed server-side with the EcoLogits methodology.
23
+
24
+ ```bash
25
+ pip install shdwsdk
26
+ export SHDW_API_KEY=shdw_live_...
27
+ ```
28
+
29
+ ## Instrument a client
30
+
31
+ ```python
32
+ import shdwsdk
33
+ from openai import OpenAI
34
+
35
+ shdwsdk.init() # reads SHDW_API_KEY; optional grid_region="eu-north-1"
36
+ client = shdwsdk.instrument(OpenAI()) # also Anthropic(), AsyncOpenAI(), AsyncAnthropic()
37
+
38
+ client.chat.completions.create(model="gpt-5.4-mini", messages=[...])
39
+ ```
40
+
41
+ ## Per-customer Scope 3 statements
42
+
43
+ Tag calls with **your** customer's account id (pseudonymous, never an email).
44
+ SHDWsdk then produces an emissions statement per customer for their supplier reporting.
45
+
46
+ ```python
47
+ with shdwsdk.customer(request.account_id):
48
+ client.messages.create(model="claude-sonnet-5-5", ...)
49
+ ```
50
+
51
+ `customer()` uses `contextvars`, so it is safe with threads and asyncio.
52
+
53
+ ## LiteLLM
54
+
55
+ ```python
56
+ import litellm
57
+ from shdwsdk.integrations.litellm import ShdwLiteLLMLogger
58
+ litellm.callbacks = [ShdwLiteLLMLogger()]
59
+ litellm.completion(model="anthropic/claude-haiku-5-5", messages=[...],
60
+ metadata={"shdw_customer_ref": "acme-corp"})
61
+ ```
62
+
63
+ LiteLLM proxy (`config.yaml`):
64
+
65
+ ```yaml
66
+ litellm_settings:
67
+ callbacks: shdwsdk.integrations.litellm.proxy_handler_instance
68
+ ```
69
+
70
+ ## Short-lived processes
71
+
72
+ Events are sent from a background thread every 5 seconds and at exit. In serverless functions call `shdwsdk.get_client().flush()` before returning.
@@ -0,0 +1,55 @@
1
+ # shdwsdk (Python)
2
+
3
+ Non-blocking AI carbon telemetry for OpenAI, Anthropic, Gemini and anything routed through LiteLLM.
4
+ Reports model names and token counts only. It never sends prompts or completions, and it never raises into your application.
5
+ Energy and carbon are computed server-side with the EcoLogits methodology.
6
+
7
+ ```bash
8
+ pip install shdwsdk
9
+ export SHDW_API_KEY=shdw_live_...
10
+ ```
11
+
12
+ ## Instrument a client
13
+
14
+ ```python
15
+ import shdwsdk
16
+ from openai import OpenAI
17
+
18
+ shdwsdk.init() # reads SHDW_API_KEY; optional grid_region="eu-north-1"
19
+ client = shdwsdk.instrument(OpenAI()) # also Anthropic(), AsyncOpenAI(), AsyncAnthropic()
20
+
21
+ client.chat.completions.create(model="gpt-5.4-mini", messages=[...])
22
+ ```
23
+
24
+ ## Per-customer Scope 3 statements
25
+
26
+ Tag calls with **your** customer's account id (pseudonymous, never an email).
27
+ SHDWsdk then produces an emissions statement per customer for their supplier reporting.
28
+
29
+ ```python
30
+ with shdwsdk.customer(request.account_id):
31
+ client.messages.create(model="claude-sonnet-5-5", ...)
32
+ ```
33
+
34
+ `customer()` uses `contextvars`, so it is safe with threads and asyncio.
35
+
36
+ ## LiteLLM
37
+
38
+ ```python
39
+ import litellm
40
+ from shdwsdk.integrations.litellm import ShdwLiteLLMLogger
41
+ litellm.callbacks = [ShdwLiteLLMLogger()]
42
+ litellm.completion(model="anthropic/claude-haiku-5-5", messages=[...],
43
+ metadata={"shdw_customer_ref": "acme-corp"})
44
+ ```
45
+
46
+ LiteLLM proxy (`config.yaml`):
47
+
48
+ ```yaml
49
+ litellm_settings:
50
+ callbacks: shdwsdk.integrations.litellm.proxy_handler_instance
51
+ ```
52
+
53
+ ## Short-lived processes
54
+
55
+ Events are sent from a background thread every 5 seconds and at exit. In serverless functions call `shdwsdk.get_client().flush()` before returning.
@@ -0,0 +1,33 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.24"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "shdwsdk"
7
+ version = "0.1.0"
8
+ description = "Non-blocking Scope 3 AI carbon telemetry and AI-BOM discovery for OpenAI, Anthropic, Gemini and LiteLLM."
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = { text = "MIT" }
12
+ authors = [{ name = "SHDWsdk" }]
13
+ keywords = ["ai", "carbon", "scope-3", "telemetry", "ai-bom", "litellm", "openai", "anthropic"]
14
+ classifiers = [
15
+ "Programming Language :: Python :: 3",
16
+ "License :: OSI Approved :: MIT License",
17
+ "Operating System :: OS Independent",
18
+ ]
19
+ dependencies = []
20
+
21
+ [project.optional-dependencies]
22
+ test = ["pytest>=8"]
23
+
24
+ [project.urls]
25
+ Homepage = "https://www.shdwsdk.ai"
26
+ Documentation = "https://www.shdwsdk.ai/docs"
27
+
28
+ [tool.hatch.build.targets.wheel]
29
+ packages = ["src/shdwsdk"]
30
+
31
+ [tool.pytest.ini_options]
32
+ testpaths = ["tests"]
33
+ pythonpath = ["src"]
@@ -0,0 +1,26 @@
1
+ """SHDWsdk for Python: non-blocking AI carbon telemetry.
2
+
3
+ import shdwsdk
4
+ shdw = shdwsdk.init(api_key="shdw_live_...") # or SHDW_API_KEY env var
5
+ client = shdwsdk.instrument(OpenAI()) # or Anthropic()
6
+ with shdwsdk.customer("acme-corp"): # per-customer Scope 3
7
+ client.chat.completions.create(model="gpt-5.4-mini", messages=[...])
8
+
9
+ Energy and carbon are computed server-side from token counts (EcoLogits), so
10
+ this package only reports models, token usage and context. It never sends
11
+ prompts or completions, and it never raises into your application.
12
+ """
13
+
14
+ from .client import ShdwClient, get_client, init
15
+ from .context import customer, current_customer
16
+ from .integrations import instrument
17
+
18
+ __all__ = [
19
+ "ShdwClient",
20
+ "init",
21
+ "get_client",
22
+ "customer",
23
+ "current_customer",
24
+ "instrument",
25
+ ]
26
+ __version__ = "0.1.0"
@@ -0,0 +1,205 @@
1
+ """Background, fail-silent telemetry queue."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import atexit
6
+ import json
7
+ import logging
8
+ import os
9
+ import threading
10
+ import time
11
+ import urllib.request
12
+ from datetime import datetime, timezone
13
+ from typing import Any, Callable, Dict, List, Optional
14
+
15
+ from .context import current_customer, valid_customer_ref
16
+
17
+ log = logging.getLogger("shdwsdk")
18
+
19
+ DEFAULT_ENDPOINT = "https://www.shdwsdk.ai/api/v1/ingest-telemetry"
20
+ MAX_TIMEOUT_SECONDS = 1.5
21
+ MAX_BUFFER = 5000
22
+ MAX_BATCH = 250
23
+ SDK_VERSION = "0.1.0"
24
+
25
+ Sender = Callable[[str, Dict[str, str], bytes, float], int]
26
+
27
+
28
+ def _urllib_send(url: str, headers: Dict[str, str], body: bytes, timeout: float) -> int:
29
+ req = urllib.request.Request(url, data=body, headers=headers, method="POST")
30
+ try:
31
+ with urllib.request.urlopen(req, timeout=timeout) as resp: # noqa: S310 (fixed https endpoint)
32
+ return resp.status
33
+ except urllib.error.HTTPError as e:
34
+ return e.code
35
+
36
+
37
+ def _infer_provider(model: str) -> str:
38
+ m = model.lower()
39
+ if "claude" in m:
40
+ return "anthropic"
41
+ if "gemini" in m or "gemma" in m:
42
+ return "gemini"
43
+ if "gpt" in m or m.startswith(("o1", "o3", "o4")):
44
+ return "openai"
45
+ return "custom"
46
+
47
+
48
+ class ShdwClient:
49
+ """Queues usage events and delivers them from a daemon thread.
50
+
51
+ Never raises into the host application. Network calls time out after
52
+ at most 1.5 s. Use ``flush()`` before short-lived processes exit.
53
+ """
54
+
55
+ def __init__(
56
+ self,
57
+ api_key: Optional[str] = None,
58
+ *,
59
+ endpoint: Optional[str] = None,
60
+ grid_region: Optional[str] = None,
61
+ workload_name: Optional[str] = None,
62
+ batch_size: int = 50,
63
+ flush_interval: float = 5.0,
64
+ timeout: float = MAX_TIMEOUT_SECONDS,
65
+ source: str = "sdk-python",
66
+ sender: Optional[Sender] = None,
67
+ start_thread: bool = True,
68
+ ) -> None:
69
+ self.api_key = api_key or os.environ.get("SHDW_API_KEY", "")
70
+ self.endpoint = endpoint or os.environ.get("SHDW_ENDPOINT", DEFAULT_ENDPOINT)
71
+ self.grid_region = grid_region or os.environ.get("SHDW_GRID_REGION", "us-east-1")
72
+ self.workload_name = workload_name or os.environ.get("SHDW_WORKLOAD_NAME")
73
+ self.batch_size = max(1, min(batch_size, MAX_BATCH))
74
+ self.flush_interval = max(0.5, flush_interval)
75
+ self.timeout = min(max(0.1, timeout), MAX_TIMEOUT_SECONDS)
76
+ self.source = source
77
+ self._send = sender or _urllib_send
78
+ self._buffer: List[Dict[str, Any]] = []
79
+ self._lock = threading.Lock()
80
+ self._wake = threading.Event()
81
+ self._closed = False
82
+ self.stats = {"queued": 0, "delivered": 0, "dropped": 0}
83
+ self._thread: Optional[threading.Thread] = None
84
+ if start_thread:
85
+ self._thread = threading.Thread(target=self._run, name="shdwsdk", daemon=True)
86
+ self._thread.start()
87
+ atexit.register(self.close)
88
+
89
+ # ------------------------------------------------------------------ public
90
+ def record_usage(
91
+ self,
92
+ model: str,
93
+ prompt_tokens: int,
94
+ completion_tokens: int,
95
+ *,
96
+ provider: Optional[str] = None,
97
+ latency_ms: Optional[float] = None,
98
+ is_streaming: bool = False,
99
+ customer_ref: Optional[str] = None,
100
+ grid_region: Optional[str] = None,
101
+ workload_name: Optional[str] = None,
102
+ ingest_source: Optional[str] = None,
103
+ ) -> None:
104
+ try:
105
+ if not self.api_key or self._closed:
106
+ return
107
+ model = str(model or "unknown-model")[:128]
108
+ event: Dict[str, Any] = {
109
+ "model_name": model,
110
+ "provider": provider or _infer_provider(model),
111
+ "prompt_tokens": max(0, int(prompt_tokens or 0)),
112
+ "completion_tokens": max(0, int(completion_tokens or 0)),
113
+ "grid_region": grid_region or self.grid_region,
114
+ "is_streaming": bool(is_streaming),
115
+ "timestamp": datetime.now(timezone.utc).isoformat(),
116
+ }
117
+ if latency_ms is not None and latency_ms > 0:
118
+ event["latency_ms"] = int(latency_ms)
119
+ ref = valid_customer_ref(customer_ref) or current_customer()
120
+ if ref:
121
+ event["customer_ref"] = ref
122
+ name = workload_name or self.workload_name
123
+ if name:
124
+ event["workload_name"] = name
125
+ if ingest_source:
126
+ event["ingest_source"] = ingest_source
127
+ with self._lock:
128
+ if len(self._buffer) >= MAX_BUFFER:
129
+ self._buffer.pop(0)
130
+ self.stats["dropped"] += 1
131
+ self._buffer.append(event)
132
+ self.stats["queued"] += 1
133
+ full = len(self._buffer) >= self.batch_size
134
+ if full:
135
+ self._wake.set()
136
+ except Exception: # pragma: no cover - fail-silent by contract
137
+ log.debug("shdwsdk: failed to record usage", exc_info=True)
138
+
139
+ def flush(self) -> None:
140
+ """Deliver everything queued now (blocks for at most a few timeouts)."""
141
+ try:
142
+ while True:
143
+ with self._lock:
144
+ batch = self._buffer[: MAX_BATCH]
145
+ del self._buffer[: MAX_BATCH]
146
+ if not batch:
147
+ return
148
+ self._deliver(batch)
149
+ except Exception: # pragma: no cover
150
+ log.debug("shdwsdk: flush failed", exc_info=True)
151
+
152
+ def close(self) -> None:
153
+ if self._closed:
154
+ return
155
+ self.flush()
156
+ self._closed = True
157
+ self._wake.set()
158
+
159
+ # ---------------------------------------------------------------- internal
160
+ def _deliver(self, batch: List[Dict[str, Any]]) -> None:
161
+ body = json.dumps({"events": batch}).encode()
162
+ headers = {
163
+ "Content-Type": "application/json",
164
+ "X-SHDW-Key": self.api_key,
165
+ "X-SHDW-Source": self.source,
166
+ "X-SHDW-Python-SDK-Version": SDK_VERSION,
167
+ }
168
+ for attempt in range(2):
169
+ try:
170
+ status = self._send(self.endpoint, headers, body, self.timeout)
171
+ except Exception:
172
+ status = 0
173
+ if 200 <= status < 300:
174
+ self.stats["delivered"] += len(batch)
175
+ return
176
+ if 400 <= status < 500 and status != 429:
177
+ break # bad key or payload: retrying will not help
178
+ time.sleep(0.2 * (attempt + 1))
179
+ self.stats["dropped"] += len(batch)
180
+ log.warning("shdwsdk: dropped %d telemetry events (HTTP %s)", len(batch), status)
181
+
182
+ def _run(self) -> None:
183
+ while not self._closed:
184
+ self._wake.wait(self.flush_interval)
185
+ self._wake.clear()
186
+ self.flush()
187
+
188
+
189
+ _default: Optional[ShdwClient] = None
190
+
191
+
192
+ def init(api_key: Optional[str] = None, **kwargs: Any) -> ShdwClient:
193
+ """Create (or replace) the process-wide client used by integrations."""
194
+ global _default
195
+ if _default is not None:
196
+ _default.close()
197
+ _default = ShdwClient(api_key, **kwargs)
198
+ return _default
199
+
200
+
201
+ def get_client() -> Optional[ShdwClient]:
202
+ global _default
203
+ if _default is None and os.environ.get("SHDW_API_KEY"):
204
+ _default = ShdwClient()
205
+ return _default
@@ -0,0 +1,34 @@
1
+ """Request-scoped customer attribution (works with threads and asyncio)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import contextvars
6
+ import re
7
+ from contextlib import contextmanager
8
+ from typing import Iterator, Optional
9
+
10
+ _current: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar("shdw_customer_ref", default=None)
11
+
12
+ # Pseudonymous account ids only. Emails are rejected by the server as well.
13
+ CUSTOMER_REF_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$")
14
+
15
+
16
+ def valid_customer_ref(value: Optional[str]) -> Optional[str]:
17
+ if not value:
18
+ return None
19
+ value = str(value).strip()
20
+ return value if CUSTOMER_REF_PATTERN.match(value) else None
21
+
22
+
23
+ @contextmanager
24
+ def customer(customer_ref: str) -> Iterator[None]:
25
+ """Attribute every AI call inside this block to one of your customers."""
26
+ token = _current.set(valid_customer_ref(customer_ref))
27
+ try:
28
+ yield
29
+ finally:
30
+ _current.reset(token)
31
+
32
+
33
+ def current_customer() -> Optional[str]:
34
+ return _current.get()
@@ -0,0 +1,20 @@
1
+ """Wrap provider clients so every call reports token usage."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any, Optional
6
+
7
+ from ..client import ShdwClient
8
+ from ._wrap import instrument_client
9
+
10
+
11
+ def instrument(client: Any, *, shdw: Optional[ShdwClient] = None, provider: Optional[str] = None) -> Any:
12
+ """Instrument an ``openai.OpenAI``/``AsyncOpenAI`` or ``anthropic.Anthropic``/``AsyncAnthropic`` client.
13
+
14
+ Patches the client instance in place and returns it. Responses are returned
15
+ unchanged; streaming responses are passed through chunk by chunk.
16
+ """
17
+ return instrument_client(client, shdw=shdw, provider=provider)
18
+
19
+
20
+ __all__ = ["instrument"]
@@ -0,0 +1,169 @@
1
+ from __future__ import annotations
2
+
3
+ import functools
4
+ import inspect
5
+ import time
6
+ from typing import Any, Callable, Iterable, Optional, Tuple
7
+
8
+ from ..client import ShdwClient, get_client
9
+ from ..context import current_customer
10
+
11
+ # (path to resource, method name, provider)
12
+ _TARGETS = [
13
+ (("chat", "completions"), "create", "openai"),
14
+ (("responses",), "create", "openai"),
15
+ (("messages",), "create", "anthropic"),
16
+ ]
17
+
18
+
19
+ def _get(obj: Any, key: str) -> Any:
20
+ if obj is None:
21
+ return None
22
+ if isinstance(obj, dict):
23
+ return obj.get(key)
24
+ return getattr(obj, key, None)
25
+
26
+
27
+ def usage_from_response(resp: Any) -> Tuple[Optional[str], int, int]:
28
+ """Returns (model, prompt_tokens, completion_tokens) from OpenAI/Anthropic objects or dicts."""
29
+ usage = _get(resp, "usage")
30
+ model = _get(resp, "model")
31
+ prompt = _get(usage, "prompt_tokens") or _get(usage, "input_tokens") or 0
32
+ completion = _get(usage, "completion_tokens") or _get(usage, "output_tokens") or 0
33
+ if not prompt and not completion:
34
+ # Anthropic streaming events carry usage on message_start / message_delta
35
+ message = _get(resp, "message")
36
+ if message is not None:
37
+ return usage_from_response(message)
38
+ return (str(model) if model else None), int(prompt or 0), int(completion or 0)
39
+
40
+
41
+ class _StreamTally:
42
+ def __init__(self) -> None:
43
+ self.model: Optional[str] = None
44
+ self.prompt = 0
45
+ self.completion = 0
46
+
47
+ def add(self, chunk: Any) -> None:
48
+ model, p, c = usage_from_response(chunk)
49
+ self.model = self.model or model
50
+ self.prompt = max(self.prompt, p)
51
+ self.completion = max(self.completion, c)
52
+
53
+
54
+ def _report(shdw: Optional[ShdwClient], provider: str, model: Optional[str], p: int, c: int,
55
+ started: float, streaming: bool, customer: Optional[str], fallback_model: Optional[str]) -> None:
56
+ client = shdw or get_client()
57
+ if client is None:
58
+ return
59
+ client.record_usage(
60
+ model or fallback_model or "unknown-model",
61
+ p,
62
+ c,
63
+ provider=provider,
64
+ latency_ms=(time.monotonic() - started) * 1000,
65
+ is_streaming=streaming,
66
+ customer_ref=customer,
67
+ )
68
+
69
+
70
+ def _wrap_sync_stream(stream: Iterable[Any], done: Callable[[_StreamTally], None]) -> Any:
71
+ tally = _StreamTally()
72
+
73
+ class Wrapped:
74
+ def __iter__(self):
75
+ try:
76
+ for chunk in stream:
77
+ try:
78
+ tally.add(chunk)
79
+ except Exception:
80
+ pass
81
+ yield chunk
82
+ finally:
83
+ done(tally)
84
+
85
+ def __getattr__(self, name: str) -> Any:
86
+ return getattr(stream, name)
87
+
88
+ def __enter__(self):
89
+ return self
90
+
91
+ def __exit__(self, *exc: Any) -> None:
92
+ close = getattr(stream, "close", None)
93
+ if callable(close):
94
+ close()
95
+
96
+ return Wrapped()
97
+
98
+
99
+ def _wrap_async_stream(stream: Any, done: Callable[[_StreamTally], None]) -> Any:
100
+ tally = _StreamTally()
101
+
102
+ class Wrapped:
103
+ async def __aiter__(self):
104
+ try:
105
+ async for chunk in stream:
106
+ try:
107
+ tally.add(chunk)
108
+ except Exception:
109
+ pass
110
+ yield chunk
111
+ finally:
112
+ done(tally)
113
+
114
+ def __getattr__(self, name: str) -> Any:
115
+ return getattr(stream, name)
116
+
117
+ return Wrapped()
118
+
119
+
120
+ def _patch(resource: Any, method: str, provider: str, shdw: Optional[ShdwClient]) -> None:
121
+ original = getattr(resource, method, None)
122
+ if original is None or getattr(original, "__shdw_wrapped__", False):
123
+ return
124
+
125
+ if inspect.iscoroutinefunction(original):
126
+ @functools.wraps(original)
127
+ async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
128
+ started, customer, model_hint = time.monotonic(), current_customer(), kwargs.get("model")
129
+ result = await original(*args, **kwargs)
130
+ try:
131
+ if kwargs.get("stream"):
132
+ return _wrap_async_stream(result, lambda t: _report(
133
+ shdw, provider, t.model, t.prompt, t.completion, started, True, customer, model_hint))
134
+ _report(shdw, provider, *usage_from_response(result), started, False, customer, model_hint)
135
+ except Exception:
136
+ pass
137
+ return result
138
+
139
+ async_wrapper.__shdw_wrapped__ = True # type: ignore[attr-defined]
140
+ setattr(resource, method, async_wrapper)
141
+ return
142
+
143
+ @functools.wraps(original)
144
+ def wrapper(*args: Any, **kwargs: Any) -> Any:
145
+ started, customer, model_hint = time.monotonic(), current_customer(), kwargs.get("model")
146
+ result = original(*args, **kwargs)
147
+ try:
148
+ if kwargs.get("stream"):
149
+ return _wrap_sync_stream(result, lambda t: _report(
150
+ shdw, provider, t.model, t.prompt, t.completion, started, True, customer, model_hint))
151
+ _report(shdw, provider, *usage_from_response(result), started, False, customer, model_hint)
152
+ except Exception:
153
+ pass
154
+ return result
155
+
156
+ wrapper.__shdw_wrapped__ = True # type: ignore[attr-defined]
157
+ setattr(resource, method, wrapper)
158
+
159
+
160
+ def instrument_client(client: Any, *, shdw: Optional[ShdwClient] = None, provider: Optional[str] = None) -> Any:
161
+ for path, method, default_provider in _TARGETS:
162
+ resource = client
163
+ for attr in path:
164
+ resource = getattr(resource, attr, None)
165
+ if resource is None:
166
+ break
167
+ if resource is not None:
168
+ _patch(resource, method, provider or default_provider, shdw)
169
+ return client
@@ -0,0 +1,87 @@
1
+ """LiteLLM callback: one line covers every provider LiteLLM routes to.
2
+
3
+ SDK:
4
+ import litellm
5
+ from shdwsdk.integrations.litellm import ShdwLiteLLMLogger
6
+ litellm.callbacks = [ShdwLiteLLMLogger()]
7
+
8
+ Proxy (config.yaml):
9
+ litellm_settings:
10
+ callbacks: shdwsdk.integrations.litellm.proxy_handler_instance
11
+
12
+ Per-customer attribution: pass ``metadata={"shdw_customer_ref": "acme-corp"}``
13
+ on a request, or use ``shdwsdk.customer(...)``. On the proxy, the virtual key's
14
+ ``user_api_key_team_alias`` / ``end_user`` are NOT used automatically because
15
+ they may contain emails; map them yourself in metadata if they are account ids.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ from typing import Any, Dict, Optional
21
+
22
+ from ..client import ShdwClient, get_client
23
+ from ..context import current_customer
24
+
25
+ try: # LiteLLM is optional
26
+ from litellm.integrations.custom_logger import CustomLogger # type: ignore
27
+ except Exception: # pragma: no cover - exercised only without litellm installed
28
+ class CustomLogger: # type: ignore[no-redef]
29
+ pass
30
+
31
+
32
+ def _provider(kwargs: Dict[str, Any]) -> Optional[str]:
33
+ name = str((kwargs.get("litellm_params") or {}).get("custom_llm_provider") or kwargs.get("custom_llm_provider") or "")
34
+ name = name.lower()
35
+ if "anthropic" in name:
36
+ return "anthropic"
37
+ if "gemini" in name or "vertex" in name:
38
+ return "gemini"
39
+ if "openai" in name or "azure" in name:
40
+ return "openai"
41
+ return None
42
+
43
+
44
+ class ShdwLiteLLMLogger(CustomLogger): # type: ignore[misc]
45
+ def __init__(self, shdw: Optional[ShdwClient] = None) -> None:
46
+ super().__init__()
47
+ self._shdw = shdw
48
+
49
+ def _record(self, kwargs: Dict[str, Any], response_obj: Any, start_time: Any, end_time: Any) -> None:
50
+ try:
51
+ client = self._shdw or get_client()
52
+ if client is None:
53
+ return
54
+ usage = getattr(response_obj, "usage", None)
55
+ if usage is None and isinstance(response_obj, dict):
56
+ usage = response_obj.get("usage")
57
+ get = (lambda k: usage.get(k)) if isinstance(usage, dict) else (lambda k: getattr(usage, k, None))
58
+ prompt = int(get("prompt_tokens") or 0) if usage is not None else 0
59
+ completion = int(get("completion_tokens") or 0) if usage is not None else 0
60
+ model = getattr(response_obj, "model", None) or kwargs.get("model") or "unknown-model"
61
+ metadata = (kwargs.get("litellm_params") or {}).get("metadata") or kwargs.get("metadata") or {}
62
+ latency_ms = None
63
+ try:
64
+ latency_ms = (end_time - start_time).total_seconds() * 1000
65
+ except Exception:
66
+ pass
67
+ client.record_usage(
68
+ str(model),
69
+ prompt,
70
+ completion,
71
+ provider=_provider(kwargs),
72
+ latency_ms=latency_ms,
73
+ is_streaming=bool(kwargs.get("stream")),
74
+ customer_ref=metadata.get("shdw_customer_ref") or current_customer(),
75
+ ingest_source="litellm",
76
+ )
77
+ except Exception:
78
+ pass
79
+
80
+ def log_success_event(self, kwargs, response_obj, start_time, end_time): # noqa: D401
81
+ self._record(kwargs, response_obj, start_time, end_time)
82
+
83
+ async def async_log_success_event(self, kwargs, response_obj, start_time, end_time):
84
+ self._record(kwargs, response_obj, start_time, end_time)
85
+
86
+
87
+ proxy_handler_instance = ShdwLiteLLMLogger()
@@ -0,0 +1,113 @@
1
+ import asyncio
2
+ import json
3
+ from datetime import datetime, timedelta
4
+ from types import SimpleNamespace as NS
5
+
6
+ import shdwsdk
7
+ from shdwsdk import ShdwClient
8
+ from shdwsdk.integrations.litellm import ShdwLiteLLMLogger
9
+
10
+
11
+ class Recorder:
12
+ def __init__(self, status=202):
13
+ self.calls = []
14
+ self.status = status
15
+
16
+ def __call__(self, url, headers, body, timeout):
17
+ self.calls.append((url, headers, json.loads(body), timeout))
18
+ return self.status
19
+
20
+ @property
21
+ def events(self):
22
+ return [e for _, _, b, _ in self.calls for e in b["events"]]
23
+
24
+
25
+ def make(status=202):
26
+ rec = Recorder(status)
27
+ return ShdwClient("shdw_live_test_key_123", sender=rec, start_thread=False), rec
28
+
29
+
30
+ def test_record_and_flush_with_customer_context():
31
+ shdw, rec = make()
32
+ with shdwsdk.customer("acme-corp"):
33
+ shdw.record_usage("claude-sonnet-5-5", 100, 20)
34
+ shdw.record_usage("gpt-5.4-mini", 10, 5, customer_ref="jane@acme.com") # email rejected
35
+ shdw.flush()
36
+ url, headers, _, timeout = rec.calls[0]
37
+ assert headers["X-SHDW-Source"] == "sdk-python" and headers["X-SHDW-Key"].startswith("shdw_")
38
+ assert timeout <= 1.5
39
+ assert [e.get("customer_ref") for e in rec.events] == ["acme-corp", None]
40
+ assert [e["provider"] for e in rec.events] == ["anthropic", "openai"]
41
+ assert shdw.stats == {"queued": 2, "delivered": 2, "dropped": 0}
42
+
43
+
44
+ def test_never_raises_and_drops_on_4xx():
45
+ def boom(*a):
46
+ raise OSError("network down")
47
+
48
+ shdw = ShdwClient("shdw_live_test_key_123", sender=boom, start_thread=False)
49
+ shdw.record_usage("gpt-5.5", 1, 1)
50
+ shdw.flush()
51
+ assert shdw.stats["dropped"] == 1
52
+
53
+ shdw, rec = make(status=401)
54
+ shdw.record_usage("gpt-5.5", 1, 1)
55
+ shdw.flush()
56
+ assert len(rec.calls) == 1 and shdw.stats["dropped"] == 1 # no retry on auth errors
57
+
58
+
59
+ def _fake_openai(result):
60
+ completions = NS(create=lambda **kw: result(kw))
61
+ return NS(chat=NS(completions=completions))
62
+
63
+
64
+ def test_instrument_openai_sync_and_stream():
65
+ shdw, rec = make()
66
+ resp = NS(model="gpt-5.4-mini", usage=NS(prompt_tokens=42, completion_tokens=7))
67
+
68
+ def result(kw):
69
+ if kw.get("stream"):
70
+ return iter([NS(model="gpt-5.4-mini", usage=None), NS(model="gpt-5.4-mini", usage=NS(prompt_tokens=5, completion_tokens=9))])
71
+ return resp
72
+
73
+ client = shdwsdk.instrument(_fake_openai(result), shdw=shdw)
74
+ assert client.chat.completions.create(model="gpt-5.4-mini", messages=[]) is resp
75
+ with shdwsdk.customer("globex"):
76
+ chunks = list(client.chat.completions.create(model="gpt-5.4-mini", messages=[], stream=True))
77
+ assert len(chunks) == 2
78
+ shdw.flush()
79
+ assert [(e["prompt_tokens"], e["completion_tokens"], e["is_streaming"]) for e in rec.events] == [(42, 7, False), (5, 9, True)]
80
+ assert rec.events[1]["customer_ref"] == "globex"
81
+ # idempotent
82
+ shdwsdk.instrument(client, shdw=shdw)
83
+ assert client.chat.completions.create.__shdw_wrapped__
84
+
85
+
86
+ def test_instrument_async_anthropic():
87
+ shdw, rec = make()
88
+
89
+ class Messages:
90
+ async def create(self, **kw):
91
+ return {"model": "claude-haiku-5-5", "usage": {"input_tokens": 11, "output_tokens": 3}}
92
+
93
+ client = shdwsdk.instrument(NS(messages=Messages()), shdw=shdw)
94
+ asyncio.run(client.messages.create(model="claude-haiku-5-5", max_tokens=10, messages=[]))
95
+ shdw.flush()
96
+ assert rec.events[0]["provider"] == "anthropic"
97
+ assert (rec.events[0]["prompt_tokens"], rec.events[0]["completion_tokens"]) == (11, 3)
98
+
99
+
100
+ def test_litellm_logger():
101
+ shdw, rec = make()
102
+ logger = ShdwLiteLLMLogger(shdw)
103
+ start = datetime(2026, 11, 19, 12, 0, 0)
104
+ logger.log_success_event(
105
+ {"model": "claude-sonnet-5-5", "litellm_params": {"custom_llm_provider": "anthropic", "metadata": {"shdw_customer_ref": "acme-corp"}}},
106
+ NS(model="claude-sonnet-5-5", usage=NS(prompt_tokens=300, completion_tokens=80)),
107
+ start,
108
+ start + timedelta(milliseconds=850),
109
+ )
110
+ shdw.flush()
111
+ e = rec.events[0]
112
+ assert e["ingest_source"] == "litellm" and e["customer_ref"] == "acme-corp"
113
+ assert e["provider"] == "anthropic" and e["latency_ms"] == 850