llmapi-tracker 1.0.0__tar.gz

llmapi_tracker-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 API Tracker contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

llmapi_tracker-1.0.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: llmapi-tracker
+Version: 1.0.0
+Summary: Local-first API usage and cost tracking platform
+Author: API Tracker
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.32
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn[standard]>=0.30
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: pydantic>=2.8
+Provides-Extra: openai
+Requires-Dist: openai>=1.40; extra == "openai"
+Provides-Extra: gemini
+Requires-Dist: google-genai>=0.7; extra == "gemini"
+Provides-Extra: all
+Requires-Dist: openai>=1.40; extra == "all"
+Requires-Dist: google-genai>=0.7; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+# API Tracker
+
+## What API Tracker Is
+
+API Tracker is a local-first API usage and cost observability tool. It records request volume, token usage, latency, status, and versioned pricing for models from providers such as OpenAI and Gemini.
+
+The project is built to keep data local by default. It stores usage and pricing in a local SQLite database and does not persist prompts, responses, or raw API keys in the application database.
+
+## Features
+
+- Local FastAPI backend with SQLite storage
+- Versioned pricing records for historical cost tracking
+- Usage capture for input, output, thinking, cached, and total tokens
+- Cost calculation per request and across analytics views
+- React + Vite dashboard for usage, analytics, providers, models, and pricing
+- SDK wrappers for OpenAI and Gemini
+- Packaged launcher command that starts the local app and opens the browser
+- Open-source repository setup with tests, CI, and release automation
+
+## Installation
+
+### Prerequisites
+
+- Python 3.10 or newer
+- Node.js 20 or newer for frontend development
+
+### Local development install
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate
+pip install -r requirements.txt
+cd frontend
+npm install
+```
+
+### Package install
+
+If you install this project as a package, the launcher command is:
+
+```bash
+api-tracker
+```
+
+## Starting the Application
+
+### Backend only
+
+```bash
+uvicorn backend.app.main:app --reload
+```
+
+### Frontend only
+
+```bash
+cd frontend
+npm run dev
+```
+
+### Packaged app
+
+After building the frontend assets and packaging them into the backend static directory, run:
+
+```bash
+api-tracker
+```
+
+The launcher starts the backend server and opens the browser to the local dashboard.
+
+## SDK Usage
+
+### Initialize the SDK
+
+```python
+import os
+from sdk.api_tracker import APITracker
+
+tracker = APITracker(
+    project="Pharmacy-AI",
+    backend_url=os.getenv("TRACKER_BACKEND_URL", "http://localhost:8000"),
+    openai_api_key=os.getenv("OPENAI_API_KEY"),
+    gemini_api_key=os.getenv("GEMINI_API_KEY"),
+)
+```
+
+### OpenAI
+
+```python
+response = tracker.openai.chat(
+    model="gpt-5",
+    messages=[{"role": "user", "content": "Analyze this prescription"}],
+)
+```
+
+### Gemini
+
+```python
+response = tracker.gemini.generate(
+    model="gemini-2.5-flash",
+    contents="Analyze this prescription",
+)
+```
+
+The SDK reads usage metadata from the provider response and sends it to the local backend automatically.
+
+## Database Location
+
+By default, the SQLite database is stored in a stable user data directory so it survives uninstall and reinstall.
+
+The path is resolved in this order:
+
+1. `API_TRACKER_DB_PATH` if set
+2. `DATABASE_URL` if set
+3. A user-data location based on the operating system
+
+Typical defaults:
+
+- Windows: `%LOCALAPPDATA%\\APITracker\\api_tracker.db`
+- macOS/Linux: `~/.local/share/APITracker/api_tracker.db`
+
+If the preferred user-data directory cannot be created, the app falls back to a writable local `.api-tracker-data/` directory in the current workspace.
+
+## Configuration
+
+Environment variables:
+
+```bash
+DATABASE_URL=sqlite:///./api_tracker.db
+API_TRACKER_DATA_DIR=
+API_TRACKER_DB_PATH=
+API_TRACKER_HOST=127.0.0.1
+API_TRACKER_PORT=8000
+API_TRACKER_OPEN_BROWSER=true
+OPENAI_API_KEY=
+GEMINI_API_KEY=
+TRACKER_BACKEND_URL=http://localhost:8000
+VITE_API_BASE_URL=http://localhost:8000
+```
+
+Notes:
+
+- `DATABASE_URL` overrides the database connection string
+- `API_TRACKER_DATA_DIR` sets the user-data root used for SQLite storage
+- `API_TRACKER_DB_PATH` points directly to a specific SQLite file
+- `API_TRACKER_OPEN_BROWSER=false` disables browser auto-open for the launcher
+
+## Development Setup
+
+### Backend
+
+```bash
+python -m compileall backend sdk tests
+pytest -q
+```
+
+### Frontend
+
+```bash
+cd frontend
+npm run build
+```
+
+### Packaging assets
+
+```bash
+cd frontend
+npm run build
+cd ..
+python scripts/package_frontend_assets.py
+python scripts/verify_frontend_assets.py
+```
+
+## Contributing
+
+This repository is intended to be open source and contributor friendly.
+
+Contribution files:
+
+- [`CONTRIBUTING.md`](L:/Personal/APITracker/CONTRIBUTING.md)
+- [`CODE_OF_CONDUCT.md`](L:/Personal/APITracker/CODE_OF_CONDUCT.md)
+- [`SECURITY.md`](L:/Personal/APITracker/SECURITY.md)
+- [`CHANGELOG.md`](L:/Personal/APITracker/CHANGELOG.md)
+- [`LICENSE`](L:/Personal/APITracker/LICENSE)
+
+Contribution expectations:
+
+- Open changes through pull requests
+- Require review before merge
+- Keep the app local-first
+- Avoid storing prompts, responses, or raw API keys
+- Add tests for behavior changes
+
+## License
+
+API Tracker is released under the MIT License. See [`LICENSE`](L:/Personal/APITracker/LICENSE).
+

llmapi_tracker-1.0.0/README.md

@@ -0,0 +1,196 @@
+# API Tracker
+
+## What API Tracker Is
+
+API Tracker is a local-first API usage and cost observability tool. It records request volume, token usage, latency, status, and versioned pricing for models from providers such as OpenAI and Gemini.
+
+The project is built to keep data local by default. It stores usage and pricing in a local SQLite database and does not persist prompts, responses, or raw API keys in the application database.
+
+## Features
+
+- Local FastAPI backend with SQLite storage
+- Versioned pricing records for historical cost tracking
+- Usage capture for input, output, thinking, cached, and total tokens
+- Cost calculation per request and across analytics views
+- React + Vite dashboard for usage, analytics, providers, models, and pricing
+- SDK wrappers for OpenAI and Gemini
+- Packaged launcher command that starts the local app and opens the browser
+- Open-source repository setup with tests, CI, and release automation
+
+## Installation
+
+### Prerequisites
+
+- Python 3.10 or newer
+- Node.js 20 or newer for frontend development
+
+### Local development install
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate
+pip install -r requirements.txt
+cd frontend
+npm install
+```
+
+### Package install
+
+If you install this project as a package, the launcher command is:
+
+```bash
+api-tracker
+```
+
+## Starting the Application
+
+### Backend only
+
+```bash
+uvicorn backend.app.main:app --reload
+```
+
+### Frontend only
+
+```bash
+cd frontend
+npm run dev
+```
+
+### Packaged app
+
+After building the frontend assets and packaging them into the backend static directory, run:
+
+```bash
+api-tracker
+```
+
+The launcher starts the backend server and opens the browser to the local dashboard.
+
+## SDK Usage
+
+### Initialize the SDK
+
+```python
+import os
+from sdk.api_tracker import APITracker
+
+tracker = APITracker(
+    project="Pharmacy-AI",
+    backend_url=os.getenv("TRACKER_BACKEND_URL", "http://localhost:8000"),
+    openai_api_key=os.getenv("OPENAI_API_KEY"),
+    gemini_api_key=os.getenv("GEMINI_API_KEY"),
+)
+```
+
+### OpenAI
+
+```python
+response = tracker.openai.chat(
+    model="gpt-5",
+    messages=[{"role": "user", "content": "Analyze this prescription"}],
+)
+```
+
+### Gemini
+
+```python
+response = tracker.gemini.generate(
+    model="gemini-2.5-flash",
+    contents="Analyze this prescription",
+)
+```
+
+The SDK reads usage metadata from the provider response and sends it to the local backend automatically.
+
+## Database Location
+
+By default, the SQLite database is stored in a stable user data directory so it survives uninstall and reinstall.
+
+The path is resolved in this order:
+
+1. `API_TRACKER_DB_PATH` if set
+2. `DATABASE_URL` if set
+3. A user-data location based on the operating system
+
+Typical defaults:
+
+- Windows: `%LOCALAPPDATA%\\APITracker\\api_tracker.db`
+- macOS/Linux: `~/.local/share/APITracker/api_tracker.db`
+
+If the preferred user-data directory cannot be created, the app falls back to a writable local `.api-tracker-data/` directory in the current workspace.
+
+## Configuration
+
+Environment variables:
+
+```bash
+DATABASE_URL=sqlite:///./api_tracker.db
+API_TRACKER_DATA_DIR=
+API_TRACKER_DB_PATH=
+API_TRACKER_HOST=127.0.0.1
+API_TRACKER_PORT=8000
+API_TRACKER_OPEN_BROWSER=true
+OPENAI_API_KEY=
+GEMINI_API_KEY=
+TRACKER_BACKEND_URL=http://localhost:8000
+VITE_API_BASE_URL=http://localhost:8000
+```
+
+Notes:
+
+- `DATABASE_URL` overrides the database connection string
+- `API_TRACKER_DATA_DIR` sets the user-data root used for SQLite storage
+- `API_TRACKER_DB_PATH` points directly to a specific SQLite file
+- `API_TRACKER_OPEN_BROWSER=false` disables browser auto-open for the launcher
+
+## Development Setup
+
+### Backend
+
+```bash
+python -m compileall backend sdk tests
+pytest -q
+```
+
+### Frontend
+
+```bash
+cd frontend
+npm run build
+```
+
+### Packaging assets
+
+```bash
+cd frontend
+npm run build
+cd ..
+python scripts/package_frontend_assets.py
+python scripts/verify_frontend_assets.py
+```
+
+## Contributing
+
+This repository is intended to be open source and contributor friendly.
+
+Contribution files:
+
+- [`CONTRIBUTING.md`](L:/Personal/APITracker/CONTRIBUTING.md)
+- [`CODE_OF_CONDUCT.md`](L:/Personal/APITracker/CODE_OF_CONDUCT.md)
+- [`SECURITY.md`](L:/Personal/APITracker/SECURITY.md)
+- [`CHANGELOG.md`](L:/Personal/APITracker/CHANGELOG.md)
+- [`LICENSE`](L:/Personal/APITracker/LICENSE)
+
+Contribution expectations:
+
+- Open changes through pull requests
+- Require review before merge
+- Keep the app local-first
+- Avoid storing prompts, responses, or raw API keys
+- Add tests for behavior changes
+
+## License
+
+API Tracker is released under the MIT License. See [`LICENSE`](L:/Personal/APITracker/LICENSE).
+

