tracellm-cli 0.1.0__py3-none-any.whl

app/models/project.py

@@ -0,0 +1,32 @@
+from datetime import datetime, timezone
+from typing import Literal
+
+from pydantic import Field
+
+from app.models.trace import MongoFriendlyModel
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+EnvironmentLiteral = Literal["development", "staging", "production"]
+
+
+class ProjectSchema(MongoFriendlyModel):
+    project_id: str
+    name: str
+    description: str = ""
+    created_at: datetime = Field(default_factory=_utcnow)
+
+
+class ApiKeySchema(MongoFriendlyModel):
+    key: str
+    project_id: str
+    environment: str
+    created_at: datetime = Field(default_factory=_utcnow)
+
+
+class ProjectCreateResponse(MongoFriendlyModel):
+    project: ProjectSchema
+    api_key: ApiKeySchema

app/models/trace.py

@@ -0,0 +1,71 @@
+from datetime import datetime, timezone
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+TraceStatus = Literal["success", "warning", "failed"]
+
+
+class MongoFriendlyModel(BaseModel):
+    """Base settings shared by MongoDB-backed models."""
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        json_encoders={datetime: lambda value: value.isoformat()},
+    )
+
+
+class StepSchema(MongoFriendlyModel):
+    step_id: str
+    tool_name: str
+    input: dict[str, Any] = Field(default_factory=dict)
+    output: dict[str, Any] = Field(default_factory=dict)
+    duration: float
+    success: bool
+    timestamp: datetime = Field(default_factory=_utcnow)
+
+    @field_validator("duration")
+    @classmethod
+    def validate_duration(cls, value: float) -> float:
+        if value < 0:
+            raise ValueError("duration must be greater than or equal to 0")
+        return value
+
+
+class TraceSchema(MongoFriendlyModel):
+    trace_id: str
+    prompt: str
+    response: Optional[str] = None
+    latency: float
+    token_count: int
+    model_name: Optional[str] = None
+    project_id: str = "default"
+    project_name: Optional[str] = None
+    api_key: Optional[str] = None
+    environment: str = "development"
+    status: TraceStatus
+    steps: list[StepSchema] = Field(default_factory=list)
+    retry_count: int = 0
+    slow_request: bool = False
+    failure_reason: Optional[str] = None
+    created_at: datetime = Field(default_factory=_utcnow)
+    updated_at: datetime = Field(default_factory=_utcnow)
+
+    @field_validator("latency")
+    @classmethod
+    def validate_latency(cls, value: float) -> float:
+        if value < 0:
+            raise ValueError("latency must be greater than or equal to 0")
+        return value
+
+    @field_validator("token_count", "retry_count")
+    @classmethod
+    def validate_non_negative_ints(cls, value: int) -> int:
+        if value < 0:
+            raise ValueError("value must be greater than or equal to 0")
+        return value

app/models/trace_model.py

@@ -0,0 +1,62 @@
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from app.models.trace import TraceSchema
+
+
+class TraceListResponse(BaseModel):
+    total: int
+    items: list[TraceSchema]
+
+
+class TraceFilters(BaseModel):
+    latency_min: Optional[float] = None
+    latency_max: Optional[float] = None
+    status: Optional[str] = None
+    model: Optional[str] = None
+    project_id: Optional[str] = None
+    environment: Optional[str] = None
+    token_min: Optional[int] = None
+    token_max: Optional[int] = None
+    limit: int = Field(default=50, ge=1, le=200)
+
+
+class AnalyticsSummary(BaseModel):
+    total_traces: int
+    success_rate: float
+    average_latency: float
+    p95_latency: float
+    total_token_usage: int
+    failed_traces: int
+    warning_traces: int
+    retries: int
+    slow_requests: int
+
+
+class AnalyticsChartPoint(BaseModel):
+    label: str
+    latency: float
+    tokens: int
+    traces: int
+
+
+class AnalyticsBreakdownItem(BaseModel):
+    key: str
+    count: int
+
+
+class AnalyticsResponse(BaseModel):
+    summary: AnalyticsSummary
+    charts: list[AnalyticsChartPoint]
+    status_breakdown: list[AnalyticsBreakdownItem]
+    model_breakdown: list[AnalyticsBreakdownItem]
+    project_breakdown: list[AnalyticsBreakdownItem]
+    recent_failures: list[TraceSchema]
+
+
+class FailureResponse(BaseModel):
+    failed_traces: list[TraceSchema]
+    retries: list[TraceSchema]
+    slow_requests: list[TraceSchema]
+    totals: dict[str, int]

