llm-cost-guard 0.1.0__tar.gz

llm_cost_guard-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.10', '3.11', '3.12']
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev]"
+    
+    - name: Lint with ruff
+      run: ruff check llm_cost_guard/
+    
+    - name: Type check with mypy
+      run: mypy llm_cost_guard/ --ignore-missing-imports
+      continue-on-error: true
+    
+    - name: Security check with bandit
+      run: bandit -r llm_cost_guard/ -ll
+      continue-on-error: true
+    
+    - name: Run tests
+      run: pytest tests/ -v --cov=llm_cost_guard --cov-report=xml
+    
+    - name: Upload coverage
+      uses: codecov/codecov-action@v4
+      if: matrix.python-version == '3.11'
+      with:
+        files: coverage.xml
+        fail_ci_if_error: false
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+    
+    - name: Install build tools
+      run: pip install build
+    
+    - name: Build package
+      run: python -m build
+    
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist
+        path: dist/

llm_cost_guard-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.10', '3.11', '3.12']
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev]"
+    
+    - name: Run tests
+      run: pytest tests/ -v --cov=llm_cost_guard
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+    
+    - name: Install build tools
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+    
+    - name: Build package
+      run: python -m build
+    
+    - name: Publish to PyPI
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: twine upload dist/*

llm_cost_guard-0.1.0/.gitignore

@@ -0,0 +1,82 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# 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/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db

llm_cost_guard-0.1.0/LICENSE

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

llm_cost_guard-0.1.0/PKG-INFO

@@ -0,0 +1,357 @@
+Metadata-Version: 2.4
+Name: llm-cost-guard
+Version: 0.1.0
+Summary: Real-time cost tracking, budget enforcement, and usage analytics for LLM applications
+Project-URL: Homepage, https://github.com/prashantdudami/llm-cost-guard
+Project-URL: Documentation, https://github.com/prashantdudami/llm-cost-guard#readme
+Project-URL: Repository, https://github.com/prashantdudami/llm-cost-guard
+Project-URL: Issues, https://github.com/prashantdudami/llm-cost-guard/issues
+Author: Prashant Dudami
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anthropic,bedrock,budget,cost-tracking,langchain,llm,openai
+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
+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
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tiktoken>=0.5.0
+Provides-Extra: all
+Requires-Dist: anthropic>=0.18.0; extra == 'all'
+Requires-Dist: boto3>=1.28.0; extra == 'all'
+Requires-Dist: langchain-core>=0.1.0; extra == 'all'
+Requires-Dist: langchain>=0.1.0; extra == 'all'
+Requires-Dist: opentelemetry-api>=1.20.0; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'all'
+Requires-Dist: prometheus-client>=0.17.0; extra == 'all'
+Requires-Dist: redis>=4.5.0; extra == 'all'
+Requires-Dist: sqlalchemy>=2.0.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.18.0; extra == 'anthropic'
+Provides-Extra: bedrock
+Requires-Dist: boto3>=1.28.0; extra == 'bedrock'
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7.0; extra == 'dev'
+Requires-Dist: moto>=4.2.0; extra == 'dev'
+Requires-Dist: mypy>=1.5.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
+Requires-Dist: langchain>=0.1.0; extra == 'langchain'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20.0; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'otel'
+Provides-Extra: prometheus
+Requires-Dist: prometheus-client>=0.17.0; extra == 'prometheus'
+Provides-Extra: redis
+Requires-Dist: redis>=4.5.0; extra == 'redis'
+Provides-Extra: sql
+Requires-Dist: sqlalchemy>=2.0.0; extra == 'sql'
+Description-Content-Type: text/markdown
+
+# LLM Cost Guard
+
+[![PyPI version](https://badge.fury.io/py/llm-cost-guard.svg)](https://badge.fury.io/py/llm-cost-guard)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Real-time cost tracking, budget enforcement, and usage analytics for LLM applications. Supports OpenAI, Anthropic, AWS Bedrock, and more.
+
+## Features
+
+- **Real-time Cost Tracking**: Track costs as they happen, not when the bill arrives
+- **Budget Enforcement**: Set limits with configurable actions (warn, throttle, block)
+- **Multi-Provider Support**: OpenAI, Anthropic, AWS Bedrock, Google Vertex AI
+- **LangChain Integration**: Native callback support for LangChain applications
+- **Rate Limiting**: Control request rates per model, provider, or custom tags
+- **Hierarchical Tracking**: Group related LLM calls with spans
+- **Flexible Storage**: In-memory, SQLite, PostgreSQL, Redis, DynamoDB backends
+- **Zero External Dependencies**: Works offline with no external services required
+
+## Installation
+
+```bash
+pip install llm-cost-guard
+```
+
+With optional integrations:
+
+```bash
+# LangChain support
+pip install llm-cost-guard[langchain]
+
+# AWS Bedrock support
+pip install llm-cost-guard[bedrock]
+
+# All optional dependencies
+pip install llm-cost-guard[all]
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from llm_cost_guard import CostTracker
+
+tracker = CostTracker()
+
+# Decorator-based tracking
+@tracker.track
+def my_llm_call():
+    response = openai.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": "Hello!"}]
+    )
+    return response
+
+result = my_llm_call()
+
+# Check costs
+print(tracker.last_call().total_cost)  # $0.0015
+```
+
+### With Budget Enforcement
+
+```python
+from llm_cost_guard import CostTracker, Budget, BudgetAction
+
+tracker = CostTracker(
+    budgets=[
+        Budget(
+            name="daily",
+            limit=10.00,
+            period="day",
+            action=BudgetAction.WARN
+        ),
+        Budget(
+            name="monthly",
+            limit=500.00,
+            period="month",
+            action=BudgetAction.BLOCK
+        ),
+    ]
+)
+
+# Get notified when approaching limits
+@tracker.on_budget_warning
+def handle_warning(budget, current):
+    print(f"Warning: Budget '{budget.name}' at {current/budget.limit*100:.0f}%")
+
+@tracker.on_budget_exceeded
+def handle_exceeded(budget):
+    print(f"Budget '{budget.name}' exceeded!")
+```
+
+### Manual Recording
+
+```python
+# For custom integrations
+record = tracker.record(
+    provider="openai",
+    model="gpt-4o",
+    input_tokens=1234,
+    output_tokens=567,
+    tags={"team": "search", "feature": "autocomplete"}
+)
+
+print(record.total_cost)  # $0.0208
+```
+
+### Wrapped Clients
+
+```python
+from llm_cost_guard import CostTracker
+from llm_cost_guard.clients import TrackedOpenAI
+
+tracker = CostTracker()
+client = TrackedOpenAI(tracker=tracker)
+
+# Automatic tracking - no decorators needed
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+```
+
+### LangChain Integration
+
+```python
+from llm_cost_guard import CostTracker
+from llm_cost_guard.integrations.langchain import CostTrackingCallback
+
+tracker = CostTracker()
+
+llm = ChatOpenAI(
+    model="gpt-4o",
+    callbacks=[CostTrackingCallback(tracker)]
+)
+
+result = llm.invoke("Hello!")
+print(tracker.last_call().total_cost)
+```
+
+### Hierarchical Tracking (Spans)
+
+```python
+# Track costs for complex operations like agents
+with tracker.span("customer_support_agent", tags={"user_id": "123"}) as span:
+    result = agent.invoke(query)
+    
+    print(span.total_cost)      # $0.45 (sum of all calls)
+    print(span.call_count)      # 5
+    print(span.models_used)     # ["gpt-4o", "gpt-3.5-turbo"]
+```
+
+## Configuration
+
+### Storage Backends
+
+```python
+# In-memory (default, development)
+tracker = CostTracker(backend="memory")
+
+# SQLite (single-machine persistence)
+tracker = CostTracker(backend="sqlite:///costs.db")
+
+# PostgreSQL (production)
+tracker = CostTracker(backend="postgresql://user:pass@host/db")
+
+# Redis (distributed, real-time)
+tracker = CostTracker(backend="redis://localhost:6379/0")
+```
+
+### Rate Limiting
+
+```python
+from llm_cost_guard import CostTracker, RateLimit
+
+tracker = CostTracker(
+    rate_limits=[
+        RateLimit(
+            name="requests-per-minute",
+            limit=100,
+            period="minute",
+            scope="global"
+        ),
+        RateLimit(
+            name="user-requests",
+            limit=10,
+            period="minute",
+            scope="tag:user_id"
+        )
+    ]
+)
+```
+
+### Fail-Safe Modes
+
+```python
+tracker = CostTracker(
+    # Block LLM calls if tracking fails (strict)
+    on_tracking_failure="block",
+    
+    # Allow LLM calls but log warning (available)
+    # on_tracking_failure="allow",
+    
+    # Use in-memory fallback temporarily
+    # on_tracking_failure="fallback",
+)
+```
+
+## CLI
+
+```bash
+# View current costs
+llm-cost-guard status
+
+# Generate report
+llm-cost-guard report --period day --group-by model
+
+# Check health
+llm-cost-guard health
+
+# List supported models and pricing
+llm-cost-guard models --provider openai
+
+# Export data
+llm-cost-guard export --format csv --output costs.csv
+```
+
+## Supported Providers
+
+| Provider | Models |
+|----------|--------|
+| OpenAI | GPT-4o, GPT-4, GPT-3.5, o1, Embeddings, DALL-E |
+| Anthropic | Claude 3.5, Claude 3, Claude 2 |
+| AWS Bedrock | Claude, Titan, Llama, Mistral, Cohere |
+| Google Vertex AI | Gemini 1.5, Gemini 1.0, PaLM 2 |
+
+## Reporting
+
+```python
+# Daily summary
+tracker.daily_report()
+
+# Cost by model
+tracker.report_by_model(period="week")
+
+# Query with filters
+report = tracker.get_costs(
+    start_date="2024-01-01",
+    end_date="2024-01-31",
+    tags={"team": "search"},
+    group_by=["model", "feature"]
+)
+
+# Export to DataFrame
+df = tracker.to_dataframe()
+```
+
+## Security
+
+- **No API key logging**: Keys are never stored, logged, or transmitted
+- **No prompt storage by default**: Only metadata (tokens, cost) stored
+- **PII redaction**: Optional redaction for user IDs
+- **Encryption support**: For SQL/Redis backends
+
+```python
+tracker = CostTracker(
+    store_prompts=False,          # Default: never store prompts
+    redact_user_ids=True,         # Hash user IDs in storage
+)
+```
+
+## Custom Pricing
+
+For negotiated enterprise rates:
+
+```python
+tracker = CostTracker(
+    pricing_overrides={
+        "openai/gpt-4": {
+            "input_cost_per_1k": 0.02,    # Your negotiated rate
+            "output_cost_per_1k": 0.04,
+        }
+    }
+)
+```
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines and submit pull requests.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.