INTEGRATION_GUIDE.md

🧠 HALE API Integration Guide (Next.js, Flutter, React, Mobile)

Welcome! This guide outlines how to integrate the HALE (Adaptive Learning Engine) backend into any frontend application. The HALE backend is a production-grade FastAPI app with a Reinforcement Learning engine that dynamically customizes study plans.

---

🌐 Server Details

• Production API URL: https://raunak211006-hale-api.hf.space
• Swagger Documentation: https://raunak211006-hale-api.hf.space/docs
• Response Format: JSON only.
• Authentication: JWT Bearer token in headers: Authorization: Bearer <token>

---

🔄 The Complete Lifecycle Flow

To build a seamless interface, your frontend should follow this logical flow:

graph TD
    A[1. Auth: Login/Register] -->|JWT Token| B[2. Setup: Create Goals & Timetable]
    B --> C[3. Daily Plan: Fetch Today's Tasks]
    C -->|If tasks pending| D[4. Work: Complete Tasks & Update State]
    D -->|Award XP + RL Reward| C
    C -->|If all tasks done| E[5. Day Close: Done for Today]
    E -->|Unlock Next Day Preview| F[6. Next Day Preview]

---

🛠️ Step-by-Step Implementation

1. Authentication (Login & JWT Store)

Save the access_token and refresh_token in localStorage, secure_store, or cookies.

Request Example (Javascript/Typescript):

const API_URL = "https://raunak211006-hale-api.hf.space";

// 1. Register User
async function registerUser(userId: string, password: string, email?: string) {
  const res = await fetch(`${API_URL}/api/auth/register`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ user_id: userId, password, email })
  });
  return res.json();
}

// 2. Login User
async function loginUser(userId: string, password: string) {
  const res = await fetch(`${API_URL}/api/auth/login`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ user_id: userId, password })
  });
  const data = await res.json(); // returns { access_token, refresh_token }
  
  if (data.access_token) {
    localStorage.setItem("access_token", data.access_token);
    localStorage.setItem("refresh_token", data.refresh_token);
  }
  return data;
}

---

2. Authenticated Fetch Helper

Use this helper to automatically inject the Bearer token into all headers:

async function fetchWithAuth(endpoint: string, options: RequestInit = {}) {
  const token = localStorage.getItem("access_token");
  const headers = {
    "Content-Type": "application/json",
    ...(token ? { "Authorization": `Bearer ${token}` } : {}),
    ...options.headers,
  };

  const response = await fetch(`${API_URL}${endpoint}`, { ...options, headers });
  
  if (response.status === 401) {
     // Handle expired token: refresh token logic goes here
     console.error("Session expired. Redirect to login.");
  }
  
  return response.json();
}

---

3. Create a Learning Goal

Curriculum plans are generated by Gemini AI instantly based on the prompt.

async function createGoal(goalText: string, days = 30, priority = 1) {
  return fetchWithAuth("/api/goals/", {
    method: "POST",
    body: JSON.stringify({
      goal: goalText,             // e.g. "Master React and Typescript"
      duration_days: days,
      priority: priority          // Higher priority (1) gets more study allocation
    })
  });
}

---

4. Fetch the Daily Plan

This returns today's tasks and the Reinforcement Learning behavior engine's state parameters.

async function getDailyPlan() {
  return fetchWithAuth("/api/plan");
}

JSON Response Schema:

{
  "date": "2026-05-21",
  "tasks": [
    "Core: Learn JSX Syntax (~40 min)"
  ],
  "tasks_detail": [
    {
      "type": "core",
      "title": "Learn JSX Syntax",
      "est_min": 40,
      "deliverable": "Build static portfolio header",
      "goal_id": 1,
      "goal_label": "React.js Mastery",
      "date": "2026-05-21"
    }
  ],
  "behavior": {
    "action_label": "Normal",
    "intensity": 0.65,
    "mood": 0.8,
    "fatigue": 0.1,
    "cold_start": false,
    "plateau_detected": false
  },
  "coach_message": "Awesome energy today! Let's conquer this first React building block.",
  "streak": 5,
  "total_minutes": 40,
  "goals_count": 1,
  "next_day_preview": null
}

