Spaces:
Sleeping
Sleeping
| # 🧠 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 <token>` 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. | |