Advanced

# Start each module as an independent HTTP server (each in a separate terminal)

# Chatbot API (port 8000)
chatbot-server --host 0.0.0.0 --port 8000

# Doc Upload API (port 8001)
doc-upload-server --host 0.0.0.0 --port 8001

# Mapper API (port 8002) — used when MAPPER_API_URL is set
pdf-mapper-server --host 0.0.0.0 --port 8002

# RAG API (port 8003) — used when RAG_MODE=http
ragpdf-server
# or: uvicorn ragpdf.entrypoints.fastapi_app:app --port 8003

# HTTP mode wiring (.env):
# Set MAPPER_API_URL=http://localhost:8002 to switch mapper from inprocess to HTTP
# Set RAG_API_URL=http://localhost:8003 and RAG_MODE=http to switch RAG to HTTP

# AWS S3 (.env)
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1
STORAGE=s3

# mapper_config.ini
[general]
source_type = aws

# ─────────────────────────────────────────────────────
# Azure Blob Storage (.env)
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
STORAGE=azure

# mapper_config.ini
[general]
source_type = azure

# ─────────────────────────────────────────────────────
# GCP Storage (.env)
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
STORAGE=gcp

# mapper_config.ini
[general]
source_type = gcp

# .env - enable rate limiting
chatbot_RATE_LIMIT_ENABLED=true

# Backend - choose one:

# Local (in-memory, resets on restart - fine for single-server)
chatbot_RATE_LIMIT_STORAGE=local

# Redis (persistent across restarts, works across multiple servers)
chatbot_RATE_LIMIT_STORAGE=redis
REDIS_URL=redis://localhost:6379

# .env - enable telemetry (opt-in only)
chatbot_TELEMETRY=true

# Mode 1: local - send events to your own HTTP endpoint
chatbot_TELEMETRY_MODE=local
TELEMETRY_ENDPOINT=http://localhost:9000/events

# Mode 2: managed - send to the Autofiller telemetry service
chatbot_TELEMETRY_MODE=managed
chatbot_SDK_API_KEY=chatbot_tel_your-key-here
# Note: managed telemetry requires chatbot_PDF_FILLER=managed

# .env - customise bot name and opening message
chatbot_BOT_NAME=Aria
chatbot_GREETING=Hi! I'm Aria, here to help you complete your onboarding forms. \
Ready to get started?

from chatbot.extraction.prompt_builder import PromptBuilder

class HedgeFundPromptBuilder(PromptBuilder):
    """
    Custom prompt builder that adds domain-specific extraction rules
    for hedge fund subscription forms.
    """
    def _base_rules(self):
        return super()._base_rules() + '''

        Additional rules for hedge fund subscriptions:
        - ERISA fields only apply to US pension and benefit plans.
          Do not extract ERISA values for non-US investors.
        - Preserve country names exactly as provided by the investor.
          Do not normalise or expand abbreviations (e.g. "US" stays "US").
        - EIN/tax ID values should be formatted as XX-XXXXXXX (9 digits with hyphen).
        '''

# Pass to chatbotClient to replace the default prompt builder:
from chatbot import chatbotClient, LocalStorage, FormConfig

client = chatbotClient(
    openai_api_key='sk-...',
    prompt_builder=HedgeFundPromptBuilder(),
    storage=LocalStorage('./chatbot_data', './configs'),
    form_config=FormConfig.from_directory('./configs'),
)

from chatbot.storage.base import StorageBackend

class PostgresStorage(StorageBackend):
    """
    Store sessions in PostgreSQL instead of local disk or S3.
    Implement all abstract methods from StorageBackend.
    """
    def __init__(self, connection_string: str):
        import psycopg2
        self.conn = psycopg2.connect(connection_string)

    def get_session_state(self, user_id: str, session_id: str) -> dict | None:
        # Return the stored state dict or None if not found
        ...

    def save_session_state(self, user_id: str, session_id: str, state: dict) -> None:
        # Persist the state dict
        ...

    # Implement all remaining abstract methods:
    # save_conversation_log, get_conversation_log,
    # save_final_output, get_final_output,
    # save_fill_report, get_fill_report, etc.

client = chatbotClient(
    storage=PostgresStorage('postgresql://user:pass@localhost/mydb'),
    ...
)

# Step 1 - Add the state to src/chatbot/core/states.py
class State(str, Enum):
    ...
    COMPLIANCE_CHECK = "COMPLIANCE_CHECK"   # new state

# Step 2 - Create src/chatbot/handlers/compliance_check_handler.py
from chatbot.handlers.base import BaseHandler
from chatbot.core.states import State

class ComplianceCheckHandler(BaseHandler):
    async def handle(self, session, user_message: str):
        # Implement your state logic here.
        # Return (bot_response: str, next_state: State)
        if session.compliance_verified:
            return "Thank you. Moving on.", State.MANDATORY_FIELDS
        return "Please confirm your compliance status: Yes or No.", State.COMPLIANCE_CHECK

# Step 3 - Register in src/chatbot/core/router.py
class StateRouter:
    def build(self):
        return {
            ...
            State.COMPLIANCE_CHECK: ComplianceCheckHandler(),
        }

# Step 4 - Route to it from the investor type handler
# In InvestorTypeHandler.handle(), return State.COMPLIANCE_CHECK
# instead of State.MANDATORY_FIELDS to insert the new check.

from chatbot.limits.rate_limiter import RateLimiter, RateLimitConfig

limiter = RateLimiter(
    config=RateLimitConfig(
        messages_per_session=200,          # max turns per session
        sessions_per_user_per_day=10,      # max sessions one user can start per day
        llm_calls_per_session=40,          # max LLM extraction calls per session
    ),
    backend='redis',
    redis_url='redis://localhost:6379',
)

client = chatbotClient(
    openai_api_key='sk-...',
    rate_limiter=limiter,
    ...
)

# Install test dependencies
pip install "pdf-autofillr-chatbot[dev]"
# or from repo: pip install -r requirements.txt  (pytest is included)

# Run all tests
pytest

# Unit tests only - fast, no network, no OpenAI calls
pytest tests/unit/ -v

# Integration tests - requires a running server on port 8001
pytest tests/integration/ -v

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

# Run a specific test file
pytest tests/unit/test_rate_limiter.py -v
pytest tests/unit/test_engine.py -v
pytest tests/unit/test_extraction.py -v