Skip to main content

barestats

PyPI Version Python Versions License: MIT

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 Face transformers, 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)

Source distribution for barestats 1.4.0
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)

Table of built distributions (wheels) for barestats 1.4.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

1.4.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page