Metadata-Version: 2.4
Name: llm-usage-framework
Version: 0.1.0
Summary: Generic LLM usage and observability framework
Author: LLM Usage Framework Contributors
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: ollama
Requires-Dist: httpx>=0.27; extra == "ollama"
Provides-Extra: tiktoken
Requires-Dist: tiktoken>=0.14; extra == "tiktoken"
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30; extra == "anthropic"
Provides-Extra: gemini
Requires-Dist: google-genai>=1.0; extra == "gemini"
Provides-Extra: bedrock
Requires-Dist: boto3>=1.34; extra == "bedrock"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-mock>=3.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"

# LLM Usage Framework

A generic, provider-independent Python framework for tracking LLM usage.

The framework provides a common interface for executing LLM requests and collecting standardized usage telemetry across different LLM providers.

The framework is **storage-agnostic**. It does not create database tables, manage databases, or require a specific persistence technology.

Applications consuming the package decide how usage data should be stored or exported.

---

## Features

The framework captures:

- Input tokens
- Output tokens
- Total tokens
- Input character count
- Output character count
- Token source
- Provider
- Model
- Request ID
- Session ID
- Latency
- Project
- Service
- Feature
- Custom metadata

Additional capabilities include:

- Generic provider interface
- Provider registry
- Lazy provider loading
- Optional tokenizer support
- Token counting fallback
- Character-based token estimation
- Usage callback
- Provider-specific adapters
- Provider exceptions are propagated to the consuming application
- No persistence dependency

---

## Supported Providers

| Provider | Status | Optional Dependency |
|---|---|---|
| Ollama | Supported | `httpx` |
| OpenAI | Supported | `openai` |
| Anthropic | Supported | `anthropic` |
| Gemini | Planned | `google-genai` |
| AWS Bedrock | Planned | `boto3` |

Providers are implemented as adapters behind the same generic `LLMTracker` interface.

---

## Architecture

```text
Application
     |
     v
LLMTracker
     |
     v
Provider Registry
     |
     v
Provider Adapter
     |
     +---- Ollama
     +---- OpenAI
     +---- Anthropic
     +---- Gemini
     +---- Bedrock
     |
     v
Standardized LLMResponse
     |
     +---- Application Database
     +---- Kafka
     +---- Prometheus
     +---- Logging
     +---- Other Systems
