token0 0.1.0__py3-none-any.whl

token0/api/auth.py

@@ -0,0 +1,32 @@
+"""API key authentication middleware."""
+
+import hashlib
+
+from fastapi import HTTPException, Security
+from fastapi.security import APIKeyHeader
+
+from token0.config import settings
+
+api_key_header = APIKeyHeader(name="X-Token0-Key", auto_error=False)
+
+
+def hash_api_key(key: str) -> str:
+    return hashlib.sha256(key.encode()).hexdigest()
+
+
+async def verify_api_key(api_key: str | None = Security(api_key_header)) -> str | None:
+    """Verify API key if provided. For open-source mode, auth is optional.
+
+    Returns the hashed key if valid, None if no key provided.
+    In cloud mode, this would be required.
+    """
+    if api_key is None:
+        # Open-source mode — no auth required
+        return None
+
+    # For now, validate against master key
+    if api_key == settings.token0_master_key:
+        return hash_api_key(api_key)
+
+    # TODO: Look up in database for multi-tenant cloud mode
+    raise HTTPException(status_code=401, detail="Invalid API key")

token0/api/v1/chat.py

@@ -0,0 +1,306 @@
+"""Main /v1/chat/completions endpoint — the core proxy."""
+
+import time
+import uuid
+
+from fastapi import APIRouter, Header, HTTPException
+
+from token0.config import settings
+from token0.models.db import Request
+from token0.models.request import (
+    ChatRequest,
+    ChatResponse,
+    Choice,
+    Message,
+    Token0Usage,
+    UsageInfo,
+)
+from token0.optimization.analyzer import analyze_image
+from token0.optimization.cache import get_cached_response, make_cache_key, set_cached_response
+from token0.optimization.prompt_classifier import classify_prompt_detail, extract_prompt_text
+from token0.optimization.router import OptimizationPlan, get_provider_from_model, plan_optimization
+from token0.optimization.transformer import transform_image
+from token0.providers.anthropic import AnthropicProvider
+from token0.providers.base import BaseProvider, get_cost_per_token
+from token0.providers.google import GoogleProvider
+from token0.providers.openai import OpenAIProvider
+from token0.storage.postgres import async_session
+
+router = APIRouter()
+
+
+def _get_provider(provider_name: str, api_key: str | None = None) -> BaseProvider:
+    """Instantiate the right provider with API key."""
+    if provider_name == "openai":
+        key = api_key or settings.openai_api_key
+        if not key:
+            raise HTTPException(400, "OpenAI API key required. Pass via X-Provider-Key header.")
+        return OpenAIProvider(api_key=key)
+    elif provider_name == "anthropic":
+        key = api_key or settings.anthropic_api_key
+        if not key:
+            raise HTTPException(400, "Anthropic API key required. Pass via X-Provider-Key header.")
+        return AnthropicProvider(api_key=key)
+    elif provider_name == "google":
+        key = api_key or settings.google_api_key
+        if not key:
+            raise HTTPException(400, "Google API key required. Pass via X-Provider-Key header.")
+        return GoogleProvider(api_key=key)
+    else:
+        raise HTTPException(400, f"Unsupported provider: {provider_name}")
+
+
+@router.post("/chat/completions", response_model=ChatResponse)
+async def chat_completions(
+    request: ChatRequest,
+    authorization: str | None = Header(None),
+    x_provider_key: str | None = Header(None),
+    x_token0_key: str | None = Header(None),
+):
+    start_time = time.time()
+
+    # --- Step 1: Classify the prompt ---
+    prompt_text = extract_prompt_text(
+        [{"role": m.role, "content": m.content} for m in request.messages]
+    )
+    prompt_detail = classify_prompt_detail(prompt_text) if request.token0_optimize else "auto"
+
+    # --- Step 2: Determine provider and model ---
+    actual_model = request.model
+    model_cascaded_to = None
+    provider_name = get_provider_from_model(request.model)
+
+    # --- Step 3: Process messages — find and optimize images ---
+    optimized_messages = []
+    total_tokens_before = 0
+    total_tokens_after = 0
+    optimizations_applied = []
+    plans: list[OptimizationPlan] = []
+    cache_key = None
+    first_pil_image = None  # for cache key generation
+
+    for msg in request.messages:
+        if isinstance(msg.content, str):
+            optimized_messages.append({"role": msg.role, "content": msg.content})
+            continue
+
+        optimized_parts = []
+        for part in msg.content:
+            if part.type == "text":
+                optimized_parts.append({"type": "text", "text": part.text})
+            elif part.type == "image_url" and part.image_url and request.token0_optimize:
+                image_data = part.image_url.url
+                analysis, raw_bytes, pil_image = analyze_image(image_data)
+
+                # Save first image for cache key
+                if first_pil_image is None:
+                    first_pil_image = pil_image
+
+                plan = plan_optimization(
+                    analysis,
+                    request.model,
+                    detail_override=request.token0_detail_override,
+                    prompt_detail=prompt_detail,
+                    enable_cascade=request.token0_enable_cascade,
+                )
+                plans.append(plan)
+
+                # Check for model cascade recommendation
+                if plan.recommended_model and model_cascaded_to is None:
+                    model_cascaded_to = plan.recommended_model
+                    actual_model = plan.recommended_model
+
+                total_tokens_before += plan.estimated_tokens_before
+                total_tokens_after += plan.estimated_tokens_after
+                optimizations_applied.extend(plan.reasons)
+
+                if plan.use_ocr_route:
+                    result = transform_image(plan, analysis, raw_bytes, pil_image)
+                    optimized_parts.append(
+                        {
+                            "type": "text",
+                            "text": f"[Extracted text from image]:\n{result['content']}",
+                        }
+                    )
+                elif any([plan.resize, plan.recompress_jpeg, plan.force_detail_low]):
+                    result = transform_image(plan, analysis, raw_bytes, pil_image)
+                    detail = "low" if plan.force_detail_low else (part.image_url.detail or "auto")
+                    optimized_parts.append(
+                        {
+                            "type": "image_url",
+                            "image_url": {
+                                "url": f"data:{result['media_type']};base64,{result['base64']}",
+                                "detail": detail,
+                            },
+                        }
+                    )
+                else:
+                    optimized_parts.append(
+                        {
+                            "type": "image_url",
+                            "image_url": {"url": image_data, "detail": part.image_url.detail},
+                        }
+                    )
+            elif part.type == "image_url" and part.image_url:
+                optimized_parts.append(
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": part.image_url.url, "detail": part.image_url.detail},
+                    }
+                )
+
+        optimized_messages.append({"role": msg.role, "content": optimized_parts})
+
+    # --- Step 4: Check semantic cache ---
+    cache_hit = False
+    if request.token0_enable_cache and first_pil_image is not None and prompt_text:
+        cache_key = make_cache_key(first_pil_image, prompt_text, actual_model)
+        cached = await get_cached_response(cache_key)
+        if cached:
+            cache_hit = True
+            latency_ms = int((time.time() - start_time) * 1000)
+
+            # Log cache hit
+            tokens_saved = total_tokens_before  # saved everything
+            cost_per_input_token = get_cost_per_token(request.model, "input")
+            optimizations_applied.append("cache hit — 0 tokens")
+
+            async with async_session() as session:
+                db_request = Request(
+                    provider=provider_name,
+                    model=actual_model,
+                    customer_id="00000000-0000-0000-0000-000000000000",
+                    image_count=len(plans),
+                    optimization_type="cache_hit",
+                    tokens_original_estimate=total_tokens_before,
+                    tokens_actual=0,
+                    tokens_saved=total_tokens_before,
+                    cost_original_estimate=total_tokens_before * cost_per_input_token,
+                    cost_actual=0,
+                    cost_saved=total_tokens_before * cost_per_input_token,
+                    response_tokens=0,
+                    latency_ms=latency_ms,
+                    optimization_details={"cache_hit": True, "cache_key": cache_key},
+                )
+                session.add(db_request)
+                await session.commit()
+
+            return ChatResponse(
+                id=f"token0-{uuid.uuid4().hex[:12]}",
+                model=cached["model"],
+                choices=[
+                    Choice(
+                        index=0,
+                        message=Message(role="assistant", content=cached["content"]),
+                        finish_reason=cached.get("finish_reason", "stop"),
+                    )
+                ],
+                usage=UsageInfo(
+                    prompt_tokens=0,
+                    completion_tokens=cached.get("completion_tokens", 0),
+                    total_tokens=cached.get("completion_tokens", 0),
+                ),
+                token0=Token0Usage(
+                    original_prompt_tokens_estimate=total_tokens_before,
+                    optimized_prompt_tokens=0,
+                    tokens_saved=total_tokens_before,
+                    cost_saved_usd=round(total_tokens_before * cost_per_input_token, 6),
+                    optimizations_applied=optimizations_applied,
+                    cache_hit=True,
+                    model_cascaded_to=model_cascaded_to,
+                ),
+            )
+
+    # --- Step 5: Resolve provider for actual model (may have been cascaded) ---
+    actual_provider_name = get_provider_from_model(actual_model)
+    provider = _get_provider(actual_provider_name, api_key=x_provider_key)
+
+    # --- Step 6: Forward to provider ---
+    provider_response = await provider.chat_completion(
+        model=actual_model,
+        messages=optimized_messages,
+        max_tokens=request.max_tokens,
+        temperature=request.temperature,
+    )
+
+    latency_ms = int((time.time() - start_time) * 1000)
+
+    # --- Step 7: Cache the response ---
+    if cache_key and not cache_hit:
+        await set_cached_response(
+            cache_key,
+            {
+                "model": provider_response.model,
+                "content": provider_response.content,
+                "finish_reason": provider_response.finish_reason,
+                "completion_tokens": provider_response.completion_tokens,
+            },
+        )
+
+    # --- Step 8: Calculate savings ---
+    tokens_saved = max(0, total_tokens_before - total_tokens_after)
+    # If model was cascaded, factor in the price difference
+    original_cost_per_token = get_cost_per_token(request.model, "input")
+    actual_cost_per_token = get_cost_per_token(actual_model, "input")
+
+    cost_before = total_tokens_before * original_cost_per_token
+    cost_after = total_tokens_after * actual_cost_per_token
+    cost_saved = max(0, cost_before - cost_after)
+
+    # --- Step 9: Log to database ---
+    async with async_session() as session:
+        db_request = Request(
+            provider=actual_provider_name,
+            model=actual_model,
+            customer_id="00000000-0000-0000-0000-000000000000",
+            image_count=len(plans),
+            optimization_type=", ".join(set(optimizations_applied)) or "none",
+            tokens_original_estimate=total_tokens_before,
+            tokens_actual=provider_response.prompt_tokens,
+            tokens_saved=tokens_saved,
+            cost_original_estimate=cost_before,
+            cost_actual=cost_after,
+            cost_saved=cost_saved,
+            response_tokens=provider_response.completion_tokens,
+            latency_ms=latency_ms,
+            optimization_details={
+                "plans": [
+                    {
+                        "reasons": p.reasons,
+                        "before": p.estimated_tokens_before,
+                        "after": p.estimated_tokens_after,
+                    }
+                    for p in plans
+                ],
+                "model_cascaded": model_cascaded_to,
+                "prompt_detail": prompt_detail,
+            },
+        )
+        session.add(db_request)
+        await session.commit()
+
+    return ChatResponse(
+        id=f"token0-{uuid.uuid4().hex[:12]}",
+        model=provider_response.model,
+        choices=[
+            Choice(
+                index=0,
+                message=Message(role="assistant", content=provider_response.content),
+                finish_reason=provider_response.finish_reason,
+            )
+        ],
+        usage=UsageInfo(
+            prompt_tokens=provider_response.prompt_tokens,
+            completion_tokens=provider_response.completion_tokens,
+            total_tokens=provider_response.total_tokens,
+        ),
+        token0=Token0Usage(
+            original_prompt_tokens_estimate=total_tokens_before,
+            optimized_prompt_tokens=provider_response.prompt_tokens,
+            tokens_saved=tokens_saved,
+            cost_saved_usd=round(cost_saved, 6),
+            optimizations_applied=optimizations_applied,
+            cache_hit=False,
+            model_cascaded_to=model_cascaded_to,
+        ),
+    )

