RamonCalvo
a1f33e2046
Cron-triggered endpoint that uses Claude to auto-categorize uncategorized bookmarks. Includes full project documentation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
111 lines
2.5 KiB
Markdown
111 lines
2.5 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8000/api/bookmarks \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"title":"FastAPI docs","link":"https://fastapi.tiangolo.com"}'
|
|
```
|
|
|
|
### Listar todos
|
|
|
|
```bash
|
|
curl http://localhost:8000/api/bookmarks
|
|
```
|
|
|
|
### Filtrar por categoría
|
|
|
|
```bash
|
|
curl http://localhost:8000/api/bookmarks?category=python
|
|
```
|
|
|
|
### Obtener uno
|
|
|
|
```bash
|
|
curl http://localhost:8000/api/bookmarks/{id}
|
|
```
|
|
|
|
### Actualizar
|
|
|
|
```bash
|
|
curl -X PUT http://localhost:8000/api/bookmarks/{id} \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"title":"Nuevo titulo"}'
|
|
```
|
|
|
|
### Eliminar
|
|
|
|
```bash
|
|
curl -X DELETE http://localhost:8000/api/bookmarks/{id}
|
|
```
|
|
|
|
### Categorizar pendientes (LLM)
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
```
|