### Install openwebui-token-tracking

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/README.md

Install the library using pip.

```bash
pip install openwebui-token-tracking
```

--------------------------------

### Install Dependencies and Build Docs

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/README.md

Installs necessary packages for documentation and builds the HTML documentation locally using Sphinx.

```bash
pip install -e ".[docs]"
sphinx-build -b html docs/source/ docs/build/html
```

--------------------------------

### Example: Run Database Migrations

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/cli-reference.md

Executes the database migration command.

```bash
owui-token-tracking database migrate
```

--------------------------------

### Install Documentation Dependencies

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/docs/source/readme.md

Installs the necessary packages to build the documentation locally.

```bash
pip install -e ".[docs]"
```

--------------------------------

### Example: Get and Print Sponsored Allowance Details

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/types.md

Demonstrates how to retrieve a sponsored allowance by name and print its daily and total credit limits. Requires importing `get_sponsored_allowance`.

```python
from openwebui_token_tracking.sponsored import get_sponsored_allowance

allowance = get_sponsored_allowance(name="AI Department GPT-4 Grant")
print(f"Daily limit: {allowance['daily_credit_limit']} per user")
print(f"Total limit: {allowance['total_credit_limit']} overall")
```

--------------------------------

### Example Output of Credit Balance Action

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/credit-balance-action.md

This is an example of the output message displayed to the user after the credit balance action is executed. It shows the remaining daily credits and the time until the next reset.

```text
Remaining daily credits: 3450 / 5000 (resets in 15:30:45)
```

--------------------------------

### Complete System Setup CLI Commands

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/cli-reference.md

Initialize the database, create credit groups, add users, set up sponsored allowances, and adjust base credit allowances.

```bash
# 1. Initialize database and defaults
owui-token-tracking init

# 2. Create credit groups
owui-token-tracking credit-group create "Power Users" 5000 "Advanced users"
owui-token-tracking credit-group create "Researchers" 10000 "Research team"

# 3. Add users to groups
owui-token-tracking credit-group add-user user123 "Power Users"
owui-token-tracking credit-group add-user user456 "Researchers"

# 4. Create sponsored allowance
owui-token-tracking sponsored create "AI Dept" "ai-dept" 100000 2000 gpt-4-turbo gpt-4o

# 5. Update base allowance if needed
owui-token-tracking settings set base_credit_allowance 2000 "Updated baseline"
```

--------------------------------

### Manage Settings via CLI

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/settings-utilities.md

Provides examples of using the `owui-token-tracking` CLI to initialize settings, set specific values, retrieve a setting, and list all available settings.

```bash
# Initialize with defaults
owui-token-tracking init

# Set a specific setting
owui-token-tracking settings set base_credit_allowance 5000 \
    "Baseline credit allowance for all users"

# Get a specific setting
owui-token-tracking settings get base_credit_allowance

# List all settings
owui-token-tracking settings list
```

--------------------------------

### Example Concrete Implementation of BaseTrackedPipe

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/base-tracked-pipe.md

Provides an example of how to implement a concrete tracked pipe. This includes setting up configuration, defining request headers, formatting the payload, and logging token usage after a request.

```python
from openwebui_token_tracking.pipes.base_tracked_pipe import BaseTrackedPipe
from pydantic import BaseModel, Field
import os

class MyTrackedPipe(BaseTrackedPipe):
    class Valves(BaseModel):
        API_KEY: str = Field(default="", description="API key")
        API_BASE_URL: str = Field(default="https://api.example.com", description="API base URL")

    def __init__(self):
        super().__init__(provider="myprovider", url="https://api.example.com")
        self.valves = self.Valves(**{"API_KEY": os.getenv("MY_API_KEY", "")})

    def _headers(self) -> dict:
        return {
            "Authorization": f"Bearer {self.valves.API_KEY}",
            "content-type": "application/json"
        }

    def _payload(self, model_id: str, body: dict) -> dict:
        return {**body, "model": model_id}

    def pipe(self, body: dict, user: dict, model_id: str, **kwargs):
        # Check limits
        if not self._check_limits(model_id, user):
            raise Exception("Credit limit exceeded")
        
        # Make request, get response
        prompt_tokens = 100
        response_tokens = 50
        
        # Log usage
        self.token_tracker.log_token_usage(
            provider=self.provider,
            model_id=model_id,
            user=user,
            prompt_tokens=prompt_tokens,
            response_tokens=response_tokens
        )
        
        return response_data
```

--------------------------------

### Example User Object Usage

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/types.md

Demonstrates how to use a typical user object from Open WebUI with the TokenTracker to check remaining credits.

```python
# Typical user object from Open WebUI
user = {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "alice",
    "email": "alice@example.com"
}

tracker = TokenTracker(db_url)
remaining, _ = tracker.remaining_credits(user)
```

--------------------------------

### Example: List Model Pricing by Provider

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/types.md

Shows how to fetch model pricing for a specific provider from a database and iterate through the results to print model IDs and their input costs. Requires importing `get_model_pricing`.

