apps/learning-api/AGENTS.md

AGENTS.md

AGENTS.md

Project Overview

LearningAPI V2 is a Python monorepo that generates educational content (flashcards, quizzes, summaries) from documents using AI. It consists of:

  • api/: FastAPI web service providing REST endpoints
  • workers/: Background processing with Celery (learning_agents for AI tasks, parser for document parsing)
  • shared/: Common schemas and utilities used by all services

Essential Commands

# Development
poe dev              # Start API + workers (no parser/OCR)
poe dev-docker       # Start all services with slim CPU parser/OCR (requires TRITON_URL)
poe dev-docker-parser-gpu   # Start legacy local GPU/VLLM parser stack
poe install          # Install dependencies for all services

# Code Quality
poe lint             # Run Ruff linter
poe format           # Format code with Ruff
poe typecheck        # Run Pyright type checking
poe ci               # Run full CI pipeline (lint + typecheck)

# Testing
poe test             # Run all tests
poe test-unit        # Run unit tests only
poe test-integration # Run integration tests only

# Testing with automatic service management
poe test-with-services  # Run all tests (starts test Docker services)

# Other
poe update-types     # Generate TypeScript types from OpenAPI (requires poe dev running)
poe set-secrets      # Pull secrets from Infisical

Architecture

  1. API Service (api/): FastAPI application handling HTTP requests
    • Endpoints: /ingest_document, /generate_flashcards, /generate_quiz, /generate_summary
    • Authentication via X-API-Key header
    • Delegates heavy processing to Celery workers
  2. Worker Services (workers/):
    • learning_agents/: AI-powered content generation using LangChain/LangGraph
      • Separate agents for flashcards, quizzes, summaries, and document ingestion
      • Uses Google Vertex AI and OpenAI models
    • parser/: Document parsing with Docling (optional, GPU-capable)
  3. Shared Package (shared/): Common Pydantic schemas and utilities
    • All services depend on this package for type safety
    • Contains schemas for Chunks, Languages, Subjects, and API contracts
    • IMPORTANT: Since this is a monorepo with separate apps, shared code between API and Workers MUST be placed in the shared package. The API cannot import from workers and vice versa.

Development Workflow

  1. Each service is an independent UV project with its own pyproject.toml
  2. Docker Compose with watch mode enables hot-reloading
  3. Services communicate via Celery/Redis task queue
  4. Strong typing enforced with Pyright and Pydantic

Key Technologies

  • Python 3.12+ (3.10+ for parser due to Docling requirements)
  • UV for package management
  • Poe the Poet for task running
  • FastAPI for REST API
  • Celery + Redis for task queue
  • Docker Compose for local development
  • Ruff for linting/formatting
  • Pyright for type checking

Test Structure

The project follows a distributed testing approach:

  1. Unit Tests: Located within each service directory
    • api/tests/ - API endpoint unit tests with mocked dependencies (13 tests)
    • workers/learning_agents/tests/ - Worker task unit tests (currently empty)
    • workers/parser/tests/ - Parser unit tests (currently empty)
  2. Integration Tests: Located at the root level (tests_integration/)
    • test_integration.py - All integration tests including connectivity checks and complete workflows (10 tests)
    • Tests use pytest markers: @pytest.mark.unit, @pytest.mark.integration, @pytest.mark.slow
  3. Test Configuration:
    • .env - Environment variables (uses same as development)
    • pytest.ini - Pytest configuration with markers and paths
    • Test user: test@email.com / password (from supabase seed)
  4. Running Tests:
    • Option 1: Manual setup
      • Start Supabase and edge functions: cd ~/work/studyflash_v2/apps/supabase && pnpm run dev
        • This runs npx supabase start (predev hook) and serves edge functions
        • If test user doesn't exist, run: pnpm run seed to create test@email.com
      • Start learning-api services: poe dev
      • Run tests: poe test
    • Option 2: Automatic setup (recommended)
      • Use poe test-with-services - automatically stops existing Docker services and starts test-specific ones
      • The test script handles all service management
      • IMPORTANT: Core-api Supabase must still be running separately at http://localhost:54321
        • Without Supabase, only smoke tests will pass (6/7), integration tests will fail
  5. Test Commands:
    • poe test - Run all tests
    • poe test-unit - Run unit tests only
    • poe test-integration - Run integration tests only
    • poe test-with-services - Run all tests with automatic service management

Code Quality Workflow

When making code changes, always follow this workflow to ensure code quality:

  1. After Each Edit: Run linting and type checking for the project you modified
    poe lint        # Check for linting issues
poe typecheck   # Verify type safety
  2. Fix Any Issues: Address all linting and type checking errors before proceeding
  3. Final Step: Once all edits are complete and all checks pass, format the code
    poe format      # Auto-format all code with Ruff

Important: Always run these checks in this order. Format last to ensure consistent code style after all manual fixes.

Important Instructions

  • Package Management: Always use uv add instead of uv pip install when adding dependencies in UV projects
  • File Management: Never create files unless absolutely necessary. Always prefer editing existing files
  • Documentation: Don't create documentation files (*.md) or README files unless explicitly requested
  • Validation: Validate JSON/dict payloads with Pydantic models by default (except when an external library already validates/parses them)
  • Type Safety: Avoid getattr for production code. Prefer typed models, explicit attributes, or typed fallbacks. Use getattr only when interfacing with truly dynamic/unknown objects and document why.