# 🧠 HALE — Adaptive Learning Engine: System Architecture This document serves as a comprehensive architectural guide for the HALE (LifeOS-2) backend and system structure. It is designed to provide full context to any AI tool or developer building new components, models, or frontends on top of this common backend. --- ## 1. System Overview HALE is a FastAPI-based AI-powered adaptive learning engine. The backend is designed to be **model-agnostic** on the consumer side, meaning it can serve multiple different frontends or applications (e.g., the primary web app, a mobile app, or other AI agents). The core differentiator of this backend is its **Reinforcement Learning (RL) behavioral engine** combined with **LLM-driven (Gemini) curriculum generation**, which dynamically scales learning tasks based on user behavior, mood, and fatigue. ### Tech Stack - **Framework:** Python 3.12, FastAPI - **Database:** PostgreSQL 16 (Relational DB) via SQLAlchemy ORM & Alembic (Migrations) - **Caching & Rate Limiting:** Redis 7 - **AI Integration:** Google Gemini (LLM) for curriculum and lesson generation - **Containerization:** Docker & docker-compose --- ## 2. Directory Structure ```text lifeos-2/ ├── app/ # Core Backend Application │ ├── api/ # FastAPI Routers (Controllers) │ ├── core/ # App config, DB setup, Auth/Security, Middleware │ ├── models/ # SQLAlchemy DB Models (Schema) │ ├── schemas/ # Pydantic Models (Validation / Serialization) │ ├── services/ # Core Business Logic (LLM, RL, Planner) │ └── main.py # App entry point, lifecycle, and middleware ├── alembic/ # DB Migration scripts ├── data/ # Local volume mounts ├── hale-frontend/ # Next.js 14 Frontend Application ├── tests/ # Pytest Suite ├── docker-compose.yml # Container orchestration └── requirements.txt # Python dependencies ``` --- ## 3. Database Schema The database uses PostgreSQL. All models inherit from SQLAlchemy's declarative base. ### 3.1 `User` (`app/models/user.py`) Central entity managing authentication, gamification, and the user's RL state. - **Identity & Security:** `user_id`, `email`, `hashed_password`, `refresh_token`, lockout mechanics (`locked_until`, `failed_login_count`). - **Behavioral State:** `mood`, `fatigue`, `stress`, `sleep_quality`, `competence`, `shock`, `sick`. (Values between 0.0 and 1.0). - **RL Decision State:** `current_action_label` (e.g., "Deep Work", "Recovery"), `current_intensity`, `rl_bandit_params` (Thompson Sampling data). - **Gamification:** `xp`, `level`, `current_streak`, `longest_streak`. - **Schedule:** `schedule_json` storing available learning blocks per day. ### 3.2 `Goal` (`app/models/goal.py`) Represents a learning target or objective set by the user. - **Relational:** Belongs to `user_id`. - **Content:** `goal_text` (e.g., "Learn Python"), `category`, `duration_days`. - **Generated Plan:** `plan_json` stores the entire AI-generated curriculum. - **Tracking:** `is_active`, `is_completed`, `completion_pct`. ### 3.3 `Progress` (`app/models/progress.py`) Tracks the daily plan and task execution. - **Relational:** Belongs to `user_id` and `goal_id`. - **Daily Content:** `date` (YYYY-MM-DD), `module`, `topic`, `tasks` (JSON list). - **State Snapshot:** Snapshots the behavioral state at the time of creation (`mood`, `fatigue`, `action_label`, `intensity`). - **Completion Data:** `completed`, `actual_duration_min`, `satisfaction`, `notes`. --- ## 4. Core Services (Business Logic) The heavy lifting is separated from the API routing into dedicated services (`app/services/`). ### 4.1 `rl_engine.py` (Behavioral Adaptation) - Evaluates the user's 7-dimensional behavioral state. - Uses **Thompson Sampling** (a multi-armed bandit approach) to dynamically select an `action_label` (Recovery, Light Review, Normal, Deep Work, Exploration). - Adjusts `intensity` to define how hard the daily plan should push the user. ### 4.2 `llm_service.py` (AI Generation) - Wraps the Google Gemini API. - Converts high-level goals into structured curricula (`generate_plan`). - Generates localized, micro-learning lessons based on the daily topic (`generate_lesson`). ### 4.3 `planner.py` (Daily Engine) - Combines the Goal's JSON curriculum, the RL Engine's intensity, and the User's schedule. - Extracts the exact tasks for the day and creates `Progress` records. - Handles streak calculations and XP distribution upon task completion. ### 4.4 `day_closer.py` - A background scheduler (APScheduler configured in `main.py` running at 2 AM IST). - Auto-closes pending tasks for the day, resets streaks if tasks are missed, and updates competence decay. --- ## 5. API Endpoints The API is fully RESTful and versioned implicitly via FastAPI routes. Secured routes require a JWT Bearer Token. ### `/api/auth` - `POST /register`: Account creation with rate-limiting. - `POST /login`: Returns JWT access and refresh tokens. - `GET /profile`: Fetch the current user data (including RL state & XP). - `PATCH /profile`: Update schedule or coach personality. ### `/api/goals` - `POST /`: Submit a goal text. Triggers `llm_service` to generate a curriculum. - `GET /`: List active goals. - `PATCH / {id}`: Update priorities. ### `/api/schedule` - (Implicit in `user.py` / `auth.py` but handles schedule blocking/unblocking). ### `/api/plans` (or `/api/progress`) - `GET /plan`: Fetches today's plan. If one doesn't exist, invokes `planner.py` and `rl_engine.py` to construct it dynamically. - `POST /complete-task`: Marks tasks as done, distributes XP, checks for level-ups. - `POST /update-state`: Endpoint to manually ping the backend with new mood/fatigue metrics. - `GET /behavior`: Exposes the current RL parameters. - `GET /stats`: Aggregated statistics for frontend charts. --- ## 6. How to Integrate New AI Models / Apps When plugging in new AI models or frontend clients to this backend: 1. **Authentication:** Use `/api/auth/login` to obtain the JWT token. Pass it as `Authorization: Bearer ` in subsequent requests. 2. **Behavioral Sync:** Continuously feed the user's state to the backend using `/api/plans/update-state` so the `rl_engine` remains accurate. 3. **Task Fetching:** Only rely on `/api/plan` for the daily tasks. Do not attempt to parse the Goal's raw curriculum on the client side; let `planner.py` handle the intensity adaptation. 4. **Data Models:** Do not bypass the FastAPI endpoints. Direct database interaction from a secondary app will cause the RL engine and Streak logic to fall out of sync. Use the provided REST APIs.