```python
from openwebui_token_tracking.model_pricing import get_model_pricing

pricing = get_model_pricing(
    database_url="postgresql://...",
    provider="openai"
)
for model in pricing:
    print(f"{model['id']}: {model['input_cost_credits']} credits per {model['per_input_tokens']} input tokens")
```

--------------------------------

### Development Setup for Settings

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/settings-utilities.md

Configures base settings for a development environment with a high credit allowance for testing purposes. Uses a local SQLite database.

```python
init_base_settings(
    database_url="sqlite:////tmp/openwebui.db",
    settings=[
        {
            "setting_key": "base_credit_allowance",
            "setting_value": "100000",  # High for testing
            "description": "Dev: High allowance for testing"
        }
    ]
)
```

--------------------------------

### Get a specific setting

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/cli-reference.md

Retrieves the value of a particular system setting using its key.

```bash
owui-token-tracking settings get base_credit_allowance
```

--------------------------------

### Production Setup for Settings

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/settings-utilities.md

Sets up base settings for a production environment, using environment variables for the database URL and a standard credit allowance. This configuration is suitable for live user environments.

```python
init_base_settings(
    database_url=os.getenv("DATABASE_URL"),
    settings=[
        {
            "setting_key": "base_credit_allowance",
            "setting_value": "1000",  # 1 USD equivalent
            "description": "Production baseline: 1 USD per user per day"
        }
    ]
)
```

--------------------------------

### Database Connection URL Example

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/configuration.md

Specifies the SQLAlchemy-format database connection URL. This is required for TokenTracker, BaseTrackedPipe, and most functions.

```bash
DATABASE_URL=postgresql://user:password@host:port/database
```

```bash
postgresql://openwebui:secretpass@localhost:5432/openwebui
```

```bash
sqlite:////data/openwebui.db
```

```bash
mysql+pymysql://user:pass@localhost/openwebui
```

--------------------------------

### Instantiate and Use ModelPricingSchema

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/types.md

Example of creating an instance of ModelPricingSchema, accessing its fields, and converting it to a dictionary. This demonstrates how to work with model pricing data.

```python
from openwebui_token_tracking.models import ModelPricingSchema

schema = ModelPricingSchema(
    provider="openai",
    id="gpt-4-turbo",
    name="GPT-4 Turbo",
    input_cost_credits=3000,
    per_input_tokens=1000000,
    output_cost_credits=6000,
    per_output_tokens=1000000
)

# Access fields
print(f"{schema.provider}: {schema.id}")
print(f"Input cost: {schema.input_cost_credits} credits per {schema.per_input_tokens} tokens")

# Convert to dict
data = schema.model_dump()
```

--------------------------------

### Example CreditGroup Retrieval

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/types.md

Shows how to retrieve a credit group by name and access its properties like name and max_credit.

```python
from openwebui_token_tracking.credit_groups import get_credit_group

group = get_credit_group("Power Users")
print(f"{group['name']}: {group['max_credit']} credits per member")
```

--------------------------------

### Setup CreditBalance Action in Open WebUI

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/credit-balance-action.md

Configure the CreditBalance action within Open WebUI by creating a new Action with the provided Python code. Ensure the 'openwebui-token-tracking' requirement is met.

```python
"""
title: Show credit balance
author: Simon Stone
requirements: openwebui-token-tracking
version: 0.0.1
icon_url: data:image/svg+xml;base64,[ICON_DATA]
"""

from openwebui_token_tracking.actions.credit_balance import CreditBalance

Action = CreditBalance
```

--------------------------------

### TokenTracker Usage with Default Settings

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/settings-utilities.md

Demonstrates how to use the `TokenTracker` to get maximum daily credits, which internally incorporates the `base_credit_allowance` and group allowances. Requires database URL for initialization.

```python
from openwebui_token_tracking import TokenTracker

tracker = TokenTracker(db_url)
user = {"id": "user123"}

# max_credits internally queries base_credit_allowance
max_daily = tracker.max_credits(user)  # Includes base_credit_allowance + group allowances
remaining = tracker.remaining_credits(user)  # Based on max_daily
```

--------------------------------

### Usage of OpenAITrackedPipe in Open WebUI

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/pipe-implementations.md

Example of how to integrate the OpenAITrackedPipe into Open WebUI by defining it as a Pipe.

```python
"""
title: OpenAI Pipe
author: Your Name
requirements: openwebui-token-tracking
version: 0.1.0
"""

from openwebui_token_tracking.pipes.openai import OpenAITrackedPipe

Pipe = OpenAITrackedPipe
```

--------------------------------

### Get All and Filtered Models

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/token-tracker.md

Retrieve available AI models and their pricing. You can fetch all models or filter them by a specific provider.

```python
# Get all models
all_models = tracker.get_models()

# Get models from specific provider
openai_models = tracker.get_models(provider="openai")

# Iterate through models
for model in all_models:
    print(f"{model.provider}: {model.id} - {model.name}")
```

--------------------------------

### Research Team Setup with Credit Group

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/settings-utilities.md

Initializes base settings for a research team and creates a dedicated credit group with an additional allowance. Requires a database URL to be defined.

