qa-and-rag-ai-assistant/README.md

# RAG AI Assistant

A FastAPI application with Telegram bot integration for user authentication and profile management.

## Features

- **User Authentication** via Telegram Bot
- **Profile Management** with CV upload to MinIO
- **PostgreSQL Database** with async SQLAlchemy ORM
- **RESTful API** endpoints for profiles and vacancies

## Architecture

- **Backend**: FastAPI (Python)
- **Database**: PostgreSQL with async support (asyncpg)
- **File Storage**: MinIO (S3-compatible)
- **Bot**: Telegram Bot (aiogram 3.x)
- **ORM**: SQLAlchemy with async sessions

## Database Schema

### Users Table
- `id` - Auto-increment primary key
- `telegram_id` - Unique Telegram user ID (indexed)
- `token` - Unique auth token (indexed)
- `username` - Telegram username
- `status` - Auth status ('pending' or 'success')
- `created_at` - Timestamp
- `updated_at` - Timestamp

### Profiles Table
- `id` - Auto-increment primary key
- `email` - Unique email (indexed)
- `name`, `position`, `competencies`, `experience`, `skills`
- `country`, `languages`, `employment_format`, `rate`, `relocation`
- `cv_url` - Link to uploaded CV in MinIO
- `created_at` - Timestamp
- `updated_at` - Timestamp

## Setup Instructions

### 1. Prerequisites

- Python 3.10+
- PostgreSQL 14+
- Docker (for MinIO)

### 2. Install Dependencies

```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

### 3. Configure Environment

Copy and configure your `.env` file:

```env
# Bot Configuration
BOT_API_KEY=your_telegram_bot_token
HOST=localhost
PORT=8000

# PostgreSQL Configuration
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=rag_ai_assistant
POSTGRES_PORT=5432
POSTGRES_HOST=localhost

# MinIO Configuration
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=minioadmin
MINIO_ENDPOINT=localhost:9000
MINIO_PORT=9000
MINIO_CONSOLE_PORT=9001
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=resumes
```

### 4. Start Services

```bash
# Start PostgreSQL and MinIO using Docker
docker-compose up -d

# Verify services are running
docker ps
```

### 5. Initialize Database

```bash
# Run database initialization script
python init_db.py

# Or manually create tables
python -c "from database.database import init_db; import asyncio; asyncio.run(init_db())"
```

### 6. Run Application

**Option A: Run bot and API together**
```bash
python bot.py
```

**Option B: Run separately**
```bash
# Terminal 1 - API
uvicorn app:app --reload --host localhost --port 8000

# Terminal 2 - Bot
python -c "from bot import start_bot; import asyncio; asyncio.run(start_bot())"
```

## API Endpoints

### Authentication
- `GET /login` - Generate auth token and Telegram bot URL
- `GET /check-auth/{token}` - Check authentication status
- `GET /database/tokens` - List all tokens (debug)

### Profiles
- `POST /profile` - Create/update profile with CV upload
- `GET /profile/{email}` - Get profile by email
- `GET /profile/cv/{file_id}` - Download CV file

### Vacancies
- `GET /vacancies` - List all vacancies

## Usage Flow

1. **User visits website** → Calls `GET /login`
2. **Gets Telegram bot link** with unique token
3. **User clicks link** → Opens Telegram bot
4. **User sends `/start {token}`** to bot
5. **Bot validates token** → Updates status to "success" in DB
6. **Website polls** `GET /check-auth/{token}` → User authenticated!

## Database Operations

### Manual Database Operations

```python
# Test database connection
python database/database.py

# Initialize database
python init_db.py

# Drop and recreate tables (⚠️ DELETES ALL DATA)
python init_db.py  # Choose option 2
```

### Using Database Sessions in Code

```python
from database.database import get_db, User
from sqlalchemy import select
from fastapi import Depends

@app.get("/example")
async def example_endpoint(db: AsyncSession = Depends(get_db)):
    # Query users
    result = await db.execute(select(User).where(User.status == "success"))
    users = result.scalars().all()
    return users
```

## Development

### Project Structure
```
.
├── app.py                  # FastAPI application
├── bot.py                  # Telegram bot
├── config.py               # Configuration
├── init_db.py              # Database initialization script
├── requirements.txt        # Python dependencies
├── .env                    # Environment variables
├── database/
│   ├── database.py         # Database models and session management
│   └── minio-processor.py  # MinIO utilities
├── tests/                  # Test files
└── docker-compose.yml      # Docker services
```

### Testing

```bash
# Install test dependencies
pip install pytest pytest-asyncio httpx

# Run tests
pytest tests/ -v

# Test specific file
pytest tests/test_bot.py -v
```

## Troubleshooting

### PostgreSQL Connection Issues
```bash
# Check if PostgreSQL is running
docker ps | grep postgres

# Check connection
psql -h localhost -U postgres -d rag_ai_assistant
```

### MinIO Connection Issues
```bash
# Check if MinIO is running
docker ps | grep minio

# Access MinIO console
open http://localhost:9001
```

### Database Migration
```bash
# If you need to reset the database
python init_db.py  # Choose option 2 (reset)
```

## Production Considerations

1. **Security**
   - Change default passwords in `.env`
   - Use environment-specific configurations
   - Enable SSL/TLS for PostgreSQL
   - Implement rate limiting

2. **Performance**
   - Adjust SQLAlchemy pool settings
   - Add database indexes as needed
   - Implement caching (Redis)

3. **Monitoring**
   - Add logging
   - Set up error tracking (Sentry)
   - Monitor database performance

## License

MIT