{"id":39219021,"url":"https://github.com/cwest/ai-tokentrace","last_synced_at":"2026-01-17T23:26:08.946Z","repository":{"id":320311081,"uuid":"1081352614","full_name":"cwest/ai-tokentrace","owner":"cwest","description":"ai-tokentrace is a Python library for GenAI cost observability. It helps developers track token consumption in Google Generative AI applications to manage costs and optimize performance.","archived":false,"fork":false,"pushed_at":"2025-10-27T12:24:41.000Z","size":340,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-22T02:04:03.939Z","etag":null,"topics":["adk-python","ai","cost-management","firestore","gemini","genai","google","google-genai","observability","pubsub","python","telemetry","token-tracing"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/ai-tokentrace/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cwest.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/code-of-conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-22T16:59:11.000Z","updated_at":"2025-10-27T12:23:50.000Z","dependencies_parsed_at":"2025-10-23T05:26:51.414Z","dependency_job_id":"7d2578e0-db63-4386-802c-ecf8bd88e405","html_url":"https://github.com/cwest/ai-tokentrace","commit_stats":null,"previous_names":["cwest/ai-tokentrace"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cwest/ai-tokentrace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cwest%2Fai-tokentrace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cwest%2Fai-tokentrace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cwest%2Fai-tokentrace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cwest%2Fai-tokentrace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cwest","download_url":"https://codeload.github.com/cwest/ai-tokentrace/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cwest%2Fai-tokentrace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28522129,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T22:11:28.393Z","status":"ssl_error","status_checked_at":"2026-01-17T22:11:27.841Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adk-python","ai","cost-management","firestore","gemini","genai","google","google-genai","observability","pubsub","python","telemetry","token-tracing"],"created_at":"2026-01-17T23:26:08.894Z","updated_at":"2026-01-17T23:26:08.940Z","avatar_url":"https://github.com/cwest.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ai-tokentrace\n\n[![PyPI version](https://badge.fury.io/py/ai-tokentrace.svg)](https://badge.fury.io/py/ai-tokentrace)\n[![CI](https://github.com/cwest/ai-tokentrace/actions/workflows/ci.yml/badge.svg)](https://github.com/cwest/ai-tokentrace/actions/workflows/ci.yml)\n\n**GenAI Cost Observability for Google's Generative AI.**\n\n`ai-tokentrace` provides a transparent and easy way to track token consumption in your GenAI applications. Whether you're using the standard `google-genai` SDK or building complex agents with the Google Agent Development Kit (ADK), this library helps you manage costs, optimize performance, and gain deep insights into your model usage.\n\n## Features\n\n*   **🔍 Automatic Tracking:** Seamlessly integrates with `google-genai` to capture token usage from every API call.\n*   **🤖 ADK Support:** Includes a plugin for the Google Agent Development Kit for effortless agent monitoring.\n*   **🔌 Multiple Backends:** Export data to where you need it:\n    *   **Logging:** Simple standard output for development.\n    *   **JSONL:** Structured local files for easy analysis.\n    *   **Google Cloud Firestore:** Scalable, queryable cloud storage.\n    *   **Google Cloud Pub/Sub:** Event-driven pipelines for real-time analytics.\n*   **⚡ Async Native:** Fully non-blocking to keep your applications fast.\n*   **📊 Rich Metrics:** Tracks input/output tokens, thinking tokens, cached content, tool usage, and more.\n\n## Installation\n\nInstall using `pip` or `uv` (recommended).\n\n### Basic Installation\n\nFor standard logging or JSONL export:\n\n```bash\npip install ai-tokentrace\n# or\nuv pip install ai-tokentrace\n```\n\n### With Extra Backends\n\nInstall with specific extras for Cloud integrations or ADK support:\n\n```bash\n# For Google Cloud Firestore\nuv pip install \"ai-tokentrace[firestore]\"\n\n# For Google Cloud Pub/Sub\nuv pip install \"ai-tokentrace[pubsub]\"\n\n# For Google ADK support\nuv pip install \"ai-tokentrace[adk]\"\n\n# Install everything\nuv pip install \"ai-tokentrace[firestore,pubsub,adk]\"\n```\n\n## Quick Start\n\n### 1. Using with `google-genai` SDK\n\nSimply wrap your client with `TrackedGenaiClient`. It works exactly like the standard client but logs all token usage.\n\n```python\nimport os\nfrom google import genai\nfrom ai_tokentrace import TrackedGenaiClient\n\n# 1. Initialize standard client\nclient = genai.Client(api_key=os.environ[\"GEMINI_API_KEY\"])\n\n# 2. Wrap with tracking (uses logging by default)\ntracked_client = TrackedGenaiClient(client=client)\n\n# 3. Use as normal!\nresponse = tracked_client.models.generate_content(\n    model=\"gemini-2.5-flash\",\n    contents=\"Explain quantum computing in 5 words.\"\n)\nprint(response.text)\n# Output: \"Complex superposition processes information fast.\"\n# Log: {\"timestamp\": \"...\", \"model_name\": \"gemini-2.5-flash\", \"total_tokens\": 15, ...}\n```\n\n### 2. Using with Google ADK\n\nAdd the `TokenTrackingPlugin` to your ADK app.\n\n```python\nfrom google.adk.agents import LlmAgent\nfrom google.adk.apps.app import App\nfrom ai_tokentrace.adk import TokenTrackingPlugin\n\nagent = LlmAgent(model=\"gemini-2.5-flash\", ...)\n\napp = App(\n    name=\"my_app\",\n    root_agent=agent,\n    plugins=[TokenTrackingPlugin()]  # Tracks all agent interactions\n)\n```\n\n## Advanced Usage\n\n### Configuring Backends\n\nYou can configure different backends for storing your token usage data.\n\n**Firestore Example:**\n\n```python\nfrom ai_tokentrace import TrackedGenaiClient\nfrom ai_tokentrace.services import FirestoreTokenUsageService\n\nservice = FirestoreTokenUsageService(collection_name=\"genai_usage_logs\")\ntracked_client = TrackedGenaiClient(client=client, service=service)\n```\n\n**Pub/Sub Example:**\n\n```python\nfrom ai_tokentrace import TrackedGenaiClient\nfrom ai_tokentrace.services import PubSubTokenUsageService\n\nservice = PubSubTokenUsageService(topic_id=\"my-usage-topic\", project_id=\"my-project\")\ntracked_client = TrackedGenaiClient(client=client, service=service)\n```\n\n### Self-Inspection for Agents\n\nGive your agents the ability to see their own token usage!\n\n```python\nfrom ai_tokentrace.services import FirestoreTokenUsageService\n\nservice = FirestoreTokenUsageService(...)\n\n# Add the inspection tool to your agent\nagent = LlmAgent(\n    ...,\n    tools=[service.get_inspection_tool()]\n)\n```\n\n## Examples\n\nCheck out the `examples/` directory for complete, runnable projects:\n\n*   **[google-genai/](examples/google-genai/)**: Scripts demonstrating sync/async usage, streaming, and different backends.\n*   **[adk/](examples/adk/)**: Full ADK applications showing multi-agent tracking, multimodal capabilities, and self-inspection.\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](docs/contributing.md) for guidelines.\n\n## License\n\nApache 2.0 - See [LICENSE](LICENSE) for more details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcwest%2Fai-tokentrace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcwest%2Fai-tokentrace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcwest%2Fai-tokentrace/lists"}