```python
init_base_settings(
    database_url=db_url,
    settings=[
        {
            "setting_key": "base_credit_allowance",
            "setting_value": "5000",
            "description": "Base allowance for all researchers"
        }
    ]
)

# Then add research team to a credit group with additional allowance
from openwebui_token_tracking.credit_groups import create_credit_group

create_credit_group(
    credit_group_name="Research Team",
    credit_allowance=10000,  # Additional 10 USD
    description="Additional budget for research projects",
    database_url=db_url
)
```

--------------------------------

### Usage of MistralTrackedPipe in Open WebUI

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/pipe-implementations.md

Example of how to integrate the MistralTrackedPipe into Open WebUI by defining it as a Pipe. Requires MISTRAL_API_KEY and API_BASE_URL valves.

```python
"""
title: Mistral Pipe
author: Your Name
requirements: openwebui-token-tracking
version: 0.1.0
"""

from openwebui_token_tracking.pipes.mistral import MistralTrackedPipe

Pipe = MistralTrackedPipe
```

--------------------------------

### Add model pricing

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/cli-reference.md

Adds pricing for a new model. This is typically used for additional models not included during initial setup.

```bash
owui-token-tracking pricing add PROVIDER MODEL_ID NAME \
    --input-cost INT \
    --per-input-tokens INT \
    --output-cost INT \
    --per-output-tokens INT \
    [OPTIONS]
```

--------------------------------

### Export Provider API Keys

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/configuration.md

Examples of exporting environment variables for provider-specific API keys. These are used by pipe implementations to load API keys.

```bash
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
```

--------------------------------

### Set Database URL Environment Variable

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/credit-balance-action.md

The DATABASE_URL environment variable must be set in Open WebUI for the action to function. This example shows the required format.

```bash
DATABASE_URL=postgresql://user:pass@localhost/openwebui
```

--------------------------------

### Check Token Limits Example

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/base-tracked-pipe.md

Demonstrates how to use `_check_limits` to enforce daily token limits before processing a request. This method should be called before making an API call to ensure the user is within their allowed usage.

```python
class MyTrackedPipe(BaseTrackedPipe):
    def pipe(self, body: dict, user: dict, ...):
        if not self._check_limits("gpt-4", user):
            raise DailyTokenLimitExceededError()
        # Continue with request...
```

--------------------------------

### Initialize with Defaults

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/cli-reference.md

Initializes the token tracking system using default configurations and the DATABASE_URL environment variable.

```bash
# Initialize with defaults
DATABASE_URL="postgresql://localhost/openwebui" owui-token-tracking init
```

--------------------------------

### Initialize with Custom Pricing and Settings

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/cli-reference.md

Initializes the token tracking system with custom model pricing and settings JSON files.

```bash
owui-token-tracking \
    --database-url postgresql://localhost/openwebui \
    --model-json ./models.json \
    --settings-json ./settings.json
```

--------------------------------

### List all system settings

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/cli-reference.md

Lists all available system settings.

```bash
owui-token-tracking settings list [OPTIONS]
```

--------------------------------

### credit-group get

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/cli-reference.md

Retrieves and displays the details of a specific credit group by its name.

```APIDOC
## credit-group get

### Description
Retrieves and displays the details of a specific credit group by its name.

### Method
CLI COMMAND

### Endpoint
credit-group get NAME

### Parameters
#### Arguments
- **NAME** (TEXT) - Required - Name of the credit group

### Request Example
```bash
owui-token-tracking credit-group get "Power Users"
```

### Response
#### Success Response
- **Group** (TEXT) - Name of the credit group
- **ID** (TEXT) - Unique identifier for the group
- **Max Credit** (INTEGER) - Maximum daily credits allowed
- **Description** (TEXT) - Description of the group
- **Members** (INTEGER) - Number of users in the group

### Response Example
```
Group: Power Users
ID: 550e8400-e29b-41d4-a716-446655440001
Max Credit: 5000
Description: Additional credits for power users
Members: 12
```
```

--------------------------------

### Initialize Database with Defaults

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/INDEX.md

Initializes the database with default settings using the provided PostgreSQL connection URL. Ensure the database is accessible before running.

```python
from openwebui_token_tracking.db import migrate_database
migrate_database("postgresql://user:pass@localhost/openwebui")
```

--------------------------------

### Get a specific sponsored allowance

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/cli-reference.md

Retrieves the details of a specific sponsored allowance by its name.

```bash
owui-token-tracking sponsored get NAME [OPTIONS]
```

--------------------------------

### Usage of AnthropicTrackedPipe in Open WebUI

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/pipe-implementations.md

Example of how to integrate the AnthropicTrackedPipe into Open WebUI by defining it as a Pipe.

```python
"""
title: Anthropic Pipe
author: Your Name
requirements: openwebui-token-tracking
version: 0.1.0
"""

from openwebui_token_tracking.pipes.anthropic import AnthropicTrackedPipe

Pipe = AnthropicTrackedPipe
```

--------------------------------

### Command: Initialize Token Tracking System

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/cli-reference.md

Initializes the token tracking system with database migrations and default settings.

```bash
owui-token-tracking init [OPTIONS]
```

--------------------------------

### Initialize CLI with Custom Settings

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/configuration.md

Use this command to initialize the token tracking CLI with custom database, model, and settings configurations.

```bash
owui-token-tracking init \
    --database-url postgresql://user:pass@localhost/openwebui \
    --model-json /path/to/models.json \
    --settings-json /path/to/settings.json
```

--------------------------------

### Build Documentation Locally

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/docs/source/readme.md

Builds the HTML documentation from the source files.

```bash
sphinx-build -b html docs/source/ docs/build/html
```

--------------------------------

### Get All Sponsored Allowances

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/sponsored-allowances.md

Retrieve a list of all sponsored allowances. Optionally, filter the results by providing a sponsor ID.

```python
# Get all allowances
all_allowances = get_sponsored_allowances()

# Get allowances from specific sponsor
ai_dept_allowances = get_sponsored_allowances(sponsor_id="ai-dept-001")
for allowance in ai_dept_allowances:
    print(f"{allowance['name']}: {allowance['daily_credit_limit']} credits/day")
```

--------------------------------

### Initialize Token Tracking System

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/README.md

Initialize the Open WebUI database for token tracking with default settings. This command migrates the database, adds pricing information, and sets a baseline daily credit allowance.

```bash
owui-token-tracking init
```

--------------------------------

### Usage of GoogleGenAITrackedPipe in Open WebUI

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/pipe-implementations.md

Example of how to integrate the GoogleGenAITrackedPipe into Open WebUI by defining it as a Pipe. Requires GOOGLE_API_KEY valve.

```python
"""
title: Google Generative AI Pipe
author: Your Name
requirements: openwebui-token-tracking
version: 0.1.0
"""

from openwebui_token_tracking.pipes.google_genai import GoogleGenAITrackedPipe

Pipe = GoogleGenAITrackedPipe
```

--------------------------------

### Initialize Base Settings with Environment Variables

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/settings-utilities.md

Initializes base settings using environment variables for database URL and credit allowance. Ensure database migration is completed before calling this function.

```python
import os

base_allowance = os.getenv("BASE_CREDIT_ALLOWANCE", "1000")

init_base_settings(
    database_url=os.getenv("DATABASE_URL"),
    settings=[
        {
            "setting_key": "base_credit_allowance",
            "setting_value": base_allowance,
            "description": "Baseline credit allowance for all users"
        }
    ]
)
```

--------------------------------

### remaining_credits

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/token-tracker.md

Gets the remaining daily credits available to a user. Returns both user credits and optionally sponsored allowance credits.

```APIDOC
## remaining_credits

### Description
Gets the remaining daily credits available to a user. Returns both user credits and optionally sponsored allowance credits.

### Parameters
#### Path Parameters
- **user** (dict) - Required - User object with 'id' key
- **sponsored_allowance_name** (str) - Optional - Name of sponsored allowance to check. If None, only returns user daily credits

### Returns
`tuple[int, int]` — (remaining_user_credits, remaining_sponsored_credits). Second value is None if no sponsored allowance specified

### Example
```python
user = {"id": "user123"}

# Check all remaining credits
user_remaining, _ = tracker.remaining_credits(user)
print(f"User has {user_remaining} credits remaining today")

# Check credits with sponsored allowance
user_remaining, sponsored_remaining = tracker.remaining_credits(
    user,
    sponsored_allowance_name="AI Department"
)
print(f"Personal: {user_remaining}, Sponsored: {sponsored_remaining}")
```
```

--------------------------------

### Get Model Pricing

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/model-pricing.md

Retrieves pricing information for AI models. Can filter by a specific model ID and/or provider.

```python
from openwebui_token_tracking.model_pricing import get_model_pricing

# Get pricing for specific model
gpt4_pricing = get_model_pricing(
    database_url="postgresql://user:pass@localhost/openwebui",
    model_id="gpt-4-turbo",
    provider="openai"
)

# Get all OpenAI models
openai_models = get_model_pricing(
    database_url="postgresql://user:pass@localhost/openwebui",
    provider="openai"
)
```

--------------------------------

### Initialize Database Engine

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/database-models.md

Creates and returns a SQLAlchemy database engine. Use this to establish a connection to your database.

```python
from openwebui_token_tracking.db import init_db

engine = init_db("postgresql://user:pass@localhost/openwebui")
```

--------------------------------

### Initialize Base Settings

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/INDEX.md

Initializes the base settings for the system, including a default daily credit allowance per user. Requires a database URL and a list of settings to configure.

```python
from openwebui_token_tracking.settings import init_base_settings
init_base_settings(db_url, settings=[
    {
        "setting_key": "base_credit_allowance",
        "setting_value": "1000",
        "description": "Daily credits per user"
    }
])
```

--------------------------------

### Get Sponsored Allowance by Name

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/sponsored-allowances.md

Retrieve a specific sponsored allowance by its name. The database URL can be provided or will default to the DATABASE_URL environment variable.

```python
allowance = get_sponsored_allowance(name="AI Department GPT-4 Grant")
print(f"Total limit: {allowance['total_credit_limit']}")
print(f"Daily limit per user: {allowance['daily_credit_limit']}")
```

