openai-usage 0.1.0__tar.gz

openai_usage-0.1.0/LICENSE

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

openai_usage-0.1.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.3
+Name: openai-usage
+Version: 0.1.0
+Summary: Simple Library for OpenAI Usage
+License: MIT
+Author: Allen Chou
+Author-email: f1470891079@gmail.com
+Requires-Python: >=3.11,<4
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: dictpress (>=0.3.0)
+Requires-Dist: openai (>=1,<2)
+Requires-Dist: openai-agents (>=0.1.0,<1.0.0)
+Requires-Dist: pydantic (>=2)
+Requires-Dist: str-or-none
+Project-URL: Homepage, https://github.com/allen2c/openai-usage
+Project-URL: PyPI, https://pypi.org/project/openai-usage/
+Project-URL: Repository, https://github.com/allen2c/openai-usage
+Description-Content-Type: text/markdown
+
+# openai-usage
+
+[![PyPI](https://img.shields.io/pypi/v/openai-usage.svg)](https://pypi.org/project/openai-usage/)
+
+Utilities to track OpenAI API usage.
+
+## Installation
+
+```bash
+pip install openai-usage
+```
+
+## Usage
+
+```python
+from openai_usage import Usage
+
+# Track usage manually
+usage = Usage()
+usage.add(Usage(requests=1, input_tokens=10, output_tokens=20, total_tokens=30))
+
+# Create from OpenAI object
+from openai.types.completion_usage import CompletionUsage
+openai_usage = CompletionUsage(prompt_tokens=10, completion_tokens=20, total_tokens=30)
+usage = Usage.from_openai(openai_usage)
+```
+

openai_usage-0.1.0/README.md

@@ -0,0 +1,26 @@
+# openai-usage
+
+[![PyPI](https://img.shields.io/pypi/v/openai-usage.svg)](https://pypi.org/project/openai-usage/)
+
+Utilities to track OpenAI API usage.
+
+## Installation
+
+```bash
+pip install openai-usage
+```
+
+## Usage
+
+```python
+from openai_usage import Usage
+
+# Track usage manually
+usage = Usage()
+usage.add(Usage(requests=1, input_tokens=10, output_tokens=20, total_tokens=30))
+
+# Create from OpenAI object
+from openai.types.completion_usage import CompletionUsage
+openai_usage = CompletionUsage(prompt_tokens=10, completion_tokens=20, total_tokens=30)
+usage = Usage.from_openai(openai_usage)
+```

openai_usage-0.1.0/openai_usage/VERSION

@@ -0,0 +1 @@
+0.1.0

openai_usage-0.1.0/openai_usage/__init__.py

@@ -0,0 +1,128 @@
+# openai_usage/__init__.py
+"""OpenAI usage tracking utilities.
+
+Simple models for tracking and aggregating OpenAI API usage data.
+"""
+
+import pathlib
+
+import agents
+import pydantic
+from openai.types.completion_usage import CompletionUsage
+from openai.types.responses.response_usage import (
+    InputTokensDetails,
+    OutputTokensDetails,
+    ResponseUsage,
+)
+
+__version__ = pathlib.Path(__file__).parent.joinpath("VERSION").read_text().strip()
+
+
+class Usage(pydantic.BaseModel):
+    """Usage statistics for OpenAI API calls.
+
+    Tracks token counts and request metrics across API interactions.
+    """
+
+    requests: int = 0
+    input_tokens: int = 0
+    input_tokens_details: InputTokensDetails = pydantic.Field(
+        default_factory=lambda: InputTokensDetails(cached_tokens=0)
+    )
+    output_tokens: int = 0
+    output_tokens_details: OutputTokensDetails = pydantic.Field(
+        default_factory=lambda: OutputTokensDetails(reasoning_tokens=0)
+    )
+    total_tokens: int = 0
+
+    @classmethod
+    def from_openai(
+        cls,
+        openai_usage: (
+            ResponseUsage | agents.RunContextWrapper | agents.Usage | CompletionUsage
+        ),
+        *,
+        inplace: bool = False,
+    ) -> "Usage":
+        """Create Usage from OpenAI usage objects.
+
+        Supports ResponseUsage, RunContextWrapper, agents.Usage, and CompletionUsage types.
+        Returns new instance unless inplace=True.
+        """  # noqa: E501
+
+        if isinstance(openai_usage, ResponseUsage):
+            usage = cls(
+                requests=1,
+                input_tokens=openai_usage.input_tokens,
+                input_tokens_details=openai_usage.input_tokens_details,
+                output_tokens=openai_usage.output_tokens,
+                output_tokens_details=openai_usage.output_tokens_details,
+                total_tokens=openai_usage.total_tokens,
+            )
+        elif isinstance(openai_usage, agents.RunContextWrapper):
+            usage = cls(
+                requests=1,
+                input_tokens=openai_usage.usage.input_tokens,
+                input_tokens_details=openai_usage.usage.input_tokens_details,
+                output_tokens=openai_usage.usage.output_tokens,
+                output_tokens_details=openai_usage.usage.output_tokens_details,
+                total_tokens=openai_usage.usage.total_tokens,
+            )
+        elif isinstance(openai_usage, agents.Usage):
+            usage = cls(
+                requests=1,
+                input_tokens=openai_usage.input_tokens,
+                input_tokens_details=openai_usage.input_tokens_details,
+                output_tokens=openai_usage.output_tokens,
+                output_tokens_details=openai_usage.output_tokens_details,
+                total_tokens=openai_usage.total_tokens,
+            )
+
+        elif isinstance(openai_usage, CompletionUsage):
+            usage = cls(
+                requests=1,
+                input_tokens=openai_usage.prompt_tokens,
+                input_tokens_details=InputTokensDetails(
+                    cached_tokens=(
+                        openai_usage.prompt_tokens_details.cached_tokens or 0
+                        if openai_usage.prompt_tokens_details
+                        else 0
+                    )
+                ),
+                output_tokens=openai_usage.completion_tokens,
+                output_tokens_details=OutputTokensDetails(
+                    reasoning_tokens=(
+                        openai_usage.completion_tokens_details.reasoning_tokens or 0
+                        if openai_usage.completion_tokens_details
+                        else 0
+                    )
+                ),
+                total_tokens=openai_usage.total_tokens,
+            )
+
+        else:
+            raise ValueError(f"Unsupported usage type: {type(openai_usage)}")
+
+        if inplace:
+            return usage
+        else:
+            return cls.model_validate_json(usage.model_dump_json())
+
+    def add(self, other: "Usage") -> None:
+        """Add usage from another Usage instance.
+
+        Accumulates all metrics including token counts and request totals.
+        """
+        self.requests += other.requests if other.requests else 0
+        self.input_tokens += other.input_tokens if other.input_tokens else 0
+        self.output_tokens += other.output_tokens if other.output_tokens else 0
+        self.total_tokens += other.total_tokens if other.total_tokens else 0
+        self.input_tokens_details = InputTokensDetails(
+            cached_tokens=self.input_tokens_details.cached_tokens
+            + other.input_tokens_details.cached_tokens
+        )
+
+        self.output_tokens_details = OutputTokensDetails(
+            reasoning_tokens=self.output_tokens_details.reasoning_tokens
+            + other.output_tokens_details.reasoning_tokens
+        )

openai_usage-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+authors = [{ name = "Allen Chou", email = "f1470891079@gmail.com" }]
+dependencies = [
+  "dictpress (>=0.3.0)",
+  "openai (>=1,<2)",
+  "openai-agents (>=0.1.0,<1.0.0)",
+  "pydantic (>=2)",
+  "str-or-none",
+]
+description = "Simple Library for OpenAI Usage"
+license = { text = "MIT" }
+name = "openai-usage"
+readme = "README.md"
+requires-python = ">=3.11,<4"
+version = "0.1.0"
+
+[project.urls]
+Homepage = "https://github.com/allen2c/openai-usage"
+"PyPI" = "https://pypi.org/project/openai-usage/"
+Repository = "https://github.com/allen2c/openai-usage"
+
+[tool.poetry]
+packages = [{ include = "openai_usage" }]
+
+[tool.poetry.extras]
+all = []
+
+[tool.poetry.group.dev.dependencies]
+black = { extras = ["jupyter"], version = "*" }
+codepress = "*"
+isort = "*"
+poetry-plugin-export = "*"
+pytest = "*"
+pytest-asyncio = "*"
+pytest-cov = "*"
+pytest-env = "*"
+pytest-xdist = "*"
+rich = "*"
+rich-color-support = "*"
+setuptools = "*"
+twine = "*"
+
+[tool.isort]
+profile = "black"
+
+[tool.flake8]
+ignore = ["E203", "E704", "W503"]
+max-line-length = 88
+
+[tool.pytest.ini_options]
+env = ["ENVIRONMENT=test", "PYTEST_IS_RUNNING=true"]
+
+[build-system]
+build-backend = "poetry.core.masonry.api"
+requires = ["poetry-core>=2.0.0,<3.0.0"]