apps/learning-api/README.md

README

LearningAPI V2

📁 Codebase Structure

This is a monorepo with multiple UV projects:

  • shared/ - Common interfaces, types, and utilities used by all services
  • api/ - FastAPI web service (depends on shared)
  • workers/ - Background processing services (depends on shared)
    • learning_agents/ - AI learning worker handling generation tasks
    • parser/ - Document Parsing with Docling

Each directory is an independent UV project with its own pyproject.toml, but all depend on the shared package.

🚀 Getting Started

No setup required! Just open in a codespace and run:

poe dev

Everything is pre-configured and ready to go.

Option 2: Local Development

Prerequisites:

Setup:

  1. Install Poe the Poet:
    uv tool install poethepoet
  2. Login to Infisical:
    infisical login
  3. Set your environment:
    export INFISICAL_ENV=dev
  4. Verify secrets access:
    poe set-secrets
  5. Start development:
    poe dev

🛠️ Development Commands

Local Development (Default - Recommended):

poe dev

Runs API and workers locally with Redis in Docker. All logs in one terminal with color coding and auto-reload on code changes.

Full Docker Environment:

poe dev-docker              # Slim CPU parser stack; requires TRITON_URL
poe dev-docker-parser-gpu   # Legacy local GPU/VLLM parser stack

Other Useful Commands

# Install dependencies for all projects
poe install

# Generate TS types (then copy manually to core-api)
poe update-types 

# Run linting across all projects
poe lint

# Format code across all projects
poe format

# Run type checking
poe typecheck

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

# Run tests with automatic service management (recommended)
poe test-with-services  # Automatically starts test Docker services

# Run CI pipeline (lint + typecheck)
poe ci

🧪 Testing

The project includes comprehensive unit and integration tests:

Test Structure

  • Unit Tests: Located in api/tests/ - Fast, isolated tests for API endpoints
  • Integration Tests: Located in tests_integration/test_integration.py - Service connectivity and end-to-end workflows

Running Tests

Quick Testing (requires services running)

# Start services first
poe dev  # In one terminal

# Run tests in another terminal
poe test              # Run all tests
poe test-unit         # Run unit tests only
poe test-integration  # Run integration tests only

# This command handles all service management automatically
poe test-with-services

When to Run Tests

  • Before committing: Run poe test-unit for quick validation
  • Before pushing: Run poe test to ensure nothing is broken
  • After major changes: Run poe test-with-services for comprehensive validation
  • CI/CD: Tests run automatically on pull requests

🔧 Optional: Pre-commit Setup

For automatic code formatting on commits:

# Install pre-commit
uv tool install pre-commit

# Install git hooks
poe pre-commit-install