tokoscope 0.1.0__tar.gz

tokoscope-0.1.0/LICENSE

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

tokoscope-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: tokoscope
+Version: 0.1.0
+Summary: Audit, compress and monitor your LLM token usage in 2 lines of code
+Author-email: Tokoscope <hello@tokoscope.com>
+License: MIT
+Project-URL: Homepage, https://tokoscope.com
+Project-URL: Documentation, https://app.tokoscope.com/onboarding
+Project-URL: Repository, https://github.com/tokoscope/sdk
+Project-URL: Bug Tracker, https://github.com/tokoscope/sdk/issues
+Keywords: llm,openai,anthropic,tokens,optimization,cost,monitoring,prompt,compression,ai,token-usage,llm-cost,observability,gpt,claude
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Dynamic: license-file
+
+# Tokoscope Python SDK
+
+> Audit, compress, and monitor your LLM token usage in 2 lines of code.
+
+[![PyPI version](https://img.shields.io/pypi/v/tokoscope?color=00E5A0&style=flat-square)](https://pypi.org/project/tokoscope/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/tokoscope?color=00E5A0&style=flat-square)](https://pypi.org/project/tokoscope/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-00E5A0.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-00E5A0.svg?style=flat-square)](https://www.python.org/)
+
+Tokoscope sits between your app and any LLM API. It tracks every call, scores your prompts for waste, compresses bloated inputs automatically, and shows you exactly where your token budget is going.
+
+**Works with OpenAI and Anthropic out of the box.**
+
+---
+
+## Installation
+
+```bash
+pip install tokoscope
+```
+
+---
+
+## Quick start
+
+### OpenAI
+
+```python
+from openai import OpenAI
+from tokoscope import wrap
+
+client = wrap(OpenAI(), api_key="ts_live_...")  # get your key at app.tokoscope.com
+
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}]
+)
+
+print(response.choices[0].message.content)
+```
+
+### Anthropic
+
+```python
+from anthropic import Anthropic
+from tokoscope import wrap
+
+client = wrap(Anthropic(), api_key="ts_live_...")
+
+response = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello"}]
+)
+
+print(response.content[0].text)
+```
+
+That's it. Every API call is now tracked automatically.
+
+---
+
+## Real example
+
+**Original prompt:** 113 tokens
+
+```
+Please note that it is very important that you make sure to respond
+to my question. As an AI, I want you to please make sure that you
+understand that I need you to help me...
+What is the capital of France?
+```
+
+**Tokoscope compressed:** 8 tokens
+
+```
+What is the capital of France? Answer concisely.
+```
+
+**Result:** 90% token reduction. Same answer.
+
+---
+
+## What you get
+
+Once integrated, your [Tokoscope dashboard](https://app.tokoscope.com) shows:
+
+- **Token usage** broken down by model, endpoint, and provider
+- **Cost per request** calculated automatically using current pricing
+- **Waste score** for every prompt
+- **Auto-compression** — prompts with high waste scores are automatically rewritten
+- **Budget alerts** — get notified before costs spike
+
+---
+
+## Supported providers
+
+| Provider | Status |
+|---|---|
+| OpenAI | ✅ Supported |
+| Anthropic | ✅ Supported |
+| Gemini | 🔜 Coming soon |
+| Mistral | 🔜 Coming soon |
+
+---
+
+## Requirements
+
+- Python 3.8+
+- `requests` library (installed automatically)
+
+---
+
+## License
+
+MIT
+
+---
+
+## Links
+
+- [Website](https://tokoscope.com)
+- [Dashboard](https://app.tokoscope.com)
+- [JavaScript SDK](https://www.npmjs.com/package/tokoscope)
+- [Contact](mailto:hello@tokoscope.com)

tokoscope-0.1.0/README.md

@@ -0,0 +1,125 @@
+# Tokoscope Python SDK
+
+> Audit, compress, and monitor your LLM token usage in 2 lines of code.
+
+[![PyPI version](https://img.shields.io/pypi/v/tokoscope?color=00E5A0&style=flat-square)](https://pypi.org/project/tokoscope/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/tokoscope?color=00E5A0&style=flat-square)](https://pypi.org/project/tokoscope/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-00E5A0.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-00E5A0.svg?style=flat-square)](https://www.python.org/)
+
+Tokoscope sits between your app and any LLM API. It tracks every call, scores your prompts for waste, compresses bloated inputs automatically, and shows you exactly where your token budget is going.
+
+**Works with OpenAI and Anthropic out of the box.**
+
+---
+
+## Installation
+
+```bash
+pip install tokoscope
+```
+
+---
+
+## Quick start
+
+### OpenAI
+
+```python
+from openai import OpenAI
+from tokoscope import wrap
+
+client = wrap(OpenAI(), api_key="ts_live_...")  # get your key at app.tokoscope.com
+
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}]
+)
+
+print(response.choices[0].message.content)
+```
+
+### Anthropic
+
+```python
+from anthropic import Anthropic
+from tokoscope import wrap
+
+client = wrap(Anthropic(), api_key="ts_live_...")
+
+response = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello"}]
+)
+
+print(response.content[0].text)
+```
+
+That's it. Every API call is now tracked automatically.
+
+---
+
+## Real example
+
+**Original prompt:** 113 tokens
+
+```
+Please note that it is very important that you make sure to respond
+to my question. As an AI, I want you to please make sure that you
+understand that I need you to help me...
+What is the capital of France?
+```
+
+**Tokoscope compressed:** 8 tokens
+
+```
+What is the capital of France? Answer concisely.
+```
+
+**Result:** 90% token reduction. Same answer.
+
+---
+
+## What you get
+
+Once integrated, your [Tokoscope dashboard](https://app.tokoscope.com) shows:
+
+- **Token usage** broken down by model, endpoint, and provider
+- **Cost per request** calculated automatically using current pricing
+- **Waste score** for every prompt
+- **Auto-compression** — prompts with high waste scores are automatically rewritten
+- **Budget alerts** — get notified before costs spike
+
+---
+
+## Supported providers
+
+| Provider | Status |
+|---|---|
+| OpenAI | ✅ Supported |
+| Anthropic | ✅ Supported |
+| Gemini | 🔜 Coming soon |
+| Mistral | 🔜 Coming soon |
+
+---
+
+## Requirements
+
+- Python 3.8+
+- `requests` library (installed automatically)
+
+---
+
+## License
+
+MIT
+
+---
+
+## Links
+
+- [Website](https://tokoscope.com)
+- [Dashboard](https://app.tokoscope.com)
+- [JavaScript SDK](https://www.npmjs.com/package/tokoscope)
+- [Contact](mailto:hello@tokoscope.com)

tokoscope-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tokoscope"
+version = "0.1.0"
+description = "Audit, compress and monitor your LLM token usage in 2 lines of code"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Tokoscope", email = "hello@tokoscope.com" }]
+requires-python = ">=3.8"
+dependencies = ["requests>=2.28.0"]
+keywords = [
+    "llm", "openai", "anthropic", "tokens", "optimization",
+    "cost", "monitoring", "prompt", "compression", "ai",
+    "token-usage", "llm-cost", "observability", "gpt", "claude"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://tokoscope.com"
+Documentation = "https://app.tokoscope.com/onboarding"
+Repository = "https://github.com/tokoscope/sdk"
+"Bug Tracker" = "https://github.com/tokoscope/sdk/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tokoscope*"]

tokoscope-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tokoscope-0.1.0/tokoscope/__init__.py

@@ -0,0 +1,4 @@
+from .wrapper import wrap
+
+__version__ = "0.1.0"
+__all__ = ["wrap"]

tokoscope-0.1.0/tokoscope/tracker.py

@@ -0,0 +1,24 @@
+import threading
+import requests
+
+ENDPOINT = "https://us-central1-tokoscope-e8ab2.cloudfunctions.net/trackEvent"
+
+
+def track(api_key: str, payload: dict) -> None:
+    """Send tracking event to Tokoscope in a background thread."""
+    def _send():
+        try:
+            requests.post(
+                ENDPOINT,
+                json=payload,
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": f"Bearer {api_key}"
+                },
+                timeout=5
+            )
+        except Exception:
+            pass  # Silent fail — never break the main app
+
+    thread = threading.Thread(target=_send, daemon=True)
+    thread.start()

tokoscope-0.1.0/tokoscope/wrapper.py

@@ -0,0 +1,121 @@
+from .tracker import track
+
+
+class OpenAIWrapper:
+    """Wraps the OpenAI client to track token usage."""
+
+    def __init__(self, client, api_key: str):
+        self._client = client
+        self._api_key = api_key
+        self.chat = ChatWrapper(client.chat, api_key)
+
+    def __getattr__(self, name):
+        return getattr(self._client, name)
+
+
+class ChatWrapper:
+    def __init__(self, chat, api_key: str):
+        self._chat = chat
+        self._api_key = api_key
+        self.completions = CompletionsWrapper(chat.completions, api_key)
+
+    def __getattr__(self, name):
+        return getattr(self._chat, name)
+
+
+class CompletionsWrapper:
+    def __init__(self, completions, api_key: str):
+        self._completions = completions
+        self._api_key = api_key
+
+    def create(self, **kwargs):
+        result = self._completions.create(**kwargs)
+        try:
+            messages = kwargs.get("messages", [])
+            prompt = " ".join(
+                m.get("content", "") if isinstance(m, dict) else str(m)
+                for m in messages
+            )
+            track(self._api_key, {
+                "provider": "openai",
+                "model": kwargs.get("model", "unknown"),
+                "inputTokens": getattr(result.usage, "prompt_tokens", 0),
+                "outputTokens": getattr(result.usage, "completion_tokens", 0),
+                "prompt": prompt[:500],
+                "endpoint": kwargs.get("model", "unknown"),
+            })
+        except Exception:
+            pass
+        return result
+
+    def __getattr__(self, name):
+        return getattr(self._completions, name)
+
+
+class AnthropicWrapper:
+    """Wraps the Anthropic client to track token usage."""
+
+    def __init__(self, client, api_key: str):
+        self._client = client
+        self._api_key = api_key
+        self.messages = AnthropicMessagesWrapper(client.messages, api_key)
+
+    def __getattr__(self, name):
+        return getattr(self._client, name)
+
+
+class AnthropicMessagesWrapper:
+    def __init__(self, messages, api_key: str):
+        self._messages = messages
+        self._api_key = api_key
+
+    def create(self, **kwargs):
+        result = self._messages.create(**kwargs)
+        try:
+            messages = kwargs.get("messages", [])
+            prompt = " ".join(
+                m.get("content", "") if isinstance(m, dict) else str(m)
+                for m in messages
+            )
+            track(self._api_key, {
+                "provider": "anthropic",
+                "model": kwargs.get("model", "unknown"),
+                "inputTokens": getattr(result.usage, "input_tokens", 0),
+                "outputTokens": getattr(result.usage, "output_tokens", 0),
+                "prompt": prompt[:500],
+                "endpoint": kwargs.get("model", "unknown"),
+            })
+        except Exception:
+            pass
+        return result
+
+    def __getattr__(self, name):
+        return getattr(self._messages, name)
+
+
+def wrap(client, api_key: str):
+    """
+    Wrap an OpenAI or Anthropic client to track token usage with Tokoscope.
+
+    Args:
+        client: An OpenAI() or Anthropic() client instance
+        api_key: Your Tokoscope API key from app.tokoscope.com/settings
+
+    Returns:
+        Wrapped client with identical interface
+
+    Example:
+        from openai import OpenAI
+        from tokoscope import wrap
+
+        client = wrap(OpenAI(), api_key="ts_live_...")
+    """
+    if not api_key:
+        raise ValueError("Tokoscope: api_key is required")
+
+    client_type = type(client).__name__
+
+    if "Anthropic" in client_type:
+        return AnthropicWrapper(client, api_key)
+    else:
+        return OpenAIWrapper(client, api_key)

tokoscope-0.1.0/tokoscope.egg-info/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: tokoscope
+Version: 0.1.0
+Summary: Audit, compress and monitor your LLM token usage in 2 lines of code
+Author-email: Tokoscope <hello@tokoscope.com>
+License: MIT
+Project-URL: Homepage, https://tokoscope.com
+Project-URL: Documentation, https://app.tokoscope.com/onboarding
+Project-URL: Repository, https://github.com/tokoscope/sdk
+Project-URL: Bug Tracker, https://github.com/tokoscope/sdk/issues
+Keywords: llm,openai,anthropic,tokens,optimization,cost,monitoring,prompt,compression,ai,token-usage,llm-cost,observability,gpt,claude
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Dynamic: license-file
+
+# Tokoscope Python SDK
+
+> Audit, compress, and monitor your LLM token usage in 2 lines of code.
+
+[![PyPI version](https://img.shields.io/pypi/v/tokoscope?color=00E5A0&style=flat-square)](https://pypi.org/project/tokoscope/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/tokoscope?color=00E5A0&style=flat-square)](https://pypi.org/project/tokoscope/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-00E5A0.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-00E5A0.svg?style=flat-square)](https://www.python.org/)
+
+Tokoscope sits between your app and any LLM API. It tracks every call, scores your prompts for waste, compresses bloated inputs automatically, and shows you exactly where your token budget is going.
+
+**Works with OpenAI and Anthropic out of the box.**
+
+---
+
+## Installation
+
+```bash
+pip install tokoscope
+```
+
+---
+
+## Quick start
+
+### OpenAI
+
+```python
+from openai import OpenAI
+from tokoscope import wrap
+
+client = wrap(OpenAI(), api_key="ts_live_...")  # get your key at app.tokoscope.com
+
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}]
+)
+
+print(response.choices[0].message.content)
+```
+
+### Anthropic
+
+```python
+from anthropic import Anthropic
+from tokoscope import wrap
+
+client = wrap(Anthropic(), api_key="ts_live_...")
+
+response = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello"}]
+)
+
+print(response.content[0].text)
+```
+
+That's it. Every API call is now tracked automatically.
+
+---
+
+## Real example
+
+**Original prompt:** 113 tokens
+
+```
+Please note that it is very important that you make sure to respond
+to my question. As an AI, I want you to please make sure that you
+understand that I need you to help me...
+What is the capital of France?
+```
+
+**Tokoscope compressed:** 8 tokens
+
+```
+What is the capital of France? Answer concisely.
+```
+
+**Result:** 90% token reduction. Same answer.
+
+---
+
+## What you get
+
+Once integrated, your [Tokoscope dashboard](https://app.tokoscope.com) shows:
+
+- **Token usage** broken down by model, endpoint, and provider
+- **Cost per request** calculated automatically using current pricing
+- **Waste score** for every prompt
+- **Auto-compression** — prompts with high waste scores are automatically rewritten
+- **Budget alerts** — get notified before costs spike
+
+---
+
+## Supported providers
+
+| Provider | Status |
+|---|---|
+| OpenAI | ✅ Supported |
+| Anthropic | ✅ Supported |
+| Gemini | 🔜 Coming soon |
+| Mistral | 🔜 Coming soon |
+
+---
+
+## Requirements
+
+- Python 3.8+
+- `requests` library (installed automatically)
+
+---
+
+## License
+
+MIT
+
+---
+
+## Links
+
+- [Website](https://tokoscope.com)
+- [Dashboard](https://app.tokoscope.com)
+- [JavaScript SDK](https://www.npmjs.com/package/tokoscope)
+- [Contact](mailto:hello@tokoscope.com)

tokoscope-0.1.0/tokoscope.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+tokoscope/__init__.py
+tokoscope/tracker.py
+tokoscope/wrapper.py
+tokoscope.egg-info/PKG-INFO
+tokoscope.egg-info/SOURCES.txt
+tokoscope.egg-info/dependency_links.txt
+tokoscope.egg-info/requires.txt
+tokoscope.egg-info/top_level.txt

tokoscope-0.1.0/tokoscope.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tokoscope-0.1.0/tokoscope.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.28.0

tokoscope-0.1.0/tokoscope.egg-info/top_level.txt

@@ -0,0 +1 @@
+tokoscope