Metadata-Version: 2.4
Name: forge-dashboard
Version: 0.1.2
Summary: Observability dashboard for LLM inference with thinking budget and mode tracking
Author: ArkaD171717
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: dashboard,llm,observability,opentelemetry,reasoning
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.115
Requires-Dist: pydantic>=2.0
Requires-Dist: uvicorn[standard]>=0.30
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# forge-dashboard

Observability dashboard for LLM inference with reasoning mode support. Ingests OpenTelemetry trace and metric data from forge-observe, stores it in SQLite, and serves a React frontend for visualizing thinking budget burn, token splits, and mode switches.


## What it shows

- **Budget burn over time** -- how fast the thinking budget is being consumed
- **Think vs response token split** -- what fraction of output is thinking vs user-facing
- **Mode switch timeline** -- when the router flips between thinking and instruct mode
- **Alert rules** -- threshold alerts on budget exhaustion, token ratios, error rates


## Architecture

```
forge-observe (OTel SDK)
        |
        | OTLP/HTTP JSON (POST /v1/traces, /v1/metrics)
        v
forge-dashboard (FastAPI + SQLite)
        |
        +-- React frontend (Vite + Recharts + Tailwind)
```

The backend accepts OTLP JSON exports, parses forge-specific span attributes (`forge.thinking_tokens`, `forge.budget_remaining`, etc.), and stores them for dashboard queries. Authentication is via API keys scoped to projects.

There are two ways to send data:

- **Direct** -- point forge-observe's OTLP exporter straight at `http://<dashboard-host>:8000/v1/traces`. Works for single-node setups.
- **Via forge-cloud** (separate project, not yet released) -- if you run forge-cloud as a central proxy, configure it to forward traces to the dashboard. forge-cloud handles auth and routing so individual services only need the proxy address.


## Running locally

```bash
# backend
pip install -e ".[dev]"
forge-dashboard
# serves on http://localhost:8000

# frontend (separate terminal)
cd frontend
npm install
npm run dev
# serves on http://localhost:5173, proxies /v1/* to backend
```


## Setup

1. Start the backend. It creates a SQLite database on first run.
2. Set a setup secret and create a user and project via the API:

```bash
export FORGE_SETUP_SECRET="your-secret-here"
# then start the backend

# create user
curl -X POST http://localhost:8000/v1/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-here" \
  -d '{"email": "you@example.com"}'

# create project (use the user id from above)
curl -X POST http://localhost:8000/v1/projects \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-here" \
  -d '{"name": "my-project", "owner_id": 1}'
# response includes api_key -- save it
```

3. Enter the API key in the dashboard Settings page, or use it in forge-observe's exporter config.
4. Point forge-observe's OTLP exporter at `http://localhost:8000/v1/traces`.


## Configuration

Environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `SQLITE_PATH` | `forge_dashboard.db` | Path to SQLite database file |
| `FORGE_SETUP_SECRET` | (none) | Required to create users/projects via API |
| `FORGE_ALERT_INTERVAL_SECONDS` | `60` | How often to evaluate alert rules |
| `FORGE_RETENTION_DAYS` | `7` | Data retention period |
| `FORGE_CORS_ORIGINS` | `http://localhost:5173` | Comma-separated allowed CORS origins |


## Tests

```bash
pip install -e ".[dev]"
pytest -v
```


## Project status

Backend is functional with OTLP ingestion, query API, alerting, and data retention. Frontend is a working prototype with budget, token split, mode timeline, and alert management views. Notification delivery (email, Slack, etc.) is not yet implemented -- alert firings are recorded in the database only.
