agentcap 0.1.0__tar.gz

agentcap-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+
+# Virtual environments
+venv/
+.env/
+ENV/
+env/
+.venv/
+.env
+
+# IDE / editor configs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# MacOS / system files
+.DS_Store
+
+# Logs
+*.log

agentcap-0.1.0/LICENSE

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

agentcap-0.1.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: agentcap
+Version: 0.1.0
+Summary: Cost guardrails for LLM agent runs.
+Project-URL: Homepage, https://github.com/OliverIida/agentcap
+Author: Oliver Iida
+License: MIT License
+        
+        Copyright (c) 2026 OliverIida
+        
+        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: agents,anthropic,cost-control,gemini,llm,openai
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# agentcap
+`agentcap` is a cost guardrail for LLM agent runs. It calculates safe token limits before execution and enforces strict budget ceilings using real usage data.
+
+## Install
+
+```bash
+pip install agentcap
+```
+
+## Documentation
+See [DOCUMENTATION.md](DOCUMENTATION.md) for full usage details.
+
+## Supported models
+See [agentcap/models.json](agentcap/models.json) for the list of currently supported models.
+To add more models, open a PR.
+
+Note: Prices may change. Please verify with the provider.
+
+## Model pricing sources
+OpenAI pricing: https://developers.openai.com/api/docs/pricing?latest-pricing=standard  
+Anthropic pricing: https://platform.claude.com/docs/en/about-claude/pricing  
+Gemini pricing: https://ai.google.dev/gemini-api/docs/pricing#standard

agentcap-0.1.0/README.md

@@ -0,0 +1,22 @@
+# agentcap
+`agentcap` is a cost guardrail for LLM agent runs. It calculates safe token limits before execution and enforces strict budget ceilings using real usage data.
+
+## Install
+
+```bash
+pip install agentcap
+```
+
+## Documentation
+See [DOCUMENTATION.md](DOCUMENTATION.md) for full usage details.
+
+## Supported models
+See [agentcap/models.json](agentcap/models.json) for the list of currently supported models.
+To add more models, open a PR.
+
+Note: Prices may change. Please verify with the provider.
+
+## Model pricing sources
+OpenAI pricing: https://developers.openai.com/api/docs/pricing?latest-pricing=standard  
+Anthropic pricing: https://platform.claude.com/docs/en/about-claude/pricing  
+Gemini pricing: https://ai.google.dev/gemini-api/docs/pricing#standard

agentcap-0.1.0/agentcap/__init__.py

@@ -0,0 +1,9 @@
+from .core import AgentCap
+from .exceptions import BudgetExceeded, InvalidArguments, UnknownModelError
+
+__all__ = [
+    "AgentCap",
+    "BudgetExceeded",
+    "InvalidArguments",
+    "UnknownModelError"
+]

agentcap-0.1.0/agentcap/core.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import floor
+
+from .exceptions import BudgetExceeded, InvalidArguments
+from .pricing import get_model_price
+from .token_estimator import estimate_tokens
+
+@dataclass(slots=True)
+class PlanResult:
+    model: str
+    budget_usd: float
+    effective_budget_usd: float
+    prompt_tokens: int
+    estimated_input_cost_usd: float
+    remaining_budget_usd: float
+    max_output_tokens: int
+    warnings: list[str]
+
+class AgentCap:
+    def __init__(
+        self,
+        model: str,
+        budget_usd: float,
+        safety_margin: float = 0.90,
+        min_output_tokens: int = 16,
+        low_budget_warning_threshold: float = 0.15,
+    ) -> None:
+        if not isinstance(model, str) or not model.strip():
+            raise InvalidArguments("model must be a non-empty string")
+        if budget_usd <= 0:
+            raise InvalidArguments("budget_usd must be greater than 0")
+        if not (0 < safety_margin <= 1):
+            raise InvalidArguments("safety_margin must be in the range (0, 1]")
+        if min_output_tokens < 1:
+            raise InvalidArguments("min_output_tokens must be >= 1")
+        if not (0 <= low_budget_warning_threshold <= 1):
+            raise InvalidArguments(
+                "low_budget_warning_threshold must be in the range [0, 1]"
+            )
+
+        self.model = model.strip()
+        self.budget_usd = float(budget_usd)
+        self.safety_margin = float(safety_margin)
+        self.min_output_tokens = int(min_output_tokens)
+        self.low_budget_warning_threshold = float(low_budget_warning_threshold)
+        self._price = get_model_price(self.model)
+
+    def estimate_cost(self, prompt_tokens: int, output_tokens: int) -> float:
+        if prompt_tokens < 0 or output_tokens < 0:
+            raise InvalidArguments("prompt_tokens and output_tokens must be >= 0")
+
+        input_cost = (prompt_tokens / 1_000_000) * self._price.input_per_1m
+        output_cost = (output_tokens / 1_000_000) * self._price.output_per_1m
+        return input_cost + output_cost
+
+    def plan(self, prompt_text: str) -> PlanResult:
+        if not isinstance(prompt_text, str) or not prompt_text.strip():
+            raise InvalidArguments("prompt_text must be a non-empty string")
+
+        prompt_tokens = estimate_tokens(prompt_text)
+        effective_budget = self.budget_usd * self.safety_margin
+        input_cost = (prompt_tokens / 1_000_000) * self._price.input_per_1m
+
+        if input_cost >= effective_budget:
+            raise BudgetExceeded("Prompt alone exceeds budget.")
+
+        remaining = effective_budget - input_cost
+        cost_per_output_token = self._price.output_per_1m / 1_000_000
+        if cost_per_output_token <= 0:
+            raise InvalidArguments("model output pricing must be greater than 0")
+
+        max_output_tokens = floor(remaining / cost_per_output_token)
+        if max_output_tokens < self.min_output_tokens:
+            raise BudgetExceeded("Not enough budget for minimum output tokens.")
+
+        warnings: list[str] = []
+        if remaining <= self.budget_usd * self.low_budget_warning_threshold:
+            warnings.append(
+                "Low remaining budget after prompt. Consider increasing budget or "
+                "shortening prompt."
+            )
+
+        return PlanResult(
+            model=self.model,
+            budget_usd=self.budget_usd,
+            effective_budget_usd=effective_budget,
+            prompt_tokens=prompt_tokens,
+            estimated_input_cost_usd=input_cost,
+            remaining_budget_usd=remaining,
+            max_output_tokens=max_output_tokens,
+            warnings=warnings,
+        )
+
+    def finalize(self, prompt_tokens: int, output_tokens: int) -> float:
+        actual_cost = self.estimate_cost(prompt_tokens, output_tokens)
+        if actual_cost > self.budget_usd:
+            raise BudgetExceeded("Run exceeded budget.")
+        return actual_cost

