Getting Started

This guide walks you through setting up and running the AI Ingredient Scanner on your local machine, including both the backend services and optional mobile app.

Prerequisites

Requirement	Version	Purpose
Python	3.11+	Backend runtime
Node.js	18+	Mobile app (optional)
Google Cloud API Key	Gemini	AI model access
Qdrant Cloud	Free tier	Vector database

Backend Setup

Step 1: Clone the Repository

git clone https://github.com/udaytamma/IngredientScanner.git
cd IngredientScanner

Step 2: Create Virtual Environment

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Configure Environment Variables

Create a .env file in the project root with the following configuration:

# Required
GOOGLE_API_KEY=your_gemini_api_key
QDRANT_URL=your_qdrant_cloud_url
QDRANT_API_KEY=your_qdrant_api_key

# Optional (for enhanced features)
REDIS_URL=your_redis_connection_string
LANGCHAIN_API_KEY=your_langsmith_api_key

Getting API Keys

Google Gemini: Google AI Studio
Qdrant Cloud: Qdrant Cloud Console (free tier available)
LangSmith: LangSmith Console (optional, for observability)

Step 5: Verify Connections

python test_connections.py

Step 6: Run the Application

Option A: Streamlit Web Interface

streamlit run app.py

Opens at http://localhost:8501

Option B: REST API

uvicorn api:app --host 0.0.0.0 --port 8000

API available at http://localhost:8000

Mobile App Quick Start

For detailed mobile setup instructions, see the Mobile App Setup Guide.

cd mobile
npm install

# Update API URL in src/services/api.ts with your machine's IP
npx expo start

# Scan QR code with Expo Go app on your phone

Your First Analysis

1Open the Streamlit interface at http://localhost:8501
2Enter a product name (optional but helpful for context)
3Paste an ingredient list from any food or cosmetic product
4Configure your profile: select allergies and skin type
5Click Analyze to start the multi-agent workflow
6Review your personalized safety report with recommendations

Project Structure

IngredientScanner/
├── app.py                  # Streamlit web interface
├── api.py                  # FastAPI REST endpoints
├── graph.py                # LangGraph workflow orchestration
├── agents/                 # AI agents
│   ├── supervisor.py       # Workflow routing
│   ├── research.py         # Ingredient research (Qdrant + Google)
│   ├── analysis.py         # Safety report generation
│   └── critic.py           # Quality validation (5-gate)
├── tools/                  # Utility tools
│   ├── ingredient_lookup.py
│   ├── grounded_search.py
│   ├── safety_scorer.py
│   └── allergen_matcher.py
├── prompts/                # LLM prompt templates
├── config/                 # Configuration files
├── mobile/                 # React Native Expo app
└── tests/                  # Test suite (191 tests)

Troubleshooting

"Cannot connect to Qdrant"

Verify your QDRANT_URL and QDRANT_API_KEY are correct
Check your network connection and firewall settings
Ensure the Qdrant cluster is running in the cloud console

"API key not valid"

Ensure GOOGLE_API_KEY is set correctly in .env
Verify the key has Gemini API access enabled in Google AI Studio
Check for any trailing whitespace in the key

"Module not found"

Ensure your virtual environment is activated
Run pip install -r requirements.txt again
Check Python version is 3.11 or higher

Next Steps

Architecture Overview →

Multi-agent workflow and tech stack

API Reference →

REST endpoints for integration

Mobile App Setup →

React Native Expo configuration

Agent Details →

Research, Analysis, and Critic agents