token0/api/v1/usage.py

@@ -0,0 +1,46 @@
+"""Usage and savings dashboard endpoints."""
+
+from fastapi import APIRouter
+from sqlalchemy import func, select
+
+from token0.models.db import Request
+from token0.models.request import UsageSummary
+from token0.storage.postgres import async_session
+
+router = APIRouter()
+
+
+@router.get("/usage", response_model=UsageSummary)
+async def get_usage():
+    """Get aggregate usage and savings stats."""
+    async with async_session() as session:
+        result = await session.execute(
+            select(
+                func.count(Request.id).label("total_requests"),
+                func.coalesce(func.sum(Request.tokens_saved), 0).label("total_tokens_saved"),
+                func.coalesce(func.sum(Request.cost_saved), 0.0).label("total_cost_saved"),
+                func.coalesce(func.avg(Request.tokens_original_estimate), 0).label("avg_original"),
+                func.coalesce(func.avg(Request.tokens_actual), 0).label("avg_actual"),
+            )
+        )
+        row = result.one()
+
+        # Get optimization type breakdown
+        breakdown_result = await session.execute(
+            select(Request.optimization_type, func.count(Request.id)).group_by(
+                Request.optimization_type
+            )
+        )
+        breakdown = {opt_type: count for opt_type, count in breakdown_result.all()}
+
+        avg_original = float(row.avg_original) if row.avg_original else 0
+        avg_actual = float(row.avg_actual) if row.avg_actual else 0
+        compression_ratio = (avg_original / avg_actual) if avg_actual > 0 else 0
+
+        return UsageSummary(
+            total_requests=row.total_requests,
+            total_tokens_saved=int(row.total_tokens_saved),
+            total_cost_saved_usd=round(float(row.total_cost_saved), 4),
+            avg_compression_ratio=round(compression_ratio, 2),
+            optimization_breakdown=breakdown,
+        )

