favs-my

API de bookmarks personales con categorización automática via LLM.

Stack

• API: FastAPI (Python 3.12)
• DB: PostgreSQL 16
• LLM: Claude (Haiku por defecto)
• Infra: Docker Compose

Setup

cp .env.example .env
# editar .env con tu ANTHROPIC_API_KEY
docker compose up --build

La API queda en http://localhost:8000. La DB en el puerto 5433.

Uso

Crear bookmark

curl -X POST http://localhost:8000/api/bookmarks \
  -H "Content-Type: application/json" \
  -d '{"title":"FastAPI docs","link":"https://fastapi.tiangolo.com"}'

Listar todos

curl http://localhost:8000/api/bookmarks

Filtrar por categoría

curl http://localhost:8000/api/bookmarks?category=python

Obtener uno

curl http://localhost:8000/api/bookmarks/{id}

Actualizar

curl -X PUT http://localhost:8000/api/bookmarks/{id} \
  -H "Content-Type: application/json" \
  -d '{"title":"Nuevo titulo"}'

Eliminar

curl -X DELETE http://localhost:8000/api/bookmarks/{id}

Categorizar pendientes (LLM)

curl -X POST http://localhost:8000/api/categorize

Toma los bookmarks sin categoría (category: null), los envía a Claude y asigna categorías automáticamente.

Cron

Para categorizar automáticamente cada 30 minutos:

crontab -e

*/30 * * * * curl -s -X POST http://localhost:8000/api/categorize

Variables de entorno

Variable	Default	Descripción
DATABASE_URL	postgresql+asyncpg://favs:favs@favs-db:5432/favs	Conexión a PostgreSQL
ANTHROPIC_API_KEY	—	API key de Anthropic (requerida para categorizar)
CATEGORIZE_MODEL	claude-haiku-4-5-20251001	Modelo a usar para categorización

Estructura

├── docker-compose.yml
├── .env.example
└── backend/
    ├── Dockerfile
    ├── requirements.txt
    └── app/
        ├── main.py            # Entrypoint, lifespan, routers
        ├── config.py           # Settings via env vars
        ├── database.py         # Engine y sesión async
        ├── models.py           # Modelo Bookmark (SQLAlchemy)
        ├── schemas.py          # Pydantic schemas
        ├── categorizer.py      # Lógica de categorización con LLM
        └── routers/
            ├── bookmarks.py    # CRUD /api/bookmarks
            ├── categorize.py   # POST /api/categorize
            └── health.py       # GET /api/health