Feature/ Token tracking system with usage history API

[lakshayg2005]

SUMMARY

This pull request introduces a complete Token Tracking System for Sugar-AI. It enables tracking, storing, and retrieving LLM token usage per user along with cost estimation. It also adds an API endpoint to fetch detailed usage history, providing visibility into model consumption and enabling future analytics and billing capabilities.

---

IMPLEMENTATION DETAILS

Token Tracking System

A centralized TokenTracker module has been implemented to handle token usage calculation for every LLM request.

It tracks:

• Prompt tokens
• Completion tokens
• Total tokens per request
• Estimated cost per request

This module is integrated directly into the /ask endpoint to ensure every user interaction is recorded.

---

Usage History API

GET /usage/detailed-history

• New endpoint added
• Fetches token usage history from database
• Supports pagination using limit
• Returns structured usage records per user

---

GET /my-status

• Existing endpoint integrated with token tracking system
• Provides user-specific usage status and metrics
• Enhanced to reflect updated token usage data

---

GET /global-status

• Existing system-wide endpoint integrated with token tracking
• Provides aggregated usage statistics across users
• Updated to reflect real-time token consumption metrics

---

---

DATABASE INTEGRATION

• Added persistent storage for token usage in token_usage table
• Integrated SQLAlchemy session management using SessionLocal
• Ensures each request is logged with metadata for tracking and analytics
• Enables future expansion for billing and quota systems

---

TESTING DONE

• Tested /ask endpoint with multiple prompts
• Verified token tracking accuracy per request
• Tested /usage/detailed-history API
• Tested /usage/my-stats API
• Tested /usage/global-stats API
• Validated API response structure and correctness

---

IMPACT

This feature provides a foundational observability layer for Sugar-AI and enables:

• Per-user token usage tracking
• Real-time cost estimation per request
• Analytics and usage insights
• Future billing and quota enforcement systems
• Improved transparency of LLM pipeline usage

---

SCREENSHOTS

/ask Endpoint

/ask Response

/usgae/gloabl-status

/usage/detailed-history

/usage/my-status