Ethical Persuasion Chatbot

A sophisticated chatbot application built with FastAPI, React, and PostgreSQL with pgvector for semantic search capabilities.

For a demonstration of the system see the TCS Banking Assistant Demo Video.

📋 Table of Contents

Features
Tech Stack
Prerequisites
Getting Started
Docker Commands
Development
Project Structure
Environment Variables
Troubleshooting

✨ Features

FastAPI Backend: High-performance Python backend with async support
React Frontend: Modern, responsive user interface
PostgreSQL + pgvector: Vector similarity search for semantic capabilities
Docker Support: Fully containerized development and deployment
Hot-Reload: Automatic code reloading during development
AI Integration: Google Gemini (generation + embeddings) with ethics-gated pipeline

🛠 Tech Stack

Backend

FastAPI: Modern Python web framework
SQLAlchemy: SQL toolkit and ORM
pgvector: Vector similarity search
Uvicorn: ASGI server

Frontend

React: UI library
Axios: HTTP client
React Router: Navigation

Database

PostgreSQL: Relational database
pgvector: Vector extension for embeddings

📦 Prerequisites

Before you begin, ensure you have the following installed:

Docker: Version 20.10 or higher (Install Docker)
Docker Compose: Version 2.0 or higher (usually included with Docker Desktop)
Git: For version control

To verify your installation:

docker --version
docker-compose --version

🚀 Getting Started

1. Clone the Repository

git clone <your-repository-url>
cd chatbot

2. Set Up Environment Variables

Copy the example environment file and configure your settings:

cp .env.example .env

Edit .env and add your API key:

# Required: Add your Google AI API key
# Get one free at: https://aistudio.google.com/apikey
GOOGLE_API_KEY=your-google-api-key-here

# Optional: Modify ports and other settings as needed

3. Start the Application

docker-compose up

The services will be available at:

Frontend: http://localhost:3000
Backend API: http://localhost:8000
API Documentation: http://localhost:8000/docs
PostgreSQL: localhost:5433

🐳 Docker Commands

Basic Operations

Start all services

docker-compose up

Start services in detached mode (background)

docker-compose up -d

Stop all services

docker-compose down

Stop and remove volumes (⚠️ deletes database data)

docker-compose down -v

Building and Rebuilding

Build or rebuild services

docker-compose build

Rebuild and start services

docker-compose up --build

Rebuild a specific service

docker-compose build backend
docker-compose build frontend

Viewing Logs

View logs from all services

docker-compose logs

Follow logs in real-time

docker-compose logs -f

View logs for a specific service

docker-compose logs backend
docker-compose logs frontend
docker-compose logs postgres

Service Management

Restart a specific service

docker-compose restart backend

Stop a specific service

docker-compose stop backend

Start a specific service

docker-compose start backend

Database Operations

Access PostgreSQL shell

docker-compose exec postgres psql -U postgres -d chatbot_db

Run database migrations (when implemented)

docker-compose exec backend alembic upgrade head

Create a new migration

docker-compose exec backend alembic revision --autogenerate -m "description"

Troubleshooting Commands

Check service status

docker-compose ps

View resource usage

docker stats

Execute command in running container

docker-compose exec backend bash
docker-compose exec frontend sh

Remove all stopped containers

docker-compose rm

Clean up Docker system (⚠️ removes unused data)

docker system prune -a

💻 Development

Hot-Reload

Both frontend and backend support hot-reloading:

Backend: Changes to Python files automatically restart the FastAPI server
Frontend: Changes to React components automatically refresh the browser

Adding Dependencies

Backend (Python)

Add the package to backend/requirements.txt

Rebuild the backend service:

docker-compose build backend
docker-compose up -d

Frontend (Node.js)

Add the package to frontend/package.json

Rebuild the frontend service:

docker-compose build frontend
docker-compose up -d

Or install directly in the running container:

docker-compose exec frontend npm install <package-name>

Running Tests

# Backend tests
docker-compose exec backend pytest

# Frontend tests
docker-compose exec frontend npm test

📁 Project Structure

chatbot/
├── backend/                    # FastAPI backend application
│   ├── pipeline/               # Core AI pipeline (runs in order, never skip steps)
│   │   ├── ethics_gate.py      # Rules + zero-shot check (runs first — blocks/allows)
│   │   ├── classifier.py       # Zero-shot: emotion, intent, situation
│   │   ├── strategy.py         # Emotion-first YAML strategy selection
│   │   ├── generator.py        # Gemini LLM with structured prompts
│   │   ├── critic.py           # Score + optional rewrite (one pass max)
│   │   └── orchestrator.py     # Coordinates the full pipeline
│   ├── strategies/             # Human-editable YAML strategy files
│   │   ├── blocked/
│   │   ├── soft_persuasion/
│   │   └── neutral/
│   ├── routers/
│   │   ├── chat.py             # Main chat endpoint
│   │   └── conversations.py    # Conversation CRUD
│   ├── models.py               # SQLAlchemy models
│   ├── database.py             # DB session management
│   ├── main.py                 # Application entry point
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/                   # React frontend application
│   ├── Dockerfile
│   ├── package.json
│   └── src/
├── docker/
│   └── init-db.sql             # Database initialization
├── docker-compose.yml
├── .env.example                # Environment variables template
├── .gitignore
└── README.md

🔧 Environment Variables

See .env.example for all available configuration options.

Required Variables

GOOGLE_API_KEY: Your Google AI API key — used for Gemini LLM generation, embeddings, and the critic agent. Get one free at aistudio.google.com/apikey
SECRET_KEY: Secret key for session management (change in production)

Optional Variables

POSTGRES_USER: Database user (default: postgres)
POSTGRES_PASSWORD: Database password (default: postgres)
POSTGRES_DB: Database name (default: chatbot_db)
POSTGRES_PORT: Host-side PostgreSQL port (default: 5433)
DATABASE_URL: Full connection string (default: postgresql://postgres:postgres@localhost:5433/chatbot_db)
BACKEND_PORT: Backend port (default: 8000)
FRONTEND_PORT: Frontend port (default: 3000)
CORS_ORIGINS: Allowed CORS origins (default: http://localhost:3000)

🔍 Troubleshooting

Port Already in Use

If you see an error about ports already being in use:

# Change ports in .env file
BACKEND_PORT=8001
FRONTEND_PORT=3001
POSTGRES_PORT=5433

Database Connection Issues

# Check if PostgreSQL is healthy
docker-compose ps

# View PostgreSQL logs
docker-compose logs postgres

# Restart PostgreSQL
docker-compose restart postgres

Hot-Reload Not Working

For frontend hot-reload issues on Windows:

# Ensure polling is enabled in .env
CHOKIDAR_USEPOLLING=true
WATCHPACK_POLLING=true

Permission Issues (Linux/Mac)

# Fix permission issues
sudo chown -R $USER:$USER .

Clear Everything and Start Fresh

# Stop all services and remove volumes
docker-compose down -v

# Remove all images
docker-compose rm -f

# Rebuild from scratch
docker-compose build --no-cache
docker-compose up

📚 Additional Resources

📝 License

[Add your license information here]

🤝 Contributing

[Add contribution guidelines here]

Questions or Issues? Please open an issue on GitHub.

Name		Name	Last commit message	Last commit date
.claude		.claude
backend		backend
docker		docker
docs		docs
frontend		frontend
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
README.md		README.md
SETUP.md		SETUP.md
docker-compose.yml		docker-compose.yml
mock_bank_statement.pdf		mock_bank_statement.pdf
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation