How sairishi-exe/marvel-ai-backend works
Project Overview and Type
• This is a backend application built using FastAPI that powers the Marvel AI Platform.
• The application is focused on processing various “assistant” and “tool” functionalities used to generate assignments, flashcards, quizzes, presentations, and more.
• It integrates with external services such as Google Cloud (Vertex AI and AI Studio) and uses Docker for containerization.
• The overall architecture is modular, with clear separations between API endpoints, service logic, specialty assistants, and tools.
Breaking Down the File Structure
• The top-level “app” folder is the core of the application. Inside, you have several important sub-components:
• The “api” directory: Contains the FastAPI router (router.py) and error handlers.
• The “assistants” directory: Contains various assistant implementations (organized by groups, e.g., classroom_support with further subdivisions such as co_teacher).
• The “tools” directory: Contains various tool implementations (e.g., flashcards_generator, lesson_plan_generator, multiple_choice_quiz_generator, document summarizers, etc.), each having its own core logic, prompts, tests, and metadata.
• The “services” directory: Provides the auxiliary service modules (assistant_registry, logger, schemas, tool_registry) that support application functionality.
• The “utils” directory: Contains shared utilities like authentication, document loaders, allowed file extensions, and various prompt management utilities.
• Additionally, there are configuration files for Docker, Google Cloud (app.yaml), environment variables (.env.sample), and deployment scripts (local-start.sh).
Main Components
a. Client & External Interfaces:
• Clients (or external users) making HTTP requests (e.g., via FastAPI’s /docs endpoint).
• External integrations such as Google Cloud’s Vertex AI.
b. API Layer:
• FastAPI application entry point (app/main.py) that routes incoming API calls to the appropriate router in app/api/router.py.
• Error handling using error_utilities.py.
c. Business Logic & Services:
• Service modules in app/services for logging, assistant and tool registries, and schema management.
• These components centrally coordinate requests between the API and the underlying functional modules.
d. Assistants and Tools Modules:
• The “assistants” directory – each assistant (like the co_teacher module within classroom_support) is a self-contained unit with its prompts, core logic, testing, etc.
• The “tools” directory – each tool (such as flashcards generator, notes generator, lesson plan generator, etc.) represents a specialized processing unit for generating educational content.
• The tools share common utilities (e.g., tool_utilities.py in the tools/utils subfolder).
e. Utility Modules:
• Helpers like authentication, file extension verification and document loaders.
f. Deployment and Environment:
• Docker: Represent the Docker container (Dockerfile and Docker run commands) that encapsulates the backend service.
• Environment configuration (.env, app.yaml) showing how critical runtime variables (like API keys and project IDs) are injected.
Relationships and Data Flow
• The API layer forwards validated requests to a service layer which, depending on the request, calls one or more assistant or tool modules.
• Tools and assistants might interact with shared utilities (e.g., for document loading or prompt processing) and each assistant/tool can have unit tests (indicating built-in quality validations).
• External communication with Google Cloud is abstracted within the services configuration and environment variables.
Architectural Patterns and Design Principles
• Modular structure: The separation into “assistants,” “tools,” “services,” and “utils” suggests a plug-and-play, modular design that allows for adding new functionalities easily.
• API Driven: Built around FastAPI, it maintains clear boundaries between the API interface and internal processing services.
• Containerized Deployment: The presence of Dockerfile, app.yaml, and associated deployment scripts underscores the portability and encapsulation of the runtime environment.