agentcap-0.1.0/agentcap/exceptions.py

@@ -0,0 +1,8 @@
+class UnknownModelError(ValueError):
+    """Raised when a model name is not found in pricing data."""
+
+class BudgetExceeded(RuntimeError):
+    """Raised when a planned or actual run exceeds budget constraints."""
+
+class InvalidArguments(ValueError):
+    """Raised when inputs are invalid."""

agentcap-0.1.0/agentcap/models.json

@@ -0,0 +1,73 @@
+{
+    "claude-opus-4.6": {
+      "input_per_1m": 5.00,
+      "output_per_1m": 25.00
+    },
+    "claude-opus-4.5": {
+      "input_per_1m": 5.00,
+      "output_per_1m": 25.00
+    },
+    "claude-sonnet-4.6": {
+      "input_per_1m": 3.00,
+      "output_per_1m": 15.00
+    },
+    "claude-sonnet-4.5": {
+      "input_per_1m": 3.00,
+      "output_per_1m": 15.00
+    },
+    "claude-haiku-4.5": {
+      "input_per_1m": 1.00,
+      "output_per_1m": 5.00
+    },
+    "claude-haiku-3.5": {
+      "input_per_1m": 0.80,
+      "output_per_1m": 4.00
+    },
+  
+    "gpt-5.3-codex": {
+      "input_per_1m": 1.75,
+      "output_per_1m": 14.00
+    },
+    "gpt-5.2-codex": {
+      "input_per_1m": 1.75,
+      "output_per_1m": 14.00
+    },
+    "gpt-5.1-codex": {
+      "input_per_1m": 1.25,
+      "output_per_1m": 10.00
+    },
+    "gpt-5-codex": {
+      "input_per_1m": 1.25,
+      "output_per_1m": 10.00
+    },
+  
+    "gpt-5.2": {
+      "input_per_1m": 1.75,
+      "output_per_1m": 14.00
+    },
+    "gpt-5.1": {
+      "input_per_1m": 1.25,
+      "output_per_1m": 10.00
+    },
+    "gpt-5": {
+      "input_per_1m": 1.25,
+      "output_per_1m": 10.00
+    },
+
+    "gemini-3.1-pro-preview": {
+      "input_per_1m": 2.00,
+      "output_per_1m": 12.00
+    },
+    "gemini-3-flash-preview": {
+      "input_per_1m": 0.50,
+      "output_per_1m": 3.00
+    },
+    "gemini-2.5-pro": {
+      "input_per_1m": 1.25,
+      "output_per_1m": 10.00
+    },
+    "gemini-2.5-flash": {
+      "input_per_1m": 0.30,
+      "output_per_1m": 2.50
+    }
+}

agentcap-0.1.0/agentcap/pricing.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import importlib.resources as resources
+
+from .exceptions import InvalidArguments, UnknownModelError
+
+@dataclass(frozen=True, slots=True)
+class ModelPrice:
+    input_per_1m: float
+    output_per_1m: float
+
+def _load_model_prices() -> dict[str, dict[str, float]]:
+    data_file = resources.files(__package__).joinpath("models.json")
+    with data_file.open("r", encoding="utf-8") as handle:
+        raw = json.load(handle)
+    if not isinstance(raw, dict):
+        raise InvalidArguments("models.json must contain a JSON object at the root")
+    return raw
+
+def get_model_price(model: str) -> ModelPrice:
+    if not isinstance(model, str) or not model.strip():
+        raise InvalidArguments("model must be a non-empty string")
+
+    models = _load_model_prices()
+    model_key = model.strip()
+    if model_key not in models:
+        raise UnknownModelError(f"Unknown model: {model_key}")
+
+    row = models[model_key]
+    try:
+        input_per_1m = float(row["input_per_1m"])
+        output_per_1m = float(row["output_per_1m"])
+    except (TypeError, KeyError, ValueError) as exc:
+        raise InvalidArguments(f"Invalid pricing entry for model: {model_key}") from exc
+
+    return ModelPrice(input_per_1m=input_per_1m, output_per_1m=output_per_1m)

agentcap-0.1.0/agentcap/token_estimator.py

@@ -0,0 +1,6 @@
+from math import ceil
+
+def estimate_tokens(text: str) -> int:
+    if not text:
+        return 0
+    return ceil(len(text) / 4) + 30

agentcap-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentcap"
+version = "0.1.0"
+description = "Cost guardrails for LLM agent runs."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Oliver Iida" }
+]
+keywords = ["llm", "agents", "cost-control", "openai", "anthropic", "gemini"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/OliverIida/agentcap"
+
+[tool.hatch.build]
+include = [
+  "agentcap/**",
+  "README.md",
+  "LICENSE",
+]