app/routes/__init__.py

@@ -0,0 +1 @@
+"""API route modules for TraceLLM."""

app/routes/health.py

@@ -0,0 +1,10 @@
+from fastapi import APIRouter
+
+from app.models.health import HealthResponse
+
+router = APIRouter()
+
+
+@router.get("/", response_model=HealthResponse)
+async def health_check() -> HealthResponse:
+    return HealthResponse(message="TraceLLM backend running")

app/routes/observability.py

@@ -0,0 +1,60 @@
+from fastapi import APIRouter, Query
+
+from app.database.trace_service import get_analytics, get_failures, get_trace_by_id, list_traces
+from app.models.trace import TraceSchema
+from app.models.trace_model import AnalyticsResponse, FailureResponse, TraceFilters, TraceListResponse
+
+router = APIRouter()
+
+
+@router.get("/traces", response_model=TraceListResponse)
+async def get_traces(
+    latency_min: float | None = Query(default=None, ge=0),
+    latency_max: float | None = Query(default=None, ge=0),
+    status: str | None = Query(default=None),
+    model: str | None = Query(default=None),
+    project_id: str | None = Query(default=None),
+    environment: str | None = Query(default=None),
+    token_min: int | None = Query(default=None, ge=0),
+    token_max: int | None = Query(default=None, ge=0),
+    limit: int = Query(default=50, ge=1, le=200),
+) -> TraceListResponse:
+    filters = TraceFilters(
+        latency_min=latency_min,
+        latency_max=latency_max,
+        status=status,
+        model=model,
+        project_id=project_id,
+        environment=environment,
+        token_min=token_min,
+        token_max=token_max,
+        limit=limit,
+    )
+    return await list_traces(filters)
+
+
+@router.get("/traces/{trace_id}", response_model=TraceSchema)
+async def get_trace(trace_id: str) -> TraceSchema:
+    return await get_trace_by_id(trace_id)
+
+
+@router.get("/analytics", response_model=AnalyticsResponse)
+async def analytics(
+    project_id: str | None = Query(default=None),
+    environment: str | None = Query(default=None),
+) -> AnalyticsResponse:
+    return await get_analytics(
+        TraceFilters(project_id=project_id, environment=environment)
+    )
+
+
+@router.get("/failures", response_model=FailureResponse)
+async def failures(
+    limit: int = Query(default=25, ge=1, le=100),
+    project_id: str | None = Query(default=None),
+    environment: str | None = Query(default=None),
+) -> FailureResponse:
+    return await get_failures(
+        limit=limit,
+        filters=TraceFilters(limit=limit, project_id=project_id, environment=environment),
+    )

app/routes/projects.py

@@ -0,0 +1,25 @@
+from fastapi import APIRouter, Query
+
+from app.database.project_service import create_project, list_api_keys, list_projects
+from app.models.project import ApiKeySchema, ProjectCreateResponse, ProjectSchema
+
+router = APIRouter()
+
+
+@router.get("/projects", response_model=list[ProjectSchema])
+async def get_projects() -> list[ProjectSchema]:
+    return await list_projects()
+
+
+@router.get("/api-keys", response_model=list[ApiKeySchema])
+async def get_api_keys(project_id: str | None = Query(default=None)) -> list[ApiKeySchema]:
+    return await list_api_keys(project_id=project_id)
+
+
+@router.post("/projects", response_model=ProjectCreateResponse)
+async def create_project_route(
+    name: str,
+    environment: str,
+    description: str = "",
+) -> ProjectCreateResponse:
+    return await create_project(name=name, description=description, environment=environment)

app/websocket/__init__.py

@@ -0,0 +1 @@
+"""WebSocket modules for TraceLLM."""

app/websocket/socket.py

@@ -0,0 +1,64 @@
+import asyncio
+import logging
+from typing import Any
+
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect
+
+router = APIRouter()
+logger = logging.getLogger(__name__)
+
+
+class ConnectionManager:
+    """Small websocket manager for broadcasting observability events."""
+
+    def __init__(self) -> None:
+        self._connections: list[WebSocket] = []
+        self._lock = asyncio.Lock()
+
+    async def connect(self, websocket: WebSocket) -> None:
+        await websocket.accept()
+        async with self._lock:
+            self._connections.append(websocket)
+
+    async def disconnect(self, websocket: WebSocket) -> None:
+        async with self._lock:
+            if websocket in self._connections:
+                self._connections.remove(websocket)
+
+    async def broadcast(self, payload: dict[str, Any]) -> None:
+        async with self._lock:
+            connections = list(self._connections)
+
+        stale_connections: list[WebSocket] = []
+        for connection in connections:
+            try:
+                await connection.send_json(payload)
+            except Exception:
+                logger.exception("Failed to send websocket payload")
+                stale_connections.append(connection)
+
+        for stale_connection in stale_connections:
+            await self.disconnect(stale_connection)
+
+
+manager = ConnectionManager()
+
+
+@router.websocket("/ws")
+async def websocket_endpoint(websocket: WebSocket) -> None:
+    await manager.connect(websocket)
+    await websocket.send_json(
+        {
+            "type": "system.connected",
+            "status": "connected",
+            "message": "TraceLLM websocket active",
+        }
+    )
+
+    try:
+        while True:
+            message = await websocket.receive_json()
+            if message.get("type") == "ping":
+                await websocket.send_json({"type": "system.pong", "timestamp": message.get("ts")})
+    except WebSocketDisconnect:
+        await manager.disconnect(websocket)

sdk/__init__.py

@@ -0,0 +1,3 @@
+from tracellm import trace, wrap_openai, TraceOpenAI, TracellmCallbackHandler, trace_tool
+
+__all__ = ["trace", "wrap_openai", "TraceOpenAI", "TracellmCallbackHandler", "trace_tool"]

sdk/tracer.py

@@ -0,0 +1,8 @@
+from tracellm.cli import app
+from tracellm.tracer import llm_response, trace
+
+__all__ = ["app", "llm_response", "trace"]
+
+
+if __name__ == "__main__":
+    app()

tracellm/__init__.py

@@ -0,0 +1,6 @@
+from tracellm.tracer import trace
+from tracellm.integrations.openai import wrap_openai, TraceOpenAI
+from tracellm.integrations.langchain import TracellmCallbackHandler
+from tracellm.integrations.tool_tracer import trace_tool
+
+__all__ = ["trace", "wrap_openai", "TraceOpenAI", "TracellmCallbackHandler", "trace_tool"]

tracellm/banner.py

