ccproxy-api 0.1.7__py3-none-any.whl → 0.2.0a4__py3-none-any.whl

ccproxy/plugins/analytics/models.py

@@ -0,0 +1,97 @@
+"""Access log schema and payload definitions (owned by analytics)."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlmodel import Field, SQLModel
+from typing_extensions import TypedDict
+
+
+class AccessLog(SQLModel, table=True):
+    """Access log model for storing request/response data."""
+
+    __tablename__ = "access_logs"
+
+    # Core request identification
+    request_id: str = Field(primary_key=True)
+    timestamp: datetime = Field(default_factory=datetime.now, index=True)
+
+    # Request details
+    method: str
+    endpoint: str
+    path: str
+    query: str = Field(default="")
+    client_ip: str
+    user_agent: str
+
+    # Service and model info
+    service_type: str
+    provider: str = Field(default="")
+    model: str
+    streaming: bool = Field(default=False)
+
+    # Response details
+    status_code: int
+    duration_ms: float
+    duration_seconds: float
+
+    # Token and cost tracking
+    tokens_input: int = Field(default=0)
+    tokens_output: int = Field(default=0)
+    cache_read_tokens: int = Field(default=0)
+    cache_write_tokens: int = Field(default=0)
+    cost_usd: float = Field(default=0.0)
+    cost_sdk_usd: float = Field(default=0.0)
+    num_turns: int = Field(default=0)
+
+    # Session context metadata
+    session_type: str = Field(default="")
+    session_status: str = Field(default="")
+    session_age_seconds: float = Field(default=0.0)
+    session_message_count: int = Field(default=0)
+    session_client_id: str = Field(default="")
+    session_pool_enabled: bool = Field(default=False)
+    session_idle_seconds: float = Field(default=0.0)
+    session_error_count: int = Field(default=0)
+    session_is_new: bool = Field(default=True)
+
+    # SQLModel provides its own config typing; avoid overriding with Pydantic ConfigDict
+    # from_attributes=True is not required for SQLModel usage here
+    # Keep default SQLModel config to satisfy mypy type expectations
+
+
+class AccessLogPayload(TypedDict, total=False):
+    """TypedDict for access log data payloads."""
+
+    request_id: str
+    timestamp: int | float | datetime
+    method: str
+    endpoint: str
+    path: str
+    query: str
+    client_ip: str
+    user_agent: str
+    service_type: str
+    provider: str
+    model: str
+    streaming: bool
+    status_code: int
+    duration_ms: float
+    duration_seconds: float
+    tokens_input: int
+    tokens_output: int
+    cache_read_tokens: int
+    cache_write_tokens: int
+    cost_usd: float
+    cost_sdk_usd: float
+    num_turns: int
+    session_type: str
+    session_status: str
+    session_age_seconds: float
+    session_message_count: int
+    session_client_id: str
+    session_pool_enabled: bool
+    session_idle_seconds: float
+    session_error_count: int
+    session_is_new: bool

ccproxy/plugins/analytics/plugin.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from ccproxy.core.logging import get_plugin_logger
+from ccproxy.core.plugins import (
+    PluginManifest,
+    RouteSpec,
+    SystemPluginFactory,
+    SystemPluginRuntime,
+)
+
+from .config import AnalyticsPluginConfig
+
+
+logger = get_plugin_logger()
+
+
+class AnalyticsRuntime(SystemPluginRuntime):
+    async def _on_initialize(self) -> None:
+        # Ensure AccessLog model is registered and table exists on the engine.
+        from sqlmodel import SQLModel
+
+        # Import models to register with SQLModel metadata
+        try:
+            from . import models as _models  # noqa: F401
+        except Exception as e:  # pragma: no cover - defensive
+            logger.error("analytics_models_import_failed", error=str(e))
+            raise
+
+        # Assert model registration in metadata
+        table = SQLModel.metadata.tables.get("access_logs")
+        if table is None:
+            logger.error("access_logs_table_not_in_metadata")
+            raise RuntimeError("AccessLog model not registered in SQLModel metadata")
+
+        # Try to get storage engine via plugin registry service
+        engine = None
+        try:
+            registry = self.context.get("plugin_registry") if self.context else None
+            if registry:
+                storage = registry.get_service("log_storage")
+                engine = getattr(storage, "_engine", None)
+
+            # Fallback to app.state if needed
+            if (engine is None) and self.context and self.context.get("app"):
+                app = self.context["app"]
+                storage = getattr(app.state, "log_storage", None)
+                engine = getattr(storage, "_engine", None)
+        except Exception as e:  # pragma: no cover - defensive
+            logger.warning("analytics_engine_lookup_failed", error=str(e))
+
+        # If we have an engine, assert table is created (idempotent create_all)
+        if engine is not None:
+            try:
+                SQLModel.metadata.create_all(engine)
+                logger.debug("analytics_table_ready", table="access_logs")
+            except Exception as e:
+                logger.error("analytics_table_create_failed", error=str(e))
+                raise
+        else:
+            logger.warning(
+                "analytics_no_engine_available",
+                message="Storage engine not available during analytics init; table creation skipped",
+            )
+
+        # Register ingest service for access_log hook to call
+        try:
+            if self.context:
+                registry = self.context.get("plugin_registry")
+                storage = None
+                if registry:
+                    # Get storage service without importing DuckDB-specific classes
+                    storage = registry.get_service("log_storage")
+                if not storage and self.context.get("app"):
+                    storage = getattr(self.context["app"].state, "log_storage", None)
+
+                if storage:
+                    engine = getattr(storage, "_engine", None)
+                else:
+                    engine = None
+
+                if engine is not None:
+                    from .ingest import AnalyticsIngestService
+
+                    ingest_service = AnalyticsIngestService(engine)
+                    if registry:
+                        registry.register_service(
+                            "analytics_ingest", ingest_service, self.manifest.name
+                        )
+                        logger.debug("analytics_ingest_service_registered")
+                else:
+                    logger.warning(
+                        "analytics_ingest_registration_skipped",
+                        reason="no_engine_available",
+                    )
+        except Exception as e:  # pragma: no cover - defensive
+            logger.warning("analytics_ingest_registration_failed", error=str(e))
+
+        logger.debug("analytics_plugin_initialized")
+
+
+class AnalyticsFactory(SystemPluginFactory):
+    def __init__(self) -> None:
+        from .routes import router as analytics_router
+
+        manifest = PluginManifest(
+            name="analytics",
+            version="0.1.0",
+            description="Logs query, analytics, and streaming endpoints",
+            is_provider=False,
+            config_class=AnalyticsPluginConfig,
+            provides=["analytics_ingest"],
+            dependencies=["duckdb_storage"],
+            routes=[RouteSpec(router=analytics_router, prefix="/logs", tags=["logs"])],
+        )
+        super().__init__(manifest)
+
+    def create_runtime(self) -> AnalyticsRuntime:
+        return AnalyticsRuntime(self.manifest)
+
+
+factory = AnalyticsFactory()

ccproxy/plugins/analytics/routes.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import time
+from collections.abc import AsyncGenerator
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from fastapi.responses import StreamingResponse
+
+from ccproxy.auth.dependencies import ConditionalAuthDep
+from ccproxy.core.request_context import get_request_event_stream
+from ccproxy.plugins.duckdb_storage.storage import SimpleDuckDBStorage
+
+from .service import AnalyticsService
+
+
+router = APIRouter()
+
+
+@router.get("/query")
+async def query_logs(
+    storage: DuckDBStorageDep,
+    auth: ConditionalAuthDep,
+    limit: int = Query(1000, ge=1, le=10000, description="Maximum number of results"),
+    start_time: float | None = Query(None, description="Start timestamp filter"),
+    end_time: float | None = Query(None, description="End timestamp filter"),
+    model: str | None = Query(None, description="Model filter"),
+    service_type: str | None = Query(None, description="Service type filter"),
+    cursor: float | None = Query(
+        None, description="Timestamp cursor for pagination (Unix time)"
+    ),
+    order: str = Query(
+        "desc", pattern="^(?i)(asc|desc)$", description="Sort order: asc or desc"
+    ),
+) -> dict[str, Any]:
+    if not storage:
+        raise HTTPException(status_code=503, detail="Storage backend not available")
+    if not getattr(storage, "_engine", None):
+        raise HTTPException(status_code=503, detail="Storage engine not available")
+
+    try:
+        svc = AnalyticsService(storage._engine)
+        return svc.query_logs(
+            limit=limit,
+            start_time=start_time,
+            end_time=end_time,
+            model=model,
+            service_type=service_type,
+            cursor=cursor,
+            order=order,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Query failed: {str(e)}") from e
+
+
+@router.get("/analytics")
+async def get_logs_analytics(
+    storage: DuckDBStorageDep,
+    auth: ConditionalAuthDep,
+    start_time: float | None = Query(None, description="Start timestamp (Unix time)"),
+    end_time: float | None = Query(None, description="End timestamp (Unix time)"),
+    model: str | None = Query(None, description="Filter by model name"),
+    service_type: str | None = Query(
+        None,
+        description="Filter by service type. Supports comma-separated values and !negation",
+    ),
+    hours: int | None = Query(24, ge=1, le=168, description="Hours of data to analyze"),
+) -> dict[str, Any]:
+    if not storage:
+        raise HTTPException(status_code=503, detail="Storage backend not available")
+    if not getattr(storage, "_engine", None):
+        raise HTTPException(status_code=503, detail="Storage engine not available")
+
+    try:
+        svc = AnalyticsService(storage._engine)
+        analytics = svc.get_analytics(
+            start_time=start_time,
+            end_time=end_time,
+            model=model,
+            service_type=service_type,
+            hours=hours,
+        )
+        analytics["query_params"] = {
+            "start_time": start_time,
+            "end_time": end_time,
+            "model": model,
+            "service_type": service_type,
+            "hours": hours,
+        }
+        return analytics
+    except Exception as e:
+        raise HTTPException(
+            status_code=500, detail=f"Analytics query failed: {str(e)}"
+        ) from e
+
+
+@router.get("/stream")
+async def stream_logs(
+    request: Request,
+    auth: ConditionalAuthDep,
+    model: str | None = Query(None, description="Filter by model name"),
+    service_type: str | None = Query(None, description="Filter by service type"),
+    min_duration_ms: float | None = Query(None, description="Min duration (ms)"),
+    max_duration_ms: float | None = Query(None, description="Max duration (ms)"),
+    status_code_min: int | None = Query(None, description="Min status code"),
+    status_code_max: int | None = Query(None, description="Max status code"),
+) -> StreamingResponse:
+    async def event_generator() -> AsyncGenerator[str, None]:
+        try:
+            async for event in get_request_event_stream():
+                data = event
+                if model and data.get("model") != model:
+                    continue
+                if service_type and data.get("service_type") != service_type:
+                    continue
+                if min_duration_ms and data.get("duration_ms", 0) < min_duration_ms:
+                    continue
+                if max_duration_ms and data.get("duration_ms", 0) > max_duration_ms:
+                    continue
+                if status_code_min and data.get("status_code", 0) < status_code_min:
+                    continue
+                if status_code_max and data.get("status_code", 0) > status_code_max:
+                    continue
+
+                yield f"data: {data}\n\n"
+        except Exception as e:  # pragma: no cover - stream errors aren't fatal
+            yield f"event: error\ndata: {str(e)}\n\n"
+
+    return StreamingResponse(event_generator(), media_type="text/event-stream")
+
+
+@router.post("/reset")
+async def reset_logs(
+    storage: DuckDBStorageDep,
+    auth: ConditionalAuthDep,
+) -> dict[str, Any]:
+    if not storage:
+        raise HTTPException(status_code=503, detail="Storage backend not available")
+    if not hasattr(storage, "reset_data"):
+        raise HTTPException(
+            status_code=501, detail="Reset not supported by storage backend"
+        )
+
+    ok = await storage.reset_data()
+    if not ok:
+        raise HTTPException(status_code=500, detail="Failed to reset logs data")
+    return {
+        "status": "success",
+        "message": "All logs data has been reset",
+        "timestamp": time.time(),
+        "backend": "duckdb",
+    }
+
+
+async def get_duckdb_storage(request: Request) -> SimpleDuckDBStorage | None:
+    """Get DuckDB storage service from app state.
+
+    The duckdb_storage plugin registers the storage as app.state.log_storage.
+    """
+    return getattr(request.app.state, "log_storage", None)
+
+
+DuckDBStorageDep = Annotated[SimpleDuckDBStorage | None, Depends(get_duckdb_storage)]

ccproxy/plugins/analytics/service.py

@@ -0,0 +1,284 @@
+from __future__ import annotations
+
+import time
+from datetime import datetime as dt
+from typing import Any
+
+from sqlmodel import Session, col, func, select
+
+from .models import AccessLog
+
+
+class AnalyticsService:
+    """Encapsulates analytics queries over the AccessLog table."""
+
+    def __init__(self, engine: Any):
+        self._engine = engine
+
+    def query_logs(
+        self,
+        limit: int = 1000,
+        start_time: float | None = None,
+        end_time: float | None = None,
+        model: str | None = None,
+        service_type: str | None = None,
+        cursor: float | None = None,
+        order: str = "desc",
+    ) -> dict[str, Any]:
+        with Session(self._engine) as session:
+            statement = select(AccessLog)
+
+            start_dt = dt.fromtimestamp(start_time) if start_time else None
+            end_dt = dt.fromtimestamp(end_time) if end_time else None
+            cursor_dt = dt.fromtimestamp(cursor) if cursor else None
+
+            if start_dt:
+                statement = statement.where(AccessLog.timestamp >= start_dt)
+            if end_dt:
+                statement = statement.where(AccessLog.timestamp <= end_dt)
+            if model:
+                statement = statement.where(AccessLog.model == model)
+            if service_type:
+                statement = statement.where(AccessLog.service_type == service_type)
+
+            # Cursor-based pagination using timestamp
+            # For descending order (newest first): use timestamp < cursor
+            # For ascending order (oldest first): use timestamp > cursor
+            if cursor_dt:
+                if order.lower() == "asc":
+                    statement = statement.where(AccessLog.timestamp > cursor_dt)
+                else:
+                    statement = statement.where(AccessLog.timestamp < cursor_dt)
+
+            if order.lower() == "asc":
+                statement = statement.order_by(col(AccessLog.timestamp).asc()).limit(
+                    limit
+                )
+            else:
+                statement = statement.order_by(col(AccessLog.timestamp).desc()).limit(
+                    limit
+                )
+            results = session.exec(statement).all()
+            payload = [log.model_dump() for log in results]
+
+            # Compute next cursor from last item in current page
+            next_cursor = None
+            if results:
+                last = results[-1]
+                next_cursor = last.timestamp.timestamp()
+
+            return {
+                "results": payload,
+                "limit": limit,
+                "count": len(results),
+                "order": order.lower(),
+                "cursor": cursor,
+                "next_cursor": next_cursor,
+                "has_more": len(results) == limit,
+                "query_time": time.time(),
+                "backend": "sqlmodel",
+            }
+
+    def get_analytics(
+        self,
+        start_time: float | None = None,
+        end_time: float | None = None,
+        model: str | None = None,
+        service_type: str | None = None,
+        hours: int | None = 24,
+    ) -> dict[str, Any]:
+        if start_time is None and end_time is None and hours:
+            end_time = time.time()
+            start_time = end_time - (hours * 3600)
+
+        start_dt = dt.fromtimestamp(start_time) if start_time else None
+        end_dt = dt.fromtimestamp(end_time) if end_time else None
+
+        def build_filters() -> list[Any]:
+            conditions: list[Any] = []
+            if start_dt:
+                conditions.append(AccessLog.timestamp >= start_dt)
+            if end_dt:
+                conditions.append(AccessLog.timestamp <= end_dt)
+            if model:
+                conditions.append(AccessLog.model == model)
+            if service_type:
+                parts = [s.strip() for s in service_type.split(",")]
+                include = [p for p in parts if not p.startswith("!")]
+                exclude = [p[1:] for p in parts if p.startswith("!")]
+                if include:
+                    conditions.append(col(AccessLog.service_type).in_(include))
+                if exclude:
+                    conditions.append(~col(AccessLog.service_type).in_(exclude))
+            return conditions
+
+        with Session(self._engine) as session:
+            filters = build_filters()
+
+            total_requests = session.exec(
+                select(func.count()).select_from(AccessLog).where(*filters)
+            ).first()
+            total_successful_requests = session.exec(
+                select(func.count())
+                .select_from(AccessLog)
+                .where(
+                    *filters, AccessLog.status_code >= 200, AccessLog.status_code < 400
+                )
+            ).first()
+            total_error_requests = session.exec(
+                select(func.count())
+                .select_from(AccessLog)
+                .where(*filters, AccessLog.status_code >= 400)
+            ).first()
+            avg_duration = session.exec(
+                select(func.avg(AccessLog.duration_ms))
+                .select_from(AccessLog)
+                .where(*filters)
+            ).first()
+            total_cost = session.exec(
+                select(func.sum(AccessLog.cost_usd))
+                .select_from(AccessLog)
+                .where(*filters)
+            ).first()
+            total_tokens_input = session.exec(
+                select(func.sum(AccessLog.tokens_input))
+                .select_from(AccessLog)
+                .where(*filters)
+            ).first()
+            total_tokens_output = session.exec(
+                select(func.sum(AccessLog.tokens_output))
+                .select_from(AccessLog)
+                .where(*filters)
+            ).first()
+            total_cache_read_tokens = session.exec(
+                select(func.sum(AccessLog.cache_read_tokens))
+                .select_from(AccessLog)
+                .where(*filters)
+            ).first()
+            total_cache_write_tokens = session.exec(
+                select(func.sum(AccessLog.cache_write_tokens))
+                .select_from(AccessLog)
+                .where(*filters)
+            ).first()
+
+            services = session.exec(
+                select(AccessLog.service_type).distinct().where(*filters)
+            ).all()
+            breakdown: dict[str, Any] = {}
+            for svc in services:
+                svc_filters = filters + [AccessLog.service_type == svc]
+                svc_count = session.exec(
+                    select(func.count()).select_from(AccessLog).where(*svc_filters)
+                ).first()
+                svc_success = session.exec(
+                    select(func.count())
+                    .select_from(AccessLog)
+                    .where(
+                        *svc_filters,
+                        AccessLog.status_code >= 200,
+                        AccessLog.status_code < 400,
+                    )
+                ).first()
+                svc_error = session.exec(
+                    select(func.count())
+                    .select_from(AccessLog)
+                    .where(*svc_filters, AccessLog.status_code >= 400)
+                ).first()
+                svc_avg = session.exec(
+                    select(func.avg(AccessLog.duration_ms))
+                    .select_from(AccessLog)
+                    .where(*svc_filters)
+                ).first()
+                svc_cost = session.exec(
+                    select(func.sum(AccessLog.cost_usd))
+                    .select_from(AccessLog)
+                    .where(*svc_filters)
+                ).first()
+                svc_in = session.exec(
+                    select(func.sum(AccessLog.tokens_input))
+                    .select_from(AccessLog)
+                    .where(*svc_filters)
+                ).first()
+                svc_out = session.exec(
+                    select(func.sum(AccessLog.tokens_output))
+                    .select_from(AccessLog)
+                    .where(*svc_filters)
+                ).first()
+                svc_cr = session.exec(
+                    select(func.sum(AccessLog.cache_read_tokens))
+                    .select_from(AccessLog)
+                    .where(*svc_filters)
+                ).first()
+                svc_cw = session.exec(
+                    select(func.sum(AccessLog.cache_write_tokens))
+                    .select_from(AccessLog)
+                    .where(*svc_filters)
+                ).first()
+
+                breakdown[str(svc)] = {
+                    "request_count": svc_count or 0,
+                    "successful_requests": svc_success or 0,
+                    "error_requests": svc_error or 0,
+                    "success_rate": (svc_success or 0) / (svc_count or 1) * 100
+                    if svc_count
+                    else 0,
+                    "error_rate": (svc_error or 0) / (svc_count or 1) * 100
+                    if svc_count
+                    else 0,
+                    "avg_duration_ms": svc_avg or 0,
+                    "total_cost_usd": svc_cost or 0,
+                    "total_tokens_input": svc_in or 0,
+                    "total_tokens_output": svc_out or 0,
+                    "total_cache_read_tokens": svc_cr or 0,
+                    "total_cache_write_tokens": svc_cw or 0,
+                    "total_tokens_all": (svc_in or 0)
+                    + (svc_out or 0)
+                    + (svc_cr or 0)
+                    + (svc_cw or 0),
+                }
+
+            return {
+                "summary": {
+                    "total_requests": total_requests or 0,
+                    "total_successful_requests": total_successful_requests or 0,
+                    "total_error_requests": total_error_requests or 0,
+                    "avg_duration_ms": avg_duration or 0,
+                    "total_cost_usd": total_cost or 0,
+                    "total_tokens_input": total_tokens_input or 0,
+                    "total_tokens_output": total_tokens_output or 0,
+                    "total_cache_read_tokens": total_cache_read_tokens or 0,
+                    "total_cache_write_tokens": total_cache_write_tokens or 0,
+                    "total_tokens_all": (total_tokens_input or 0)
+                    + (total_tokens_output or 0)
+                    + (total_cache_read_tokens or 0)
+                    + (total_cache_write_tokens or 0),
+                },
+                "token_analytics": {
+                    "input_tokens": total_tokens_input or 0,
+                    "output_tokens": total_tokens_output or 0,
+                    "cache_read_tokens": total_cache_read_tokens or 0,
+                    "cache_write_tokens": total_cache_write_tokens or 0,
+                    "total_tokens": (total_tokens_input or 0)
+                    + (total_tokens_output or 0)
+                    + (total_cache_read_tokens or 0)
+                    + (total_cache_write_tokens or 0),
+                },
+                "request_analytics": {
+                    "total_requests": total_requests or 0,
+                    "successful_requests": total_successful_requests or 0,
+                    "error_requests": total_error_requests or 0,
+                    "success_rate": (total_successful_requests or 0)
+                    / (total_requests or 1)
+                    * 100
+                    if total_requests
+                    else 0,
+                    "error_rate": (total_error_requests or 0)
+                    / (total_requests or 1)
+                    * 100
+                    if total_requests
+                    else 0,
+                },
+                "service_type_breakdown": breakdown,
+                "query_time": time.time(),
+                "backend": "sqlmodel",
+            }

ccproxy/plugins/claude_api/README.md

@@ -0,0 +1,29 @@
+# Claude API Plugin
+
+Connects CCProxy to Anthropic's Claude HTTP API with detection, health, and metrics.
+
+## Highlights
+- Wraps `ClaudeAPIAdapter` for chat, tool, and streaming requests
+- Uses the detection service to discover CLI headers and available models
+- Emits streaming metrics and standardized health checks via the hook registry
+
+## Configuration
+- `ClaudeAPISettings` defines base URLs, model cards, and auth manager name
+- Works with `oauth_claude` or the credential balancer for token management
+- Generate defaults with `python3 scripts/generate_config_from_model.py \
+  --format toml --plugin claude_api --config-class ClaudeAPISettings`
+
+```toml
+[plugins.claude_api]
+# enabled = true
+# base_url = "https://api.anthropic.com"
+# auth_type = "oauth"
+# supports_streaming = true
+# include_sdk_content_as_xml = false
+# system_prompt_injection_mode = "minimal"
+```
+
+## Related Components
+- `adapter.py`: HTTP client for Anthropic endpoints
+- `detection_service.py`: CLI and capability discovery helpers
+- `routes.py`: FastAPI router mounted under `/claude/api`