token0/cli.py

@@ -0,0 +1,46 @@
+import argparse
+import sys
+
+import uvicorn
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="token0",
+        description="Token0 — Vision LLM cost optimization proxy",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    serve_parser = subparsers.add_parser("serve", help="Start the Token0 API server")
+    serve_parser.add_argument("--host", default="0.0.0.0", help="Bind host (default: 0.0.0.0)")
+    serve_parser.add_argument("--port", type=int, default=8000, help="Bind port (default: 8000)")
+    serve_parser.add_argument(
+        "--reload",
+        action="store_true",
+        help="Enable auto-reload for development",
+    )
+    serve_parser.add_argument(
+        "--workers",
+        type=int,
+        default=1,
+        help="Number of worker processes (default: 1)",
+    )
+
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(1)
+
+    if args.command == "serve":
+        uvicorn.run(
+            "token0.main:app",
+            host=args.host,
+            port=args.port,
+            reload=args.reload,
+            workers=args.workers,
+        )
+
+
+if __name__ == "__main__":
+    main()

token0/config.py

@@ -0,0 +1,55 @@
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    # Storage mode: "lite" (SQLite + in-memory) or "full" (Postgres + Redis + S3)
+    # Use "lite" for local dev/testing, "full" for production
+    storage_mode: str = "lite"
+
+    # Database — only needed in full mode
+    database_url: str = "postgresql+asyncpg://token0:token0@localhost:5432/token0"
+
+    # SQLite path — used in lite mode
+    sqlite_path: str = "token0.db"
+
+    # Redis — only needed in full mode
+    redis_url: str = "redis://localhost:6379/0"
+
+    # Object Storage — only needed in full mode
+    s3_endpoint: str = "http://localhost:9000"
+    s3_access_key: str = "minioadmin"
+    s3_secret_key: str = "minioadmin"
+    s3_bucket: str = "token0-images"
+
+    # LLM Provider Keys (optional defaults — users can pass their own per-request)
+    openai_api_key: str = ""
+    anthropic_api_key: str = ""
+    google_api_key: str = ""
+
+    # Server
+    host: str = "0.0.0.0"
+    port: int = 8000
+    log_level: str = "info"
+
+    # Auth
+    token0_master_key: str = "change-me-in-production"
+
+    # Optimization defaults
+    max_image_dimension: int = 1568  # Claude's max before auto-downscale
+    jpeg_quality: int = 85
+    text_density_threshold: float = 0.52  # Above this → OCR route instead of vision
+
+    @property
+    def is_lite(self) -> bool:
+        return self.storage_mode == "lite"
+
+    @property
+    def effective_database_url(self) -> str:
+        if self.is_lite:
+            return f"sqlite+aiosqlite:///{self.sqlite_path}"
+        return self.database_url
+
+    model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
+
+
+settings = Settings()