llmapi_tracker-1.0.0/backend/__init__.py

@@ -0,0 +1 @@
+

llmapi_tracker-1.0.0/backend/app/__init__.py

@@ -0,0 +1 @@
+

llmapi_tracker-1.0.0/backend/app/database.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import os
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import declarative_base, sessionmaker
+
+from .paths import get_database_url
+
+DATABASE_URL = get_database_url()
+
+connect_args = {"check_same_thread": False} if DATABASE_URL.startswith("sqlite") else {}
+
+engine = create_engine(DATABASE_URL, connect_args=connect_args, future=True)
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine, future=True)
+Base = declarative_base()
+
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()

llmapi_tracker-1.0.0/backend/app/frontend.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import APIRouter
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+from .paths import get_frontend_dist_dir
+
+
+def mount_frontend(app, prefix: str = "") -> None:
+    static_dir = get_frontend_dist_dir()
+    if static_dir.exists():
+        app.mount(prefix or "/assets", StaticFiles(directory=static_dir / "assets"), name="assets")
+
+
+def register_frontend_routes(router: APIRouter) -> None:
+    static_dir = get_frontend_dist_dir()
+    index_path = static_dir / "index.html"
+
+    if not index_path.exists():
+        return
+
+    @router.get("/{path:path}")
+    @router.get("/")
+    def serve_frontend(path: str = ""):
+        target = static_dir / path
+        if path and target.exists() and target.is_file():
+            return FileResponse(target)
+        return FileResponse(index_path)

