Amanuense

Demo local: PDF/imagen → Markdown + JSON con VLMs vía Hugging Face Inference Providers, y modo A/B con diff estructural (tablas + headings).

Cada persona que cloee el repo usa su propio HF_TOKEN. No hay backend público compartido: el consumo de Inference Providers va contra la cuenta de quien corre la app.

Requisitos

• Python 3.11+
• Node 20+
• Cuenta en Hugging Face con un token que pueda llamar Inference Providers

Creá el token acá (fine-grained, permiso Make calls to Inference Providers):
https://huggingface.co/settings/tokens/new?ownUserPermissions=inference.serverless.write&tokenType=fineGrained

Setup (primera vez)

git clone <url-del-repo>
cd Amanuense

copy .env.example .env
# Editá .env y pegá TU token: HF_TOKEN=hf_...

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r backend\requirements.txt

cd frontend
npm install
cd ..

Arranque

.\scripts\dev.ps1

O en dos terminales:

# Backend :8000
.\.venv\Scripts\python.exe -m uvicorn app.main:app --reload --app-dir backend --port 8000

# Frontend :5173
cd frontend
npm run dev

• UI: http://127.0.0.1:5173
• API docs: http://127.0.0.1:8000/docs

Fixture de prueba rápida: fixtures/smoke_page.png.

API

Método	Path	Descripción
GET	/models	Allowlist + default + max_pages
POST	/parse	Respuesta completa al terminar
POST	/parse/stream	NDJSON con etapas/páginas (lo usa la UI)
POST	/compare	A luego B + diff
POST	/compare/stream	Compare con progreso NDJSON

Cap: primeras 8 páginas (warning si trunca). Prompt único en backend/app/config.py.

Modelos (allowlist)

Editá MODELS en backend/app/config.py. Seed actual:

• google/gemma-3-12b-it (default)
• google/gemma-4-26B-A4B-it (A/B)

Si un ID devuelve model_not_supported, activá más providers en Inference Provider settings o cambiá la allowlist. Los proveedores disponibles dependen de tu cuenta HF.

Smoke / tests

# Backend debe estar corriendo
.\.venv\Scripts\python.exe scripts\smoke_parse.py

.\.venv\Scripts\python.exe -m pytest backend\tests -q

Notas

• El frontend solo habla con el backend local (no llama HF directo).
• Diff MVP: celdas de tablas + headings faltantes.
• Nunca subas .env al repo (está en .gitignore).
• Ideal para demo (video + este README): cada viewer corre localmente con su token.

CLI hf (para vos o para agentes)

Este repo asume la CLI hf instalada.

Para que Cursor/otros agentes conozcan todos los comandos hf (models, spaces, jobs, etc.), instalá el skill oficial:

# En este repo
hf skills add

# O global (todos los proyectos)
hf skills add --global

Guía: Hugging Face CLI for AI Agents.

Ejemplos útiles para Amanuense:

hf auth whoami
hf models ls --filter image-text-to-text --sort downloads --limit 20
hf models info google/gemma-3-12b-it --expand inference,pipeline_tag