Thoughtful AI Customer Support Agent

A conversational AI agent that answers questions about Thoughtful AI's products and services using a knowledge base and intelligent fallback to LLM responses.

🎨 Demo

Modern OpenAI-style chat interface with real-time AI responses

📚 Table of Contents

Demo
Quick Links
Fastest Way to Start
Features
Knowledge Base
Prerequisites
Installation & Setup
How to Start the Service
Example Questions
Verification & Testing
Troubleshooting
Architecture
Dependencies
Project Structure
Customization
Quick Reference
Deployment
Next Steps

🚀 Quick Links

Setup & Deployment 🌐

环境配置指南 - 本地开发和生产环境配置 ⭐
Vercel部署指南 - 完整的Vercel部署文档（前端+后端）

🎯 Fastest Way to Start

# 1. 安装Python依赖
pip3 install -r requirements.txt

# 2. 一键启动
./start.sh  # Mac/Linux
# 或
start.bat   # Windows

浏览器会自动打开 http://localhost:3000 显示React界面

默认端口：

🔌 后端API：5001 (避免与macOS AirPlay冲突)
🌐 React前端：3000
📊 Streamlit：8501

Features

Intelligent Question Matching: Uses semantic similarity (sentence transformers) to find the best matching answer from the knowledge base
Fuzzy Matching Fallback: Falls back to fuzzy string matching if semantic search is unavailable
LLM Fallback: Uses Claude AI for questions outside the predefined knowledge base
Multiple Interfaces:
- React Web App - Modern OpenAI-style interface (RECOMMENDED)
- Web UI (Streamlit) - Alternative web interface
- CLI - for terminal-based interactions
Source Attribution: Shows whether the answer came from the knowledge base or LLM

Knowledge Base

The agent can answer questions about:

EVA (Eligibility Verification Agent)
CAM (Claims Processing Agent)
PHIL (Payment Posting Agent)
General information about Thoughtful AI's agents and their benefits

📋 Prerequisites

Before you begin, ensure you have the following installed:

Quick Check (Recommended)

Run the automated environment checker:

./check_setup.sh

This will verify all prerequisites and dependencies are correctly installed.

Required Software

Python 3.8 or higher
```
# Check your Python version
python3 --version
```
If not installed, download from: https://www.python.org/downloads/
pip3 (Python package manager)
```
# Check pip3 version
pip3 --version
```
Usually comes with Python 3. If missing, install with:
```
# Mac
sudo easy_install pip

# Ubuntu/Debian
sudo apt-get install python3-pip
```
Note: If pip3 is not found but pip works, you can use pip instead throughout this guide.
Node.js 14+ and npm (For React frontend only)
```
# Check Node.js version
node --version

# Check npm version
npm --version
```
If not installed, download from: https://nodejs.org/

Note: Not required for Streamlit or CLI interfaces.

🔧 Installation & Setup

Step 1: Navigate to Project Directory

cd /Users/arianali/Desktop/0work/0AiAgent

Step 2: Install Python Dependencies

pip3 install -r requirements.txt

This will install:

flask and flask-cors - Backend API server
streamlit - Alternative web interface
sentence-transformers - Semantic search (optional but recommended)
torch - Required by sentence-transformers
numpy - Numerical operations
anthropic - Claude AI integration (optional)

Note: Installing sentence-transformers and torch may take 2-5 minutes and download ~500MB of data.

Step 3: Verify Installation

# Test if Flask is installed
python3 -c "import flask; print('Flask:', flask.__version__)"

# Test if Streamlit is installed
python3 -c "import streamlit; print('Streamlit:', streamlit.__version__)"

Step 4 (Optional): Set up Anthropic API Key

For LLM fallback functionality (answers questions outside the knowledge base):

# Mac/Linux - Add to ~/.bash_profile or ~/.zshrc
export ANTHROPIC_API_KEY="your_api_key_here"

# Or set for current session only
export ANTHROPIC_API_KEY="your_api_key_here"

# Windows (Command Prompt)
set ANTHROPIC_API_KEY=your_api_key_here

# Windows (PowerShell)
$env:ANTHROPIC_API_KEY="your_api_key_here"

Note: If you don't set the API key, the agent will still work perfectly with the knowledge base questions about EVA, CAM, and PHIL. Questions outside the knowledge base will receive a generic fallback message.

