Mentoros

Mentoros is an AI-powered platform that creates personalized learning roadmaps with detailed steps, resources, and milestones to help users master any skill efficiently.

Comment

Inspiration

Traditional education and online courses follow rigid, linear syllabi. When students hit roadblocks or struggle with complex sub-concepts (like Docker volume mapping or database normalization), the curriculum carries on regardless, leaving gaps in their foundation.

We were inspired to build a platform where learning pathways behave like a live, empathetic human tutor:

  • Listens to the student's struggles.
  • Adapts the learning speed and structure.
  • Reorganizes upcoming tasks to build stronger foundational skills.
  • Interactively explains concepts and dynamically updates the path.

MentorOS is the realization of that concept—a self-evolving learning roadmap companion.

What it does

MentorOS provides an integrated workspace where users can:

  • Generate Custom Roadmaps: Define a career goal or topic, and a tailored set of modules with difficulty ratings, estimated hours, mini-projects, and verified links is created.
  • Converse with an AI Mentor: A persistent, context-aware chatbot details concepts, answers coding questions, and dynamically edits the roadmap.
  • Track Milestones & Tasks: Users can check off tasks, write notes, and track overall goal progress.
  • Reflect on Cognitive Gaps: After chat interactions, an offline worker analyzes the conversation, updating the user's cognitive profile with identified "weak areas" and summary reflections to customize future modules.

How we built it

MentorOS utilizes a robust split-service architecture designed for scale, responsiveness, and complex reasoning:

graph TD
    A[Next.js Frontend] -->|REST API Requests| B[FastAPI Backend]
    B -->|User / Auth / Roadmap Data| C[(MongoDB Atlas)]
    B -->|Autonomous Agent Tasks| D[FastMCP Agent Loop]
    D -->|Tool Call / Milestones| C
    D -->|Python Sandbox Execution| E[Subprocess Jail]
    D -->|Reasoning & Tool Calls| F[Google Gemini API]
    C -->|Vector Search Queries| C

1. The Stack

  • Frontend: Next.js (React) styled with Vanilla CSS and Tailwind, providing a premium glassmorphic interface, task sidebars, markdown parser, and state synchronization.
  • Backend: FastAPI (Python) serving secure REST endpoints with JWT-based authorization.
  • Database: MongoDB Atlas to store users, roadmap trees, and historical chat profiles.
  • LLM & Agent Architecture: Google GenAI SDK (google-genai) running Gemini models in a custom ReAct (Reasoning and Acting) execution loop. We leverage Python-native FastMCP servers to expose database search, roadmap mutation, and terminal execution sandboxes as model tools.

2. Mathematical Modeling

  • Semantic Vector Similarity: Verified resources are mapped to vector embeddings ($\mathbf{q}, \mathbf{d} \in \mathbb{R}^{3072}$). We query MongoDB Atlas using cosine similarity to rank recommendations: $$\text{Similarity}(\mathbf{q}, \mathbf{d}) = \frac{\mathbf{q} \cdot \mathbf{d}}{|\mathbf{q}|2 |\mathbf{d}|_2} = \frac{\sum{i=1}^{3072} q_i d_i}{\sqrt{\sum_{i=1}^{3072} q_i^2} \sqrt{\sum_{i=1}^{3072} d_i^2}}$$

  • Progress Metrics: Roadmap completion percentage is computed dynamically: $$\text{Progress \%} = \left( \frac{\sum_{i=1}^{N} \mathbb{I}(\text{status}_i = \text{completed})}{N} \right) \times 100$$ where $\mathbb{I}$ is the indicator function checking if $\text{status}_i = \text{"completed"}$, and $N$ is the total count of milestones.

  • Exponential Backoff with Jitter: Resolves external API rate limiting: $$t_{\text{wait}} = 2^{\text{attempt}} \times t_{\text{base}} + \delta, \quad \delta \sim \mathcal{U}(0, 0.5)$$

Challenges we ran into

1. CORS Preflight Blocks on Deployed Environments

In production, the backend and frontend are hosted on separate domains. Standard wildcard CORS configurations (allow_origins=["*"]) crash FastAPI when credentials are enabled. We solved this by implementing dynamic CORS origin whitelisting configured via server environment variables.

2. LLM Tool-Call Data Overwrites

When asking the chat agent to add a topic, it would overwrite the entire roadmap, saving only the new topic. This occurred because the LLM passed only new items to the database update tool. We resolved this by updating the FastMCP docstrings and system instructions to explicitly command the model to read, merge, and pass the complete state of the roadmap.

3. API Quotas & Transient Failures

Rate-limiting and temporary unavailability on Gemini API calls disrupted testing. We created a resilient model fallback chain (gemini-2.5-flash $\rightarrow$ gemini-2.5-flash-lite $\rightarrow$ gemini-2.5-pro) and wrapped endpoints with exponential backoff algorithms to guarantee uptime.

Accomplishments that we're proud of

  • Autonomous ReAct Agent Loop: Building an agent that actively runs tool loops, updates the database, queries semantic knowledge, and outputs final answers asynchronously in background worker threads.
  • Python Execution Sandbox: Integrating a secure python execution jail so the AI Mentor can write and test code snippets dynamically on behalf of the user.
  • Mathematical Cosine Vector Search: Matching resources instantly using Atlas Vector indexes, resulting in highly relevant, contextual recommendations.
  • High-Performance Build: Creating a Next.js application that compiles into a statically optimized build with zero errors.

What we learned

  • Docstring Schema Engineering: Learning how critical python docstrings are when using FastMCP, as they are translated directly into the LLM's tool calling parameter schemas.
  • State Boundaries in LLMs: Understanding how to separate agent execution tasks from state persistence to prevent database locks and race conditions.
  • Secure Asynchronous Design: Developing background processes in FastAPI that keep the front-end informed of agent steps using non-blocking poll mechanisms.

What's next for Mentoros

  • Interactive Sandbox Quizzes: Allowing the AI Mentor to generate coding challenges evaluated directly inside the secure subprocess jail.
  • Collaborative Roadmaps: Sharing custom roadmaps with friends or teams to track collective learning.
  • Multimodal Video Recommendations: Extending vector search to parse and timestamp YouTube transcript segments for visual learners.
  • Offline Mode: Supporting local SQLite databases and local models for privacy-focused students.

Built With

Share this project:

Updates