README.md

---
title: Karl Movie Vector Backend
emoji: 🎬
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: mit
---

# Karl Movie Vector Backend

FastAPI backend for semantic movie recommendations using FAISS and OpenAI embeddings. Powers intelligent movie discovery with geometric subspace algorithms.

## Features

- Semantic movie search using OpenAI embeddings
- FAISS-powered vector similarity search
- Geometric subspace algorithms for multi-movie preferences
- ~150ms response time on CPU
- RESTful API with Bearer token authentication

## API Usage

```bash
curl -X POST "https://yonnel-karl-movie-vector-backend.hf.space/explore" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "liked_ids": [550, 680],
    "disliked_ids": [],
    "top_k": 100
  }'
```

## Environment Variables

Set these in your Space settings:
- `OPENAI_API_KEY`: Your OpenAI API key
- `TMDB_API_KEY`: Your TMDB API key  
- `API_TOKEN`: Authentication token for API access
- `ENV`: Set to "prod" for production