@@ -0,0 +1,34 @@
+"""Premium startup banner for TraceLLM CLI."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from rich.box import DOUBLE
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+from rich.align import Align
+
+
+def render_banner(
+    version: str = "0.2.0",
+    environment: str = "development",
+) -> Panel:
+    """Render a centered premium startup banner panel."""
+    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+    inner = Table.grid(padding=(0, 0))
+    inner.add_column(justify="center")
+    inner.add_row(Text(f"TraceLLM v{version}", style="bold white"))
+    inner.add_row(Text("Open-source LLM Observability", style="bright_black"))
+    inner.add_row(Text(""))
+    inner.add_row(Text(f"Started at {now}", style="dim"))
+    inner.add_row(Text(f"Environment: {environment}", style="dim"))
+
+    return Panel(
+        Align.center(inner),
+        box=DOUBLE,
+        border_style="bright_black",
+        padding=(1, 4),
+    )

tracellm/cli.py

@@ -0,0 +1,124 @@
+import os
+
+import typer
+
+from tracellm.db import create_project_with_key
+from tracellm.exporter import export_traces
+from tracellm.replay import replay_trace
+from tracellm.startup import run_start
+from tracellm.tracer import llm_response, run_live_trace
+from tracellm.utils import console, render_project_credentials
+
+app = typer.Typer(help="TraceLLM SDK and developer CLI.")
+
+
+@app.callback(invoke_without_command=True)
+def cli_entry(ctx: typer.Context) -> None:
+    if ctx.invoked_subcommand is None:
+        from tracellm.palette import run_palette
+        run_palette(app)
+
+
+@app.command()
+def demo() -> None:
+    """Generate a realistic demo trace."""
+    result = llm_response()
+    retries = result.get("retry_count", 0)
+    steps = len(result.get("steps", []))
+    console.print()
+    console.print("[bold white]Demo complete[/bold white]")
+    console.print(f"[bright_black]{steps} steps, {retries} retries[/bright_black]")
+    console.print()
+
+
+@app.command()
+def start(
+    port: int = typer.Option(8000, "--port", "-p", help="Port for the API server."),
+    dashboard: bool = typer.Option(False, "--dashboard", "-d", help="Open the dashboard in your browser."),
+    dashboard_port: int = typer.Option(3000, "--dashboard-port", help="Port for the frontend dashboard."),
+) -> None:
+    """Start the TraceLLM observability stack (backend + dashboard)."""
+    run_start(port=port, dashboard_port=dashboard_port, launch_dashboard=dashboard)
+
+
+@app.command("trace")
+def trace_command(
+    prompt: str = typer.Argument(..., help="Prompt to trace."),
+    model: str = typer.Option("gpt-4.1-mini", "--model", help="Model name label for the trace."),
+    project: str = typer.Option("default", "--project", help="Project identifier or display name."),
+    environment: str = typer.Option("development", "--environment", help="Environment label."),
+    api_key: str | None = typer.Option(None, "--api-key", help="TraceLLM API key."),
+) -> None:
+    """Run a production-style traced prompt simulation."""
+    run_live_trace(
+        prompt=prompt,
+        model_name=model,
+        project=project,
+        environment=environment,
+        api_key=api_key,
+        render=True,
+    )
+
+
+@app.command()
+def replay(
+    trace_id: str = typer.Argument(..., help="Trace ID to replay from MongoDB."),
+    speed: float = typer.Option(1.0, "--speed", min=0.1, help="Replay speed multiplier."),
+    show_response: bool = typer.Option(False, "--show-response", help="Show the full saved response after replay."),
+) -> None:
+    """Replay a saved trace from MongoDB in the terminal."""
+    replay_trace(trace_id=trace_id, speed=speed, show_response=show_response)
+
+
+@app.command()
+def monitor(
+    refresh: float = typer.Option(2.0, "--refresh", "-r", help="Polling interval in seconds."),
+    limit: int = typer.Option(10, "--limit", "-l", help="Number of recent traces to show."),
+    ws_host: str = typer.Option(os.environ.get("TRACELLM_WS_HOST", "127.0.0.1"), "--ws-host", help="Backend WebSocket host. Falls back to TRACELLM_WS_HOST env."),
+    ws_port: int = typer.Option(int(os.environ.get("TRACELLM_WS_PORT", "8000")), "--ws-port", help="Backend WebSocket port. Falls back to TRACELLM_WS_PORT env."),
+) -> None:
+    """Watch incoming real traces in realtime."""
+    from tracellm.monitor import run_monitor as _run_monitor
+    try:
+        _run_monitor(refresh=refresh, limit=limit, ws_host=ws_host, ws_port=ws_port)
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Monitor stopped.[/yellow]")
+
+
+@app.command()
+def export(
+    format: str = typer.Option("json", "--format", help="Export format: json or csv."),
+    limit: int = typer.Option(100, "--limit", min=1, max=1000, help="How many recent traces to export."),
+) -> None:
+    """Export traces from MongoDB."""
+    normalized = format.lower()
+    if normalized not in {"json", "csv"}:
+        raise typer.BadParameter("format must be one of: json, csv")
+    export_traces(export_format=normalized, limit=limit)
+
+
+@app.command("create-project")
+def create_project_command() -> None:
+    """Create a project and generate a secure API key."""
+    name = typer.prompt("Project name").strip()
+    description = typer.prompt("Description", default="", show_default=False).strip()
+    environment = typer.prompt("Environment", default="development").strip().lower()
+    if environment not in {"development", "staging", "production"}:
+        raise typer.BadParameter("environment must be development, staging, or production")
+
+    response = create_project_with_key(name=name, description=description, environment=environment)
+    render_project_credentials(
+        project_id=response.project.project_id,
+        name=response.project.name,
+        environment=response.api_key.environment,
+        api_key=response.api_key.key,
+        description=response.project.description,
+    )
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

tracellm/db.py

@@ -0,0 +1,75 @@
+"""Database helpers with persistent async lifecycle management."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, TypeVar
+
+from app.database.project_service import create_project, get_project_by_api_key, list_projects
+from app.database.trace_service import get_trace_by_id, list_traces, save_trace, save_trace_sync
+from app.models.project import ApiKeySchema, ProjectCreateResponse, ProjectSchema
+from app.models.trace import TraceSchema
+from app.models.trace_model import TraceFilters
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+_ASYNC_LOOP: asyncio.AbstractEventLoop | None = None
+
+
+def _run_async(coro: Any) -> T:
+    """Run a coroutine synchronously using a persistent event loop.
+
+    Unlike ``asyncio.run()`` this does **not** close the loop after the
+    coroutine completes, which avoids “event loop is closed” errors when
+    Motor / MongoDB background tasks reference the loop.
+    """
+    global _ASYNC_LOOP
+
+    # If an event loop is already running (e.g. inside FastAPI / uvicorn),
+    # schedule on that loop instead.
+    try:
+        running = asyncio.get_running_loop()
+        if running.is_running():
+            future = asyncio.run_coroutine_threadsafe(coro, running)
+            return future.result()
+    except RuntimeError:
+        pass
+
+    # Reuse or create a persistent loop for synchronous callers (CLI).
+    if _ASYNC_LOOP is None or _ASYNC_LOOP.is_closed():
+        _ASYNC_LOOP = asyncio.new_event_loop()
+        asyncio.set_event_loop(_ASYNC_LOOP)
+
+    return _ASYNC_LOOP.run_until_complete(coro)
+
+
+def save_trace_payload(trace_data: dict[str, Any]) -> None:
+    save_trace_sync(trace_data)
+
+
+async def save_trace_payload_async(trace_data: dict[str, Any]) -> dict[str, Any]:
+    return await save_trace(trace_data)
+
+
+def fetch_trace(trace_id: str) -> TraceSchema:
+    return _run_async(get_trace_by_id(trace_id))
+
+
+def fetch_recent_traces(limit: int = 100) -> list[TraceSchema]:
+    response = _run_async(list_traces(TraceFilters(limit=limit)))
+    return response.items
+
+
+def create_project_with_key(name: str, description: str, environment: str) -> ProjectCreateResponse:
+    return _run_async(create_project(name=name, description=description, environment=environment))
+
+
+def fetch_projects() -> list[ProjectSchema]:
+    return _run_async(list_projects())
+
+
+def resolve_api_key(api_key: str) -> ApiKeySchema:
+    return _run_async(get_project_by_api_key(api_key))

