Apppublic

noorulsehar/physical-ai-humanoid-robotics-book-backend

sourceHugging Facemitupdated 9mo agoView on Hugging Face

0likes

App README

Physical AI Humanoid Robotics Book - Python Backend API

🚀 A high-performance FastAPI backend for the Physical AI Humanoid Robotics Book project

🎯 Features

—⚡ FastAPI Framework: High-performance async API with automatic OpenAPI documentation
—🔐 JWT Authentication: Secure user authentication with token-based sessions
—🗄️ PostgreSQL Database: Async SQLAlchemy ORM with connection pooling
—🧠 Qdrant Vector DB: RAG (Retrieval-Augmented Generation) for intelligent chat
—🤖 OpenRouter Integration: AI-powered translation and personalization
—🌐 Smart CORS: Wildcard pattern matching for flexible frontend integration
—🚀 Production Ready: Optimized for both traditional and serverless (Vercel) deployment
—📚 Automatic Docs: Swagger UI & ReDoc included out-of-the-box
—🔧 Environment-Aware: Separate configurations for development, testing, and production

📁 Project Structure

physical-ai-humanoid-robotics-book-backend/
├── 📄 app.py                      # Main FastAPI application
├── 📄 main.py                     # Local development entry point
├── 📄 vercel_handler.py           # Vercel serverless handler
├── 📄 requirements.txt            # Python dependencies
├── 📄 .env.example               # Environment variables template
├── 📄 vercel.json                # Vercel deployment configuration
├── 📄 Dockerfile.python          # Docker configuration
├── 📄 README.md                  # This file
│
├── 📂 config/
│   ├── __init__.py
│   └── settings.py               # Application settings and configuration
│
├── 📂 middleware/
│   ├── __init__.py
│   └── cors_config.py            # CORS configuration with wildcard support
│
├── 📂 utils/
│   ├── __init__.py
│   ├── db.py                     # Database connection and utilities
│   ├── qdrant_client.py          # Qdrant vector database client
│   ├── auth_service.py           # Authentication utilities (JWT)
│   └── models.py                 # SQLAlchemy database models
│
└── 📂 routes/
    ├── __init__.py
    ├── auth.py                   # Authentication routes
    ├── translation.py            # Translation routes
    ├── personalization.py        # Personalization routes
    └── chat.py                   # RAG chat routes

🚀 Quick Start

Prerequisites

—Python 3.11+ (Recommended: 3.11 or higher)
—PostgreSQL 14+ (or compatible database)
—Qdrant (optional, for RAG features)
—OpenRouter API Key (get one from openrouter.ai)

1. Clone & Setup

bash

# Clone the repository
git clone <your-repository-url>
cd physical-ai-humanoid-robotics-book-backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. Environment Configuration

bash

# Copy environment template
cp .env.example .env

# Edit .env with your values
nano .env  # or use your favorite editor

Required `.env` values:

env

# Server Configuration
CENTRAL_BACKEND_PORT=3001
NODE_ENV=development

# Database
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/ai_book_db

# AI Services
OPENROUTER_API_KEY=your_openrouter_api_key_here
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_CHAT_MODEL=google/gemini-2.0-flash-exp:free
OPENROUTER_EMBEDDING_MODEL=openai/text-embedding-ada-002

# Vector Database (Optional)
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=optional_qdrant_key
QDRANT_COLLECTION_NAME=book_content

# Security
SECRET_KEY=your_super_secret_jwt_key_here_min_32_chars
BETTER_AUTH_SECRET=your_better_auth_secret_here

# CORS Configuration (for development)
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173,https://*.vercel.app

3. Database Setup

bash

# Ensure PostgreSQL is running
# Create database (if not exists)
createdb ai_book_db

# The application will automatically create tables on first run
# For manual table creation:
python -c "
from utils.db import init_db
import asyncio
asyncio.run(init_db())
print('Database initialized!')
"

4. Start Development Server

bash

# Option 1: Using main.py (auto-reload enabled)
python main.py

# Option 2: Using uvicorn directly
uvicorn app:app --reload --host 0.0.0.0 --port 3001

# Option 3: With custom port
python main.py --port 3001

# Server will be available at: http://localhost:3001

5. Verify Installation

bash

# Check health endpoint
curl http://localhost:3001/health

# Expected response: {"status":"ok","timestamp":"2024-01-01T12:00:00Z"}

📚 API Documentation

Once running, access the interactive API docs:

—Swagger UI: http://localhost:3001/docs
—ReDoc: http://localhost:3001/redoc

🔌 API Endpoints

Health Check

—GET /health - Server health status
—GET /chat/health - Chat service health

Authentication

—GET /api/auth/auth-health - Auth service status
—POST /api/auth/sign-up/email - Register new user
—POST /api/auth/sign-in/email - Login user
—POST /api/auth/sign-out - Logout user
—GET /api/auth/get-session - Get current session

AI Translation

—POST /api/gemini/translate - Translate text with AI

json

  {
    "text": "Hello world",
    "target_language": "Spanish",
    "context": "Casual conversation"
  }

—POST /api/translate - Alternative translation endpoint

json

  {
    "text": "Humanoid robotics is fascinating",
    "target_language": "French"
  }

Content Personalization

—POST /api/personalize - Personalize content based on user profile

json

  {
    "user_id": "user_123",
    "content": "Original content",
    "preferences": {"difficulty": "beginner", "topics": ["robotics"]}
  }

RAG Chat

—POST /chat - Intelligent chat with book content context

json

  {
    "message": "What are humanoid robots?",
    "user_id": "user_123",
    "session_id": "session_456"
  }

🐳 Docker Deployment

1. Build Docker Image

bash

# Build with Python 3.11
docker build -f Dockerfile.python -t physical-ai-backend .

# Build with custom tag
docker build -f Dockerfile.python -t physical-ai-backend:latest .

2. Run Container

bash

# Basic run
docker run -p 3001:3001 --name ai-backend physical-ai-backend

# With environment file
docker run -p 3001:3001 --env-file .env --name ai-backend physical-ai-backend

# With volume for logs
docker run -p 3001:3001 -v ./logs:/app/logs --env-file .env --name ai-backend physical-ai-backend

3. Docker Compose (Recommended)

Create a docker-compose.yml file:

yaml

version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: ai_book_db
      POSTGRES_USER: ai_user
      POSTGRES_PASSWORD: ai_password
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ai_user"]
      interval: 10s
      timeout: 5s
      retries: 5

  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - qdrant_data:/qdrant/storage

  backend:
    build:
      context: .
      dockerfile: Dockerfile.python
    ports:
      - "3001:3001"
    environment:
      DATABASE_URL: postgresql+asyncpg://ai_user:ai_password@postgres:5432/ai_book_db
      QDRANT_URL: http://qdrant:6333
      OPENROUTER_API_KEY: ${OPENROUTER_API_KEY}
      SECRET_KEY: ${SECRET_KEY}
    depends_on:
      postgres:
        condition: service_healthy
      qdrant:
        condition: service_started
    volumes:
      - .:/app
      - ./logs:/app/logs

volumes:
  postgres_data:
  qdrant_data:

Run with Docker Compose:

bash

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Stop and remove volumes
docker-compose down -v

☁️ Vercel Deployment

1. Install Vercel CLI

bash

npm install -g vercel
# or
yarn global add vercel

2. Deploy to Vercel

bash

# Login to Vercel
vercel login

# Deploy from current directory
vercel

# Deploy with production flag
vercel --prod

# Set environment variables
vercel env add OPENROUTER_API_KEY
vercel env add DATABASE_URL
vercel env add SECRET_KEY

3. Configure Vercel Environment Variables

In Vercel Dashboard → Project → Settings → Environment Variables:

DATABASE_URL=postgresql+asyncpg://...
OPENROUTER_API_KEY=sk-or-...
SECRET_KEY=your-secret-key-here
BETTER_AUTH_SECRET=your-auth-secret
QDRANT_URL=https://your-qdrant-instance
QDRANT_API_KEY=your-qdrant-key
NODE_ENV=production
ALLOWED_ORIGINS=https://your-frontend.vercel.app,https://*.vercel.app

4. Manual Deployment via Git

bash

# Link your repository
vercel git connect

# Each push to main branch triggers deployment
git push origin main

🔧 Configuration

Environment Variables

Variable	Description	Required	Default
`CENTRAL_BACKEND_PORT`	Server port	No	`3001`
`NODE_ENV`	Environment (development/production)	No	`development`
`DATABASE_URL`	PostgreSQL connection URL	Yes	-
`OPENROUTER_API_KEY`	OpenRouter API key	Yes	-
`OPENROUTER_BASE_URL`	OpenRouter API base URL	No	`https://openrouter.ai/api/v1`
`OPENROUTER_CHAT_MODEL`	Chat model name	No	`google/gemini-2.0-flash-exp:free`
`OPENROUTER_EMBEDDING_MODEL`	Embedding model	No	`openai/text-embedding-ada-002`
`QDRANT_URL`	Qdrant server URL	No	`http://localhost:6333`
`QDRANT_API_KEY`	Qdrant API key	No	-
`QDRANT_COLLECTION_NAME`	Vector collection name	No	`book_content`
`SECRET_KEY`	JWT secret key	Yes	-
`BETTER_AUTH_SECRET`	Auth session secret	Yes	-
`ALLOWED_ORIGINS`	CORS allowed origins	No	`*` (development)

Database Models