🚀 How to Start the Service

Choose one of the three available interfaces based on your needs:

Option 1: React Web App (RECOMMENDED) ⭐

A modern, OpenAI-style interface with beautiful animations and responsive design.

Quick Setup for Local Development

Before starting, make sure you have the local environment file:

The .env.local file has been created in frontend/.env.local with:

REACT_APP_API_URL=http://localhost:5001

This tells the frontend to connect to your local backend at http://localhost:5001.

Method A: Automatic Start (Easiest)

# Mac/Linux
./start.sh

# Windows
start.bat

The script will:

✅ Check if dependencies are installed
✅ Start the Flask backend API on port 5001
✅ Start the React frontend on port 3000
✅ Automatically open your browser to http://localhost:3000

Important: The backend runs on port 5001 (not 5002) to avoid conflicts with macOS AirPlay.

Method B: Manual Start (Step by Step)

Step 1: Start the Backend API Server

Open Terminal 1:

# Navigate to backend directory
cd backend

# Start Flask server
python3 api.py

You should see:

============================================================
Thoughtful AI Agent API Server
============================================================
Server running on: http://localhost:5001
API endpoints:
  - POST /api/chat - Send a message to the agent
  - GET /api/health - Health check
  - GET /api/knowledge-base - Get knowledge base
============================================================
 * Running on http://0.0.0.0:5001

Step 2: Verify Backend is Running

Open a new terminal and test:

curl http://localhost:5001/api/health

Expected response:

{"status":"healthy","message":"API is running"}

Step 3: Start the React Frontend

Open Terminal 2:

# Navigate to frontend directory
cd frontend

# Install Node dependencies (first time only)
npm install

# Start React development server
npm start

The terminal will show:

Compiled successfully!

You can now view thoughtful-ai-frontend in the browser.

  Local:            http://localhost:3000
  On Your Network:  http://192.168.x.x:3000

Your browser will automatically open to http://localhost:3000

Step 4: Verify Frontend is Working

You should see:

✅ Left sidebar with EVA, CAM, PHIL information
✅ Chat area with welcome message
✅ Input box at the bottom
✅ Sample questions you can click

Testing the React App

Try these actions:

Click on a sample question in the sidebar (e.g., "What does EVA do?")
Wait for the AI response (should appear within 1 second)
Type your own question in the input box
Check that the source is marked (📚 Knowledge Base or ⚡ AI Response)

Stopping the Services

# In Terminal 1 (Backend): Press Ctrl+C
# In Terminal 2 (Frontend): Press Ctrl+C

Option 2: Streamlit Web Interface

A simpler alternative web interface, great for quick demos and internal use.

Starting Streamlit

# Make sure you're in the project root directory
cd /Users/arianali/Desktop/0work/0AiAgent

# Run Streamlit app
streamlit run app.py

You should see:

You can now view your Streamlit app in your browser.

  Local URL: http://localhost:8501
  Network URL: http://192.168.x.x:8501

The browser will automatically open to http://localhost:8501

Features

✅ Simple, clean interface
✅ Chat history
✅ Sample questions in sidebar
✅ Source attribution
✅ Clear chat button

Stopping Streamlit

# Press Ctrl+C in the terminal

Option 3: Command Line Interface (CLI)

Perfect for testing, automation, or server environments without GUI.

Starting CLI

# Make sure you're in the project root directory
cd /Users/arianali/Desktop/0work/0AiAgent

# Run the CLI agent
python3 thoughtful_ai_agent.py

You should see:

============================================================
Welcome to Thoughtful AI Customer Support Agent!
============================================================
Ask me anything about Thoughtful AI's products and services.
Type 'quit' or 'exit' to end the conversation.

You:

Usage

Type your question and press Enter
The agent will respond immediately
Continue the conversation
Type quit, exit, or bye to stop

Example Session

You: What does EVA do?

Agent: EVA automates the process of verifying a patient's eligibility
and benefits information in real-time, eliminating manual data entry
errors and reducing claim rejections.
(Source: Knowledge Base)

You: quit

Agent: Thank you for chatting with Thoughtful AI support. Have a great day!

💬 Example Questions

Try asking any of these questions:

About the Agents