--------------------------------

### Openwebui-token-tracking CLI Entry Point

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/cli-reference.md

The main entry point for the CLI tool, accepting commands and options.

```bash
owui-token-tracking [COMMAND] [OPTIONS]
```

--------------------------------

### Command: Manage Database Migrations

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/cli-reference.md

Manages database migrations and initialization for the token tracking system.

```bash
owui-token-tracking database [SUBCOMMAND] [OPTIONS]
```

--------------------------------

### List all model pricing

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/cli-reference.md

Lists all configured model pricing. Use the --provider option to filter by a specific provider.

```bash
owui-token-tracking pricing list
```

```bash
owui-token-tracking pricing list --provider openai
```

--------------------------------

### Get Remaining User and Sponsored Credits

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/token-tracker.md

Check the remaining daily credits for a user. This can include both the user's personal allowance and credits from a specified sponsored allowance.

```python
user = {"id": "user123"}

# Check all remaining credits
user_remaining, _ = tracker.remaining_credits(user)
print(f"User has {user_remaining} credits remaining today")

# Check credits with sponsored allowance
user_remaining, sponsored_remaining = tracker.remaining_credits(
    user,
    sponsored_allowance_name="AI Department"
)
print(f"Personal: {user_remaining}, Sponsored: {sponsored_remaining}")
```

--------------------------------

### Initialize Base Settings for Token Tracking

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/configuration.md

Initializes the base settings for token tracking, including the database URL and specific settings like daily credit allowance. Use this to programmatically set configurations.

```python
from openwebui_token_tracking.settings import init_base_settings

init_base_settings(
    database_url="postgresql://...",
    settings=[
        {
            "setting_key": "base_credit_allowance",
            "setting_value": "5000",
            "description": "Baseline credit allowance for all users."
        }
    ]
)
```

--------------------------------

### Import init_base_settings

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/settings-utilities.md

Imports the necessary function for initializing base settings.

```python
from openwebui_token_tracking.settings import init_base_settings
```

--------------------------------

### Get details of a specific credit group

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/cli-reference.md

Retrieve detailed information about a credit group by its name. The output includes group ID, max credit, description, and member count.

```bash
owui-token-tracking credit-group get NAME [OPTIONS]
```

```bash
owui-token-tracking credit-group get "Power Users"
```

--------------------------------

### Initialize TokenTracker

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/token-tracker.md

Instantiate the TokenTracker with a SQLAlchemy database connection URL. This is required before using any tracking functionalities.

```python
from openwebui_token_tracking import TokenTracker

tracker = TokenTracker("postgresql://user:password@localhost/openwebui")
models = tracker.get_models()
```

--------------------------------

### Database Migrations and Initialization

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/docs/source/api.md

Functions for migrating and initializing the token tracking database.

```APIDOC
## Database Operations

### Description
Provides functions to manage the database schema and initial setup.

### Functions

- `migrate_database()`: Migrates the database to the latest schema version.
- `init_db()`: Initializes the database with default settings and structures.

### Related Models
- `CreditGroup`
- `CreditGroupUser`
- `ModelPricing`
- `BaseSetting`
- `SponsoredAllowance`
- `SponsoredAllowanceBaseModels`
- `TokenUsageLog`
- `User`
```

--------------------------------

### Implement Custom Tracked Pipe

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/INDEX.md

Example of implementing a custom tracked pipe by inheriting from BaseTrackedPipe. This involves defining valve configurations, headers, and payload structures for custom API interactions.

```python
from openwebui_token_tracking.pipes.base_tracked_pipe import BaseTrackedPipe
from pydantic import BaseModel, Field

class MyTrackedPipe(BaseTrackedPipe):
    class Valves(BaseModel):
        API_KEY: str = Field(default="", description="API key")
        API_BASE_URL: str = Field(default="https://api.example.com")
        DEBUG: bool = Field(default=False)

    def __init__(self):
        super().__init__(provider="myprovider", url="https://api.example.com")
        self.valves = self.Valves()

    def _headers(self) -> dict:
        return {"Authorization": f"Bearer {self.valves.API_KEY}"}

    def _payload(self, model_id: str, body: dict) -> dict:
        return {**body, "model": model_id}

    def pipe(self, body: dict, user: dict, model_id: str, **kwargs):
        # Implementation...
        pass
```

--------------------------------

### Import CreditBalance Action

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/credit-balance-action.md

Import the CreditBalance class from the openwebui_token_tracking.actions.credit_balance module.

```python
from openwebui_token_tracking.actions.credit_balance import CreditBalance
```

--------------------------------

### Import User Utilities

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/user-utilities.md

Import the necessary functions for user management from the openwebui_token_tracking.user module.

```python
from openwebui_token_tracking.user import (
    find_user,
    serialize_user
)
```

--------------------------------

### Import TokenTracker

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/token-tracker.md

Import the TokenTracker class from the openwebui_token_tracking library.

```python
from openwebui_token_tracking import TokenTracker
```

--------------------------------

### Get User's Maximum Daily Credits

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/token-tracker.md

