Biometric data in. Cognitive predictions out.
The intelligence layer for wearable health data.

---

What is FocusFuel?

FocusFuel is a developer API that transforms raw wearable health data (HRV, sleep stages, training load) into actionable cognitive performance predictions. You send biometric data, we return science-backed insights.

Built for developers building productivity apps, coaching platforms, and health dashboards.

Your App  →  POST /v1/predict/energy-curve  →  { peak_window: "09:00-12:00", curve: [...] }

Endpoints

POST /v1/predict/energy-curve

Predicts your 24-hour energy curve using the Two-Process Model (Borbely, 1982) — combining homeostatic sleep pressure with circadian rhythm harmonics.

curl -X POST https://api.focusfuel.dev/v1/predict/energy-curve \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ff_live_..." \
  -d '{
    "wake_time": "06:30",
    "sleep_duration": 7.5,
    "sleep_stages": {"deep": 1.5, "rem": 2.0, "light": 3.5, "awake": 0.5},
    "hrv_avg": 65,
    "chronotype": "intermediate"
  }'

Response:

{
  "curve": [
    {"hour": 0, "energy": 22.3, "label": "low"},
    {"hour": 9, "energy": 87.1, "label": "peak"},
    {"hour": 14, "energy": 45.2, "label": "moderate"}
  ],
  "peak_window": "09:00-12:00",
  "dip_window": "14:00-15:30"
}

POST /v1/predict/readiness

Recovery readiness score from HRV baselines, sleep quality, and prior load.

curl -X POST https://api.focusfuel.dev/v1/predict/readiness \
  -H "Content-Type: application/json" \
  -d '{
    "hrv": 68,
    "hrv_baseline_7d": 62,
    "hrv_baseline_30d": 59,
    "sleep_score": 82,
    "previous_day_load": 450
  }'

{
  "readiness_score": 76.4,
  "recommendation": "You're well-recovered. Great day for high-intensity work or training.",
  "zone": "green"
}

POST /v1/compute/acwr

Acute:Chronic Workload Ratio using EWMA method (Williams et al., 2017). Send 28+ days of load data.

curl -X POST https://api.focusfuel.dev/v1/compute/acwr \
  -H "Content-Type: application/json" \
  -d '{
    "daily_loads": [400, 420, 380, 450, 500, 0, 350, ...]
  }'

{
  "acwr": 1.12,
  "zone": "sweet_spot",
  "trend": "stable",
  "recommendation": "Optimal loading zone. Maintain current progression."
}

Zone	ACWR	Meaning
undertraining	< 0.8	Detraining risk
sweet_spot	0.8 - 1.3	Optimal adaptation
overreaching	1.3 - 1.5	Elevated injury risk
danger	> 1.5	High burnout/injury risk

POST /v1/predict/burnout-risk

Multi-factor burnout probability with contributing factor analysis and intervention recommendations.

curl -X POST https://api.focusfuel.dev/v1/predict/burnout-risk \
  -H "Content-Type: application/json" \
  -d '{
    "acwr": 1.45,
    "hrv_trend_7d": -0.18,
    "sleep_debt_14d": 9.5,
    "rest_days_last_30": 3
  }'

{
  "risk_probability": 0.72,
  "risk_level": "high",
  "contributing_factors": [
    {"factor": "ACWR", "severity": "moderate", "detail": "ACWR 1.45 indicates overreaching (1.3-1.5)"},
    {"factor": "HRV Trend", "severity": "moderate", "detail": "HRV declined 18% over 7 days"},
    {"factor": "Sleep Debt", "severity": "high", "detail": "9.5h sleep debt over 14 days"},
    {"factor": "Rest Days", "severity": "high", "detail": "Only 3 rest days in 30 days (recommend 8+)"}
  ],
  "intervention": "Significant risk detected: Take a rest day within 48h, reduce load by 30%, focus on sleep quality and stress management."
}

The Science

Algorithm	Based On	What It Does
Energy Curve	Two-Process Model (Borbely, 1982)	Process S (sleep homeostasis) + Process C (circadian rhythm with 2nd harmonic for post-lunch dip)
Readiness	HRV Research (Plews et al., 2013)	Weighted composite: 40% acute HRV deviation, 20% chronic HRV deviation, 30% sleep, 10% load
ACWR	EWMA Method (Williams et al., 2017)	Exponentially weighted 7d acute / 28d chronic ratio with Gabbett zone thresholds
Burnout Risk	Multi-Factor Model	Sigmoid-transformed weighted sum of ACWR, HRV trend, sleep debt, and rest frequency

Quickstart

# Clone
git clone https://github.com/lonexreb/FocusFuel-API.git
cd FocusFuel-API

# Setup
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run
uvicorn app.main:app --reload

# Test
pytest tests/ -v

Visit http://localhost:8000/docs for interactive Swagger documentation.

Project Structure

app/
├── main.py                    # FastAPI entry point + health check
├── algorithms/
│   ├── energy_curve.py        # Two-process model with chronotype & HRV
│   ├── readiness_score.py     # HRV baseline deviation composite
│   ├── acwr.py                # EWMA acute:chronic workload ratio
│   └── burnout_risk.py        # Multi-factor sigmoid risk model
├── models/
│   ├── requests.py            # Pydantic v2 request validation
│   └── responses.py           # Typed response schemas
├── routers/
│   ├── predict.py             # /energy-curve endpoint
│   ├── readiness.py           # /readiness endpoint
│   ├── acwr.py                # /acwr endpoint
│   └── burnout.py             # /burnout-risk endpoint
└── middleware/                 # Auth + rate limiting (coming soon)

Tech Stack

Layer	Technology	Why
Framework	FastAPI	Async, auto-docs, Pydantic validation, 15K+ req/s
Computation	NumPy + SciPy	Industry-standard numerical computing
Validation	Pydantic v2	Rust-powered, type-safe request/response models
Database	Neon (Serverless Postgres)	Scale-to-zero, pay-per-compute, no vendor lock-in
Rate Limiting	Upstash Redis	HTTP-based, sliding window, serverless-native
Hosting	Railway	Zero-config deploys, no cold starts
Payments	Stripe	Usage-based metered billing
Docs	Mintlify + OpenAPI	Beautiful public docs + auto-generated Swagger

Pricing

Tier	Price	Rate Limit
Free	$0	100 calls/day
Developer	$49/mo	10,000 calls/day
Scale	$199/mo	100,000 calls/day
Enterprise	Custom	Unlimited

License

MIT