barestats
Official Python telemetry client for BareStats, the ultra-lightweight, near-zero-overhead hardware and AI inference overlay for Windows, Linux, and macOS.
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).
Features
- Zero External Dependencies: Built strictly on Python standard library (
http.server,threading,time,contextlib). No third-party packages required. - Near-Zero Overhead: Sub-2MB resident RAM footprint and <0.01% CPU usage during polling.
- Universal Compatibility: Works with
llama_cpp, Hugging Facetransformers,vLLM,ExLlamaV2,ONNX Runtime GenAI, and custom PyTorch inference loops. - Automatic Burst Hold: Accurately retains last peak token speed with graceful 3-second decay back to
Idle.
Installation
pip install barestats
Quickstart
1. With llama.cpp (llama-cpp-python) Streaming
from barestats import BareStatsTracker
from llama_cpp import Llama
tracker = BareStatsTracker(port=38111).start()
llm = Llama.from_pretrained(
repo_id="Qwen/Qwen2.5-0.5B-Instruct-GGUF",
filename="*q4_k_m.gguf",
n_ctx=2048,
verbose=False
)
messages = [{"role": "user", "content": "Explain relativity in one sentence."}]
# stream_llama_cpp_chat automatically tracks model name, prompt tokens, and live TPS:
for chunk in tracker.stream_llama_cpp_chat(llm, messages, max_tokens=100):
print(chunk, end="", flush=True)
print()
Or wrap any custom stream generator using tracker.track_stream(generator):
stream = llm.create_chat_completion(messages=messages, max_tokens=100, stream=True)
for chunk in tracker.track_stream(stream):
...
2. With Hugging Face transformers (Batch Generation)
from barestats import BareStatsTracker
from transformers import AutoModelForCausalLM, AutoTokenizer
tracker = BareStatsTracker(model_name="Qwen2.5-7B-HF", port=38111).start()
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-7B-Instruct")
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-7B-Instruct", device_map="auto")
inputs = tokenizer("Hello!", return_tensors="pt").to(model.device)
prompt_len = len(inputs.input_ids[0])
# Context manager tracks prompt evaluation and total generated tokens
with tracker.generate(prompt_tokens=prompt_len) as session:
outputs = model.generate(**inputs, max_new_tokens=120)
session["tokens"] = len(outputs[0]) - prompt_len
print(tokenizer.decode(outputs[0], skip_special_tokens=True))
3. Custom Loop or Stepping
from barestats import BareStatsTracker
tracker = BareStatsTracker(model_name="Custom-Engine", port=38111).start()
for token in engine.generate_tokens():
tracker.step(1)
BareStats Configuration
Ensure port 38111 is included in your BareStats config.ini:
[LLM]
enabled = 1
endpoints = local=http://127.0.0.1:11434, local=http://127.0.0.1:38111
BareStats automatically polls both endpoints, merges multiple models under local:LLM, and highlights whichever model is actively generating tokens.
License
MIT License. See LICENSE for details.
Metadata
Release files for barestats 1.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| barestats-1.4.0.tar.gz | 10.3 kB | Without provenance | Details for barestats-1.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| barestats-1.4.0-py3-none-any.whl | Python 3 | none | any | Details for barestats-1.4.0-py3-none-any.whl |
Total release size: 19.3 kB
Release files / barestats-1.4.0.tar.gz
| Download URL | barestats-1.4.0.tar.gz |
|---|---|
| Size | 10.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
40b34d09fe1f703384bcf8ba4a7e9d4099e870ebde7394334675b15d3da81706
|
|
BLAKE2b-256 checksum How to use checksums |
0fba477237847bd864593785cf57683cce6fcece90ecb9a3cb39d05182ac36fe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.0.1 CPython/3.13.16
|
Release files / barestats-1.4.0-py3-none-any.whl
| Download URL | barestats-1.4.0-py3-none-any.whl |
|---|---|
| Size | 9.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
02690232c14bbdd404884b61d782e6ba5aad596f5b238062641cf4e286b23a8b
|
|
BLAKE2b-256 checksum How to use checksums |
c2bd1e7458998705c2db793c2334883c695e28613278d85601e046a8730bed71
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.0.1 CPython/3.13.16
|
Security for barestats 1.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.