Metadata-Version: 2.4
Name: ai-feedback-fastapi
Version: 2.0.0
Summary: FastAPI-based AI Feedback Processing Service
Author-email: AI Feedback Team <team@myinterviewpractice.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <3.11,>=3.10
Requires-Dist: aioboto3>=12.0.0
Requires-Dist: aiohttp>=3.9.1
Requires-Dist: aiomysql>=0.2.0
Requires-Dist: botocore>=1.34.0
Requires-Dist: cryptography>=3.4.8
Requires-Dist: dlib>=19.24.0
Requires-Dist: fastapi>=0.104.1
Requires-Dist: faster-whisper>=1.0.0
Requires-Dist: gunicorn>=21.2.0
Requires-Dist: httpx>=0.25.2
Requires-Dist: moviepy>=1.0.3
Requires-Dist: numpy>=1.24.3
Requires-Dist: opencv-python>=4.8.1.78
Requires-Dist: prometheus-client>=0.19.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pydub>=0.25.1
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: sentry-sdk[fastapi]>=1.40.0
Requires-Dist: structlog>=23.2.0
Requires-Dist: tortoise-orm[aiomysql]>=0.20.0
Requires-Dist: uvicorn[standard]>=0.24.0
Provides-Extra: dev
Requires-Dist: mypy>=1.7.1; extra == 'dev'
Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.1; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
Requires-Dist: pytest>=7.4.3; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: prod
Requires-Dist: gunicorn>=21.2.0; extra == 'prod'
Description-Content-Type: text/markdown

# AI Feedback FastAPI Service

A modern, high-performance AI feedback processing service built with FastAPI, designed to replace the legacy Flask-based implementation.

## ✨ Features

- Legacy-compatible JSON output (same keys/format consumers expect)
- Legacy pupil-based gaze tracking (left/center/right) with ROI centering, smoothing
- Whisper transcription with timestamps and detailed start/end logging
- Background queue poller (default every 30s) plus timeout monitor
- Processes only ready jobs: `status='0'` and `data_process='1'`
- Centralized S3 and temp-file handling
- **Sentry integration for error tracking and performance monitoring**

## 📁 Project Structure

```text
.
├─ app/
│  ├─ api/
│  │  └─ v1/
│  │     ├─ api.py              # Router aggregator
│  │     └─ endpoints/          # FastAPI route handlers (health, queue, ...)
│  ├─ core/                      # DB init, logging, config
│  ├─ services/                  # Business logic (analysis, processors, background tasks)
│  ├─ repositories/              # DB access (queue, feedback, interview)
│  ├─ schemas/                   # Pydantic models
│  ├─ models/                    # ORM models
│  ├─ utils/                     # Helpers (video/audio processing, runners)
│  └─ resources/
│     ├─ models/                 # dlib/cascade files
│     └─ word_lists/             # filler/power/negative/um lists
├─ config/                       # Environment files
├─ docs/                         # Documentation (see docs/index.md)
├─ tests/                        # Test suite
├─ docker/                       # Docker-related assets (if any)
├─ Dockerfile
├─ docker-compose.yml
├─ Makefile
├─ pyproject.toml
└─ README.md
```

## 🚀 Quick Start

### Prerequisites
- Python 3.10
- uv package manager
- MySQL 8.0+

### Installation

1. **Install dependencies**
   ```bash
   uv sync
   ```

2. **Setup environment**
   ```bash
   cp config/env.example config/.env
   # Edit config/.env with your settings
   ```

3. **Run the service**
   ```bash
   # Development mode
   make run-dev
   
   # Production mode
   make run-prod
   ```

## 🛠️ Development

### Available Commands
```bash
make help          # Show all available commands
make install-dev   # Install development dependencies
make test          # Run tests
make lint          # Run linting checks
make format        # Format code
make check-types   # Run type checking
make clean         # Clean generated files
```

### Code Quality
- **Black** for code formatting
- **isort** for import sorting
- **flake8** for linting
- **mypy** for type checking
- **pre-commit** hooks for automated checks

## 🐳 Docker

### Development
```bash
docker-compose up -d
```

### Production
```bash
docker build -t ai-feedback-fastapi .
docker run -p 9001:9001 ai-feedback-fastapi
```

## 📊 API Documentation

Once running, visit:
- **API Docs**: http://localhost:9001/docs
- **Health Check**: http://localhost:9001/health

### Queue Endpoints
- `POST /api/v1/queue/process` — trigger an immediate processing pass
- `POST /api/v1/queue/timeout-check` — check and reset long-running jobs (> 2h)
- `GET /api/v1/queue/status` — basic queue stats and average processing time

### Documentation
- Start here: `docs/index.md` (full index)
- End-to-end flow: `docs/architecture.md`
- Services: `docs/services.md`
- Queue: `docs/queue.md`
- Resources: `docs/resources.md`
- Quickstart: `docs/quickstart.md`

## 🔗 Related Projects

- [Legacy Flask Service](../ai-feedback.myinterviewpractice.com/)
- [PHP Frontend](../../public_html/)
- [Admin Panel](../../admin.myinterviewpractice.com/)