Installation Guide

This guide will help you set up Pili, the Exercise Tracker Chatbot, on your system.

Prerequisites

Before installing Pili, ensure you have the following prerequisites:

• Python 3.8+: Download from python.org

• Git: For cloning the repository

• Conda (recommended): For environment management

System Requirements

Component	Requirement
Operating System	Linux, macOS, or Windows 10+
Python Version	3.8 or higher
Memory	Minimum 4GB RAM (8GB recommended)
Storage	At least 2GB free space
Network	Internet connection for API calls

Quick Installation

1. Clone the Repository

   git clone <repository-url>
   cd Scaffold-your-shape-Chatbot
   

2. Create Conda Environment

   conda create -n Pili python=3.11
   conda activate Pili
   

3. Install Dependencies

   pip install -r requirements.txt
   

4. Configure Environment

   cp .env.sample .env
   # Edit .env with your actual configuration values
   

5. Run the Application

   uvicorn main:app --reload
   

6. Verify Installation

   Open your browser and navigate to:

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

   • Health Check: http://localhost:8000/api/health

Environment Configuration

Create a .env file in the project root with the following variables:

# LangChain Configuration
LANGCHAIN_API_KEY=your_langchain_api_key_here
LANGCHAIN_PROJECT=pili-exercise-chatbot

# LLM Provider Configuration
LLM_PROVIDER=openai  # Options: openai, ollama, vllm, local
OPENAI_API_KEY=your_openai_api_key_here

# Local LLM Configuration (if using local provider)
LOCAL_LLM_BASE_URL=http://localhost:11434
LOCAL_LLM_MODEL=llama2

# MCP Server Configuration
MCP_BASE_URL=http://192.168.1.98:3005/api/mcp

Docker Installation

For a containerized deployment:

1. Using Docker Compose

   docker-compose up -d
   

2. With VLLM Support

   docker-compose -f docker-compose.yml -f docker-compose.vllm.yml up -d
   

3. Production Deployment

   docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d
   

Development Setup

For development work, follow these additional steps:

1. Install Development Dependencies

   pip install -r requirements.txt
   pip install pytest pytest-asyncio black isort mypy
   

2. Pre-commit Hooks (Optional)

   pip install pre-commit
   pre-commit install
   

3. Run Tests

   pytest
   

Troubleshooting

Common installation issues and solutions:

Port Already in Use

# Find process using port 8000
lsof -i :8000

# Kill the process or use a different port
uvicorn main:app --reload --port 8001

Permission Errors

# On Linux/macOS, you may need to use sudo for global installs
# It's recommended to use virtual environments instead

Dependency Conflicts

# Create a fresh environment
conda deactivate
conda remove -n Pili --all
conda create -n Pili python=3.11
conda activate Pili
pip install -r requirements.txt

Memory Issues

If you encounter memory issues:

• Ensure you have at least 4GB RAM available

• Close other applications

• Consider using a smaller LLM model for local deployments

Next Steps

After successful installation:

1. Read the Quick Start Guide guide

2. Configure your Configuration Guide settings

3. Explore the Architecture Overview

4. Try the Basic Usage Examples

Tip

For production deployments, review the configuration guide carefully.

Warning

Make sure to never commit your .env file with real API keys to version control!