tracellm/exporter.py

@@ -0,0 +1,65 @@
+import json
+from pathlib import Path
+
+from tracellm.db import fetch_recent_traces
+from tracellm.utils import console, ensure_export_dir, export_timestamp, render_export_success, write_csv
+
+
+def export_traces(export_format: str, limit: int = 100) -> Path:
+    console.print()
+    console.print("[bold white]Exporting traces...[/bold white]")
+
+    traces = fetch_recent_traces(limit=limit)
+    export_dir = ensure_export_dir()
+    timestamp = export_timestamp()
+
+    if export_format == "json":
+        path = export_dir / f"traces-{timestamp}.json"
+        payload = [trace.model_dump(mode="json") for trace in traces]
+        path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    else:
+        path = export_dir / f"traces-{timestamp}.csv"
+        rows = [
+            {
+                "trace_id": trace.trace_id,
+                "project_id": trace.project_id,
+                "project_name": trace.project_name,
+                "environment": trace.environment,
+                "prompt": trace.prompt,
+                "model_name": trace.model_name,
+                "status": trace.status,
+                "latency": trace.latency,
+                "token_count": trace.token_count,
+                "retry_count": trace.retry_count,
+                "slow_request": trace.slow_request,
+                "failure_reason": trace.failure_reason,
+                "created_at": trace.created_at.isoformat(),
+                "updated_at": trace.updated_at.isoformat(),
+                "step_count": len(trace.steps),
+            }
+            for trace in traces
+        ]
+        write_csv(
+            path,
+            rows,
+            [
+                "trace_id",
+                "project_id",
+                "project_name",
+                "environment",
+                "prompt",
+                "model_name",
+                "status",
+                "latency",
+                "token_count",
+                "retry_count",
+                "slow_request",
+                "failure_reason",
+                "created_at",
+                "updated_at",
+                "step_count",
+            ],
+        )
+
+    render_export_success(path, len(traces))
+    return path

tracellm/integrations/__init__.py

@@ -0,0 +1,4 @@
+from tracellm.integrations.openai import wrap_openai, TraceOpenAI
+from tracellm.integrations.langchain import TracellmCallbackHandler
+
+__all__ = ["wrap_openai", "TraceOpenAI", "TracellmCallbackHandler"]