"What does the eligibility verification agent (EVA) do?"
"Tell me about CAM"
"How does PHIL work?"
"Tell me about Thoughtful AI's Agents"

About Benefits

"What are the benefits of using Thoughtful AI's agents?"
"Why should I use Thoughtful AI?"

General Questions

"What is Thoughtful AI?"
"How can these agents help my business?"

The agent will respond using either the knowledge base (for specific product questions) or AI-generated responses (for general inquiries).

🔍 Verification & Testing

Quick Health Check

After starting the services, verify everything is working:

1. Test Backend API:

# Local development
curl http://localhost:5001/api/health

# Production (after deploying to Vercel)
curl https://your-domain.vercel.app/api/health

2. Test Chat Endpoint:

# Local development
curl -X POST http://localhost:5001/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"What does EVA do?"}'

# Production (after deploying to Vercel)
curl -X POST https://your-domain.vercel.app/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"What does EVA do?"}'

3. Test Frontend:

Open http://localhost:3000 in your browser
Click a sample question
Verify you get a response

4. Run Automated Tests:

python3 test_agent.py

Expected output:

======================================================================
Testing Thoughtful AI Customer Support Agent
======================================================================
...
Test 1: What does the eligibility verification agent (EVA) do?
----------------------------------------------------------------------
Answer: EVA automates the process of verifying...
Source: knowledge_base
Status: ✓ PASSED
...
All tests completed successfully!

🐛 Troubleshooting

Problem 1: "Command not found: python3"

Error:

-bash: python3: command not found

Solution:

# Try using 'python' instead
python --version

# If version is 3.8+, use 'python' for all commands
python api.py
python thoughtful_ai_agent.py

Problem 2: "Command not found: pip3"

Error:

-bash: pip3: command not found

Solution:

# Try using 'pip' instead
pip --version

# If it shows Python 3.x, use 'pip' instead of 'pip3'
pip install -r requirements.txt

Problem 3: Port Already in Use

Error:

OSError: [Errno 48] Address already in use

Solution:

# Find process using the port
# For port 5001 (backend):
lsof -i :5001

# For port 3000 (frontend):
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or use a different port
# Backend: Edit backend/api.py, change port=5001 to port=5001
# Frontend: PORT=3001 npm start

Problem 4: Module Not Found Error

Error:

ModuleNotFoundError: No module named 'flask'

Solution:

# Reinstall dependencies
pip3 install -r requirements.txt

# If using a virtual environment, activate it first
source venv/bin/activate  # Mac/Linux
venv\Scripts\activate     # Windows

Problem 5: Frontend Can't Connect to Backend

Symptom: Messages show error "Please make sure the backend API is running"

Solution:

# 1. Verify backend is running
curl http://localhost:5001/api/health

# 2. Check if port 5001 is accessible
lsof -i :5001

# 3. Make sure frontend has .env.local file with:
#    REACT_APP_API_URL=http://localhost:5001

# 4. Check browser console for errors (F12)

# 5. Restart both services
# Kill backend and frontend, then restart

Problem 6: npm install Fails

Error:

npm ERR! code EACCES

Solution:

# Clear npm cache
npm cache clean --force

# Remove node_modules
cd frontend
rm -rf node_modules package-lock.json

# Reinstall
npm install

# If still fails, try with sudo (not recommended but works)
sudo npm install

Problem 7: React App Shows Blank Page

Solution:

# 1. Check browser console for errors (F12)

# 2. Clear browser cache
# Chrome: Ctrl+Shift+Delete

# 3. Rebuild frontend
cd frontend
rm -rf node_modules build
npm install
npm start

# 4. Try a different browser

Problem 8: Slow Loading or Timeout

Issue: First time loading takes very long

Explanation: This is normal for the first run. The sentence-transformers library needs to download language models (~500MB).

Solution:

# Just wait for the first download to complete
# Subsequent starts will be much faster

# To see download progress, check the terminal output

Getting Help

If you encounter other issues:

Check the terminal output for error messages
Check browser console (F12 → Console tab)
Check logs (if using start.sh, see logs/backend.log)
Verify prerequisites are installed correctly
Try the test script: python3 test_agent.py

Common Questions

Q: Do I need the Anthropic API key? A: No, it's optional. The agent works perfectly without it for all knowledge base questions about EVA, CAM, and PHIL.

