Metadata-Version: 2.4
Name: barestats
Version: 1.4.0
Summary: Zero-dependency background telemetry exporter for BareStats AI/LLM monitoring
Author-email: Chakrank <chakrank@outlook.com>
License: MIT
Project-URL: Homepage, https://github.com/chakrank/BareStats
Project-URL: Documentation, https://github.com/chakrank/BareStats#ai--llm-inference-telemetry
Project-URL: Repository, https://github.com/chakrank/BareStats.git
Project-URL: Issues, https://github.com/chakrank/BareStats/issues
Keywords: barestats,telemetry,llm,inference,monitoring,prometheus,llama-cpp,transformers,vllm
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# barestats

[![PyPI Version](https://img.shields.io/pypi/v/barestats.svg)](https://pypi.org/project/barestats/)
[![Python Versions](https://img.shields.io/pypi/pyversions/barestats.svg)](https://pypi.org/project/barestats/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

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.

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

```bash
pip install barestats
```

---

## Quickstart

### 1. With `llama.cpp` (`llama-cpp-python`) Streaming

```python
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)`:
```python
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)

```python
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

```python
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`:

```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](LICENSE) for details.
