Tea Shopper

An intelligent tea shopping assistant powered by AI, built with Next.js and Agno framework.

Overview

Tea Shopper is an AI-powered tea discovery and shopping platform that helps users find the perfect teas based on their preferences. The application features:

• AI Tea Assistant - Conversational AI agent that understands tea preferences and makes recommendations
• Knowledge Base - Comprehensive tea database with detailed product information
• Streaming Chat - Real-time conversation with streaming responses
• Memory & Personalization - Remembers user preferences for better recommendations

Tech Stack

• Frontend: Next.js 16, React 19, TypeScript, Tailwind CSS
• Backend: Python, FastAPI, Agno Framework, AgentOS
• AI: OpenAI GPT-4o-mini
• Database: SQLite (local file-based)

Quick Start

Prerequisites

• Node.js 18+ and npm
• Python 3.8+
• OpenAI API key

Installation

1. Install all dependencies:

   npm run install:all

2. Set up environment variables: Create a .env.local file in the project root:

   OPENAI_API_KEY=sk-your-openai-api-key-here

3. Copy tea data (if needed):

   python backend/scripts/copy_tea_data.py

Running the Application

Start both frontend and backend:

# Terminal 1: Start backend API
npm run dev:api

# Terminal 2: Start frontend
npm run dev

The application will be available at:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

Project Structure

tea-shopper/
├── frontend/          # Next.js frontend application
├── backend/           # Python backend with Agno agent
│   ├── core/         # Core application code
│   ├── tools/        # Agent tools
│   ├── knowledge/    # Knowledge base
│   ├── scripts/      # Utility scripts
│   └── data/        # Data files and databases
└── docs/             # Documentation

Documentation

• Backend Setup: See backend/docs/ENV_SETUP.md
• Migration Details: See backend/docs/MIGRATION_SUMMARY.md
• Reorganization: See backend/REORGANIZATION.md

Features

• 🤖 AI-Powered Conversations - Natural language tea discovery
• 🔍 Intelligent Search - Semantic search through tea database
• 💾 Memory & Context - Remembers user preferences
• 📊 Knowledge Base - Comprehensive tea product information
• 🚀 Streaming Responses - Real-time chat experience
• 🗄️ Local Storage - SQLite database (no external services)

Development

Backend Development

cd backend
python core/app.py

Frontend Development

cd frontend
npm run dev

Testing

# Test backend setup
python backend/scripts/test_connection.py

License

Private project