tokenmaster 0.0.1__tar.gz

tokenmaster-0.0.1/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+test_env/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Node (future packages)
+node_modules/
+
+# Rust (future crates)
+target/
+
+# Secrets and local environment
+.env
+.env.local
+*.key
+*secrets*
+
+# OS and editors
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/

tokenmaster-0.0.1/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to tokenmaster are documented in this file.
+
+## 0.0.1 (2026-07-07)
+
+- Placeholder release reserving the package name on PyPI.
+- Exposes `__version__` and `about()` only. No functional API yet.

tokenmaster-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muntaser Syed
+
+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.

tokenmaster-0.0.1/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: tokenmaster
+Version: 0.0.1
+Summary: Core context-budget metering and decision engine for LLM applications: normalized token accounting, effective-budget gauges, turns-to-exhaustion prediction, and compaction/handoff decisions. Placeholder release.
+Project-URL: Homepage, https://github.com/jemsbhai/tokenmaster
+Project-URL: Repository, https://github.com/jemsbhai/tokenmaster
+Author-email: Muntaser Syed <jemsbhai@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: compaction,context-management,context-window,continuation-prompt,llm,metering,tokens
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# tokenmaster
+
+Core context-budget metering and decision engine for LLM applications.
+
+tokenmaster is being built to answer four questions for any model, provider,
+and conversation:
+
+1. How much context has been used, and on what (messages, system prompt, tool
+   schemas, reasoning tokens, cache reads)?
+2. How much usable budget remains, measured against calibrated effective
+   capacity rather than the advertised window?
+3. How many turns remain until exhaustion at the current token velocity?
+4. Should this conversation be compacted or handed off now, and what would
+   that decision cost?
+
+The package is computational only: it ingests provider-reported usage (with
+tokenizer-based estimation as an optional fallback), maintains meter state,
+and emits snapshots and events through a stable, serializable schema.
+Rendering is deliberately excluded. The companion package ctxmaster provides
+a CLI, terminal gauge, and dashboards on top of this schema, and third
+parties can build their own visualizers against the same contract.
+
+## Status
+
+0.0.1 is a placeholder release reserving the name while the core API is
+designed. Do not build against it yet. Development happens at
+https://github.com/jemsbhai/tokenmaster
+
+## License
+
+MIT

tokenmaster-0.0.1/README.md

@@ -0,0 +1,31 @@
+# tokenmaster
+
+Core context-budget metering and decision engine for LLM applications.
+
+tokenmaster is being built to answer four questions for any model, provider,
+and conversation:
+
+1. How much context has been used, and on what (messages, system prompt, tool
+   schemas, reasoning tokens, cache reads)?
+2. How much usable budget remains, measured against calibrated effective
+   capacity rather than the advertised window?
+3. How many turns remain until exhaustion at the current token velocity?
+4. Should this conversation be compacted or handed off now, and what would
+   that decision cost?
+
+The package is computational only: it ingests provider-reported usage (with
+tokenizer-based estimation as an optional fallback), maintains meter state,
+and emits snapshots and events through a stable, serializable schema.
+Rendering is deliberately excluded. The companion package ctxmaster provides
+a CLI, terminal gauge, and dashboards on top of this schema, and third
+parties can build their own visualizers against the same contract.
+
+## Status
+
+0.0.1 is a placeholder release reserving the name while the core API is
+designed. Do not build against it yet. Development happens at
+https://github.com/jemsbhai/tokenmaster
+
+## License
+
+MIT

tokenmaster-0.0.1/examples/print_about.py

@@ -0,0 +1,8 @@
+"""Print tokenmaster placeholder metadata."""
+
+import tokenmaster
+
+
+if __name__ == "__main__":
+    for key, value in tokenmaster.about().items():
+        print(f"{key}: {value}")

tokenmaster-0.0.1/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tokenmaster"
+version = "0.0.1"
+description = "Core context-budget metering and decision engine for LLM applications: normalized token accounting, effective-budget gauges, turns-to-exhaustion prediction, and compaction/handoff decisions. Placeholder release."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Muntaser Syed", email = "jemsbhai@gmail.com" },
+]
+keywords = [
+  "llm",
+  "tokens",
+  "context-window",
+  "context-management",
+  "compaction",
+  "continuation-prompt",
+  "metering",
+]
+classifiers = [
+  "Development Status :: 1 - Planning",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://github.com/jemsbhai/tokenmaster"
+Repository = "https://github.com/jemsbhai/tokenmaster"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tokenmaster"]

tokenmaster-0.0.1/src/tokenmaster/__init__.py

@@ -0,0 +1,24 @@
+"""tokenmaster: core context-budget metering and decision engine for LLM applications.
+
+Placeholder release (0.0.1) reserving the package name while the core API is
+designed. Do not build against this version.
+"""
+
+__version__ = "0.0.1"
+
+__all__ = ["about", "__version__"]
+
+
+def about() -> dict:
+    """Return basic project metadata for this placeholder release."""
+    return {
+        "name": "tokenmaster",
+        "version": __version__,
+        "summary": (
+            "Core context-budget metering and decision engine for "
+            "LLM applications."
+        ),
+        "companion": "ctxmaster (visualization layer)",
+        "repository": "https://github.com/jemsbhai/tokenmaster",
+        "status": "placeholder",
+    }

tokenmaster-0.0.1/tests/test_placeholder.py

@@ -0,0 +1,15 @@
+"""Placeholder-release tests: import, version, and metadata sanity."""
+
+import tokenmaster
+
+
+def test_version_matches_placeholder():
+    assert tokenmaster.__version__ == "0.0.1"
+
+
+def test_about_returns_expected_metadata():
+    info = tokenmaster.about()
+    assert info["name"] == "tokenmaster"
+    assert info["version"] == tokenmaster.__version__
+    assert info["status"] == "placeholder"
+    assert "ctxmaster" in info["companion"]