For Freshmen and Transfer Students, stepping onto the massive USF campus for the first time is overwhelming. Official maps are designed for people who already know the building codes ("ENC 1002") and exact locations.
New students don't think in coordinates; they think in needs:
- "Where can I find a microwave?"
- "I need to print something before my 10 AM class."
- "Where is the closest place where I can get coffee"
There is currently no search engine at USF that bridges the gap between these vague, everyday questions and the physical campus layout.
BullsPath is an AI-powered navigation agent designed specifically to help newcomers feel at home instantly. Unlike static maps, it listens to natural language requests, understands context, and guides students to resources, not just buildings.
To ensure accessibility and rapid prototyping, we have centralized the entire application---Backend (Python), Logic (AI), and Frontend (React/HTML)---into a single Google Colab environment.
- 🗣️ Natural Language Search: Type like you talk. "Im near the USF library, where can I find a microwave" is a valid search query.
- 🎧 Audio Guide: Generates a friendly spoken guide, perfect for walking across campus without staring at a screen.
- ☁️ Zero-Install/Cloud Native: The entire app lives in the cloud. No downloads required---just open the link and go.
The entire project is contained within a single Jupyter Notebook (Google Colab). This allows us to demo a full-stack application without complex server deployments.
- Environment: Google Colab (Centralized Runtime)
- Brain (AI): Google Gemini 2.0 Flash API (via google-generativeai)
- Navigation Logic: NetworkX (A* Pathfinding on a weighted graph)
- Visualization: Matplotlib (Dynamic map generation)
- Voice: gTTS (Google Text-to-Speech)
- User Interface: HTML5 + Tailwind CSS + Lucide Icons (Generated and served directly from Python)
Since the entire architecture is centralized, running the app is effortless:
- Open the Notebook: Load the USF_SmartNav.ipynb file in Google Colab.
- Set API Key: Add your Gemini API Key in the Colab secrets manager (Key name: GEMINI_API_KEY).
- Install Dependencies: Run the first cell to install the lightweight requirements:
!pip install networkx matplotlib google-generativeai gTTS - Launch: Click "Run All".
- Interact: Scroll to the bottom cell. The AI Agent will process your request, calculate the path, generate the audio, and render the Interactive HTML Interface directly in the notebook output.
- Campus Mapping: Defined 20+ key USF locations (Library, MSC, Beard Garage, etc.) in a coordinate system.
- Connectivity: Built a weighted graph network using networkx to simulate walking paths and shortcuts.
- Intent Parsing: Integrated Gemini 2.0 Flash to translate vague student queries ("I need food") into specific graph nodes.
- Reasoning Engine: Configured the LLM to explain why it chose a specific destination (e.g., "The honors building is closest to you.").
- Dynamic Mapping: Implemented matplotlib to dynamically draw the campus graph and highlight the optimal path in Green/Gold.
- Base64 Encoding: Created pipelines to convert generated images into web-ready formats instantly.
- Frontend Generation: Wrote a Python engine that generates a modern, responsive HTML/Tailwind interface.
- Audio Engine: Implemented Text-to-Speech to provide turn-by-turn voice guidance.
- Integration: Connected all components (AI → Graph → UI) into the single Colab workflow.
- Documentation: Finalizing this README.
- Demo Video: Recording the agent helping a "transfer student" find their first class.