Q: Which interface should I use? A: For the best experience, use the React Web App (Option 1). It has the most polished UI and features.

Q: Can I use Python 2? A: No, Python 3.8 or higher is required.

Q: Do I need to keep both terminals open? A: Yes, for the React app you need one terminal for backend (Flask) and one for frontend (React).

Q: Can I deploy this to production? A: Yes! See VERCEL_DEPLOY.md for deployment instructions.

Architecture

Components

ThoughtfulAIAgent Class (thoughtful_ai_agent.py)
- Manages the knowledge base
- Implements question matching algorithms
- Handles LLM fallback
Flask API Server (backend/api.py)
- RESTful API endpoints
- CORS support for frontend communication
- JSON request/response handling
React Frontend (frontend/)
- Modern OpenAI-style UI
- Real-time chat interface
- Framer Motion animations
- Responsive design
Streamlit Web UI (app.py)
- Alternative web interface
- Simple setup
- Built-in chat components

Matching Algorithm

The agent uses a multi-tier matching approach:

Semantic Search (Primary): Uses sentence-transformers to compute semantic similarity between user questions and knowledge base questions
Fuzzy Matching (Fallback): Uses SequenceMatcher for string similarity matching
LLM Response (Last Resort): Uses Claude AI for questions not matching the knowledge base

Dependencies

Python (Backend)

flask: REST API server
flask-cors: Cross-origin resource sharing
streamlit: Alternative web UI framework
sentence-transformers: Semantic similarity matching
anthropic: Claude AI API for LLM fallback
torch: Required by sentence-transformers
numpy: Numerical operations

JavaScript (Frontend)

react: UI framework
react-dom: React DOM rendering
axios: HTTP client
framer-motion: Animation library
react-markdown: Markdown rendering

Project Structure

0AiAgent/
├── thoughtful_ai_agent.py      # Core agent logic
├── app.py                      # Streamlit web interface
├── test_agent.py               # Test suite
├── requirements.txt            # Python dependencies
├── README.md                   # Main documentation
├── VERCEL_DEPLOY.md            # Vercel deployment guide
├── start.sh                    # Quick start script (Mac/Linux)
├── start.bat                   # Quick start script (Windows)
├── backend/
│   └── api.py                  # Flask REST API server
└── frontend/                   # React application
    ├── public/
    │   └── index.html
    ├── src/
    │   ├── api/
    │   │   └── client.js       # API client
    │   ├── components/
    │   │   ├── ChatMessage.js  # Message component
    │   │   ├── InputBox.js     # Input component
    │   │   └── Sidebar.js      # Sidebar component
    │   ├── App.js              # Main app
    │   ├── App.css             # Styles
    │   └── index.js            # Entry point
    └── package.json            # Node dependencies

Customization

Adding New Questions

Edit the knowledge_base dictionary in thoughtful_ai_agent.py:

self.knowledge_base = {
    "questions": [
        {
            "question": "Your new question here?",
            "answer": "Your answer here."
        },
        # ... existing questions
    ]
}

Adjusting Matching Threshold

In thoughtful_ai_agent.py, modify the threshold parameters:

# For semantic matching (default: 0.5)
self.find_best_match_semantic(user_question, threshold=0.5)

# For fuzzy matching (default: 0.4)
self.find_best_match_fuzzy(user_question, threshold=0.4)

Lower thresholds make matching more lenient; higher thresholds make it stricter.

📝 Quick Reference

Essential Commands

# Check Environment Setup
./check_setup.sh

# Installation
pip3 install -r requirements.txt

# Start React App (Recommended)
./start.sh  # or start.bat on Windows

# Start Backend Only
cd backend && python3 api.py

# Start Frontend Only
cd frontend && npm start

# Start Streamlit
streamlit run app.py

# Start CLI
python3 thoughtful_ai_agent.py

# Run Tests
python3 test_agent.py

# Health Check (local)
curl http://localhost:5001/api/health

# Health Check (production)
curl https://your-domain.vercel.app/api/health

Troubleshooting Commands

# Check if Python3 is installed
python3 --version

# Check if pip3 is installed
pip3 --version

# Check if dependencies are installed
python3 -c "import flask; print('Flask OK')"
python3 -c "import streamlit; print('Streamlit OK')"

# Find process using port 5001
lsof -i :5001