The application uses these main models:

—User: User accounts and profiles
—Session: User authentication sessions
—Account: Linked authentication accounts
—ChatHistory: Store chat conversations
—UserPreferences: User personalization settings

🧪 Testing

Run Tests

bash

# Install test dependencies
pip install pytest pytest-asyncio httpx

# Run all tests
pytest

# Run with coverage
pytest --cov=app --cov-report=html

# Run specific test file
pytest tests/test_auth.py -v

Test Endpoints with curl

bash

# Health check
curl http://localhost:3001/health

# Auth health
curl http://localhost:3001/api/auth/auth-health

# Sign up
curl -X POST http://localhost:3001/api/auth/sign-up/email \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"secure123","name":"Test User"}'

# Translate
curl -X POST http://localhost:3001/api/gemini/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello world","target_language":"Spanish"}'

🛠️ Development

Code Quality Tools

bash

# Install development dependencies
pip install black isort flake8 mypy

# Format code
black .
isort .

# Lint code
flake8 .

# Type checking
mypy .

# Run all checks
./scripts/check.sh

Debugging

bash

# Enable debug mode
export NODE_ENV=development
python main.py --debug

# With detailed logging
export LOG_LEVEL=DEBUG
python main.py

Database Migrations

For schema changes, use Alembic:

bash

# Initialize alembic (first time only)
alembic init migrations

# Create migration
alembic revision --autogenerate -m "Description"

# Apply migration
alembic upgrade head

# Rollback migration
alembic downgrade -1

📊 Monitoring & Logging

Access Logs

bash

# Local development logs
tail -f logs/app.log

# Docker logs
docker logs -f ai-backend

# Docker Compose logs
docker-compose logs -f backend

Health Monitoring

bash

# Check all health endpoints
curl http://localhost:3001/health
curl http://localhost:3001/chat/health
curl http://localhost:3001/api/auth/auth-health

# Prometheus metrics (if enabled)
curl http://localhost:3001/metrics

🔒 Security Best Practices

1.Secrets Management:
2.Never commit .env files
3.Use environment variables in production
4.Rotate secrets regularly

1.Database Security:
2.Use strong passwords
3.Enable SSL for production databases
4.Restrict database access by IP

1.API Security:
2.Validate all input data
3.Rate limiting for public endpoints
4.JWT token expiration (default: 24 hours)

1.CORS Configuration:

python

   # Production configuration
   ALLOWED_ORIGINS=https://your-domain.com,https://*.your-domain.com
   
   # Development configuration
   ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

🚨 Troubleshooting

Common Issues & Solutions

1. Database Connection Failed

bash

# Check PostgreSQL is running
sudo systemctl status postgresql

# Test connection
psql -U username -d ai_book_db -h localhost

# Update DATABASE_URL in .env
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/ai_book_db

2. Port Already in Use

bash

# Find process using port 3001
sudo lsof -i :3001

# Kill the process
sudo kill -9 <PID>

# Or change port in .env
CENTRAL_BACKEND_PORT=3002

3. Import Errors

bash

# Reinstall dependencies
pip uninstall -r requirements.txt -y
pip install -r requirements.txt

# Check Python version
python --version  # Should be 3.11+

# Recreate virtual environment
rm -rf venv
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

4. CORS Issues

bash

# Check ALLOWED_ORIGINS
echo $ALLOWED_ORIGINS

# Test CORS headers
curl -I -X OPTIONS http://localhost:3001/api/auth/sign-in/email

5. JWT Authentication Issues

bash

# Verify SECRET_KEY length (min 32 chars)
echo ${#SECRET_KEY}

# Check token expiration
jwt.decode(token, SECRET_KEY, algorithms=["HS256"])

Debug Mode

bash

# Enable full debug output
export DEBUG=true
export LOG_LEVEL=DEBUG
python main.py

# Check logs in real-time
tail -f logs/app.log

🤝 Contributing

1.Fork the repository
2.Create a feature branch
3.Make your changes
4.Run tests and checks
5.Submit a pull request

Development Setup

bash

# Fork and clone
git clone https://github.com/your-username/physical-ai-humanoid-robotics-book-backend.git
cd physical-ai-humanoid-robotics-book-backend

# Set up development environment
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Run tests
pytest

# Make your changes and test

📄 License

MIT License - see LICENSE file for details.

📞 Support

—Issues: GitHub Issues
—Discussions: GitHub Discussions
—Email: support@example.com

🙏 Acknowledgments

—FastAPI - The modern web framework
—OpenRouter - AI model routing service
—Qdrant - Vector similarity search engine
—Vercel - Serverless deployment platform

Made with ❤️ for the Physical AI Humanoid Robotics Book Project

⚡ Get Started | 📚 API Docs | 🐳 Docker | ☁️ Vercel

</div>