Alea01901/alea-api

┌─────────────────────────────────────────────────────────────────────┐
│                        ALEA SYSTEM ARCHITECTURE                     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  USER INTERFACE                                                     │
│  ┌───────────┐    ┌───────────┐    ┌───────────┐                   │
│  │  Web API  │    │   CLI     │    │  Webhook  │                   │
│  └─────┬─────┘    └─────┬─────┘    └─────┬─────┘                   │
│        └────────────────┼────────────────┘                         │
│                         ▼                                           │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                   LANGGRAPH AGENT PIPELINE                  │   │
│  │                                                             │   │
│  │  [INTAKE] → [SKILL_GRAPH] → [RESOURCE_SELECT] →            │   │
│  │  [TASK_GEN] → [ASSESS] → [MASTERY_SCORE] →                 │   │
│  │  [ADAPTIVE_LOOP] → [DECAY_DETECT] → [PROFILE_UPDATE]       │   │
│  │                                                             │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                         ▼                                           │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐ │
│  │  SKILL GRAPH     │  │  RESOURCE        │  │  COGNITIVE       │ │
│  │  ENGINE          │  │  INTELLIGENCE    │  │  PROFILER        │ │
│  │                  │  │  LAYER           │  │                  │ │
│  │  - Skill nodes   │  │  - Quality score │  │  - Speed         │ │
│  │  - Prerequisites │  │  - Rank/Select   │  │  - Retention     │ │
│  │  - Difficulty    │  │  - Embeddings    │  │  - Consistency   │ │
│  │  - Demand weight │  │  - Vector search │  │  - Profile type  │ │
│  └──────────────────┘  └──────────────────┘  └──────────────────┘ │
│                         ▼                                           │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐ │
│  │  PERSISTENCE     │  │  VECTOR STORE    │  │  SCHEDULER       │ │
│  │  PostgreSQL      │  │  pgvector /      │  │  Weekly Adapt    │ │
│  │  + SQLAlchemy    │  │  Pinecone        │  │  Decay Jobs      │ │
│  └──────────────────┘  └──────────────────┘  └──────────────────┘ │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

START
  │
  ▼
[intake_node]           — Parses goal, skill level, budget, learning style
  │
  ▼
[skill_graph_node]      — Builds domain skill graph with prerequisites
  │
  ▼
[resource_select_node]  — Scores and selects best resources per skill node
  │
  ▼
[task_gen_node]         — Generates micro-tasks per skill node
  │
  ▼
[checkpoint]            — Human-in-the-loop: confirm roadmap
  │
  ▼
[assess_node]           — Generates assessments for completed tasks
  │
  ▼
[mastery_score_node]    — Calculates Skill Confidence Score (0–100)
  │
  ▼
[cognitive_profile_node] — Updates learning speed, retention, consistency
  │
  ▼
[decay_detect_node]     — Detects stale skills, schedules reviisions
  │
  ▼
[adaptive_loop_node]    — Weekly: reweights roadmap, adjusts pace
  │
  ▼
[profile_update_node]   — Persists full skill intelligence profile
  │
  ▼
END (loops back to assess_node on task completion)

SCS = (0.40 × Assessment_Score)
    + (0.30 × Task_Completion_Rate)
    + (0.20 × Self_Reported_Confidence)
    + (0.10 × Recency_Factor)

where Recency_Factor = e^(-λ × days_since_last_activity)
      λ = 0.1 (decay constant)

RQS_youtube = (0.35 × normalized_views)
            + (0.30 × like_ratio)
            + (0.20 × channel_authority_score)
            + (0.15 × recency_score)

RQS_course = (0.40 × rating / 5.0)
           + (0.30 × log(enrollment + 1) / log(max_enrollment + 1))
           + (0.20 × review_count_score)
           + (0.10 × recency_score)

Priority = (1 - SCS/100) × market_demand_weight × (1 + dependency_chain_depth)

adaptive-learning-agent/
├── app/
│   ├── agent/
│   │   ├── graph.py              # LangGraph pipeline definition
│   │   ├── state.py              # Agent state schema
│   │   └── nodes/                # Individual pipeline nodes
│   ├── engines/                  # Core domain logic
│   │   ├── skill_graph_engine.py
│   │   ├── resource_scorer.py
│   │   ├── assessment_engine.py
│   │   ├── mastery_engine.py
│   │   ├── decay_engine.py
│   │   └── cognitive_profiler.py
│   ├── models/                   # SQLAlchemy ORM models
│   ├── api/                      # FastAPI routes
│   ├── services/                 # Business logic services
│   └── utils/                    # LLM client, vector store
├── scripts/
│   ├── seed_domains.py
│   └── weekly_adaptation_job.py
├── tests/
├── docker-compose.yml
└── requirements.txt

# 1. Clone and enter directory
cd adaptive-learning-agent

# 2. Copy environment config
cp .env.example .env
# Edit .env with your API keys

# 3. Start infrastructure
docker-compose up -d postgres redis

# 4. Install dependencies
pip install -r requirements.txt

# 5. Run migrations
alembic upgrade head

# 6. Seed domain knowledge
python scripts/seed_domains.py

# 7. Start the API
uvicorn app.main:app --reload --port 8000

# 8. Start the worker (separate terminal)
celery -A app.worker worker --loglevel=info

# 9. Start the scheduler (separate terminal)
celery -A app.worker beat --loglevel=info