Retrieve the total daily credit allowance for a user, including base and group allowances. Optionally, fetch the limit for a specific sponsored allowance.

```python
user = {"id": "user123", "email": "user@example.com"}

# Get total allowance (base + groups)
total_max = tracker.max_credits(user)
print(f"User can use up to {total_max} credits per day")

# Get allowance for specific sponsored allowance
sponsored_max = tracker.max_credits(user, sponsored_allowance_name="AI Department")
```

--------------------------------

### TokenTracker Constructor

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/token-tracker.md

Initializes the token tracker with a database connection URL. This is the entry point for using the token tracking functionalities.

```APIDOC
## TokenTracker Constructor

### Description
Initializes the token tracker with a database connection URL.

### Parameters
#### Path Parameters
- **db_url** (str) - Required - SQLAlchemy-format database connection URL

### Example
```python
from openwebui_token_tracking import TokenTracker

tracker = TokenTracker("postgresql://user:password@localhost/openwebui")
```
```

--------------------------------

### init_db

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/docs/source/api/db.md

Initialize the database connection and returns a SQLAlchemy database engine.

```APIDOC
## init_db(database_url)

### Description
Initialize the database connection. Creates and returns a SQLAlchemy database engine using the provided connection URL.

### Parameters
#### Path Parameters
- **database_url** (str) - Required - URL for connecting to the database

### Returns
- **engine** (sqlalchemy.engine.Engine) - Configured SQLAlchemy database engine

### Example
```pycon
>>> engine = init_db("postgresql://user:password@localhost/dbname")
```
```

--------------------------------

### Get Users in a Specific Credit Group

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/database-models.md

Lists the ID, name, and email of all users who are members of a credit group identified by its name. This involves joining user, credit group user, and credit group tables.

```sql
SELECT u.id, u.name, u.email
FROM user u
JOIN token_tracking_credit_group_user cgu ON u.id = cgu.user_id
JOIN token_tracking_credit_group cg ON cgu.credit_group_id = cg.id
WHERE cg.name = 'Power Users';
```

--------------------------------

### Create a Credit Group

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/README.md

Create a new credit group using the command-line interface. Provide a name, the number of credits, and a description for the group.

```bash
owui-token-tracking credit-group create "my credit group" 2000 "my credit group granting an additional 2000 credits"
```

--------------------------------

### Handle ValueError in User Removal

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/error-reference.md

This example shows how to catch and manage `ValueError` exceptions that occur during user removal from a credit group, specifically when the user is not a member of the specified group. It also covers other `ValueError` scenarios like invalid update parameters or attempting to delete a group with users without forcing.

```python
from openwebui_token_tracking.credit_groups import remove_user

try:
    remove_user(user_id="user123", credit_group_name="Power Users")
except ValueError as e:
    print(f"Invalid operation: {e}")
```

--------------------------------

### List All Models with Pricing Information

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/database-models.md

Retrieves a comprehensive list of all available models along with their associated pricing details, ordered by provider and model name.

```sql
SELECT provider, id, name, input_cost_credits, per_input_tokens, 
       output_cost_credits, per_output_tokens
FROM token_tracking_model_pricing
ORDER BY provider, name;
```

--------------------------------

### Set a system setting

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/cli-reference.md

Sets or updates a system setting. A description can optionally be provided.

```bash
owui-token-tracking settings set base_credit_allowance 5000 "Baseline credits per user"
```

--------------------------------

### Settings JSON File Format

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/cli-reference.md

Defines the structure for the settings.json file, specifying initial system settings.

```json
[
    {
        "setting_key": "base_credit_allowance",
        "setting_value": "1000",
        "description": "Baseline credit allowance for all users"
    }
]
```

--------------------------------

### Update Settings Programmatically

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/settings-utilities.md

Demonstrates two methods for updating settings: using the `init_base_settings` function with a list of settings, or directly interacting with the database using SQLAlchemy.

```python
# Update via init_base_settings
init_base_settings(
    database_url=db_url,
    settings=[
        {
            "setting_key": "base_credit_allowance",
            "setting_value": "10000",  # New value
            "description": "Updated baseline credit allowance"
        }
    ]
)

# Or update directly via SQLAlchemy
from sqlalchemy.orm import Session
from openwebui_token_tracking.db import init_db, BaseSetting

engine = init_db(db_url)
with Session(engine) as session:
    setting = session.query(BaseSetting)
        .filter(BaseSetting.setting_key == "base_credit_allowance")
        .first())
    
    if setting:
        setting.setting_value = "10000"
        session.commit()
```

--------------------------------

### CLI Commands

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/MANIFEST.txt

Provides comprehensive documentation for over 30 CLI subcommands used for managing the token tracking system, including initialization, database operations, and various management tasks.

```APIDOC
## CLI Commands Reference

### Description
Documentation for the command-line interface tools used to manage the token tracking system.

### Commands
- `init`: Initializes the system.
- `database migrate`: Migrates the database schema.
- `credit-group create|get|list|update|delete|add-user|remove-user|list-users`: Manages credit groups.
- `user find`: Finds user information.
- `pricing list|add|update|delete`: Manages model pricing.
- `settings get|set|list`: Manages system settings.
- `sponsored create|list|get|update|delete`: Manages sponsored allowances.

### Usage Examples
- `openwebui-token-tracking init`
- `openwebui-token-tracking credit-group create --name "Default Group"`
- `openwebui-token-tracking pricing add --model-name "gpt-4" --price-per-token 0.00005`
```

