chatbot Module

Conversational investor onboarding chatbot — collects investor data through natural language and fills PDF subscription forms.

🚀 Quick Start

1. Configure

cd modules/chatbot
cp .env.example .env
nano .env          # add OPENAI_API_KEY at minimum

See SETUP_GUIDE.md for full configuration.

2. Install Dependencies

pip install -r requirements.txt
pip install -r requirements-api.txt

3. Run

# API server (recommended)
python api_server.py

# Interactive CLI
python -m entrypoints.local

# Or interactively via CLI tool
python -m entrypoints.cli

Server: http://localhost:8001
API Docs: http://localhost:8001/docs

📁 Structure

modules/chatbot/
├── .env.example              ← Copy to .env — add your API keys
├── api_server.py             ← FastAPI server (run this!)
├── requirements.txt          ← Core dependencies
├── requirements-api.txt      ← FastAPI + uvicorn
├── requirements-mapper.txt   ← PDF mapper connector (optional)
├── requirements-s3.txt       ← AWS S3 storage (optional)
├── requirements-full.txt     ← Everything (used by Docker)
├── pyproject.toml            ← Package metadata
├── Dockerfile                ← Container build
├── SETUP_GUIDE.md            ← Detailed setup
├── API_SERVER.md             ← API endpoint reference
├── entrypoints/
│   ├── local.py              ← Interactive CLI / Python-callable
│   ├── cli.py                ← Command-line interface
│   ├── fastapi_app.py        ← Bare FastAPI app (no /chatbot prefix)
│   └── aws_lambda.py         ← AWS Lambda handler
├── src/chatbot/              ← Core SDK source
│   ├── client.py             ← chatbotClient — main entry point
│   ├── config/               ← Settings, FormConfig
│   ├── core/                 ← Engine, router, session, states (13-state machine)
│   ├── extraction/           ← LLM extractor, fallback, prompt builder
│   ├── handlers/             ← One handler per conversation state
│   ├── limits/               ← Rate limiter
│   ├── logging/              ← Debug logger
│   ├── managed/              ← Stub for private managed PDF service
│   ├── pdf/                  ← PDFFillerInterface, MapperPDFFiller, workflow
│   ├── storage/              ← LocalStorage, S3Storage, StorageBackend
│   ├── telemetry/            ← Opt-in telemetry collector
│   ├── utils/                ← Field utils, address utils, intent detection
│   └── validation/           ← Field + phone validators
├── config_samples/           ← Form config JSON files (10 investor types)
├── tests/
│   ├── conftest.py           ← Shared fixtures
│   ├── unit/                 ← Fast, no I/O tests
│   └── integration/          ← Full-stack tests (TestClient)
└── data/
    ├── input/                ← Place blank PDFs here
    ├── output/               ← Filled PDFs and session data written here
    └── cache/                ← Optional: session cache

🎯 What This Module Does

A 13-state conversation engine that:

1. Greets the investor and checks for existing saved data
2. Asks the investor to select their type (Individual, Corporation, LLC, Trust, etc.)
3. Collects all mandatory fields through natural conversation using GPT-4o-mini extraction
4. Validates fields (email, phone format, boolean checks)
5. Handles address copy (mailing = registered), boolean groups, sequential fill for stubborn fields
6. Fills the blank PDF via the mapper module (optional)
7. Completes the session and saves structured JSON output

Conversation states

🔌 PDF Filling

Three modes controlled by chatbot_PDF_FILLER env var:

For mapper mode, start the mapper API server first:

cd ../mapper
python api_server.py     # runs on port 8000

# Then in modules/chatbot:
chatbot_PDF_FILLER=mapper
MAPPER_API_URL=http://localhost:8000
MAPPER_URL_PREFIX=/mapper

🌐 API Endpoints

Authentication is required. Set CHATBOT_API_KEY to a strong secret before starting the server — every endpoint below requires it as the X-API-Key header, or the server responds with a config error. (For local-only experimentation you can instead set CHATBOT_ALLOW_INSECURE_NO_AUTH=true, but never do this in a deployment reachable by anyone else.) Cross-origin access is closed by default; set CHATBOT_CORS_ALLOWED_ORIGINS (comma-separated) to allow specific origins.

user_id and session_id must be plain identifiers (no /, \, or ..) — anything else is rejected with HTTP 400. Note that the API key is a single shared secret: it keeps outsiders out, but any caller holding it can address any user_id/session_id. If you expose this service to multiple mutually-untrusting end users directly (rather than via your own authenticated backend), add a per-user ownership check in front of it.

See API_SERVER.md for full request/response schemas.

📦 Using as a Python Library

from src.chatbot import chatbotClient, LocalStorage, FormConfig

client = chatbotClient(
    openai_api_key="sk-...",
    storage=LocalStorage("./chatbot_data", "./config_samples"),
    form_config=FormConfig.from_directory("./config_samples"),
    pdf_filler=None,
)

# Send messages
response, complete, data = client.send_message(
    user_id="investor_123",
    session_id="session_abc",
    message="",
)
print(response)   # → "Hi! I am here to help you fill out..."

🧪 Testing

# Run all tests
pytest

# Unit tests only (fast, no network)
pytest tests/unit/ -v

# Integration tests
pytest tests/integration/ -v

# With coverage
pytest --cov=src/chatbot --cov-report=term-missing

# A specific test
pytest tests/unit/test_rate_limiter.py -v

🐳 Docker

docker build -t chatbot-module .
docker run -p 8001:8001 --env-file .env chatbot-module

🔗 Integration with mapper module

rv1 repo/
├── modules/
│   ├── mapper/          ← PDF extraction + mapping + filling engine
│   │   └── api_server.py  runs on :8000
│   └── chatbot/         ← This module
│       └── api_server.py  runs on :8001
│           └── MAPPER_API_URL=http://localhost:8000

📚 Documentation

• SETUP_GUIDE.md — Configuration reference
• API_SERVER.md — API endpoint documentation
• config_samples/README.md — Form config format

Quick Command Reference

# Setup
cp .env.example .env && nano .env
pip install -r requirements.txt requirements-api.txt

# Run
python api_server.py

# Test
curl http://localhost:8001/health
pytest tests/unit/

# Interactive CLI
python -m entrypoints.local