llmapi_tracker-1.0.0/backend/app/launcher.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import os
+import threading
+import webbrowser
+
+import uvicorn
+
+
+def launch_app() -> None:
+    host = os.getenv("API_TRACKER_HOST", "127.0.0.1")
+    port = int(os.getenv("API_TRACKER_PORT", "8000"))
+    open_browser = os.getenv("API_TRACKER_OPEN_BROWSER", "true").lower() not in {"0", "false", "no"}
+    if open_browser:
+        url = f"http://{host}:{port}"
+        threading.Timer(1.0, lambda: webbrowser.open(url)).start()
+    uvicorn.run("backend.app.main:app", host=host, port=port, reload=False)

llmapi_tracker-1.0.0/backend/app/main.py

@@ -0,0 +1,57 @@
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+from .database import Base, engine
+from .paths import get_frontend_dist_dir
+from .routes import analytics, models, pricing, projects, providers, usage
+
+Base.metadata.create_all(bind=engine)
+
+app = FastAPI(title="API Tracker", version="1.0.0")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(projects.router)
+app.include_router(usage.router)
+app.include_router(pricing.router)
+app.include_router(providers.router)
+app.include_router(models.router)
+app.include_router(analytics.router)
+
+frontend_dist = get_frontend_dist_dir()
+index_file = frontend_dist / "index.html"
+assets_dir = frontend_dist / "assets"
+
+if assets_dir.exists():
+    app.mount("/assets", StaticFiles(directory=assets_dir), name="assets")
+
+
+@app.get("/")
+def root():
+    if index_file.exists():
+        return FileResponse(index_file)
+    return {"name": "API Tracker", "status": "running"}
+
+
+@app.get("/{path:path}")
+def frontend_fallback(path: str):
+    target = frontend_dist / path
+    if target.exists() and target.is_file():
+        return FileResponse(target)
+    if index_file.exists():
+        return FileResponse(index_file)
+    return {"detail": "frontend not built"}
+
+
+@app.get("/health")
+def health():
+    return {"status": "healthy"}

llmapi_tracker-1.0.0/backend/app/models.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import (
+    JSON,
+    Boolean,
+    Column,
+    DateTime,
+    Float,
+    ForeignKey,
+    Integer,
+    String,
+    Text,
+    UniqueConstraint,
+)
+from sqlalchemy.orm import relationship
+
+from .database import Base
+
+
+def utcnow() -> datetime:
+    return datetime.utcnow()
+
+
+class Project(Base):
+    __tablename__ = "projects"
+
+    id = Column(Integer, primary_key=True, index=True)
+    name = Column(String(150), unique=True, nullable=False, index=True)
+    description = Column(Text, nullable=True)
+    environment = Column(String(50), default="development", nullable=False)
+    created_at = Column(DateTime, default=utcnow, nullable=False)
+
+    usage = relationship("ApiUsage", back_populates="project")
+
+
+class Provider(Base):
+    __tablename__ = "providers"
+
+    id = Column(Integer, primary_key=True, index=True)
+    name = Column(String(100), unique=True, nullable=False, index=True)
+    created_at = Column(DateTime, default=utcnow, nullable=False)
+
+    models = relationship("Model", back_populates="provider", cascade="all, delete-orphan")
+
+
+class Model(Base):
+    __tablename__ = "models"
+    __table_args__ = (UniqueConstraint("provider_id", "model_name", name="uq_provider_model_name"),)
+
+    id = Column(Integer, primary_key=True, index=True)
+    provider_id = Column(Integer, ForeignKey("providers.id"), nullable=False, index=True)
+    model_name = Column(String(150), nullable=False, index=True)
+    model_type = Column(String(50), default="text", nullable=False)
+    created_at = Column(DateTime, default=utcnow, nullable=False)
+
+    provider = relationship("Provider", back_populates="models")
+    pricing = relationship("ModelPricing", back_populates="model", cascade="all, delete-orphan")
+    usage = relationship("ApiUsage", back_populates="model_ref")
+
+
+class ModelPricing(Base):
+    __tablename__ = "model_pricing"
+    __table_args__ = (
+        UniqueConstraint("model_id", "effective_from", name="uq_model_pricing_version"),
+    )
+
+    id = Column(Integer, primary_key=True, index=True)
+    model_id = Column(Integer, ForeignKey("models.id"), nullable=False, index=True)
+    input_price_per_1m = Column(Float, default=0.0, nullable=False)
+    output_price_per_1m = Column(Float, default=0.0, nullable=False)
+    thinking_price_per_1m = Column(Float, default=0.0, nullable=False)
+    cached_input_price_per_1m = Column(Float, default=0.0, nullable=False)
+    currency = Column(String(10), default="USD", nullable=False)
+    effective_from = Column(DateTime, default=utcnow, nullable=False, index=True)
+    effective_to = Column(DateTime, nullable=True, index=True)
+    created_at = Column(DateTime, default=utcnow, nullable=False)
+    updated_at = Column(DateTime, default=utcnow, onupdate=utcnow, nullable=False)
+
+    model = relationship("Model", back_populates="pricing")
+
+
+class ApiUsage(Base):
+    __tablename__ = "api_usage"
+
+    id = Column(Integer, primary_key=True, index=True)
+    project_id = Column(Integer, ForeignKey("projects.id"), nullable=False, index=True)
+    provider_id = Column(Integer, ForeignKey("providers.id"), nullable=False, index=True)
+    model_id = Column(Integer, ForeignKey("models.id"), nullable=False, index=True)
+    internal_request_id = Column(String(255), nullable=False, unique=True, index=True)
+    provider_request_id = Column(String(255), nullable=True, index=True)
+    timestamp = Column(DateTime, default=utcnow, nullable=False, index=True)
+    input_tokens = Column(Integer, default=0, nullable=False)
+    output_tokens = Column(Integer, default=0, nullable=False)
+    thinking_tokens = Column(Integer, default=0, nullable=False)
+    cached_tokens = Column(Integer, default=0, nullable=False)
+    total_tokens = Column(Integer, default=0, nullable=False)
+    input_cost = Column(Float, default=0.0, nullable=False)
+    output_cost = Column(Float, default=0.0, nullable=False)
+    thinking_cost = Column(Float, default=0.0, nullable=False)
+    cached_cost = Column(Float, default=0.0, nullable=False)
+    total_cost = Column(Float, default=0.0, nullable=False)
+    audio_seconds = Column(Float, default=0.0, nullable=False)
+    characters = Column(Integer, default=0, nullable=False)
+    request_count = Column(Integer, default=1, nullable=False)
+    latency_ms = Column(Float, default=0.0, nullable=False)
+    status = Column(String(30), default="success", nullable=False)
+    http_status_code = Column(Integer, nullable=True)
+    error_type = Column(String(100), nullable=True)
+    metadata_json = Column(JSON, default=dict, nullable=False)
+    capture_content = Column(Boolean, default=False, nullable=False)
+
+    project = relationship("Project", back_populates="usage")
+    provider = relationship("Provider")
+    model_ref = relationship("Model", back_populates="usage")