--------------------------------

### Global Option: Database URL

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/cli-reference.md

Specifies the database connection URL. Uses the DATABASE_URL environment variable if not provided.

```bash
--database-url TEXT
    Database connection URL. Uses DATABASE_URL environment variable if not provided.
    Default: Environment variable DATABASE_URL
```

--------------------------------

### Create and Manage Credit Groups

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/INDEX.md

Creates a new credit group with a specified allowance and description, and then adds a user to that group. Requires a database URL.

```python
from openwebui_token_tracking.credit_groups import create_credit_group, add_user

create_credit_group(
    credit_group_name="Power Users",
    credit_allowance=5000,
    description="Advanced users",
    database_url=db_url
)

# Add user to group
add_user(user_id="user123", credit_group_name="Power Users", database_url=db_url)
```

--------------------------------

### Integrate User Data with TokenTracker

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/user-utilities.md

Demonstrates how to find a user, serialize their data, and then format it into a dictionary suitable for use with the TokenTracker. This is a common workflow for tracking user credits.

```python
from openwebui_token_tracking import TokenTracker
from openwebui_token_tracking.user import find_user, serialize_user

db_url = "postgresql://..."

# Find user from database
db_user = find_user(db_url, name="john")
serialized = serialize_user(db_user)

# Create dict for TokenTracker (from Open WebUI typically)
user = {
    "id": serialized['id'],
    "name": serialized['name'],
    "email": serialized['email']
}

# Use with TokenTracker
tracker = TokenTracker(db_url)
remaining_credits, _ = tracker.remaining_credits(user)
print(f"Remaining credits: {remaining_credits}")
```

--------------------------------

### Migrate Database Schema

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/database-models.md

Runs Alembic migrations to set up the token tracking tables in your database. Ensure your database URL is correctly configured.

```python
from openwebui_token_tracking.db import migrate_database

migrate_database("postgresql://user:pass@localhost/openwebui")
```

--------------------------------

### Settings Management

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/docs/source/api.md

Function to initialize base settings for the token tracking system.

```APIDOC
## Settings API

### Description
Manages system-wide settings related to token tracking.

### Functions

- `init_base_settings()`: Initializes the base settings for the token tracking system.
```

--------------------------------

### CreditBalance Constructor

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/credit-balance-action.md

Initializes the CreditBalance action. It sets up default valves and the visibility flag, which is set to True after the first action call.

```python
def __init__(self)

Initializes the action with default valves and visibility flag.

**Attributes:**
- `valves` (Valves): Configuration instance
- `is_visible` (bool): Flag indicating visibility status (set to True after first action call)
```

--------------------------------

### Initialize TokenCount Helper

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/base-tracked-pipe.md

Initializes a helper class for tracking token counts during API requests. It initializes prompt and response token counters to zero.

```python
class TokenCount:
    """Helper class for tracking token counts during requests"""
    
    def __init__(self):
        self.prompt_tokens = 0        # Input tokens
        self.response_tokens = 0      # Output tokens
```

--------------------------------

### List Model Pricing Information

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/INDEX.md

Retrieves and lists the pricing information for all available models. Requires a database URL.

```python
from openwebui_token_tracking.model_pricing import list_model_pricing

models = list_model_pricing(database_url=db_url)
for model in models:
    print(f"{model['provider']}: {model['id']} - {model['name']}")
```

--------------------------------

### init_base_settings

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/docs/source/api/settings.md

Initializes the base settings table with default values. This function is crucial for setting up the initial configuration of the system.

```APIDOC
## init_base_settings(database_url, settings=None)

### Description
Initializes the base settings table with default values.

### Parameters
#### Path Parameters
* **database_url** (str) - Required - A database URL in [SQLAlchemy format](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls)

#### Query Parameters
* **settings** (list[dict[str, str]]) - Optional - A list of dictionaries of settings to use. If None, uses default settings.
```

--------------------------------

### init_base_settings

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/settings-utilities.md

Initializes or updates base settings in the database using upsert semantics. It can create new settings or update existing ones. If no settings are provided, it defaults to initializing the 'base_credit_allowance'.

```APIDOC
## init_base_settings

### Description
Initializes or updates base settings in the database. Uses upsert semantics to create new settings or update existing ones. If `settings` is None, it uses the default `base_credit_allowance` setting.

### Method
```python
def init_base_settings(
    database_url: str,
    settings: list[dict[str, str]] | None = None
) -> None
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **database_url** (str) - Required - Database connection URL.
- **settings** (list[dict[str, str]] | None) - Optional - List of setting dictionaries. Each dictionary should have `setting_key`, `setting_value`, and `description`. If None, uses default `base_credit_allowance` setting.

