Metadata-Version: 2.4
Name: tknops-llm
Version: 0.0.2
Summary: Precise Token Tracking SDK for tknOps
Project-URL: Homepage, https://tknops.io
Project-URL: Documentation, https://docs.tknops.io
Author-email: tknOps <sujith@tknops.io>
License-File: LICENSE
Requires-Python: >=3.8
Requires-Dist: requests>=2.25.0
Description-Content-Type: text/markdown

# tknOps LLM Analytics SDK

The Python SDK for **tknOps**, an open-source AI cost and usage analytics platform.

## Features

- **Automatic Usage Tracking**: Capture token usage, cost, and latency.
- **Privacy-First**: Prompt and response content are **NOT** stored by default.
- **Cost Calculation**: Built-in pricing registry for common models (OpenAI, Anthropic).
- **Environment Tagging**: Tag events as `prod`, `dev`, or `staging`.
- **Framework Support**: Automatic extraction for OpenAI and LangChain response objects.

## Installation

```bash
pip install tknops-llm
```

## Usage

### Initialization

```python
from tknops_llm.client import AIAnalytics

client = AIAnalytics(
    api_key="your_api_key_here",
    environment="prod", # Optional: "prod", "dev", "staging". Default: "prod"
    collect_content=False # Optional: Set to True to collect prompt/response text. Default: False
)
```

### 1. Automatic Tracking (OpenAI / LangChain)

Use `track_response` to automatically extract metrics and **calculate costs** from response objects.

```python
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o", ...)
response = llm.invoke("Hello world!")

# Automatically extracts tokens and calculates cost based on model name
client.track_response(
    response=response,
    user_id="user-123",
    response_type="langchain", # "openai" or "langchain"
    tags=["chatbot", "customer-service"]
)
```

### 2. Manual Tracking

If you are using a custom model or provider, you can track events manually.

```python
client.track(
    user_id="user-123",
    model="llama-3-8b",
    provider="together-ai",
    input_tokens=150,
    output_tokens=50,
    cost_usd=0.0002, # Optional: Calculated by you
    latency_ms=450,
    tags=["custom-model"]
)
```

### 3. Content Collection (Privacy)

By default, the SDK **does not** send the prompt or response text to the server. To enable content debugging:

```python
# Initialize with collection enabled
client = AIAnalytics(..., collect_content=True)

# OR pass it explicitly in manual track (only if initialized with True)
client.track(..., prompt_text="My prompt", response_text="My response")
```

## Configuration

| Parameter | Description | Default |
|Params|---|---|
| `api_key` | Your Project API Key | Required |
| `environment` | Environment tag (e.g. prod, dev) | "prod" |
| `collect_content` | If True, sends text content to server. | `False` |

#### Comparison: Development vs Production

During local development, you can point the SDK to your local API instance without changing code by setting the environment variable:

```bash
export TKNOPS_API_URL="http://localhost:8000"
```