---

5. Mark a Task Complete (Triggers RL reward)

When completing a task, the RL engine modifies user parameters (alpha/beta parameters) based on task duration and subjective satisfaction.

async function completeTask(date: string, goalId: number, durationMin: number, satisfaction: number) {
  return fetchWithAuth("/api/complete-task", {
    method: "POST",
    body: JSON.stringify({
      date: date,                    // YYYY-MM-DD from tasks_detail
      goal_id: goalId,               // goal_id from tasks_detail
      actual_duration_min: durationMin,
      satisfaction: satisfaction,    // Float between 0.0 (hated it) to 1.0 (loved it)
      notes: "Completed all code challenges!"
    })
  });
}

Note: If all_completed is returned as true in the response, you can immediately notify the user and transition them to the next day's preview.

---

6. Done For Today (Close Day Manually)

Forces manual closure of the day. All remaining tasks are completed, streak counts are updated, and the Next Day's Preview is generated.

async function closeDay() {
  return fetchWithAuth("/api/day/complete", { method: "POST" });
}

Day Close Response Sample:

{
  "closed": 1,
  "message": "Day closed. 1 task(s) marked as done.",
  "date": "2026-05-21",
  "streak": 6,
  "xp_gained": 15,
  "total_xp": 450,
  "level": 3,
  "leveled_up": false,
  "next_day_preview": {
    "action_label": "Deep Work",
    "intensity": 0.85,
    "preview": true
  }
}

---

7. Get Tomorrow's Preview Explicitly

Fetch a preview of tomorrow's focus and adaptive intensity without actually progressing the current state.

async function getNextDayPreview() {
  return fetchWithAuth("/api/plan/next");
}

---

⚡ Real-Time Adaptive Feedback State

You should allow the user to input their behavioral metrics periodically (e.g., mood, fatigue, sleep quality). This recalibrates the Reinforcement Learning engine instantly:

async function updateBehaviorState(mood: number, fatigue: number, stress: number, sleepQuality: number) {
  return fetchWithAuth("/api/update-state", {
    method: "POST",
    body: JSON.stringify({
      mood: mood,                 // 0.0 to 1.0
      fatigue: fatigue,           // 0.0 to 1.0
      stress: stress,             // 0.0 to 1.0
      sleep_quality: sleepQuality // 0.0 to 1.0
    })
  });
}

Call this when a user changes their status slider. The next call to /api/plan will return adapted durations based on these metrics.

---

📊 Summary Table of API Endpoints

Resource	HTTP Method	Endpoint	Description
Auth	POST	/api/auth/register	Register new user
Auth	POST	/api/auth/login	Login and get tokens
Goals	POST	/api/goals/	Create a goal with AI syllabus
Goals	GET	/api/goals/	List user goals
Daily Plan	GET	/api/plan	Fetch current adaptive daily tasks
Tasks	POST	/api/complete-task	Mark task completed (awards XP/RL)
Tasks	POST	/api/skip-task	Skip a task
Lifecycle	POST	/api/day/complete	Complete day & generate next preview
Lifecycle	GET	/api/plan/next	Preview tomorrow's focus
Lifecycle	GET	/api/day/status	Today's completion details
Analytics	GET	/api/stats	Gamification stats (level, XP, streaks)
Behavior	POST	/api/update-state	Update mood/fatigue to adapt engine

---

🛡️ Production Security Checklist

1. Always keep the Hugging Face SECRET_KEY secret.
2. In production, always set the connection string DATABASE_URL to the Neon PostgreSQL cluster.
3. CORS configuration allows * by default for testing. You can restrict it in Space Settings to only allow your domain (e.g. https://my-lifeos-app.vercel.app).