virgil-ai/README.md

# Lolly AI

A FastAPI-based insurance AI assistant that integrates with talestorm-ai for chat capabilities and provides insurance estimation services.

## Features

- **Insurance Chat**: AI-powered chat interface for insurance-related questions
- **Insurance Estimation**: AI-powered estimation using TALESTORM API for comprehensive underwriting and pricing
- **Integration**: Seamless integration with talestorm-ai API
- **Modern API**: Built with FastAPI for high performance and automatic documentation

## Quick Start with Docker Compose

The easiest way to run lolly-ai is using Docker Compose, which will set up both lolly-ai and its dependency talestorm-ai.

### Prerequisites

- Docker and Docker Compose installed
- talestorm-ai repository cloned in the same parent directory as lolly-ai

### Setup

1. Clone both repositories:
```bash
git clone <talestorm-ai-repo-url> ../talestorm-ai
git clone <lolly-ai-repo-url> lolly-ai
cd lolly-ai
```

2. Create a `.env` file with your configuration:
```bash
# Database Configuration (for talestorm-ai)
POSTGRES_USER=postgres
POSTGRES_PASSWORD=password
POSTGRES_DB=talestorm
PUBLIC_POSTGRES_PORT=5432

# talestorm-ai Configuration
PUBLIC_TALESTORM_PORT=8000
ADMIN_API_KEY=changeme-admin-key
OPENAI_API_KEY=your-openai-api-key-here

# lolly-ai Configuration
PUBLIC_LOLLY_PORT=7310
TALESTORM_API_KEY=your-talestorm-api-key-here
TALESTORM_AGENT_ID=your-talestorm-chat-agent-id-here
TALESTORM_ESTIMATION_AGENT_ID=your-talestorm-estimation-agent-id-here
INSURANCE_API_BASE_URL=https://apilolly.cyberpug.ru

# Server Configuration
HOST=0.0.0.0
PORT=7310
DEBUG=false

# CORS Configuration
CORS_ORIGINS=*

# Logging
LOG_LEVEL=INFO
```

3. Start the services:
```bash
docker compose up -d
```

4. Access the services:
- **lolly-ai API**: http://localhost:7310
- **talestorm-ai API**: http://localhost:8000
- **lolly-ai docs**: http://localhost:7310/docs
- **talestorm-ai docs**: http://localhost:8000/docs

### Development with Docker Compose

For development, you can mount the source code:

```bash
docker compose up -d
```

The source code is automatically mounted, so changes will be reflected immediately.

### Stopping the services

```bash
docker compose down
```

To remove volumes as well:
```bash
docker compose down -v
```

## Agent Configuration

The system uses two different TALESTORM agents for different purposes:

- **TALESTORM_AGENT_ID**: Used for general insurance chat functionality
- **TALESTORM_ESTIMATION_AGENT_ID**: Used specifically for insurance estimation with structured output schema

This separation allows for specialized agents optimized for their respective tasks.

## Estimation Service

The estimation service has been refactored to use the TALESTORM API instead of local underwriting logic. This provides:

- **AI-Powered Analysis**: Uses advanced AI models for risk assessment and pricing
- **Comprehensive Evaluation**: Analyzes all health factors, medications, and conditions
- **Structured Output**: Returns detailed tier assignments and pricing for each applicant
- **Flexible Response**: Handles both accepted and rejected applications with detailed reasoning

### Estimation Request Format

The service accepts insurance application data and returns structured estimation results:

```json
{
  "status": "accepted",
  "details": {
    "dtq": false,
    "reason": "All applicants have manageable conditions...",
    "tier": 3,
    "total_price": 815.75
  },
  "results": [
    {
      "name": "Sarah Johnson",
      "applicant_type": "primary",
      "age": 39,
      "bmi": 23.38,
      "tier": 3,
      "rx_spend": 40.0,
      "message": "Type 2 diabetes well-controlled..."
    }
  ]
}
```

## API Endpoints

All API endpoints are versioned under `/api/v1/`:

### `/api/v1/sessions` (POST)
Create a new chat session.

**Query Parameters:**
- `agent_id` (optional): Specific agent ID to use for the session

**Response:**
```json
{
  "session_id": "session-uuid"
}
```

### `/api/v1/sessions` (GET)
List all available sessions.

**Response:**
```json
{
  "sessions": [
    {
      "id": "session-uuid",
      "organization_id": "org-uuid",
      "agent_id": "agent-uuid",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}
```

### `/api/v1/sessions/{session_id}` (GET)
Get details of a specific session.

**Response:**
```json
{
  "id": "session-uuid",
  "organization_id": "org-uuid",
  "agent_id": "agent-uuid",
  "created_at": "2024-01-01T00:00:00Z"
}
```

### `/api/v1/agents` (GET)
List available AI agents.

**Response:**
```json
{
  "agents": [
    {
      "id": "agent-uuid",
      "name": "Insurance Assistant",
      "model_name": "gpt-3.5-turbo",
      "model_provider": "openai",
      "enable_rag_search": true,
      "instructions": "You are an insurance expert..."
    }
  ]
}
```

### `/api/v1/insurance_chat` (POST)
Handles insurance-related chat requests.

**Request Body:**
```json
{
  "message": "What does my health insurance cover?",
  "session_id": "optional-session-id"
}
```

**Response:**
```json
{
  "session_id": "session-uuid",
  "answer": "Your health insurance covers...",
  "sources": [
    {
      "plan_name": "Cigna 1000 Classic",
      "chunk_number": 0,
      "content_chunk": "This plan covers preventive care, doctor visits, and prescription drugs..."
    }
  ],
  "history": [
    {
      "role": "user",
      "message": "What does my health insurance cover?"
    },
    {
      "role": "assistant", 
      "message": "Your health insurance covers..."
    }
  ]
}
```

### `/api/v1/estimation` (POST)
Handles insurance estimation and underwriting requests.

**Request Body:**
```json
{
  "uid": "string",
  "applicants": [
    {
      "applicant": 1,
      "firstName": "string",
      "lastName": "string",
      "midName": "string",
      "phone": "string",
      "gender": "male",
      "dob": "2025-07-25",
      "nicotine": true,
      "weight": 0,
      "heightFt": 0,
      "heightIn": 0
    }
  ],
  "plans": [
    {
      "id": 0,
      "coverage": 1,
      "tier": "string"
    }
  ],
  "phq": {
    "treatment": true,
    "invalid": true,
    "pregnancy": true,
    "effectiveDate": "2025-07-25",
    "disclaimer": true,
    "signature": "string",
    "medications": [
      {
        "applicant": 0,
        "name": "string",
        "rxcui": "string",
        "dosage": "string",
        "frequency": "string",
        "description": "string"
      }
    ],
    "issues": [
      {
        "key": "string",
        "details": [
          {
            "key": "string",
            "description": "string"
          }
        ]
      }
    ],
    "conditions": [
      {
        "key": "string",
        "description": "string"
      }
    ]
  },
  "income": 0,
  "address": {
    "address1": "string",
    "address2": "string",
    "city": "string",
    "state": "string",
    "zipcode": "string"
  }
}
```

**Response:**
```json
{
  "status": "accepted",
  "details": {
    "dtq": true,
    "reason": "string",
    "tier": 0,
    "total_price": 0
  },
  "results": [
    {
      "name": "string",
      "applicant_type": "Primary",
      "age": 0,
      "bmi": 0,
      "tier": 0,
      "rx_spend": 0,
      "message": "string"
    }
  ]
}
```