How tamaghnadutta/tutor-vision-engine works
Project type and purpose
• This is a backend microservice/API focused on step-level error detection in student handwritten math solutions. It exposes a RESTful endpoint (/api/v1/detect-error) implemented with FastAPI, orchestrates three AI-based approaches (OCR→LLM, Direct VLM, Hybrid), persists request/response data in SQLite, and provides observability via Prometheus and Grafana.
File structure
• Top-level service code lives under src/api/ (FastAPI app, routes, middleware).
• AI logic is in src/models/ (approach implementations, model routing, circuit breakers).
• Data handling modules under src/data/ and src/analytics/ for caching and persistence.
• Configuration in src/config/.
• Tests under testing/.
• Scripts for demo, evaluation, load testing, and analytics are in scripts/.
• Monitoring manifests (prometheus.yml, docker-compose.monitoring.yml) and Grafana dashboards under grafana/.
README insights
• Stateless, horizontally scalable design
• Async processing and background jobs
• Circuit breaker patterns for AI provider fallbacks
• Structured logging, Prometheus metrics, API key auth
• Caching layer for repeated results
Main components
a. Client / Consumer
• Demo scripts, load-test runners, or external UI/CLI
b. API Layer (FastAPI)
• Request validation, authentication middleware (src/api/middleware.py)
• Routing (src/api/routes/error_detection.py)
• Metrics endpoint (/metrics)
• Background workers (async tasks for long-running AI calls)
c. AI-Processing Layer
• Model Router (src/models/model_router.py), Robust Router (robust_model_router.py)
• OCR→LLM module, Direct VLM module (error_detection_approaches.py)
• Gemini processor (gemini_processor.py)
d. Persistence & Caching
• SQLite database (data/analytics.db) via src/analytics/result_storage.py and src/utils/persistence.py
• In-memory or file-based cache with expiration
e. External Services
• OpenAI API (OCR model, reasoning model)
• Google Gemini API
• Optional local image server for sample images
f. Monitoring & Observability
• Prometheus (scrapes metrics from FastAPI)
• Grafana (dashboards under grafana/dashboards/)
• Structured logging (src/utils/logging.py), metrics collection (src/utils/metrics.py)
g. Configuration & Deployment
• Environment variables (.env.sample, src/config/settings.py)
• Dockerfile, docker-compose for service and monitoring stack
Relationships and data flows
1. Client issues HTTP POST → FastAPI
2. FastAPI authenticates (API key), logs request, increments Prometheus counters
3. Route handler enqueues or directly invokes AI-Processing Layer
4. Model Router selects approach based on ERROR_DETECTION_APPROACH env var
5. AI modules call external OpenAI/Gemini APIs (with retries, timeouts, circuit breakers)
6. Results returned to API layer; cache/store in SQLite; cost & token usage computed
7. API responds to client; metrics exported for Prometheus
Architectural patterns & principles
• Stateless REST API for horizontal scaling
• Modular separation: API vs AI logic vs data vs utils
• Circuit breaker and retry patterns for external calls
• Async processing for long-running calls
• Cache-aside pattern for repeated results
• Observability: metrics, logging, dashboards