tknops-llm 0.0.2

Precise Token Tracking SDK for tknOps

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

pip install tknops-llm

Usage

Initialization

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.

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.

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:

# 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:

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