tokenmeter-cli 0.2.0__tar.gz

tokenmeter_cli-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Sync dependencies
+        run: uv sync --all-extras --dev
+      - name: Lint
+        run: uv run ruff check .
+      - name: Format check
+        run: uv run ruff format --check .
+      - name: Test
+        run: uv run pytest --cov --cov-report=term-missing

tokenmeter_cli-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        run: uv publish

tokenmeter_cli-0.2.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+
+# uv
+uv.lock
+
+# Test and coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.ruff_cache/
+
+# Editor / OS
+.vscode/
+.idea/
+.DS_Store

tokenmeter_cli-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict

tokenmeter_cli-0.2.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based
+on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-03-26
+
+### Added
+- Docker image and a published container entry point.
+- Continuous integration across Python 3.10, 3.11 and 3.12.
+- Expanded documentation and usage examples.
+
+## [0.1.0] - 2026-03-23
+
+### Added
+- `count` command: exact token counts for files, directories or stdin, with a
+  per-model cost estimate.
+- `budget` command: fail when the estimated cost exceeds a limit, for use as a
+  CI gate.
+- `models` command: list the known models and their dated prices.
+- Token counting via tiktoken for the supported OpenAI encodings.
+
+[0.2.0]: https://github.com/jmweb-org/tokenmeter/releases/tag/v0.2.0
+[0.1.0]: https://github.com/jmweb-org/tokenmeter/releases/tag/v0.1.0

tokenmeter_cli-0.2.0/Dockerfile

@@ -0,0 +1,19 @@
+# Count tokens from inside a container by mounting your prompts:
+#
+#   docker build -t tokenmeter .
+#   docker run --rm -v "$PWD:/w" -w /w tokenmeter count prompts/ --model gpt-4o
+#
+FROM python:3.12-slim
+
+LABEL org.opencontainers.image.source="https://github.com/jmweb-org/tokenmeter"
+LABEL org.opencontainers.image.description="Count tokens and estimate cost for prompts before you send them."
+LABEL org.opencontainers.image.licenses="MIT"
+
+WORKDIR /app
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+
+RUN pip install --no-cache-dir .
+
+ENTRYPOINT ["tokenmeter"]
+CMD ["--help"]

