Quick Start
Getting Started
Load the bundled demo data or upload a CSV to begin. The platform supports wide-format tables with one date column, optional dimensions, and one numeric column per metric.
Tip
Start with the built-in demo data to explore the platform without login. Connect only when uploading your own CSV.
1. Load Data — Load demo data or upload a CSV file.
2. Model Fitting — Configure parameters, train candidate models, backtest with holdout periods, and inspect leaderboard diagnostics.
3. Forecasting — Review BOY planning forecasts, residual-scaled confidence intervals, and run periodic same-method reforecasts.
Key Concepts
Wide Format
A table where each metric is a column: date, channel, persona, weekly_active_users, new_trials. This is the default workflow.
Fitting Levels
Aggregate: Fit the total directly. Segments Rollup: Fit each segment independently, then sum to produce the total forecast.
Backtesting
Holdout the most recent N periods, fit on the remaining history, then measure forecast accuracy on the withheld actuals.
Governed Run Metadata
API-backed forecasts include data-quality status, selected method version, parameter hash, lineage IDs, draft approval state, and backtest artifact references.
Confidence Intervals
Use holdout residual scale and horizon growth to produce clear confidence intervals around the fitted model.
API Reference
Base URL & Auth
Production: https://forecasting-agent-platform-154742125932.us-central1.run.app/api. Local development uses http://127.0.0.1:8000 behind the Vite proxy. Authenticated endpoints require Authorization: Bearer <token>; public demo endpoints use X-Demo-Session and are limited to bundled demo data.
Data & Session Endpoints
POST /auth/frictionless-login issues a user-scoped bearer token. POST /metrics/upload-csv-text registers custom CSV data for an authenticated tenant. POST /demo/metrics/upload-csv-text registers bundled demo data without login. GET /datasets/latest restores the latest authenticated dataset.
Forecast Execution
POST /forecasts/run accepts metric_id, segment_id, method_id, frequency, horizon_periods, holdout_periods, interval_width, selection_metric, optional training_start_date/training_end_date, and model parameters. POST /demo/forecasts/run runs the same contract for public demo sessions.
Snapshots, Reports & Agent
POST /forecasts/snapshot saves a governed forecast artifact. GET /forecasts/snapshots lists saved artifacts. POST /forecasts/compare-snapshots compares original and refreshed plans. POST /ai/e2e-report creates a grounded report. POST /agent/run lets the LLM plan, critique, narrate, and orchestrate while Python owns the math.
Operational Endpoints
GET /health checks service health. GET /api/agent/manifest discovers the agent contract. GET /api/mcp/tools and POST /api/mcp/call expose the MCP-compatible tool layer.
MCP Server Configuration
Server Setup
Use mcp_config.example.json as the client setup template. The hosted MCP-compatible HTTP server exposes tools through GET /api/mcp/tools and executes them through POST /api/mcp/call. Production calls require Authorization: Bearer <token> from Connect or a service API token.
Source Of Truth
Tool discovery is generated from backend/forecasting_platform/mcp_contract.py. The current contract is version 0.3.0 and mirrors the authenticated API contracts for CSV ingestion, forecast execution, training windows, selection metrics, snapshots, business reviews, and E2E reports.
Available Tools
forecasting.list_metrics, forecasting.upload_csv_text, forecasting.actual_summary, forecasting.run_forecast, forecasting.create_snapshot, forecasting.list_snapshots, forecasting.compare_snapshots, forecasting.business_review, and forecasting.e2e_report.
Agent Workflow Pattern
MCP clients should let the LLM inspect available metrics, select a valid forecast request, call Python-backed forecast tools, critique diagnostics, and then produce a narrative. Forecast math, confidence intervals, model scoring, snapshot immutability, and tenant boundaries remain in the backend.
