# AI Powered Gifting Platform

An intelligent API service that helps users find the perfect gift for any recipient using AI recommendations based on preferences and interests.

## Features

- 🎁 **Gift Management**: Track gift ideas, purchases, and occasions
- 🧠 **AI-Powered Recommendations**: Get personalized gift suggestions based on recipient preferences
- 👤 **User Profiles**: Secure authentication and user management
- 🔍 **Preference Tracking**: Store recipient interests, hobbies, sizes, and dislikes
- 🔒 **Secure API**: JWT authentication with role-based access control

## Tech Stack

- **Framework**: FastAPI
- **Database**: SQLite with SQLAlchemy ORM
- **Authentication**: JWT with OAuth2
- **Migrations**: Alembic
- **AI Integration**: OpenAI API
- **Code Quality**: Ruff linter

## Getting Started

### Prerequisites

- Python 3.8+
- OpenAI API key (for AI-powered recommendations)

### Environment Variables

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

```
SECRET_KEY=your-secret-key-for-jwt
OPENAI_API_KEY=your-openai-api-key
OPENAI_MODEL=gpt-3.5-turbo  # or another OpenAI model
```

### Installation

1. Clone the repository:

```bash
git clone <repository-url>
cd ai-powered-gifting-platform
```

2. Install dependencies:

```bash
pip install -r requirements.txt
```

3. Run database migrations:

```bash
alembic upgrade head
```

4. Start the server:

```bash
uvicorn main:app --reload
```

The API will be available at http://localhost:8000.

## API Documentation

Once the application is running, you can access:

- Interactive API documentation: http://localhost:8000/docs
- Alternative documentation: http://localhost:8000/redoc
- OpenAPI schema: http://localhost:8000/openapi.json

## API Endpoints

### Health Check
- `GET /api/v1/health`: Check the API service health

### Authentication
- `POST /api/v1/auth/login`: Get access token

### Users
- `POST /api/v1/users`: Create new user
- `GET /api/v1/users/me`: Get current user info
- `PUT /api/v1/users/me`: Update current user

### Gifts
- `GET /api/v1/gifts`: List all gifts
- `POST /api/v1/gifts`: Create a new gift
- `GET /api/v1/gifts/{id}`: Get gift details
- `PUT /api/v1/gifts/{id}`: Update a gift
- `DELETE /api/v1/gifts/{id}`: Delete a gift

### Preferences
- `GET /api/v1/preferences`: List all preferences
- `POST /api/v1/preferences`: Create a new preference
- `GET /api/v1/preferences/{id}`: Get preference details
- `PUT /api/v1/preferences/{id}`: Update a preference
- `DELETE /api/v1/preferences/{id}`: Delete a preference

### Recommendations
- `GET /api/v1/recommendations`: List all recommendations
- `POST /api/v1/recommendations`: Get AI-powered gift recommendation
- `GET /api/v1/recommendations/{id}`: Get recommendation details
- `PUT /api/v1/recommendations/{id}`: Update a recommendation
- `DELETE /api/v1/recommendations/{id}`: Delete a recommendation

## Project Structure

```
.
├── alembic.ini                   # Alembic configuration
├── app                           # Application package
│   ├── api                       # API endpoints
│   │   └── v1                    # API version 1
│   │       ├── endpoints         # API endpoint modules
│   │       └── api.py            # API router
│   ├── core                      # Core modules
│   │   ├── config.py             # Settings and configuration
│   │   └── security.py           # Security utilities
│   ├── db                        # Database modules
│   │   ├── base.py               # SQLAlchemy Base
│   │   ├── deps.py               # Dependency functions
│   │   └── session.py            # Database session
│   ├── models                    # SQLAlchemy models
│   ├── schemas                   # Pydantic schemas
│   └── services                  # Business logic services
├── main.py                       # Application entry point
├── migrations                    # Alembic migrations
│   ├── versions                  # Migration scripts
│   └── env.py                    # Alembic environment
└── requirements.txt              # Project dependencies
```

## Development

### Database Migrations

To create a new migration after modifying models:

```bash
alembic revision --autogenerate -m "Description of changes"
```

To apply migrations:

```bash
alembic upgrade head
```

### Linting

Run the linter to ensure code quality:

```bash
ruff check .
```

Fix auto-fixable issues:

```bash
ruff check --fix .
```

## License

[MIT License](LICENSE)