Download the PHP package deus-global/deus-ai-token-fee-guru without Composer

Deus AI Token Fee Guru

A comprehensive PHP package for calculating Large Language Model (LLM) token usage costs with support for cached tokens, multiple users, conversation rounds, and model comparison.

Features

• Multi-Model Support: Calculate costs for different LLM models (GPT-5, GPT-4.1, etc.)
• Cache-Aware Calculations: Factor in prompt cache hit rates for accurate cost estimates
• Enterprise Scale: Support for multi-user scenarios and conversation rounds
• Multiple Output Formats: Plain text, JSON, and Markdown exports
• Multi-Language Support: English (en-US) and Traditional Chinese (zh-TW)
• Custom Pricing Tables: Use your own CSV pricing data
• Extensible Model Support: Easily add new LLM models via CSV configuration
• CLI Interface: Interactive and command-line modes
• Chainable API: Fluent interface with method chaining
• PSR-4 Autoloading: Modern PHP package standards

Installation

Via Composer (Recommended)

Quick Start

CLI Usage

After installing via Composer, the CLI tool is available in your vendor/bin directory:

PHP API Usage

Configuration

The client accepts configuration options during instantiation:

Advanced Usage

Enterprise-scale calculations

Model comparison

Using utility functions

Composer Scripts

After installation, you can use these convenient scripts:

Pricing Data Format

The system uses CSV files for pricing data. Default format:

All prices are per 1 million tokens (as per PRD requirements).

Adding Custom Models

You can easily extend support to additional LLM models by adding their pricing data to data/ai_token_pricing_table.csv:

CSV Column Specification:

• vendor: Model provider (e.g., "OpenAI", "Anthropic", "Google")
• model: Human-readable model name (e.g., "Claude 3.5 Sonnet")
• model_api_name: API identifier used in code (e.g., "claude-3-5-sonnet-20241022")
• input_token_price: Cost per 1M input tokens (e.g., "3.00")
• cached_input_token_price: Cost per 1M cached input tokens (e.g., "0.30")
• output_token_price: Cost per 1M output tokens (e.g., "15.00")
• currency: Currency code (e.g., "USD")

Example: Adding Claude 3.5 Sonnet

Usage with Custom Models:

CLI Usage with Custom Models:

Using External Pricing Files:

💡 Tip: Keep your CSV file updated with the latest pricing from model providers to ensure accurate cost calculations.

📖 For detailed model extension guide: See docs/EXTENDING_MODELS.md for comprehensive instructions and examples.

CLI Parameters

Core Parameters

• --model=MODEL - Model name (e.g., gpt-5-mini)
• --input-token-count=NUM - Input tokens per conversation
• --output-token-count=NUM - Output tokens per conversation
• --cache-hit-rate=RATE - Cache hit rate (0.0 to 1.0)
• --conversation-rounds=NUM - Conversations per user
• --user-count=NUM - Number of users

Output Options

• --output-format=FORMAT - text, json, or markdown
• --output-file=FILE - Save to file
• --language=LANG - en-US or zh-TW

Advanced Features

• --compare-models=MODELS - Compare multiple models (comma-separated)
• --pricing-table-path=PATH - Custom pricing CSV file
• --interactive-mode - Interactive CLI session
• --list-available-models - Show available models
• --show-pricing-data - Show detailed pricing info

Complete CLI Examples

Basic Usage Examples

Simple Single Model Calculation

Multi-User Scenarios

Information & Discovery

List Available Models

Show Pricing Information

Help and Usage

Model Comparison Examples

Compare All GPT-5 Models

Enterprise Model Comparison

Output Format Examples

Plain Text Output (Default)

JSON Output

Markdown Output

File Output Examples

Save to Files

Interactive Mode Examples

Interactive CLI Session

Custom Pricing Table Examples

Using Custom Pricing Data

Real-World Scenario Examples

Chatbot Cost Estimation (High Cache Hit Rate)

API Service Cost Planning

Content Generation Service

Cost Optimization Analysis

Advanced Parameter Combinations

All Parameters Example

Batch Analysis Scripts

Language-Specific Examples

Traditional Chinese Interface

English Interface (Default)

Testing

The package includes comprehensive test examples that you can run after installation:

Key Features Explained

Cache-Aware Pricing

The system understands that cached tokens (prompt cache hits) are typically priced at 90% savings compared to regular input tokens. Cache hit rate only applies to input tokens, not output tokens.

Multi-User Scaling

Perfect for enterprise scenarios where you need to calculate costs across:

• Multiple users (user_count)
• Multiple conversations per user (conversation_rounds)
• Different models and configurations

Flexible Output Formats

• Text: Human-readable console output
• JSON: Structured data for APIs and integrations
• Markdown: Documentation-friendly tables

Multi-Language Support

Full internationalization with comprehensive translations for English and Traditional Chinese interfaces.

Requirements

• PHP 7.2.5 or higher
• ext-json (required)
• ext-curl (suggested for HTTP-based pricing data fetching)
• ext-mbstring (suggested for multi-byte string operations)

Architecture

The Token Fee Guru follows modern PHP practices and design patterns:

Core Components

• Client: Main entry point implementing ClientInterface
• Calculator: Token cost calculation logic implementing CalculatorInterface
• DataSource: Pluggable data sources implementing DataSourceInterface
• RequestOptions: Value object for calculation parameters
• Exceptions: Custom exception hierarchy for error handling

Design Principles

• Interface-based design: All major components implement interfaces for flexibility
• Dependency injection: Components are injected rather than hardcoded
• Single responsibility: Each class has a focused purpose
• Fluent interface: Method chaining for easy configuration
• Type safety: Strict typing where possible
• PSR compliance: Follows PSR-4 autoloading and other relevant PSRs

Extension Points

The library is designed to be extensible:

License

This project follows the Deus AI development standards and conventions.

For comprehensive model extension guide, see: docs/EXTENDING_MODELS.md