Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/vruizz22/innova-ai-engine/llms.txt

Use this file to discover all available pages before exploring further.

The innova-ai-engine deploys ten Lambda functions from a single container image built with Dockerfile.lambda. Each function is registered in serverless.yml under its own entry point — a Python module inside src/pipeline/ — but every invocation loads the exact same image. This approach eliminates cold-start image variance between workers and ensures that native dependencies (pypdfium2, pillow, scipy) are identical across the fleet. Functions are triggered by two mechanisms: SQS event-source mappings (for processing queues owned by the backend stack) and EventBridge scheduled rules (cron expressions, for nightly and hourly background jobs). One function, health, is triggered over HTTP through API Gateway and the custom domain ai.superprofes.app.

​
Function reference table

FunctionTriggerQueue / ScheduleBatch sizeTimeoutMemoryHandler module
healthHTTP GETai.superprofes.app/health—10 s128 MBsrc.pipeline.health
llmClassifierSQSllm-classify-queue20300 s512 MBsrc.pipeline.llm_consumer
nightlyBktEventBridgecron(0 7 * * ? *)—900 s1024 MBsrc.pipeline.nightly_bkt
nightlyIrtEventBridgecron(15 7 * * ? *)—900 s1024 MBsrc.pipeline.nightly_irt
hourlyAlertsEventBridgecron(0 * * * ? *)—900 s1024 MBsrc.pipeline.hourly_alerts
ocrWorkerSQSocr-queue560 s512 MBsrc.pipeline.ocr_worker
guideIngestSQSguide-ingest-queue1600 s2048 MBsrc.pipeline.guide_ingest_worker
solutionGeneratorSQSsolution-generation-queue1600 s1024 MBsrc.pipeline.solution_generator
submissionGraderSQSsubmission-grade-queue5120 s512 MBsrc.pipeline.submission_grader
exerciseGeneratorSQSexercise-generate-queue1300 s512 MBsrc.pipeline.exercise_generator
The llmClassifier, ocrWorker, submissionGrader, guideIngest, solutionGenerator, and exerciseGenerator functions all use functionResponseType: ReportBatchItemFailures, meaning a failed item is reported individually rather than failing the entire batch.

​
Shared container image

All functions reference the same ECR image defined in the provider.ecr block of serverless.yml: 
provider:
  ecr:
    images:
      ai-engine-image:
        path: ./
        file: Dockerfile.lambda
Each function overrides the entry command: 
functions:
  nightlyBkt:
    image:
      name: ai-engine-image
      command:
        - src.pipeline.nightly_bkt.handler
This means a single docker build and docker push to ECR updates all ten functions simultaneously on sls deploy.

​
Health endpoint

The health function responds to GET /health at the custom domain ai.superprofes.app. It returns a static JSON body and requires no database access: 
{
  "status": "ok",
  "service": "innova-ai-engine"
}
Verify the deployment at any time with: 
curl -s https://ai.superprofes.app/health
Expected response: 200 OK with the payload above.

​
Invoking a handler locally

Lambda handlers are plain Python callables that take (event, context). You can invoke any of them directly with uv run by passing a simulated event dict and None as the context: 
uv run python -c "from src.pipeline.nightly_bkt import handler; handler({}, None)"
Replace nightly_bkt with any other handler module (e.g., nightly_irt, hourly_alerts). SQS-triggered workers accept a standard SQS event envelope: 
event = {
    "Records": [
        {
            "messageId": "abc123",
            "body": '{"attempt_id": "..."}',
            # ...
        }
    ]
}
Running handlers locally that interact with Postgres or external APIs requires a valid .env file with DATABASE_URL, ANTHROPIC_API_KEY, and/or GEMINI_API_KEY set. See the project README for local setup instructions.

​
Unimplemented worker: adhoc_solver

The src/adhoc_solver/ package (A10) exists in the repository and is fully implemented, but it is not currently registered as a function in serverless.yml. It is reserved for a future ad-hoc scan-solving feature and will be wired into the deployment when that use case is activated in production.

​
Individual worker pages

Nightly BKT

EventBridge cron that recalibrates BKT parameters for every active skill nightly at 07:00 UTC.

Nightly IRT

EventBridge cron that fits 2PL IRT parameters for every exercise with ≥50 attempts at 07:15 UTC.

Hourly Alerts

EventBridge cron that detects at-risk students and class-level patterns every hour.

LLM Classifier

SQS worker that classifies student attempt errors against the error taxonomy using Claude Haiku in batches of 20.

OCR Worker

SQS worker that transcribes handwritten math submissions using Gemini 2.5 Flash with automatic Claude vision escalation.

Guide Ingest

SQS worker that extracts math questions from uploaded worksheet PDFs using Gemini precheck and Claude Sonnet.

Solution Generator

SQS worker that builds step-by-step solution keys for extracted guide questions using Claude Sonnet.

Submission Grader

SQS worker that transcribes and grades student photo submissions using Claude Haiku vision.

Exercise Generator

SQS worker that generates new math exercises on teacher request using Claude Haiku forced tool_use.

Build docs developers (and LLMs) love

Get started for freeTalk to us