token0/main.py

@@ -0,0 +1,52 @@
+import logging
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from token0.api.v1.chat import router as chat_router
+from token0.api.v1.usage import router as usage_router
+from token0.config import settings
+from token0.storage.postgres import close_db, init_db
+from token0.storage.redis import close_redis, init_redis
+
+logger = logging.getLogger("token0")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    mode = settings.storage_mode
+    logger.info(f"Starting Token0 in {mode} mode")
+    if settings.is_lite:
+        logger.info(f"  Database: SQLite ({settings.sqlite_path})")
+        logger.info("  Cache: in-memory")
+        logger.info("  Storage: local filesystem")
+        logger.info("  Tip: Set STORAGE_MODE=full for production (Postgres + Redis + S3)")
+    else:
+        logger.info(f"  Database: {settings.database_url}")
+        logger.info(f"  Cache: {settings.redis_url}")
+        logger.info(f"  Storage: {settings.s3_endpoint}")
+    await init_db()
+    await init_redis()
+    yield
+    await close_db()
+    await close_redis()
+
+
+app = FastAPI(
+    title="Token0",
+    description="Open-source API proxy that makes vision LLM calls 5-10x cheaper",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+app.include_router(chat_router, prefix="/v1")
+app.include_router(usage_router, prefix="/v1")
+
+
+@app.get("/health")
+async def health():
+    return {
+        "status": "ok",
+        "service": "token0",
+        "storage_mode": settings.storage_mode,
+    }

token0/models/db.py

@@ -0,0 +1,85 @@
+import uuid
+from datetime import datetime
+
+from sqlalchemy import JSON, DateTime, Float, Integer, String, Text, func
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Customer(Base):
+    __tablename__ = "customers"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    name: Mapped[str] = mapped_column(String(255))
+    api_key_hash: Mapped[str] = mapped_column(String(128), unique=True, index=True)
+    # Customers can pass their own provider keys, stored encrypted
+    provider_keys: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now())
+    is_active: Mapped[bool] = mapped_column(default=True)
+
+
+class Request(Base):
+    __tablename__ = "requests"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    customer_id: Mapped[str] = mapped_column(String(36), index=True)
+    provider: Mapped[str] = mapped_column(String(50))  # openai, anthropic, google
+    model: Mapped[str] = mapped_column(String(100))  # gpt-4o, claude-sonnet-4-6, etc.
+
+    # Image metadata
+    original_width: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    original_height: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    original_size_bytes: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    image_count: Mapped[int] = mapped_column(Integer, default=0)
+
+    # Optimization applied
+    optimization_type: Mapped[str] = mapped_column(
+        String(50)
+    )  # resize, ocr_route, detail_mode, none
+    optimized_width: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    optimized_height: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    detail_mode: Mapped[str | None] = mapped_column(String(20), nullable=True)  # low, high, auto
+
+    # Token accounting
+    tokens_original_estimate: Mapped[int] = mapped_column(Integer)  # what it would have cost
+    tokens_actual: Mapped[int] = mapped_column(Integer)  # what it actually cost
+    tokens_saved: Mapped[int] = mapped_column(Integer)
+
+    # Cost accounting (USD)
+    cost_original_estimate: Mapped[float] = mapped_column(Float)
+    cost_actual: Mapped[float] = mapped_column(Float)
+    cost_saved: Mapped[float] = mapped_column(Float)
+
+    # Prompt/response metadata
+    prompt_text: Mapped[str | None] = mapped_column(Text, nullable=True)
+    response_tokens: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    latency_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+
+    # Full optimization decision log
+    optimization_details: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now())
+
+
+class OptimizationProfile(Base):
+    """Learned optimization profiles — Month 3 feature.
+    Stores what works best per customer + content type + task type.
+    """
+
+    __tablename__ = "optimization_profiles"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    customer_id: Mapped[str] = mapped_column(String(36), index=True)
+    content_type: Mapped[str] = mapped_column(String(100))  # invoice, receipt, screenshot, photo
+    task_type: Mapped[str] = mapped_column(String(100))  # classify, extract, describe, ocr
+    recommended_optimization: Mapped[str] = mapped_column(String(50))
+    recommended_detail_mode: Mapped[str | None] = mapped_column(String(20), nullable=True)
+    recommended_max_dimension: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    avg_quality_score: Mapped[float | None] = mapped_column(Float, nullable=True)
+    sample_count: Mapped[int] = mapped_column(Integer, default=0)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime, server_default=func.now(), onupdate=func.now()
+    )