### Request Example
```python
from openwebui_token_tracking.settings import init_base_settings

db_url = "postgresql://user:pass@localhost/openwebui"

# Initialize with default settings
init_base_settings(db_url)

# Initialize with custom settings
init_base_settings(
    database_url=db_url,
    settings=[
        {
            "setting_key": "base_credit_allowance",
            "setting_value": "5000",
            "description": "Baseline credit allowance for all users"
        },
        {
            "setting_key": "max_models_per_day",
            "setting_value": "10",
            "description": "Maximum number of different models a user can access per day"
        }
    ]
)
```

### Response
#### Success Response
None

#### Response Example
None

### Raises
None (SQLAlchemy exceptions propagated)
```

--------------------------------

### List and Update Model Pricing

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/configuration.md

Commands for viewing all model pricing, filtering by provider, and updating specific model costs and token rates.

```bash
# List all model pricing
owui-token-tracking pricing list

# List by provider
owui-token-tracking pricing list --provider openai

# Update model pricing
owui-token-tracking pricing update openai gpt-4-turbo \
    --input-cost 3500 \
    --per-input-tokens 1000000 \
    --output-cost 7000 \
    --per-output-tokens 1000000
```

--------------------------------

### migrate_database

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/docs/source/api/db.md

Creates the tables required for token tracking in the specified database.

```APIDOC
## migrate_database(database_url)

### Description
Creates the tables required for token tracking in the specified database.

### Parameters
#### Path Parameters
- **database_url** (str) - Required - A database URL in [SQLAlchemy format](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls)
```

--------------------------------

### Import Sponsored Allowance Functions

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/sponsored-allowances.md

Import all necessary functions for managing sponsored allowances from the openwebui_token_tracking.sponsored module.

```python
from openwebui_token_tracking.sponsored import (
    create_sponsored_allowance,
    get_sponsored_allowance,
    get_sponsored_allowances,
    update_sponsored_allowance,
    delete_sponsored_allowance
)
```

--------------------------------

### Manage Credit Groups

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/configuration.md

Commands for creating, adding users to, and listing credit groups. Ensure user IDs are correct when adding users.

```bash
# Create credit group
owui-token-tracking credit-group create "Power Users" 2000 "Additional credits"

# Add user to group
owui-token-tracking credit-group add-user user_id "Power Users"

# List groups
owui-token-tracking credit-group list
```

--------------------------------

### Create Sponsored Allowance

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/INDEX.md

Creates a sponsored allowance for users, defining models, total credit limits, and daily credit limits. Requires a database URL.

```python
from openwebui_token_tracking.sponsored import create_sponsored_allowance

create_sponsored_allowance(
    database_url=db_url,
    sponsor_id="ai-dept",
    name="AI Department GPT-4 Grant",
    models=["gpt-4-turbo", "gpt-4o"],
    total_credit_limit=100000,
    daily_credit_limit=2000
)
```

--------------------------------

### Adjust Pricing CLI Commands

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/cli-reference.md

Commands to list current pricing for a provider and update pricing for a specific model.

```bash
# List current pricing
owui-token-tracking pricing list --provider openai

# Update if model costs change
owui-token-tracking pricing update openai gpt-4-turbo \
    --input-cost 3000 \
    --output-cost 6000
```

--------------------------------

### Import Model Pricing Functions

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/model-pricing.md

Imports all necessary functions for managing model pricing from the openwebui_token_tracking library.

```python
from openwebui_token_tracking.model_pricing import (
    get_model_pricing,
    list_model_pricing,
    add_model_pricing,
    update_model_pricing,
    upsert_model_pricing,
    delete_model_pricing
)
```

--------------------------------

### Subcommand: Run Database Migrations

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/cli-reference.md

Executes Alembic database migrations to update the database schema.

```bash
owui-token-tracking database migrate [OPTIONS]
```

--------------------------------

### BaseSetting Model

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/docs/source/api/db.md

SQLAlchemy model for the baseline settings table, storing global configuration settings.

```APIDOC
## class BaseSetting(**kwargs)

### Description
SQLAlchemy model for the baseline settings table. Stores global configuration settings for the token tracking system as key-value pairs.

### Attributes
- **setting_key** (str) - Primary key representing the unique setting identifier
- **setting_value** (str) - Value of the setting stored as a string
- **description** (str) - Human-readable description of what the setting controls and its purpose
```

--------------------------------

### Initialize Base Settings

Source: https://github.com/dartmouth/openwebui-token-tracking/blob/main/_autodocs/settings-utilities.md

Initializes or updates base settings in the database using upsert semantics. Can be used with default settings or a custom list of settings.

```python
from openwebui_token_tracking.settings import init_base_settings

db_url = "postgresql://user:pass@localhost/openwebui"

# Initialize with default settings
init_base_settings(db_url)

# Initialize with custom settings
init_base_settings(
    database_url=db_url,
    settings=[
        {
            "setting_key": "base_credit_allowance",
            "setting_value": "5000",
            "description": "Baseline credit allowance for all users"
        },
        {
            "setting_key": "max_models_per_day",
            "setting_value": "10",
            "description": "Maximum number of different models a user can access per day"
        }
    ]
)
```