📥 Installation

Prerequisites

• Python 3.10+
• OpenAI API key
• [Optional] LangSmith API key for tracing and monitoring

Step 1: Clone the Repository

git clone https://github.com/DonGuillotine/ai-virtual-sales-agent.git
cd ai-virtual-sales-agent

Step 2: Create and Activate Virtual Environment

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

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Set Up Environment Variables

Create a .env file in the root directory with the following variables:

OPENAI_API_KEY=your_openai_api_key_here
LANGSMITH_API_KEY=your_langsmith_api_key_here  # Optional
LANGSMITH_TRACING=true  # Optional
LANGSMITH_PROJECT=virtual-sales-agent  # Optional

Step 5: Initialize the Database

python setup_database.py

🪄 Database Migration System

Overview

The Virtual Sales Agent includes a robust database migration system that allows for schema evolution over time. This system tracks all schema changes, applies them in order, and ensures database consistency across environments.

Features

• Version Tracking: Automatically manages migration version history
• SQL-Based Migrations: Define schema changes using familiar SQL syntax
• Transactional Safety: All migrations run within transactions for safety
• Developer Tools: Convenient scripts for migration creation and management

Migration Management

Setting Up Migrations

Initialize the migration system with:

python setup_migrations.py

This creates the necessary directory structure and converts your existing schema into the initial migration.

Creating New Migrations

To create a new migration:

python create_migration.py add_product_ratings

This creates a new numbered migration file in database/migrations/versions/ where you can define your schema changes:

-- Migration: add_product_ratings
-- Created: 2025-03-24 14:30:25

-- Write your migration SQL here
ALTER TABLE products ADD COLUMN rating FLOAT DEFAULT 0;
ALTER TABLE products ADD COLUMN review_count INTEGER DEFAULT 0;

Applying Migrations

Migrations are automatically applied when the application starts. You can also apply them manually with:

python reset_database.py

This resets the database and applies all migrations in sequence.

Migration Structure

Migrations are stored in SQL files with version numbers:

database/migrations/
└── versions/
    ├── 001_initial_schema.sql
    ├── 002_sample_migration.sql
    ├── 003_add_product_ratings.sql
    └── ...

The system tracks which migrations have been applied in the schema_migrations table, ensuring each migration runs only once.

Benefits

• Collaborative Development: Multiple developers can make schema changes without conflicts
• Deployment Safety: Consistent schema across development, testing, and production
• Version Control: All database changes are tracked in version control
• Rollback Capability: Clear history of changes with ability to restore previous states
• Documentation: Self-documenting schema evolution history

Best Practices

• Keep migrations small and focused on specific changes
• Always test migrations on development before applying to production
• Include both "up" (apply) and "down" (rollback) logic when possible
• Document complex migrations with comments
• Never modify existing migration files after they've been committed

For more information on database management, refer to the code documentation in the database/migrations/ directory.

🧪 Testing

Overview

This project includes a comprehensive testing suite to ensure core functionality works as expected. Tests are designed to be straightforward and maintainable, focusing on key functionality.

Test Structure

Tests are organized in the tests/ directory:

tests/
├── __init__.py
├── test_database.py
└── test_graph.py

Database Tests

The database tests (test_database.py) verify that:

• The database can be created successfully
• Products can be inserted correctly into the database
• Products can be loaded from a JSON file
• Database connections are managed properly

Database tests use a temporary database location to avoid affecting the production database.

Graph Tests

The graph tests (test_graph.py) verify that:

• The LangGraph can be initialized and invoked
• The assistant can process basic customer inquiries
• The conversation flow works as expected

These tests use mocks to avoid making actual API calls to language models.

Running Tests

You can run all tests with the included test runner:

python run_tests.py

Or run individual test files:

python -m unittest tests/test_database.py
python -m unittest tests/test_graph.py

Test Dependencies

Additional dependencies for testing are specified in requirements-dev.txt:

pytest==7.4.0
coverage==7.3.1

Install them with:

pip install -r requirements-dev.txt

Test Coverage

To generate a test coverage report:

coverage run -m unittest discover
coverage report
coverage html  # for a detailed HTML report

🚀 Running the Application

Start the Streamlit App

streamlit run main.py

The application will be available at http://localhost:8501.

💬 Usage Examples

Here are some example interactions with the virtual sales agent:

Product Search

User: I'm looking for a gaming mouse for big hands.
Agent: I'd be happy to help you find a gaming mouse suitable for larger hands! 
       Looking at our inventory, I would recommend the Logitech G604 LIGHTSPEED.

       It features:
       • Larger frame specifically designed for palm grip and larger hands
       • 15 programmable controls
       • Wireless with dual connectivity options
       • Extended battery life of up to 240 hours
       • Price: $99.99

       Would you like more information about this mouse or would you prefer to see other options?

Product Comparison

User: What's the difference between the Samsung Galaxy S21 and S22?

Agent: Here's a comparison between the Samsung Galaxy S21 and S22:

Samsung Galaxy S21 ($799.99):
• 6.2" Dynamic AMOLED display
• Exynos 2100 processor
• 8GB RAM, 128GB storage
• 4000mAh battery
• Triple rear camera (12MP+12MP+64MP)
• 8K video recording

Samsung Galaxy S22 ($899.99):
• 6.1" Dynamic AMOLED 2X display (slightly smaller but improved quality)
• Newer Snapdragon 8 Gen 1 processor (better performance)
• 8GB RAM, 128GB storage (same)
• 3700mAh battery (slightly smaller) but with faster 45W charging
• Enhanced camera system with improved night mode and 3x optical zoom
• $100 price difference

The S22 offers better performance, improved camera capabilities especially in low light, and faster charging, but has a slightly smaller screen and battery. Would you like me to recommend one based on your specific needs?

Order Placement

User: I'd like to buy the Logitech G604 mouse.

Agent: Great choice! I'd be happy to help you place an order for the Logitech G604 LIGHTSPEED gaming mouse.

       Here's the product details:
       • Product: Logitech G604 LIGHTSPEED
       • Price: $99.99
       • In stock: 45 units available

       How many would you like to order?

User: Just one please.

Agent: I'll place an order for 1 Logitech G604 LIGHTSPEED gaming mouse at $99.99.

       [Order preview appears with approval buttons]

       ⚠️ The assistant wants to perform an action. Do you approve?

       [After approval]

       Great news! Your order has been successfully placed.

       Order Details:
       • Order ID: 1
       • Total amount: $99.99
       • Status: Pending
       • Product: Logitech G604 LIGHTSPEED (x1)

       Your order is being processed and will ship soon. You can check your order status anytime by providing your order ID. Is there anything else you need help with today?

Order Status Check

User: What's the status of my order?

Agent: I'd be happy to check the status of your order for you. Could you please provide your order ID?

User: It's order 1.

Agent: Thank you for providing your order ID. Here's the status of your order:

       Order ID: 1
       Order Date: 2025-03-21T14:30:45.123456
       Status: Pending
       Products: Logitech G604 LIGHTSPEED (x1)
       Total Amount: $99.99

       Your order is currently being processed and should ship soon. Is there anything else you'd like to know about your order?

Return Policy Information

User: What's your return policy?

Agent: Our return policy allows you to return most items within 30 days of purchase for a full refund or exchange. Items must be in their original condition, with all tags and packaging intact. Please bring your receipt or proof of purchase when returning items.

       Would you like to know more about specific aspects of our return policy, such as non-returnable items or how refunds are proce