Lifeline AI

Lifeline AI is an advanced AI service designed to function as a copilot for mental health counselors. This project leverages FastAPI to deliver a robust and scalable API backend, integrating custom middleware and enhanced logging capabilities to ensure reliable performance and traceability. With environment-based configuration and containerization via Docker, Lifeline AI is built for seamless deployment and development. Managed with Poetry for dependency handling, the service provides intelligent insights and support tools to empower mental health professionals in their daily practice.

Getting Started

📋 Table of Contents

• Overview
• Prerequisites
• Quick Start
• Development Setup
• Database Management
• Code Quality & Testing
• Docker Deployment
• API Documentation
• Project Structure
• Contributing

✨ Overview

• AI-Powered Counseling Support: Intelligent insights and analysis for mental health professionals
• FastAPI Backend: High-performance, async API with automatic documentation
• Vector Database Integration: Weaviate for semantic search and conversation analysis
• Migration System: Comprehensive database schema management with rollback capabilities
• Environment-Based Configuration: Flexible deployment across different environments
• Docker Support: Containerized deployment for consistent environments
• Code Quality Tools: Pre-commit hooks, linting, and formatting
• HIPAA Compliance: Secure handling of sensitive mental health data

🔧 Prerequisites

Before you begin, ensure you have the following installed:

• Python 3.12+ - Download Python
• Poetry - Install Poetry
• Docker - Install Docker
• Git - Install Git

🚀 Quick Start

1. Clone the Repository

git clone [email protected]:KeyValueSoftwareSystems/lifeline-ai.git
cd lifeline-ai

2. Install Dependencies

poetry install

3. Set Up Database

# Run all pending migrations
poetry run python scripts/migrate.py all

4. Start the Application

poetry run python app/main.py

The application will be available at:

• API: http://localhost:8000
• Documentation: http://localhost:8000/docs

🛠️ Development Setup

Environment Configuration

Create a .env file in the project root with your configuration:

# Copy example environment file
cp .env.example .env

# Edit with your specific settings
nano .env

Database Setup

Weaviate Connection

For local development, you can use Docker Compose to run Weaviate:

# Start Weaviate locally
docker-compose up -d

# Or connect to remote Weaviate via SSH tunnel
ssh -L 8080:localhost:8080 -L 50051:localhost:50051 your-remote-server

Migration Management

# Check migration status
poetry run python scripts/migrate.py status

# View migration history
poetry run python scripts/migrate.py history

# Test database connection
poetry run python scripts/test_weaviate_connection.py

# List reference documents
poetry run python scripts/list_reference_documents.py

Development Workflow

# Install pre-commit hooks
pre-commit install

# Run code formatting
poetry run black app/
poetry run isort app/

# Run linting
poetry run flake8 app/

# Run all pre-commit hooks
pre-commit run --all-files

🗄️ Database Management

Migration System Overview

Lifeline AI uses a comprehensive migration system to manage Weaviate database schema changes:

• Location: app/migrations/ directory
• Naming Convention: {number}-{description}.py (e.g., 001-create-conversation-collection.py)
• Tracking: Migration history stored in Weaviate MigrationHistory collection
• Rollback Support: Each migration has both up and down functions

Migration Commands

Generate New Migration

# Create a new migration file
poetry run python scripts/migrate.py generate "add-user-session-collection"

This creates a file like 003-add-user-session-collection.py with boilerplate code.

Execute Migrations

# Run the next pending migration
poetry run python scripts/migrate.py up

# Run all pending migrations
poetry run python scripts/migrate.py all

# Rollback last migration
poetry run python scripts/migrate.py down

Monitor Migrations

# Check current status
poetry run python scripts/migrate.py status

# View detailed history
poetry run python scripts/migrate.py history

Migration Status Tracking

The system tracks migration status with visual indicators:

• completed: ✅ Successfully applied
• failed: ❌ Failed during execution
• running: 🔄 Currently executing
• pending: ⏳ Not yet started

Migration Examples

Creating a New Collection

async def up(client):
    await client.collections.create(
        name="UserSession",
        properties=[
            wvc.Property(name="user_id", data_type=wvc.DataType.TEXT),
            wvc.Property(name="session_data", data_type=wvc.DataType.TEXT),
        ]
    )

async def down(client):
    await client.collections.delete("UserSession")

Adding Properties to Existing Collection

async def up(client):
    collection = client.collections.get("Conversation")
    await collection.config.add_property(
        wvc.Property(name="new_field", data_type=wvc.DataType.TEXT)
    )

async def down(client):
    collection = client.collections.get("Conversation")
    await collection.config.remove_property("new_field")

Migration Best Practices

1. Always implement both up and down functions
2. Test migrations thoroughly before applying to production
3. Use descriptive migration names
4. Keep migrations small and focused
5. Never modify existing migration files after they've been applied

Note: Weaviate doesn't support property deletion in current versions. To "delete" a property, either recreate the collection or simply stop using the property (it will remain in storage but unused).

🧪 Code Quality & Testing

Pre-commit Hooks

The project uses pre-commit hooks to ensure code quality:

# Install pre-commit hooks
pre-commit install

# Run all hooks manually
pre-commit run --all-files

# Run specific hooks
pre-commit run black --all-files
pre-commit run isort --all-files
pre-commit run flake8 --all-files

Code Formatting & Linting

# Format code with Black
poetry run black app/

# Sort imports with isort
poetry run isort app/

# Lint with flake8
poetry run flake8 app/ --count --show-source --statistics

# Check formatting without changes
poetry run black --check app/
poetry run isort --check-only app/

Testing

# Run all tests
poetry run pytest

# Run tests with coverage
poetry run pytest --cov=app --cov-report=term-missing --cov-report=html

# Run specific test file
poetry run pytest tests/core/test_specific.py

🐳 Docker Deployment

Build Docker Image

# Build the application image
docker build -t lifeline-ai .

# Build with specific tag
docker build -t lifeline-ai:v1.0.0 .

Run Docker Container

# Run the container
docker run -p 8000:8000 lifeline-ai

# Run with environment variables
docker run -p 8000:8000 -e ENVIRONMENT=production lifeline-ai

# Run in detached mode
docker run -d -p 8000:8000 --name lifeline-ai lifeline-ai

Docker Compose

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Full Local Stack

To run the API together with LocalStack (SQS/S3) and Weaviate, use the bundled compose file:

docker compose -f docker-compose.full.yml up --build

Key details:

• The API is exposed on http://localhost:8001.
• The compose file injects WEAVIATE__HTTP_HOST=weaviate, so no manual .env change is needed for the in-cluster hostname.
• scripts/bootstrap_localstack.sh runs on container start and waits for LocalStack before creating the required queues (TRANSCRIPTION_RESULTS_QUEUE, TRANSCRIBE_AND_SUMMARIZE_RESPONSE_QUEUE) and the S3 bucket defined by QUEUE__TRANSCRIBE_AND_SUMMARIZE_RESULTS_BUCKET.
• Ensure your .env contains the queue URLs/bucket name you want the application to use; the bootstrap script derives queue names from those URLs when present.
• When you shut the stack down, volumes keep LocalStack and Weaviate data so subsequent starts are fast.

To tear everything down:

docker compose -f docker-compose.full.yml down

📚 API Documentation

Interactive Documentation

Once the application is running, access the automatically generated API documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI Schema: http://localhost:8000/openapi.json

📁 Project Structure

lifeline-ai/
├── app/                          # Main application code
│   ├── api/                      # API routes and endpoints
│   ├── core/                     # Core business logic
│   │   ├── conversations/        # Conversation analysis services
│   │   ├── embeddings/           # Embedding services
│   │   ├── text_generations/     # Text generation services
│   │   ├── vector_db/            # Vector database services
│   │   └── config.py             # Application configuration
│   ├── migrations/               # Database migration files
│   ├── schemas/                  # Pydantic models
│   ├── utils/                    # Utility functions
│   └── main.py                   # Application entry point
├── scripts/                      # Utility scripts
│   ├── migrate.py                # Migration management
│   ├── list_reference_documents.py # Database exploration
│   └── test_weaviate_connection.py # Connection testing
├── tests/                        # Test files
├── docker-compose.yml            # Docker Compose configuration
├── Dockerfile                    # Docker image definition
├── pyproject.toml                # Poetry configuration
└── README.md                     # This file

🤝 Contributing

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Make your changes
4. Run tests and linting: pre-commit run --all-files
5. Commit your changes: git commit -m "Add your feature"
6. Push to your fork: git push origin feature/your-feature-name
7. Create a Pull Request

Code Standards

• Follow PEP 8 style guidelines
• Use type hints for all functions
• Write comprehensive docstrings
• Include tests for new functionality
• Ensure all pre-commit hooks pass

Reporting Issues

When reporting issues, please include:

• Python version
• Operating system
• Steps to reproduce
• Expected vs actual behavior
• Relevant error messages

Contributing

Please see the CONTRIBUTING.md to get started.

🆘 Support

For support and questions:

• Create an issue in the repository
• Contact the development team
• Check the API documentation at /docs

---

Lifeline AI - Empowering mental health professionals with AI-driven insights and support.