# Find process using port 3000
lsof -i :3000

# Kill process on port
kill -9 <PID>

# Clear npm cache
npm cache clean --force

# Reinstall frontend dependencies
cd frontend && rm -rf node_modules package-lock.json && npm install

URLs

Local Development:

React Frontend: http://localhost:3000
Backend API: http://localhost:5001
Streamlit: http://localhost:8501
API Health Check: http://localhost:5001/api/health

Production (Vercel):

Application: https://your-domain.vercel.app
Backend API: https://your-domain.vercel.app/api
API Health Check: https://your-domain.vercel.app/api/health

File Locations

Core Agent: thoughtful_ai_agent.py
Backend API: backend/api.py
React App: frontend/src/App.js
Streamlit UI: app.py
Dependencies: requirements.txt

Environment Files

Local Dev: frontend/.env.local - Auto-created for local development
Production: frontend/.env.production - Auto-created for Vercel

Documentation Files

Main Guide: README.md (this file)
Environment Setup: ENVIRONMENT_SETUP.md - Configuration guide
Deployment Guide: VERCEL_DEPLOY.md - Vercel deployment

🎓 Next Steps

After getting the application running:

Try all the interfaces - Compare React, Streamlit, and CLI
Customize the knowledge base - Add your own questions and answers
Explore the code - Learn how the matching algorithm works
Deploy to production - See VERCEL_DEPLOY.md

📄 License

This project is created as a demonstration for Thoughtful AI.

🆘 Support

For questions or issues:

Check the Troubleshooting section above
Run python3 test_agent.py to verify your setup
Review the VERCEL_DEPLOY.md for deployment issues
Contact the development team

Made with ❤️ for Thoughtful AI

🚀 Start now: pip3 install -r requirements.txt && ./start.sh

Name		Name	Last commit message	Last commit date
.claude		.claude
api		api
backend		backend
docs/images		docs/images
frontend		frontend
logs		logs
.gitignore		.gitignore
.vercelignore		.vercelignore
README.md		README.md
VERCEL_DEPLOY.md		VERCEL_DEPLOY.md
app.py		app.py
check_setup.sh		check_setup.sh
requirements.txt		requirements.txt
start.bat		start.bat
start.sh		start.sh
test_agent.py		test_agent.py
thoughtful_ai_agent.py		thoughtful_ai_agent.py
vercel-flask-anthropic.skill		vercel-flask-anthropic.skill
vercel.json		vercel.json

Latest commit

History

Folders and files

Repository files navigation

Thoughtful AI Customer Support Agent

🎨 Demo

📚 Table of Contents

🚀 Quick Links

Setup & Deployment 🌐

🎯 Fastest Way to Start

Features

Knowledge Base

📋 Prerequisites

Quick Check (Recommended)

Required Software

🔧 Installation & Setup

Step 1: Navigate to Project Directory

Step 2: Install Python Dependencies

Step 3: Verify Installation

Step 4 (Optional): Set up Anthropic API Key

🚀 How to Start the Service

Option 1: React Web App (RECOMMENDED) ⭐

Quick Setup for Local Development

Method A: Automatic Start (Easiest)

Method B: Manual Start (Step by Step)

Testing the React App

Stopping the Services

Option 2: Streamlit Web Interface

Starting Streamlit

Features

Stopping Streamlit

Option 3: Command Line Interface (CLI)

Starting CLI

Usage

Example Session

💬 Example Questions

About the Agents

About Benefits

General Questions

🔍 Verification & Testing

Quick Health Check

🐛 Troubleshooting

Problem 1: "Command not found: python3"

Problem 2: "Command not found: pip3"

Problem 3: Port Already in Use

Problem 4: Module Not Found Error

Problem 5: Frontend Can't Connect to Backend

Problem 6: npm install Fails

Problem 7: React App Shows Blank Page

Problem 8: Slow Loading or Timeout

Getting Help

Common Questions

Architecture

Components

Matching Algorithm

Dependencies

Python (Backend)

JavaScript (Frontend)

Project Structure

Customization

Adding New Questions

Adjusting Matching Threshold

📝 Quick Reference

Essential Commands

Troubleshooting Commands

URLs

File Locations

Environment Files

Documentation Files

🎓 Next Steps

📄 License

🆘 Support

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors