barestats 1.4.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.
- barestats/__init__.py +9 -0
- barestats/py.typed +1 -0
- barestats/tracker.py +430 -0
- barestats-1.4.0.dist-info/METADATA +142 -0
- barestats-1.4.0.dist-info/RECORD +8 -0
- barestats-1.4.0.dist-info/WHEEL +5 -0
- barestats-1.4.0.dist-info/licenses/LICENSE +21 -0
- barestats-1.4.0.dist-info/top_level.txt +1 -0
barestats/__init__.py
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
"""
|
|
2
|
+
BareStats Universal Telemetry Tracker
|
|
3
|
+
Zero-dependency background metrics exporter for BareStats AI/LLM monitoring.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from .tracker import BareStatsTracker, DEFAULT_BARESTATS_PORT
|
|
7
|
+
|
|
8
|
+
__version__ = "1.4.0"
|
|
9
|
+
__all__ = ["BareStatsTracker", "DEFAULT_BARESTATS_PORT"]
|
barestats/py.typed
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
# Marker file for PEP 561.
|
barestats/tracker.py
ADDED
|
@@ -0,0 +1,430 @@
|
|
|
1
|
+
"""
|
|
2
|
+
BareStats Universal Telemetry Tracker (pip install barestats)
|
|
3
|
+
Zero-dependency background metrics exporter for BareStats (Port 38111).
|
|
4
|
+
Supports Python 3.8+. Compatible with:
|
|
5
|
+
- llama.cpp (llama-cpp-python)
|
|
6
|
+
- Hugging Face Transformers (model.generate streamer & pipelines)
|
|
7
|
+
- Ollama Python SDK (ollama.chat / ollama.generate)
|
|
8
|
+
- OpenAI / vLLM / LM Studio / LiteLLM Python SDKs
|
|
9
|
+
- ExLlamaV2 / ONNX Runtime GenAI / Custom PyTorch loops
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
import atexit
|
|
13
|
+
import threading
|
|
14
|
+
from http.server import HTTPServer, BaseHTTPRequestHandler
|
|
15
|
+
from contextlib import contextmanager
|
|
16
|
+
from typing import Any, Dict, Iterable, Iterator, Optional
|
|
17
|
+
|
|
18
|
+
__version__ = "1.4.0"
|
|
19
|
+
DEFAULT_BARESTATS_PORT = 38111
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def _normalize_content(value: Any) -> str:
|
|
23
|
+
"""Normalize chunk content to a plain string."""
|
|
24
|
+
if value is None:
|
|
25
|
+
return ""
|
|
26
|
+
if isinstance(value, bytes):
|
|
27
|
+
return value.decode("utf-8", errors="replace")
|
|
28
|
+
return str(value)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def _model_name_from_llama(llm: Any, default: str = "llama.cpp") -> str:
|
|
32
|
+
"""Best-effort model name extraction from a llama-cpp-python Llama object."""
|
|
33
|
+
for attr in (
|
|
34
|
+
"model_name",
|
|
35
|
+
"model_path",
|
|
36
|
+
"model_path_str",
|
|
37
|
+
"model_file",
|
|
38
|
+
"gguf_path",
|
|
39
|
+
"file",
|
|
40
|
+
"path",
|
|
41
|
+
):
|
|
42
|
+
value = getattr(llm, attr, None)
|
|
43
|
+
if isinstance(value, str) and value:
|
|
44
|
+
name = value.replace("\\", "/").rsplit("/", 1)[-1].strip()
|
|
45
|
+
if name:
|
|
46
|
+
return name
|
|
47
|
+
|
|
48
|
+
try:
|
|
49
|
+
metadata = llm.metadata()
|
|
50
|
+
if isinstance(metadata, dict):
|
|
51
|
+
general = metadata.get("general") or {}
|
|
52
|
+
if isinstance(general, dict):
|
|
53
|
+
for key in ("name", "architecture"):
|
|
54
|
+
if general.get(key):
|
|
55
|
+
return str(general[key])
|
|
56
|
+
except Exception:
|
|
57
|
+
pass
|
|
58
|
+
|
|
59
|
+
return default
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def _estimate_llama_cpp_prompt_tokens(llm: Any, messages: Any) -> int:
|
|
63
|
+
"""Estimate prompt tokens for a llama-cpp-python chat completion request."""
|
|
64
|
+
try:
|
|
65
|
+
prompt = llm.format_chat_prompt(
|
|
66
|
+
messages,
|
|
67
|
+
add_bos=True,
|
|
68
|
+
add_eos=False,
|
|
69
|
+
)
|
|
70
|
+
tokens = llm.tokenize(prompt, add_bos=False, special=True)
|
|
71
|
+
if tokens is not None:
|
|
72
|
+
return len(tokens)
|
|
73
|
+
except Exception:
|
|
74
|
+
pass
|
|
75
|
+
|
|
76
|
+
try:
|
|
77
|
+
message_list = list(messages)
|
|
78
|
+
except TypeError:
|
|
79
|
+
message_list = []
|
|
80
|
+
|
|
81
|
+
text = " ".join(
|
|
82
|
+
_normalize_content(message.get("content"))
|
|
83
|
+
for message in message_list
|
|
84
|
+
if isinstance(message, dict)
|
|
85
|
+
)
|
|
86
|
+
|
|
87
|
+
try:
|
|
88
|
+
tokens = llm.tokenize(text, add_bos=True, special=True)
|
|
89
|
+
if tokens is not None:
|
|
90
|
+
return len(tokens)
|
|
91
|
+
except Exception:
|
|
92
|
+
pass
|
|
93
|
+
|
|
94
|
+
return max(1, len(text.split()))
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
class _ReusableHTTPServer(HTTPServer):
|
|
98
|
+
"""HTTP Server that immediately reuses socket address without TIME_WAIT delays."""
|
|
99
|
+
allow_reuse_address = True
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
class BareStatsTracker:
|
|
103
|
+
"""
|
|
104
|
+
Lightweight, near-zero-overhead metrics server exposing Prometheus /metrics
|
|
105
|
+
on 127.0.0.1:38111 for BareStats LLM telemetry scrapers.
|
|
106
|
+
"""
|
|
107
|
+
|
|
108
|
+
def __init__(
|
|
109
|
+
self,
|
|
110
|
+
model_name: str = "custom-llm",
|
|
111
|
+
port: int = DEFAULT_BARESTATS_PORT,
|
|
112
|
+
auto_start: bool = False,
|
|
113
|
+
):
|
|
114
|
+
self.model_name = str(model_name)
|
|
115
|
+
self.port = int(port)
|
|
116
|
+
self.gen_tokens = 0
|
|
117
|
+
self.prompt_tokens = 0
|
|
118
|
+
self.is_thinking = False
|
|
119
|
+
self.active_requests = 0
|
|
120
|
+
self.kv_cache_pct = 0.0
|
|
121
|
+
self._thinking_pulse = 0
|
|
122
|
+
self._server: Optional[HTTPServer] = None
|
|
123
|
+
self._thread: Optional[threading.Thread] = None
|
|
124
|
+
self._lock = threading.Lock()
|
|
125
|
+
self._running = False
|
|
126
|
+
if auto_start:
|
|
127
|
+
self.start()
|
|
128
|
+
|
|
129
|
+
def start(self) -> "BareStatsTracker":
|
|
130
|
+
"""Starts the background telemetry HTTP server daemon."""
|
|
131
|
+
with self._lock:
|
|
132
|
+
if self._running:
|
|
133
|
+
return self
|
|
134
|
+
|
|
135
|
+
tracker = self
|
|
136
|
+
|
|
137
|
+
class PrometheusMetricsHandler(BaseHTTPRequestHandler):
|
|
138
|
+
def do_GET(self):
|
|
139
|
+
if self.path in ("/metrics", "/"):
|
|
140
|
+
with tracker._lock:
|
|
141
|
+
if tracker.is_thinking:
|
|
142
|
+
tracker._thinking_pulse += 1
|
|
143
|
+
gen = tracker.gen_tokens
|
|
144
|
+
prompt = tracker.prompt_tokens + tracker._thinking_pulse
|
|
145
|
+
model = tracker.model_name
|
|
146
|
+
running = tracker.active_requests if tracker.active_requests > 0 else (1 if (tracker.is_thinking or tracker.gen_tokens > 0) else 0)
|
|
147
|
+
kv_pct = tracker.kv_cache_pct
|
|
148
|
+
|
|
149
|
+
body = (
|
|
150
|
+
f"# HELP vllm:generation_tokens_total Cumulative generated tokens\n"
|
|
151
|
+
f"# TYPE vllm:generation_tokens_total counter\n"
|
|
152
|
+
f'vllm:generation_tokens_total{{model="{model}"}} {gen}\n'
|
|
153
|
+
f"# HELP vllm:prompt_tokens_total Cumulative prompt tokens\n"
|
|
154
|
+
f"# TYPE vllm:prompt_tokens_total counter\n"
|
|
155
|
+
f'vllm:prompt_tokens_total{{model="{model}"}} {prompt}\n'
|
|
156
|
+
f"# HELP vllm:num_requests_running Number of currently active requests\n"
|
|
157
|
+
f"# TYPE vllm:num_requests_running gauge\n"
|
|
158
|
+
f'vllm:num_requests_running{{model="{model}"}} {running}\n'
|
|
159
|
+
f"# HELP vllm:kv_cache_usage_perc Current KV cache utilization percentage\n"
|
|
160
|
+
f"# TYPE vllm:kv_cache_usage_perc gauge\n"
|
|
161
|
+
f'vllm:kv_cache_usage_perc{{model="{model}"}} {kv_pct:.2f}\n'
|
|
162
|
+
).encode("utf-8")
|
|
163
|
+
|
|
164
|
+
self.send_response(200)
|
|
165
|
+
self.send_header(
|
|
166
|
+
"Content-Type", "text/plain; version=0.0.4; charset=utf-8"
|
|
167
|
+
)
|
|
168
|
+
self.send_header("Content-Length", str(len(body)))
|
|
169
|
+
self.end_headers()
|
|
170
|
+
self.wfile.write(body)
|
|
171
|
+
else:
|
|
172
|
+
self.send_response(404)
|
|
173
|
+
self.end_headers()
|
|
174
|
+
|
|
175
|
+
def log_message(self, format: str, *args: Any) -> None:
|
|
176
|
+
# Suppress console logging to keep application terminal clean
|
|
177
|
+
pass
|
|
178
|
+
|
|
179
|
+
try:
|
|
180
|
+
self._server = _ReusableHTTPServer(
|
|
181
|
+
("127.0.0.1", self.port), PrometheusMetricsHandler
|
|
182
|
+
)
|
|
183
|
+
except OSError:
|
|
184
|
+
# Port already in use or permission denied; fail gracefully without crashing
|
|
185
|
+
return self
|
|
186
|
+
|
|
187
|
+
self._running = True
|
|
188
|
+
self._thread = threading.Thread(target=self._server.serve_forever, daemon=True)
|
|
189
|
+
self._thread.start()
|
|
190
|
+
atexit.register(self.stop)
|
|
191
|
+
return self
|
|
192
|
+
|
|
193
|
+
def stop(self) -> None:
|
|
194
|
+
"""Shuts down the background HTTP server."""
|
|
195
|
+
with self._lock:
|
|
196
|
+
if self._server and self._running:
|
|
197
|
+
self._running = False
|
|
198
|
+
try:
|
|
199
|
+
self._server.shutdown()
|
|
200
|
+
self._server.server_close()
|
|
201
|
+
except Exception:
|
|
202
|
+
pass
|
|
203
|
+
self._server = None
|
|
204
|
+
self._thread = None
|
|
205
|
+
try:
|
|
206
|
+
atexit.unregister(self.stop)
|
|
207
|
+
except Exception:
|
|
208
|
+
pass
|
|
209
|
+
|
|
210
|
+
def step(self, tokens: int = 1) -> None:
|
|
211
|
+
"""Increment generated tokens counter by N."""
|
|
212
|
+
with self._lock:
|
|
213
|
+
self.gen_tokens += tokens
|
|
214
|
+
self.is_thinking = False
|
|
215
|
+
|
|
216
|
+
def set_prompt_tokens(self, count: int) -> None:
|
|
217
|
+
"""Set or increment prompt tokens count."""
|
|
218
|
+
with self._lock:
|
|
219
|
+
self.prompt_tokens += count
|
|
220
|
+
|
|
221
|
+
def set_thinking(self, thinking: bool = True) -> None:
|
|
222
|
+
"""Set thinking state (prompt evaluation / prefill phase)."""
|
|
223
|
+
with self._lock:
|
|
224
|
+
self.is_thinking = thinking
|
|
225
|
+
|
|
226
|
+
def set_model(self, model_name: str) -> None:
|
|
227
|
+
"""Dynamically update model name if the script swaps weights at runtime."""
|
|
228
|
+
with self._lock:
|
|
229
|
+
self.model_name = str(model_name)
|
|
230
|
+
|
|
231
|
+
def set_kv_cache(self, pct: float) -> None:
|
|
232
|
+
"""Update KV cache utilization percentage (0.0 to 100.0)."""
|
|
233
|
+
with self._lock:
|
|
234
|
+
self.kv_cache_pct = max(0.0, min(100.0, float(pct)))
|
|
235
|
+
|
|
236
|
+
@staticmethod
|
|
237
|
+
def _extract_chunk_text(chunk: Any) -> Optional[str]:
|
|
238
|
+
"""
|
|
239
|
+
Universal text extractor supporting OpenAI SDK, Ollama, llama-cpp-python,
|
|
240
|
+
vLLM, DeepSeek reasoning content, and raw strings.
|
|
241
|
+
"""
|
|
242
|
+
if chunk is None:
|
|
243
|
+
return None
|
|
244
|
+
if isinstance(chunk, str):
|
|
245
|
+
return chunk
|
|
246
|
+
if isinstance(chunk, bytes):
|
|
247
|
+
return chunk.decode("utf-8", errors="replace")
|
|
248
|
+
|
|
249
|
+
# 1. Dict-like chunk (llama-cpp-python, ollama dict, raw JSON)
|
|
250
|
+
if isinstance(chunk, dict):
|
|
251
|
+
# DeepSeek / reasoning content check
|
|
252
|
+
choices = chunk.get("choices")
|
|
253
|
+
if choices and isinstance(choices, list) and len(choices) > 0:
|
|
254
|
+
first = choices[0]
|
|
255
|
+
if isinstance(first, dict):
|
|
256
|
+
delta = first.get("delta") or {}
|
|
257
|
+
if isinstance(delta, dict):
|
|
258
|
+
if delta.get("reasoning_content") or delta.get("thinking"):
|
|
259
|
+
return "__THINKING__"
|
|
260
|
+
content = delta.get("content")
|
|
261
|
+
if content is not None:
|
|
262
|
+
return content if isinstance(content, str) else str(content)
|
|
263
|
+
if first.get("text"):
|
|
264
|
+
return str(first["text"])
|
|
265
|
+
|
|
266
|
+
# Ollama chat dict
|
|
267
|
+
msg = chunk.get("message")
|
|
268
|
+
if isinstance(msg, dict):
|
|
269
|
+
if msg.get("thinking"):
|
|
270
|
+
return "__THINKING__"
|
|
271
|
+
content = msg.get("content")
|
|
272
|
+
if content is not None:
|
|
273
|
+
return content if isinstance(content, str) else str(content)
|
|
274
|
+
|
|
275
|
+
# Ollama generate dict
|
|
276
|
+
if "response" in chunk:
|
|
277
|
+
resp = chunk["response"]
|
|
278
|
+
return resp if isinstance(resp, str) else str(resp)
|
|
279
|
+
|
|
280
|
+
# 2. Object with attributes (OpenAI SDK ChatCompletionChunk, Ollama ChatResponse object)
|
|
281
|
+
try:
|
|
282
|
+
if hasattr(chunk, "choices"):
|
|
283
|
+
choices = getattr(chunk, "choices", None)
|
|
284
|
+
if choices and len(choices) > 0:
|
|
285
|
+
delta = getattr(choices[0], "delta", None)
|
|
286
|
+
if delta is not None:
|
|
287
|
+
if getattr(delta, "reasoning_content", None) or getattr(delta, "thinking", None):
|
|
288
|
+
return "__THINKING__"
|
|
289
|
+
content = getattr(delta, "content", None)
|
|
290
|
+
if content is not None:
|
|
291
|
+
return str(content)
|
|
292
|
+
text = getattr(choices[0], "text", None)
|
|
293
|
+
if text is not None:
|
|
294
|
+
return str(text)
|
|
295
|
+
|
|
296
|
+
if hasattr(chunk, "message"):
|
|
297
|
+
msg = getattr(chunk, "message", None)
|
|
298
|
+
if msg is not None:
|
|
299
|
+
if getattr(msg, "thinking", None):
|
|
300
|
+
return "__THINKING__"
|
|
301
|
+
content = getattr(msg, "content", None)
|
|
302
|
+
if content is not None:
|
|
303
|
+
return str(content)
|
|
304
|
+
|
|
305
|
+
if hasattr(chunk, "response"):
|
|
306
|
+
resp = getattr(chunk, "response", None)
|
|
307
|
+
if resp is not None:
|
|
308
|
+
return str(resp)
|
|
309
|
+
except Exception:
|
|
310
|
+
pass
|
|
311
|
+
|
|
312
|
+
return None
|
|
313
|
+
|
|
314
|
+
def track_stream(self, stream: Iterable[Any], prompt_tokens: int = 0) -> Iterator[Any]:
|
|
315
|
+
"""
|
|
316
|
+
Universal wrapper for any streaming token generator.
|
|
317
|
+
Increments token count on each yielded item, tracks prompt prefill,
|
|
318
|
+
and automatically recognizes DeepSeek reasoning phases.
|
|
319
|
+
"""
|
|
320
|
+
self.start()
|
|
321
|
+
with self._lock:
|
|
322
|
+
if prompt_tokens > 0:
|
|
323
|
+
self.prompt_tokens += prompt_tokens
|
|
324
|
+
self.is_thinking = True
|
|
325
|
+
self.active_requests += 1
|
|
326
|
+
|
|
327
|
+
try:
|
|
328
|
+
for chunk in stream:
|
|
329
|
+
text = self._extract_chunk_text(chunk)
|
|
330
|
+
if text == "__THINKING__":
|
|
331
|
+
with self._lock:
|
|
332
|
+
self.is_thinking = True
|
|
333
|
+
self._thinking_pulse += 1
|
|
334
|
+
elif text:
|
|
335
|
+
self.step(1)
|
|
336
|
+
yield chunk
|
|
337
|
+
finally:
|
|
338
|
+
with self._lock:
|
|
339
|
+
self.is_thinking = False
|
|
340
|
+
self.active_requests = max(0, self.active_requests - 1)
|
|
341
|
+
|
|
342
|
+
def stream_llama_cpp_chat(
|
|
343
|
+
self,
|
|
344
|
+
llm: Any,
|
|
345
|
+
messages: Any,
|
|
346
|
+
*,
|
|
347
|
+
model_name: Optional[str] = None,
|
|
348
|
+
**kwargs: Any,
|
|
349
|
+
) -> Iterator[str]:
|
|
350
|
+
"""
|
|
351
|
+
Track a llama-cpp-python chat completion stream.
|
|
352
|
+
Yields assistant content strings directly while updating BareStats telemetry.
|
|
353
|
+
"""
|
|
354
|
+
self.start()
|
|
355
|
+
chosen_model = model_name or kwargs.pop("model_name", None)
|
|
356
|
+
if chosen_model:
|
|
357
|
+
self.set_model(chosen_model)
|
|
358
|
+
else:
|
|
359
|
+
self.set_model(_model_name_from_llama(llm, self.model_name))
|
|
360
|
+
|
|
361
|
+
kwargs.pop("model_name", None)
|
|
362
|
+
prompt_tokens = _estimate_llama_cpp_prompt_tokens(llm, messages)
|
|
363
|
+
kwargs["stream"] = True
|
|
364
|
+
stream = llm.create_chat_completion(messages=messages, **kwargs)
|
|
365
|
+
|
|
366
|
+
for chunk in self.track_stream(stream, prompt_tokens=prompt_tokens):
|
|
367
|
+
text = self._extract_chunk_text(chunk)
|
|
368
|
+
if text and text != "__THINKING__":
|
|
369
|
+
yield text
|
|
370
|
+
|
|
371
|
+
def hf_streamer(self) -> Any:
|
|
372
|
+
"""
|
|
373
|
+
Returns a Hugging Face `model.generate(..., streamer=tracker.hf_streamer())`
|
|
374
|
+
compatible streamer object that reports live token generation to BareStats
|
|
375
|
+
without requiring any extra dependencies.
|
|
376
|
+
"""
|
|
377
|
+
tracker = self
|
|
378
|
+
tracker.start()
|
|
379
|
+
|
|
380
|
+
class _HFStreamer:
|
|
381
|
+
def __init__(self) -> None:
|
|
382
|
+
self._first = True
|
|
383
|
+
with tracker._lock:
|
|
384
|
+
tracker.is_thinking = True
|
|
385
|
+
tracker.active_requests += 1
|
|
386
|
+
|
|
387
|
+
def put(self, value: Any) -> None:
|
|
388
|
+
# Hugging Face passes prompt input_ids on the very first put() call
|
|
389
|
+
if self._first:
|
|
390
|
+
self._first = False
|
|
391
|
+
try:
|
|
392
|
+
prompt_len = value.shape[-1] if hasattr(value, "shape") else len(value)
|
|
393
|
+
except Exception:
|
|
394
|
+
prompt_len = 1
|
|
395
|
+
tracker.set_prompt_tokens(max(1, int(prompt_len)))
|
|
396
|
+
return
|
|
397
|
+
tracker.step(1)
|
|
398
|
+
|
|
399
|
+
def end(self) -> None:
|
|
400
|
+
with tracker._lock:
|
|
401
|
+
tracker.is_thinking = False
|
|
402
|
+
tracker.active_requests = max(0, tracker.active_requests - 1)
|
|
403
|
+
|
|
404
|
+
return _HFStreamer()
|
|
405
|
+
|
|
406
|
+
@contextmanager
|
|
407
|
+
def generate(self, prompt_tokens: int = 0):
|
|
408
|
+
"""
|
|
409
|
+
Context manager for non-streaming batch execution.
|
|
410
|
+
Usage:
|
|
411
|
+
with tracker.generate(prompt_tokens=len(input_ids[0])) as gen:
|
|
412
|
+
outputs = model.generate(**inputs, max_new_tokens=150)
|
|
413
|
+
gen["tokens"] = len(outputs[0]) - len(input_ids[0])
|
|
414
|
+
"""
|
|
415
|
+
self.start()
|
|
416
|
+
with self._lock:
|
|
417
|
+
self.prompt_tokens += max(1, prompt_tokens)
|
|
418
|
+
self.is_thinking = True
|
|
419
|
+
self.active_requests += 1
|
|
420
|
+
state: Dict[str, int] = {"tokens": 0}
|
|
421
|
+
try:
|
|
422
|
+
yield state
|
|
423
|
+
finally:
|
|
424
|
+
with self._lock:
|
|
425
|
+
self.gen_tokens += max(0, int(state.get("tokens", 0)))
|
|
426
|
+
self.is_thinking = False
|
|
427
|
+
self.active_requests = max(0, self.active_requests - 1)
|
|
428
|
+
|
|
429
|
+
|
|
430
|
+
__all__ = ["BareStatsTracker", "DEFAULT_BARESTATS_PORT"]
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: barestats
|
|
3
|
+
Version: 1.4.0
|
|
4
|
+
Summary: Zero-dependency background telemetry exporter for BareStats AI/LLM monitoring
|
|
5
|
+
Author-email: Chakrank <chakrank@outlook.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/chakrank/BareStats
|
|
8
|
+
Project-URL: Documentation, https://github.com/chakrank/BareStats#ai--llm-inference-telemetry
|
|
9
|
+
Project-URL: Repository, https://github.com/chakrank/BareStats.git
|
|
10
|
+
Project-URL: Issues, https://github.com/chakrank/BareStats/issues
|
|
11
|
+
Keywords: barestats,telemetry,llm,inference,monitoring,prometheus,llama-cpp,transformers,vllm
|
|
12
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
24
|
+
Classifier: Topic :: System :: Monitoring
|
|
25
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
26
|
+
Requires-Python: >=3.8
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
License-File: LICENSE
|
|
29
|
+
Dynamic: license-file
|
|
30
|
+
|
|
31
|
+
# barestats
|
|
32
|
+
|
|
33
|
+
[](https://pypi.org/project/barestats/)
|
|
34
|
+
[](https://pypi.org/project/barestats/)
|
|
35
|
+
[](LICENSE)
|
|
36
|
+
|
|
37
|
+
Official Python telemetry client for **[BareStats](https://github.com/chakrank/BareStats)**, the ultra-lightweight, near-zero-overhead hardware and AI inference overlay for Windows, Linux, and macOS.
|
|
38
|
+
|
|
39
|
+
If you run local AI models in Python scripts rather than pre-packaged servers (such as Ollama or LM Studio), `barestats` runs a non-blocking background metrics exporter on dedicated port `38111`. BareStats automatically discovers the endpoint, displays your model name, calculates real-time token generation speed (TPS), and tracks inference state transitions (`Idle` -> `Thinking` -> `Generating` -> `BurstHold`).
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## Features
|
|
44
|
+
|
|
45
|
+
- **Zero External Dependencies:** Built strictly on Python standard library (`http.server`, `threading`, `time`, `contextlib`). No third-party packages required.
|
|
46
|
+
- **Near-Zero Overhead:** Sub-2MB resident RAM footprint and <0.01% CPU usage during polling.
|
|
47
|
+
- **Universal Compatibility:** Works with `llama_cpp`, Hugging Face `transformers`, `vLLM`, `ExLlamaV2`, `ONNX Runtime GenAI`, and custom PyTorch inference loops.
|
|
48
|
+
- **Automatic Burst Hold:** Accurately retains last peak token speed with graceful 3-second decay back to `Idle`.
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## Installation
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
pip install barestats
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## Quickstart
|
|
61
|
+
|
|
62
|
+
### 1. With `llama.cpp` (`llama-cpp-python`) Streaming
|
|
63
|
+
|
|
64
|
+
```python
|
|
65
|
+
from barestats import BareStatsTracker
|
|
66
|
+
from llama_cpp import Llama
|
|
67
|
+
|
|
68
|
+
tracker = BareStatsTracker(port=38111).start()
|
|
69
|
+
llm = Llama.from_pretrained(
|
|
70
|
+
repo_id="Qwen/Qwen2.5-0.5B-Instruct-GGUF",
|
|
71
|
+
filename="*q4_k_m.gguf",
|
|
72
|
+
n_ctx=2048,
|
|
73
|
+
verbose=False
|
|
74
|
+
)
|
|
75
|
+
|
|
76
|
+
messages = [{"role": "user", "content": "Explain relativity in one sentence."}]
|
|
77
|
+
|
|
78
|
+
# stream_llama_cpp_chat automatically tracks model name, prompt tokens, and live TPS:
|
|
79
|
+
for chunk in tracker.stream_llama_cpp_chat(llm, messages, max_tokens=100):
|
|
80
|
+
print(chunk, end="", flush=True)
|
|
81
|
+
print()
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Or wrap any custom stream generator using `tracker.track_stream(generator)`:
|
|
85
|
+
```python
|
|
86
|
+
stream = llm.create_chat_completion(messages=messages, max_tokens=100, stream=True)
|
|
87
|
+
for chunk in tracker.track_stream(stream):
|
|
88
|
+
...
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### 2. With Hugging Face `transformers` (Batch Generation)
|
|
92
|
+
|
|
93
|
+
```python
|
|
94
|
+
from barestats import BareStatsTracker
|
|
95
|
+
from transformers import AutoModelForCausalLM, AutoTokenizer
|
|
96
|
+
|
|
97
|
+
tracker = BareStatsTracker(model_name="Qwen2.5-7B-HF", port=38111).start()
|
|
98
|
+
|
|
99
|
+
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-7B-Instruct")
|
|
100
|
+
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-7B-Instruct", device_map="auto")
|
|
101
|
+
|
|
102
|
+
inputs = tokenizer("Hello!", return_tensors="pt").to(model.device)
|
|
103
|
+
prompt_len = len(inputs.input_ids[0])
|
|
104
|
+
|
|
105
|
+
# Context manager tracks prompt evaluation and total generated tokens
|
|
106
|
+
with tracker.generate(prompt_tokens=prompt_len) as session:
|
|
107
|
+
outputs = model.generate(**inputs, max_new_tokens=120)
|
|
108
|
+
session["tokens"] = len(outputs[0]) - prompt_len
|
|
109
|
+
|
|
110
|
+
print(tokenizer.decode(outputs[0], skip_special_tokens=True))
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### 3. Custom Loop or Stepping
|
|
114
|
+
|
|
115
|
+
```python
|
|
116
|
+
from barestats import BareStatsTracker
|
|
117
|
+
|
|
118
|
+
tracker = BareStatsTracker(model_name="Custom-Engine", port=38111).start()
|
|
119
|
+
|
|
120
|
+
for token in engine.generate_tokens():
|
|
121
|
+
tracker.step(1)
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## BareStats Configuration
|
|
127
|
+
|
|
128
|
+
Ensure port `38111` is included in your BareStats `config.ini`:
|
|
129
|
+
|
|
130
|
+
```ini
|
|
131
|
+
[LLM]
|
|
132
|
+
enabled = 1
|
|
133
|
+
endpoints = local=http://127.0.0.1:11434, local=http://127.0.0.1:38111
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
BareStats automatically polls both endpoints, merges multiple models under `local:LLM`, and highlights whichever model is actively generating tokens.
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## License
|
|
141
|
+
|
|
142
|
+
MIT License. See [LICENSE](LICENSE) for details.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
barestats/__init__.py,sha256=A3wgKy-lJwRdphJ-uXGWuzq4nIHTxKRViWYZLcKTbDw,266
|
|
2
|
+
barestats/py.typed,sha256=bWew9mHgMy8LqMu7RuqQXFXLBxh2CRx0dUbSx-3wE48,27
|
|
3
|
+
barestats/tracker.py,sha256=aQOMKa1XLNdLKAvUgRoJn5FGsBp1LoiDOa0JNq0-G7U,16157
|
|
4
|
+
barestats-1.4.0.dist-info/licenses/LICENSE,sha256=TMHT9mq8gEhdzw0-FZt4pEOytwPxMkH42frS-L-3XVM,1079
|
|
5
|
+
barestats-1.4.0.dist-info/METADATA,sha256=CZ9i5sMC77x0FaPH31yRSJGC-97zzeawkQwLcXRCN5E,5400
|
|
6
|
+
barestats-1.4.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
7
|
+
barestats-1.4.0.dist-info/top_level.txt,sha256=F6WE-yf9xN-0PzBch7bV6qI_H1d_N5lYRBvgUyF-zRE,10
|
|
8
|
+
barestats-1.4.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 BareStats Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
barestats
|