tokenmeter_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 José del Río
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tokenmeter_cli-0.2.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: tokenmeter-cli
+Version: 0.2.0
+Summary: Count tokens and estimate cost for prompts before you send them.
+Project-URL: Homepage, https://github.com/jmweb-org/tokenmeter
+Project-URL: Repository, https://github.com/jmweb-org/tokenmeter
+Project-URL: Issues, https://github.com/jmweb-org/tokenmeter/issues
+Author: José del Río
+License: MIT License
+        
+        Copyright (c) 2026 José del Río
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: budget,cli,cost,llm,openai,tiktoken,tokens
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: rich>=13.0
+Requires-Dist: tiktoken>=0.7
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# tokenmeter
+
+[![CI](https://github.com/jmweb-org/tokenmeter/actions/workflows/ci.yml/badge.svg)](https://github.com/jmweb-org/tokenmeter/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tokenmeter-cli.svg)](https://pypi.org/project/tokenmeter-cli/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Count tokens and estimate cost for prompts before you send them, from the
+command line or as a CI budget gate.
+
+Prompt templates grow, a few-shot example gets added, a retrieved context
+balloons, and suddenly every call costs more than you thought. `tokenmeter`
+gives you the exact token count and a dollar estimate up front, for a single
+prompt or a whole directory of templates.
+
+```console
+$ tokenmeter count prompts/system.txt --model gpt-4o
+input            in tok   out tok   cost (USD)
+prompts/system.txt  812         0   $0.002030
+
+$ tokenmeter count prompts/ --model gpt-4o-mini --json
+```
+
+## Install
+
+```console
+$ pip install tokenmeter-cli                 # from PyPI, once released
+$ pip install git+https://github.com/jmweb-org/tokenmeter   # latest, available now
+```
+
+Token counting is exact for the supported OpenAI encodings via `tiktoken`.
+
+## Usage
+
+```console
+$ tokenmeter count system.txt -m gpt-4o          # one file
+$ tokenmeter count prompts/ -m gpt-4o-mini       # every text file in a directory
+$ cat prompt.txt | tokenmeter count - -m gpt-4o  # standard input
+$ tokenmeter count p.txt --output-tokens 500     # include an assumed completion
+$ tokenmeter models                              # list models and prices
+```
+
+### As a budget gate
+
+Fail a build when a prompt set would cost more than you allow:
+
+```console
+$ tokenmeter budget prompts/ --model gpt-4o --max-cost 0.05
+```
+
+```yaml
+- run: tokenmeter budget prompts/ --model gpt-4o --max-cost 0.05
+```
+
+## Cost model
+
+Counts are real tokens. Cost multiplies tokens by a per-model rate from a small,
+dated price table (`tokenmeter models` prints it with its "as of" date). By
+default only input tokens are counted; pass `--output-tokens N` to add an
+assumed completion length to the estimate. Prices change, so treat the dollar
+figures as estimates and update the table when they move.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Counted; under budget (or `count` was used) |
+| 1 | `budget` estimate exceeded `--max-cost` |
+| 2 | An input was missing, or the model is unknown |
+
+## License
+
+MIT. See [LICENSE](LICENSE).

tokenmeter_cli-0.2.0/README.md

@@ -0,0 +1,73 @@
+# tokenmeter
+
+[![CI](https://github.com/jmweb-org/tokenmeter/actions/workflows/ci.yml/badge.svg)](https://github.com/jmweb-org/tokenmeter/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tokenmeter-cli.svg)](https://pypi.org/project/tokenmeter-cli/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Count tokens and estimate cost for prompts before you send them, from the
+command line or as a CI budget gate.
+
+Prompt templates grow, a few-shot example gets added, a retrieved context
+balloons, and suddenly every call costs more than you thought. `tokenmeter`
+gives you the exact token count and a dollar estimate up front, for a single
+prompt or a whole directory of templates.
+
+```console
+$ tokenmeter count prompts/system.txt --model gpt-4o
+input            in tok   out tok   cost (USD)
+prompts/system.txt  812         0   $0.002030
+
+$ tokenmeter count prompts/ --model gpt-4o-mini --json
+```
+
+## Install
+
+```console
+$ pip install tokenmeter-cli                 # from PyPI, once released
+$ pip install git+https://github.com/jmweb-org/tokenmeter   # latest, available now
+```
+
+Token counting is exact for the supported OpenAI encodings via `tiktoken`.
+
+## Usage
+
+```console
+$ tokenmeter count system.txt -m gpt-4o          # one file
+$ tokenmeter count prompts/ -m gpt-4o-mini       # every text file in a directory
+$ cat prompt.txt | tokenmeter count - -m gpt-4o  # standard input
+$ tokenmeter count p.txt --output-tokens 500     # include an assumed completion
+$ tokenmeter models                              # list models and prices
+```
+
+### As a budget gate
+
+Fail a build when a prompt set would cost more than you allow:
+
+```console
+$ tokenmeter budget prompts/ --model gpt-4o --max-cost 0.05
+```
+
+```yaml
+- run: tokenmeter budget prompts/ --model gpt-4o --max-cost 0.05
+```
+
+## Cost model
+
+Counts are real tokens. Cost multiplies tokens by a per-model rate from a small,
+dated price table (`tokenmeter models` prints it with its "as of" date). By
+default only input tokens are counted; pass `--output-tokens N` to add an
+assumed completion length to the estimate. Prices change, so treat the dollar
+figures as estimates and update the table when they move.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Counted; under budget (or `count` was used) |
+| 1 | `budget` estimate exceeded `--max-cost` |
+| 2 | An input was missing, or the model is unknown |
+
+## License
+
+MIT. See [LICENSE](LICENSE).

tokenmeter_cli-0.2.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tokenmeter-cli"
+version = "0.2.0"
+description = "Count tokens and estimate cost for prompts before you send them."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "José del Río" }]
+keywords = ["llm", "tokens", "tiktoken", "cost", "openai", "budget", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=13.0",
+    "tiktoken>=0.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/jmweb-org/tokenmeter"
+Repository = "https://github.com/jmweb-org/tokenmeter"
+Issues = "https://github.com/jmweb-org/tokenmeter/issues"
+
+[project.scripts]
+tokenmeter = "tokenmeter.cli:entrypoint"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tokenmeter"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "S", "C4", "RUF"]
+
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = ["typer.Argument", "typer.Option"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101"]
+
+[tool.coverage.run]
+source = ["tokenmeter"]
+branch = true

tokenmeter_cli-0.2.0/src/tokenmeter/__init__.py

@@ -0,0 +1,19 @@
+"""tokenmeter: count tokens and estimate cost for prompts before sending them."""
+
+from tokenmeter.meter import Measurement, measure, over_budget, total_cost
+from tokenmeter.pricing import ModelPrice, known_models, price_for
+from tokenmeter.pricing import total_cost as cost
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Measurement",
+    "ModelPrice",
+    "__version__",
+    "cost",
+    "known_models",
+    "measure",
+    "over_budget",
+    "price_for",
+    "total_cost",
+]

tokenmeter_cli-0.2.0/src/tokenmeter/__main__.py

@@ -0,0 +1,4 @@
+from tokenmeter.cli import entrypoint
+
+if __name__ == "__main__":
+    entrypoint()

tokenmeter_cli-0.2.0/src/tokenmeter/cli.py

@@ -0,0 +1,135 @@
+"""Command-line interface for tokenmeter."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from tokenmeter import __version__
+from tokenmeter.encoder import EncoderError, encoder_for_model
+from tokenmeter.inputs import read_inputs
+from tokenmeter.meter import measure, over_budget, total_cost
+from tokenmeter.pricing import (
+    PRICES_AS_OF,
+    UnknownModel,
+    known_models,
+    price_for,
+)
+from tokenmeter.render import measurements_to_json, render_table
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="Count tokens and estimate cost for prompts before you send them.",
+)
+_out = Console()
+_err = Console(stderr=True)
+
+EXIT_OK = 0
+EXIT_OVER_BUDGET = 1
+EXIT_BAD_INPUT = 2
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        _out.print(f"tokenmeter {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    _version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the version and exit.",
+    ),
+) -> None:
+    """tokenmeter command-line interface."""
+
+
+def _collect(paths, model, output_tokens):
+    inputs = read_inputs(paths)
+    encoder = encoder_for_model(model)
+    return [
+        measure(encoder, model, name, text, output_tokens=output_tokens) for name, text in inputs
+    ]
+
+
+@app.command("count")
+def count(
+    paths: list[str] = typer.Argument(..., help="Files, directories, or - for stdin."),
+    model: str = typer.Option("gpt-4o", "--model", "-m", help="Model to price against."),
+    output_tokens: int = typer.Option(
+        0, "--output-tokens", help="Assumed completion tokens, for cost only."
+    ),
+    as_json: bool = typer.Option(False, "--json", help="Emit JSON."),
+) -> None:
+    """Count tokens and estimate cost for one or more inputs."""
+
+    try:
+        measurements = _collect(paths, model, output_tokens)
+    except UnknownModel as exc:
+        _err.print(f"tokenmeter: {exc}; try 'tokenmeter models'")
+        raise typer.Exit(EXIT_BAD_INPUT) from exc
+    except (OSError, EncoderError) as exc:
+        _err.print(f"tokenmeter: {exc}")
+        raise typer.Exit(EXIT_BAD_INPUT) from exc
+
+    if as_json:
+        _out.print_json(json.dumps(measurements_to_json(measurements)))
+    else:
+        _out.print(render_table(measurements))
+
+
+@app.command("budget")
+def budget(
+    paths: list[str] = typer.Argument(..., help="Files, directories, or - for stdin."),
+    max_cost: float = typer.Option(..., "--max-cost", help="Fail above this USD cost."),
+    model: str = typer.Option("gpt-4o", "--model", "-m", help="Model to price against."),
+    output_tokens: int = typer.Option(0, "--output-tokens", help="Assumed completion tokens."),
+) -> None:
+    """Fail when the estimated cost of the inputs exceeds a budget."""
+
+    try:
+        measurements = _collect(paths, model, output_tokens)
+    except UnknownModel as exc:
+        _err.print(f"tokenmeter: {exc}; try 'tokenmeter models'")
+        raise typer.Exit(EXIT_BAD_INPUT) from exc
+    except (OSError, EncoderError) as exc:
+        _err.print(f"tokenmeter: {exc}")
+        raise typer.Exit(EXIT_BAD_INPUT) from exc
+
+    cost = total_cost(measurements)
+    _err.print(f"tokenmeter: estimated ${cost:.6f} against a ${max_cost:.6f} budget")
+    if over_budget(measurements, max_cost):
+        raise typer.Exit(EXIT_OVER_BUDGET)
+
+
+@app.command("models")
+def models() -> None:
+    """List the known models and their prices."""
+
+    title = f"prices as of {PRICES_AS_OF} (USD per 1M tokens)"
+    table = Table(box=None, pad_edge=False, title=title)
+    table.add_column("model")
+    table.add_column("encoding")
+    table.add_column("input", justify="right")
+    table.add_column("output", justify="right")
+    for name in known_models():
+        p = price_for(name)
+        table.add_row(p.model, p.encoding, f"${p.input_per_mtok:g}", f"${p.output_per_mtok:g}")
+    _out.print(table)
+
+
+def entrypoint() -> None:
+    try:
+        app()
+    except KeyboardInterrupt:  # pragma: no cover - interactive only
+        print("tokenmeter: interrupted", file=sys.stderr)
+        raise SystemExit(130) from None

tokenmeter_cli-0.2.0/src/tokenmeter/encoder.py

@@ -0,0 +1,52 @@
+"""Token counting behind a small interface.
+
+The real encoder uses ``tiktoken``, imported lazily so the package installs and
+imports without it and so the test suite can run with a fake encoder and no
+network access. Counting is therefore exact for the supported OpenAI encodings
+at run time, and deterministic in tests.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from tokenmeter.pricing import price_for
+
+
+class Encoder(Protocol):
+    def count(self, text: str) -> int: ...
+
+
+class EncoderError(RuntimeError):
+    """Raised when an encoder cannot be constructed."""
+
+
+class TiktokenEncoder:
+    """Count tokens with tiktoken for a given encoding name."""
+
+    def __init__(self, encoding: str) -> None:
+        self.encoding = encoding
+        self._enc = None
+
+    def _ensure(self):
+        if self._enc is not None:
+            return self._enc
+        try:
+            import tiktoken
+        except ImportError as exc:  # pragma: no cover - import guard
+            raise EncoderError(
+                "tiktoken is not installed; install tokenmeter with its default "
+                "dependencies to count tokens"
+            ) from exc
+        try:
+            self._enc = tiktoken.get_encoding(self.encoding)
+        except Exception as exc:  # pragma: no cover - needs network on first use
+            raise EncoderError(f"could not load encoding {self.encoding!r}") from exc
+        return self._enc
+
+    def count(self, text: str) -> int:
+        return len(self._ensure().encode(text))
+
+
+def encoder_for_model(model: str) -> Encoder:
+    return TiktokenEncoder(price_for(model).encoding)

tokenmeter_cli-0.2.0/src/tokenmeter/inputs.py

@@ -0,0 +1,41 @@
+"""Gather text inputs from files, directories, or standard input."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Iterable, Sequence
+from pathlib import Path
+
+TEXT_SUFFIXES = {".txt", ".md", ".prompt", ".jinja", ".j2", ".tmpl"}
+
+
+def read_inputs(
+    paths: Sequence[str | Path],
+    *,
+    stdin_text: str | None = None,
+) -> list[tuple[str, str]]:
+    """Return ``(name, text)`` pairs for every requested input.
+
+    A path of ``-`` reads standard input. Directories are expanded to their
+    text-like files, sorted for stable output.
+    """
+
+    out: list[tuple[str, str]] = []
+    for raw in paths:
+        if str(raw) == "-":
+            text = stdin_text if stdin_text is not None else sys.stdin.read()
+            out.append(("<stdin>", text))
+            continue
+        path = Path(raw)
+        if path.is_dir():
+            for child in _text_files(path):
+                out.append((str(child), child.read_text(encoding="utf-8")))
+        else:
+            out.append((str(path), path.read_text(encoding="utf-8")))
+    return out
+
+
+def _text_files(directory: Path) -> Iterable[Path]:
+    return sorted(
+        p for p in directory.rglob("*") if p.is_file() and p.suffix.lower() in TEXT_SUFFIXES
+    )

tokenmeter_cli-0.2.0/src/tokenmeter/meter.py

@@ -0,0 +1,57 @@
+"""Combine token counts with prices into measurements and a budget gate."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from tokenmeter.encoder import Encoder
+from tokenmeter.pricing import input_cost, output_cost
+
+
+@dataclass(frozen=True, slots=True)
+class Measurement:
+    name: str
+    model: str
+    input_tokens: int
+    output_tokens: int
+    input_cost: float
+    output_cost: float
+
+    @property
+    def total_cost(self) -> float:
+        return self.input_cost + self.output_cost
+
+    @property
+    def total_tokens(self) -> int:
+        return self.input_tokens + self.output_tokens
+
+
+def measure(
+    encoder: Encoder,
+    model: str,
+    name: str,
+    text: str,
+    *,
+    output_tokens: int = 0,
+) -> Measurement:
+    input_tokens = encoder.count(text)
+    return Measurement(
+        name=name,
+        model=model,
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        input_cost=input_cost(model, input_tokens),
+        output_cost=output_cost(model, output_tokens),
+    )
+
+
+def total_cost(measurements: list[Measurement]) -> float:
+    return sum(m.total_cost for m in measurements)
+
+
+def total_tokens(measurements: list[Measurement]) -> int:
+    return sum(m.total_tokens for m in measurements)
+
+
+def over_budget(measurements: list[Measurement], max_cost: float) -> bool:
+    return total_cost(measurements) > max_cost

tokenmeter_cli-0.2.0/src/tokenmeter/pricing.py

@@ -0,0 +1,67 @@
+"""Per-model token prices and the cost arithmetic on top of them.
+
+Prices are expressed in US dollars per million tokens and carry an "as of"
+date so a stale table is obvious. The numbers are easy to override or extend;
+the cost functions are pure and do not care where the rates came from.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+PRICES_AS_OF = "2025-08-01"
+
+
+@dataclass(frozen=True, slots=True)
+class ModelPrice:
+    """Input and output price in USD per million tokens."""
+
+    model: str
+    encoding: str
+    input_per_mtok: float
+    output_per_mtok: float
+
+
+# A small, explicit table. Values are USD per 1,000,000 tokens.
+_PRICES: dict[str, ModelPrice] = {
+    "gpt-4o": ModelPrice("gpt-4o", "o200k_base", 2.50, 10.00),
+    "gpt-4o-mini": ModelPrice("gpt-4o-mini", "o200k_base", 0.15, 0.60),
+    "gpt-4-turbo": ModelPrice("gpt-4-turbo", "cl100k_base", 10.00, 30.00),
+    "gpt-3.5-turbo": ModelPrice("gpt-3.5-turbo", "cl100k_base", 0.50, 1.50),
+    "text-embedding-3-small": ModelPrice("text-embedding-3-small", "cl100k_base", 0.02, 0.0),
+    "text-embedding-3-large": ModelPrice("text-embedding-3-large", "cl100k_base", 0.13, 0.0),
+}
+
+
+class UnknownModel(KeyError):
+    """Raised when a model has no entry in the price table."""
+
+    def __init__(self, model: str) -> None:
+        self.model = model
+        super().__init__(model)
+
+    def __str__(self) -> str:
+        return f"unknown model: {self.model}"
+
+
+def known_models() -> list[str]:
+    return sorted(_PRICES)
+
+
+def price_for(model: str) -> ModelPrice:
+    try:
+        return _PRICES[model]
+    except KeyError as exc:
+        raise UnknownModel(model) from exc
+
+
+def input_cost(model: str, tokens: int) -> float:
+    return price_for(model).input_per_mtok * tokens / 1_000_000
+
+
+def output_cost(model: str, tokens: int) -> float:
+    return price_for(model).output_per_mtok * tokens / 1_000_000
+
+
+def total_cost(model: str, input_tokens: int, output_tokens: int = 0) -> float:
+    return input_cost(model, input_tokens) + output_cost(model, output_tokens)

tokenmeter_cli-0.2.0/src/tokenmeter/render.py

@@ -0,0 +1,51 @@
+"""Render measurements for the terminal and as JSON."""
+
+from __future__ import annotations
+
+from rich.console import Group
+from rich.table import Table
+
+from tokenmeter.meter import Measurement, total_cost, total_tokens
+
+
+def measurements_to_json(measurements: list[Measurement]) -> dict:
+    return {
+        "inputs": [
+            {
+                "name": m.name,
+                "model": m.model,
+                "input_tokens": m.input_tokens,
+                "output_tokens": m.output_tokens,
+                "input_cost": round(m.input_cost, 6),
+                "output_cost": round(m.output_cost, 6),
+                "total_cost": round(m.total_cost, 6),
+            }
+            for m in measurements
+        ],
+        "total_tokens": total_tokens(measurements),
+        "total_cost": round(total_cost(measurements), 6),
+    }
+
+
+def render_table(measurements: list[Measurement]) -> Group:
+    table = Table(box=None, pad_edge=False)
+    table.add_column("input")
+    table.add_column("in tok", justify="right")
+    table.add_column("out tok", justify="right")
+    table.add_column("cost (USD)", justify="right")
+    for m in measurements:
+        table.add_row(
+            m.name,
+            f"{m.input_tokens}",
+            f"{m.output_tokens}",
+            f"${m.total_cost:.6f}",
+        )
+    if len(measurements) != 1:
+        table.add_section()
+        table.add_row(
+            "total",
+            f"{sum(m.input_tokens for m in measurements)}",
+            f"{sum(m.output_tokens for m in measurements)}",
+            f"${total_cost(measurements):.6f}",
+        )
+    return Group(table)

tokenmeter_cli-0.2.0/tests/conftest.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import pytest
+
+from tokenmeter.encoder import Encoder
+
+
+class WordEncoder(Encoder):
+    """A deterministic fake encoder: one token per whitespace-separated word.
+
+    Keeps tests free of tiktoken and network access while exercising all the
+    counting, pricing and budget logic.
+    """
+
+    def count(self, text: str) -> int:
+        return len(text.split())
+
+
+@pytest.fixture
+def encoder():
+    return WordEncoder()

tokenmeter_cli-0.2.0/tests/test_cli.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import json
+
+import pytest
+from tests.conftest import WordEncoder
+from typer.testing import CliRunner
+
+from tokenmeter import __version__
+from tokenmeter import cli as cli_module
+from tokenmeter import encoder as encoder_module
+
+runner = CliRunner()
+
+
+@pytest.fixture(autouse=True)
+def patch_encoder(monkeypatch):
+    monkeypatch.setattr(cli_module, "encoder_for_model", lambda model: WordEncoder())
+    monkeypatch.setattr(encoder_module, "encoder_for_model", lambda model: WordEncoder())
+
+
+def test_version():
+    result = runner.invoke(cli_module.app, ["--version"])
+    assert result.exit_code == 0
+    assert __version__ in result.stdout
+
+
+def test_count_file_json(tmp_path):
+    f = tmp_path / "p.txt"
+    f.write_text("one two three four")
+    result = runner.invoke(cli_module.app, ["count", str(f), "--json"])
+    assert result.exit_code == 0
+    payload = json.loads(result.stdout)
+    assert payload["total_tokens"] == 4
+    assert payload["inputs"][0]["input_tokens"] == 4
+
+
+def test_count_unknown_model_is_bad_input(tmp_path):
+    f = tmp_path / "p.txt"
+    f.write_text("hello")
+    result = runner.invoke(cli_module.app, ["count", str(f), "--model", "nope"])
+    assert result.exit_code == cli_module.EXIT_BAD_INPUT
+
+
+def test_budget_passes_under_limit(tmp_path):
+    f = tmp_path / "p.txt"
+    f.write_text("one two three")
+    result = runner.invoke(cli_module.app, ["budget", str(f), "--max-cost", "1.0"])
+    assert result.exit_code == 0
+
+
+def test_budget_fails_over_limit(tmp_path):
+    f = tmp_path / "p.txt"
+    f.write_text("word " * 100000)
+    result = runner.invoke(cli_module.app, ["budget", str(f), "--max-cost", "0.0001"])
+    assert result.exit_code == cli_module.EXIT_OVER_BUDGET
+
+
+def test_models_lists_prices():
+    result = runner.invoke(cli_module.app, ["models"])
+    assert result.exit_code == 0
+    assert "gpt-4o" in result.stdout

tokenmeter_cli-0.2.0/tests/test_inputs.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from tokenmeter.inputs import read_inputs
+
+
+def test_read_single_file(tmp_path):
+    f = tmp_path / "p.txt"
+    f.write_text("hello world")
+    assert read_inputs([f]) == [(str(f), "hello world")]
+
+
+def test_read_stdin_marker():
+    assert read_inputs(["-"], stdin_text="piped text") == [("<stdin>", "piped text")]
+
+
+def test_read_directory_expands_text_files(tmp_path):
+    (tmp_path / "a.txt").write_text("a")
+    (tmp_path / "b.md").write_text("b")
+    (tmp_path / "skip.bin").write_text("nope")
+    sub = tmp_path / "sub"
+    sub.mkdir()
+    (sub / "c.prompt").write_text("c")
+
+    results = read_inputs([tmp_path])
+    names = [name for name, _ in results]
+    assert any(n.endswith("a.txt") for n in names)
+    assert any(n.endswith("b.md") for n in names)
+    assert any(n.endswith("c.prompt") for n in names)
+    assert not any(n.endswith("skip.bin") for n in names)
+
+
+def test_directory_results_are_sorted(tmp_path):
+    for name in ["z.txt", "a.txt", "m.txt"]:
+        (tmp_path / name).write_text(name)
+    names = [n for n, _ in read_inputs([tmp_path])]
+    assert names == sorted(names)

tokenmeter_cli-0.2.0/tests/test_meter.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import pytest
+
+from tokenmeter.meter import measure, over_budget, total_cost, total_tokens
+
+
+def test_measure_counts_input_tokens(encoder):
+    m = measure(encoder, "gpt-4o", "p", "one two three four five")
+    assert m.input_tokens == 5
+    assert m.output_tokens == 0
+    assert m.input_cost == pytest.approx(2.50 * 5 / 1_000_000)
+    assert m.total_cost == m.input_cost
+
+
+def test_measure_includes_output_tokens_in_cost(encoder):
+    m = measure(encoder, "gpt-4o", "p", "one two", output_tokens=1_000)
+    assert m.output_tokens == 1_000
+    assert m.output_cost == pytest.approx(10.00 * 1_000 / 1_000_000)
+    assert m.total_tokens == 1_002
+
+
+def test_totals_across_measurements(encoder):
+    ms = [
+        measure(encoder, "gpt-4o", "a", "one two three"),
+        measure(encoder, "gpt-4o", "b", "four five"),
+    ]
+    assert total_tokens(ms) == 5
+    assert total_cost(ms) == pytest.approx(2.50 * 5 / 1_000_000)
+
+
+def test_over_budget(encoder):
+    ms = [measure(encoder, "gpt-4o", "a", "word " * 1_000_000)]
+    assert over_budget(ms, max_cost=1.0) is True
+    assert over_budget(ms, max_cost=100.0) is False

tokenmeter_cli-0.2.0/tests/test_pricing.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import pytest
+
+from tokenmeter.pricing import (
+    UnknownModel,
+    input_cost,
+    known_models,
+    output_cost,
+    price_for,
+    total_cost,
+)
+
+
+def test_known_models_sorted_and_nonempty():
+    models = known_models()
+    assert models == sorted(models)
+    assert "gpt-4o" in models
+
+
+def test_price_for_unknown_model_raises():
+    with pytest.raises(UnknownModel) as info:
+        price_for("does-not-exist")
+    assert "does-not-exist" in str(info.value)
+
+
+def test_input_cost_scales_with_tokens():
+    # gpt-4o input is $2.50 per million tokens.
+    assert input_cost("gpt-4o", 1_000_000) == pytest.approx(2.50)
+    assert input_cost("gpt-4o", 500_000) == pytest.approx(1.25)
+
+
+def test_output_cost_uses_output_rate():
+    assert output_cost("gpt-4o", 1_000_000) == pytest.approx(10.00)
+
+
+def test_total_cost_adds_input_and_output():
+    cost = total_cost("gpt-4o", 1_000_000, 1_000_000)
+    assert cost == pytest.approx(12.50)
+
+
+def test_embeddings_have_no_output_cost():
+    assert output_cost("text-embedding-3-small", 1_000_000) == 0.0