AGENTS.md

Repo Shape

The primary app is now backend/ (Python/FastAPI) plus frontend/ (Next.js/TypeScript/Tailwind); estacion documentos.html is a browser-only prototype/reference for behavior.
Runtime data is stored under data/ and is gitignored; do not commit uploaded class files, generated Markdown, SQLite DBs, temporary audio, or API keys.
The included Griffin(2020).Comportamiento_organizacionalSOLOCAPITULO7.13Ed.pdf is a local sample/source PDF for import behavior.

Local setup: python -m venv .venv, .venv\Scripts\activate, pip install -r requirements.txt, copy .env.example to .env.
Run API: uvicorn backend.app.main:app --reload from the repo root.
Run frontend: cd frontend, npm install, npm run dev -- -p 3000 with NEXT_PUBLIC_API_URL=http://127.0.0.1:8000.
Windows non-technical flow: double-click abrir_estacion.bat; it chooses free ports, starts backend/frontend, and opens the browser. Use cerrar_estacion.bat to stop only this project.
Docker/Coolify check: docker compose up --build.
Basic syntax check: python -m compileall backend.

Knowledge is organized as Materia -> Semana -> fuentes raw -> Markdown procesado -> exports under data/subjects/<materia>/week-XX/.
KnowledgeManager owns filesystem layout and SQLite metadata; processors should not write final Markdown directly.
IngestionService selects processors by source_type and wraps output with Markdown frontmatter for LLM ingestion.
Text and Markdown are read directly; .docx uses python-docx; PDFs use PyMuPDF text extraction unless use_ocr=true is passed. PDF uploads can also pass page_ranges like 1-5,8,10-12; ranges apply to both standard extraction and Mistral OCR.
OCR uses Mistral https://api.mistral.ai/v1/chat/completions with model pixtral-12b-2409.
Audio uses Deepgram https://api.deepgram.com/v1/listen?model=nova-3&smart_format=true&language=es.
Video processing requires ffmpeg; audio is extracted to data/tmp/, transcribed with Deepgram, then deleted.
The frontend calls the backend through NEXT_PUBLIC_API_URL; when ports change, update frontend/.env.local or use the adaptive .bat.

Use .env locally and Coolify environment variables in production; never hardcode or commit MISTRAL_API_KEY or DEEPGRAM_API_KEY.
For Coolify, mount persistent storage for /app/data or all subjects, outputs, and SQLite state will be lost on redeploy.

Preserve the Spanish-language UX and Markdown-first output conventions from estacion documentos.html when building the new UI.
The prototype sanitizes preview HTML with DOMPurify after marked.parse; keep equivalent sanitization in any future web UI.