Velo-Physics Simulation

Inspiration

Physics is often difficult because equations, diagrams, and motion are taught separately. We wanted to create a tutor that brings them together, helping learners move from a question to a clear explanation, guided lesson, or visual animation in one place.

What Velo does

Velo is a local-first AI physics tutor. It supports three learning modes:

Explain: Breaks concepts into structured explanations and equations.
Guide: Teaches through step-by-step questions and interactive lessons.
Visualize: Uses MotionForge’s Prompt Animator to turn physics prompts into rendered animations.

Velo works without an account, offers credential-free local responses, and supports optional Ollama, OpenAI, and Anthropic models. Cloud API keys are stored in the operating system’s secure credential vault.

How we built it

We built the interface with React and Vite, supported by a lightweight Node.js API. The backend manages conversations, lesson state, model providers, animation jobs, and rendered video delivery.

For visualization, Velo launches a packaged Prompt Animator from MotionForge. MotionForge compiles a generated scene description, simulates the physics, and exports an MP4 that Velo embeds in the lesson.

GPT-5.6 assisted development by helping translate requirements into implementation plans, refine the frontend and backend, investigate defects, and review automated tests. Its suggestions were validated against the codebase and tested before being accepted.

Challenges we faced

One major challenge was connecting an interactive web application to a separate animation pipeline while keeping the experience reliable. We needed to manage queued jobs, timeouts, progress updates, failures, cancellation, and video streaming.

Packaging was another challenge. Prompt Animator uses Python, Manim, physics libraries, and native dependencies, while Velo uses Node.js. We addressed this by packaging Prompt Animator as a self-contained executable that can be distributed with Velo.

We also had to support multiple AI providers without exposing credentials or tightly coupling the application to one model. This led us to build a provider abstraction and use the operating system credential vault instead of plaintext configuration files.

What we learned

We learned that a useful AI tutor needs more than generated text. Structured responses, lesson state, visual feedback, safe credential handling, and predictable error recovery all contribute to a trustworthy learning experience.

We also learned the importance of strict boundaries between AI-generated suggestions and verified application behavior. Automated tests, stable API contracts, and human review were essential throughout development.

What’s next

Next, we want to add more physics topics, improve animation quality and rendering speed, provide downloadable lesson materials, and distribute Velo with cross-platform Prompt Animator packages for Windows, macOS, and Linux.