shdwsdk 0.1.0__py3-none-any.whl
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.
- shdwsdk/__init__.py +26 -0
- shdwsdk/client.py +205 -0
- shdwsdk/context.py +34 -0
- shdwsdk/integrations/__init__.py +20 -0
- shdwsdk/integrations/_wrap.py +169 -0
- shdwsdk/integrations/litellm.py +87 -0
- shdwsdk-0.1.0.dist-info/METADATA +72 -0
- shdwsdk-0.1.0.dist-info/RECORD +9 -0
- shdwsdk-0.1.0.dist-info/WHEEL +4 -0
shdwsdk/__init__.py
ADDED
|
@@ -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"
|
shdwsdk/client.py
ADDED
|
@@ -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
|
shdwsdk/context.py
ADDED
|
@@ -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,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,9 @@
|
|
|
1
|
+
shdwsdk/__init__.py,sha256=EP4nI5fECBg0m8i_xmHJMyFuYkFgg-KpFA-zwHMW_QQ,923
|
|
2
|
+
shdwsdk/client.py,sha256=CdKwBT0krtsOEtw9LYP_fPmgjW1A1Ifkt0aW578L5Bo,7603
|
|
3
|
+
shdwsdk/context.py,sha256=xieMPieX9W6N4dgkUWDpMJspSdrMfahRjPpD7fsRAPM,1052
|
|
4
|
+
shdwsdk/integrations/__init__.py,sha256=N__-7Ug5jRjhDpBA0U6ZY_t5bfOskOoBGEAdzEZq1hQ,693
|
|
5
|
+
shdwsdk/integrations/_wrap.py,sha256=NjRhnKojbB-mvndBK4kyamcncHK9TCB-IJIBVSSg2Jw,5969
|
|
6
|
+
shdwsdk/integrations/litellm.py,sha256=32ccAh01ALONLNxzRD7x3dsc69yWmY6pQrOVeF2o5is,3586
|
|
7
|
+
shdwsdk-0.1.0.dist-info/METADATA,sha256=46Zfs2pLBnKclcCQHoIA17THqNmnkyCrsxTArIUt74o,2336
|
|
8
|
+
shdwsdk-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
9
|
+
shdwsdk-0.1.0.dist-info/RECORD,,
|