Amala Atlas

• 

  amalaAtlas_landing_page

Inspiration

The inspiration for Amala Atlas comes from a deep appreciation for Nigerian cultural heritage and the challenges of preserving and accessing culinary traditions in a digital world. Amala, a staple swallow food, is more than just a meal; it's a cultural experience. Yet, finding authentic, high-quality amala spots, especially outside of Nigeria, relies on scattered word-of-mouth recommendations. We wanted to create a definitive, community-driven "atlas" to map out these cultural gems, making it easy for anyone, anywhere, to find their next great amala meal.

What it does

Amala Atlas is an AI-powered discovery platform that helps users find and contribute to a growing database of authentic amala restaurants. It features:

A Conversational AI Expert: Users can chat with the "Amala Connoisseur," an agent powered by Google's Gemini model, to ask for recommendations in natural language (e.g., "Find amala spots near Yaba").

Intelligent Location Search: The agent uses the Google Maps Places API to find restaurants near any specified location, enriching a local, persistent knowledge base with each search.

Community-Driven Contributions: A user-friendly modal allows anyone to submit a new amala spot, complete with location details autocompleted by Google, which gets added directly to our shared database.

Direct Data Access: A fast, deterministic REST API provides a complete list of all known restaurants, enabling rich frontend experiences like interactive maps. The list of restaurants (actually an MCP resource) is populated via the tool that the AI agent calls while responding to user queries

How we built it

We built Amala Atlas on a modern, decoupled, and agentic architecture:

AI Agent(amala_finder_agent): The core conversational experience is powered by Google's Agent Development Kit (ADK) using the Gemini 2.0 Flash model.

Tools & Resources: The agent's capabilities are provided by a separate MCP (Model Context Protocol) server. This server exposes custom tools (like find_amala_restaurants) and resources (like restaurants://all) that the agent can intelligently choose to use.

Chat interface: The user interacts directly with the Agent using the Chat interface. The agent intelligently decides which of the MCP Server's available tools and resources to utilize.

Data API: We built a separate FastAPI server to provide a direct, reliable REST API (GET /restaurants, POST /restaurants). This handles simple data fetching and submission, separating it from the agent's complex reasoning tasks.

Data Source & Persistence: The Google Maps Places API (Nearby Search & Place Details) is our primary source for discovering and enriching location data. All found and submitted restaurants are saved to a JSON file which acts as our persistent database for the hackathon.

Frontend: The interactive modal was designed with React/Next.js and TypeScript, using a custom LocationAutocomplete component.

Environment: The entire Python backend is managed with uv, the high-performance package installer and virtual environment manager.

Challenges we ran into

Our biggest challenge was bridging the gap between the non-deterministic nature of LLMs and the need for reliable application behavior.

Agent Reliability: Our initial plan to use a spaCy NER model to extract locations failed on specific local addresses. We pivoted to an LLM-only extraction approach, which required refining the agent's instructions to be highly explicit about its workflow to ensure consistency.

CORS & Web Errors: We ran into classic web development hurdles with Cross-Origin Resource Sharing (CORS) when connecting our frontend to the ADK server, requiring us to debug preflight requests and configure the server correctly.

Decoupling the API: We realized that asking the agent to simply "list all restaurants" was unreliable. The agent would sometimes try to be "too smart" and use the wrong tool. This led to a key architectural decision: building a separate FastAPI endpoint for deterministic tasks, which proved to be a much more robust solution.

Accomplishments that we're proud of

We are most proud of designing a hybrid AI architecture. We didn't just build a chatbot; we built a system that uses a conversational agent for complex discovery tasks and a standard REST API for simple, reliable data access. This separation of concerns is a powerful and scalable pattern. We're also proud of the dynamic knowledge base—the system gets smarter and its database grows with every user search and submission, creating a virtuous cycle of data enrichment.

Built With

• adk
• fastapi
• mcp
• nextjs
• tailwind