Metadata-Version: 2.4
Name: contextmeter
Version: 0.1.0
Summary: A live meter for your LLM's context window — see exactly what's filling it.
Project-URL: Homepage, https://github.com/blueprintparadise/Contextmeter
Project-URL: Repository, https://github.com/blueprintparadise/Contextmeter
Project-URL: Issues, https://github.com/blueprintparadise/Contextmeter/issues
Author-email: Rushi Hiray <researchpaperai199@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,anthropic,context-window,llm,observability,openai,tokens,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13.7
Requires-Dist: starlette>=0.37
Requires-Dist: tiktoken>=0.7
Requires-Dist: uvicorn>=0.30
Provides-Extra: dev
Requires-Dist: anyio>=4; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/logo.svg" alt="contextmeter" width="420">
</p>

# contextmeter

**A live meter for your LLM's context window — see exactly what's filling it.**

![contextmeter demo](docs/demo.svg)

`contextmeter` is a tiny local proxy + terminal HUD. Point your LLM app at it and
watch, in real time, how your context window fills up — broken down by **system
prompt**, **tool definitions**, **chat history**, and **tool outputs**. It makes the
invisible "tool tax" obvious: *"34% of your window is tool schemas you never call."*

It **auto-detects** the request format per call, so it works with **any**
OpenAI-compatible API and **Anthropic** out of the box — no code changes, just a
base-URL swap.

### Works with

Anything that speaks the **OpenAI** chat format — OpenAI, OpenRouter, Groq, Together,
Mistral, DeepSeek, Fireworks, and local servers like **Ollama**, **vLLM**, and
**LM Studio** — plus **Anthropic** (Claude). `contextmeter` figures out which format
each request uses on its own.

## Install

    uv pip install contextmeter

## Use

Start the meter (provider is auto-detected; defaults to forwarding to OpenAI):

    contextmeter

Then point your app's base URL at `http://localhost:8765`. To forward somewhere else
(Anthropic, a local server, OpenRouter, …), just set `--upstream`:

    contextmeter --upstream https://api.anthropic.com
    contextmeter --upstream http://localhost:11434

`--provider` is optional — pass `openai` or `anthropic` only if you want to pin the
format instead of letting it auto-detect.

> **Note:** pass the **host root** as `--upstream`, not the `/v1` endpoint. Your LLM
> client already appends the path (e.g. `/v1/chat/completions`), so use
> `http://localhost:11434` — not `http://localhost:11434/v1` (which would double the
> path to `/v1/v1/...`).

## Why

Most developers have no idea what's eating their context window. Tool definitions
alone can consume 40–60% before the first message. `contextmeter` shows you, live,
in your terminal.

## Status

Early. Supports OpenAI-compatible + Anthropic request analysis with automatic
per-request provider detection. Token counts are approximate (tiktoken-based; Anthropic
is approximated). Responses are currently buffered (no token-by-token streaming
pass-through yet), and the breakdown counts message text but not yet the model's emitted
`tool_calls`/`tool_use` argument payloads.

Roadmap: native Google Gemini schema; streaming pass-through; count tool-call argument
payloads in History; Python wrapper entry point (no proxy); pricing/limits auto-refresh;
richer Textual UI.
