Plan-buscador

Plan — Buscador de material

Volver a README · 08 Proyectos

Objetivo: construir una herramienta en Python que lea una lista de temas, busque material de estudio y genere una carpeta de notas por tema dentro del vault.

Estado: planificación. La implementación se escribe desde cero como ejercicio.

1. Alcance

La herramienta debe:

1. Leer 03_Fundamentos/Material/temas.md.
2. Interpretar un tema por viñeta.
3. Buscar fuentes en varios proveedores.
4. Deduplicar y ordenar los resultados.
5. Crear una carpeta por tema en 03_Fundamentos/Material/.
6. Generar README.md, notas.md y fuentes.json.
7. Actualizar 03_Fundamentos/Material/00 Material.md.
8. Poder ejecutarse a mano y también al guardar temas.md.

2. Fuera de alcance

• Descargar PDFs, videos o música.
• Saltar paywalls o iniciar sesión en sitios.
• Garantizar la calidad o vigencia de una fuente.
• Sincronizar archivos entre dispositivos: eso lo hace Syncthing.
• Reemplazar la lectura, la práctica o el criterio propio.

3. Flujo

temas.md
   │
   ▼
Lector de temas → normalización → slug
   │
   ▼
Proveedores de fuentes
   ├── documentación oficial curada
   ├── Wikipedia
   ├── GitHub
   ├── YouTube
   ├── arXiv (temas técnicos)
   └── DuckDuckGo (opcional)
   │
   ▼
Deduplicar + clasificar + ordenar
   │
   ▼
Renderizar Markdown
   ├── README.md por tema
   ├── notas.md (solo si no existe)
   └── fuentes.json
   │
   ▼
Actualizar índice 00 Material.md

4. Componentes

Componente	Responsabilidad
CLI	Recibir ruta de temas, salida, tema único y opciones
Lector de temas	Ignorar títulos, comentarios y líneas que no sean viñetas
Normalizador	Crear slugs sin acentos, espacios ni símbolos
Proveedor de documentación	Leer un JSON editable con enlaces oficiales por tema
Proveedor Wikipedia	Obtener un resumen y su URL
Proveedor GitHub	Buscar repositorios y ejercicios
Proveedor YouTube	Buscar videos y obtener título, canal y duración
Proveedor arXiv	Buscar artículos en temas académicos
Proveedor web	Añadir resultados de buscador, con manejo de errores
Ranker	Puntuar por tipo de fuente, posición y palabras clave
Renderizador	Generar Markdown legible y enlazado al vault
Índice	Reescribir solo el bloque automático de 00 Material.md
Disparador	Ejecutar el script cuando cambie temas.md

5. Hitos

Hito	Entregable	Criterio de cierre
M0	Estructura del proyecto, README y Git	Repositorio inicializado; .gitignore; primer commit
M1	Lector de temas + slug + pruebas	Lee viñetas, ignora comentarios y deduplica
M2	Renderizador de una nota de prueba	Genera Markdown con secciones y enlaces sin red
M3	Proveedor de documentación curada	Carga fuentes_oficiales.json y filtra por tema
M4	Proveedor Wikipedia	Obtiene resumen y URL; falla sin romper el flujo
M5	Proveedor GitHub + YouTube	Devuelve resultados y maneja límites o errores
M6	Índice automático	Actualiza solo el bloque entre marcadores
M7	Proveedores opcionales y ranking	Deduplica, clasifica y ordena
M8	Disparador systemd.path	Al guardar temas.md, se ejecuta el script
M9	Pruebas, documentación y demo	Pruebas sin red; README reproducible; demo grabada

6. Criterios de aceptación

• ./run.sh --tema "tema de prueba" crea una carpeta con README.md.
• El mismo comando dos veces no sobrescribe notas.md.
• El índice se actualiza sin borrar texto escrito a mano.
• Un tema sin resultados genera una nota válida con checklist.
• Un error de red no detiene el procesamiento de los demás temas.
• Las pruebas no dependen de internet.
• El proyecto se puede ejecutar en Linux y Windows.
• El disparador automático funciona al guardar temas.md.
• El README explica instalación, uso, decisiones y límites.

7. Decisiones técnicas

• Python 3.11+: suficiente para pathlib, tipos modernos y pruebas.
• Markdown + wikilinks: integración directa con Obsidian.
• Enlaces, no descargas: menos fragilidad y menos riesgo legal.
• Fuentes estables primero: Wikipedia, GitHub, YouTube y arXiv.
• DuckDuckGo opcional: los buscadores bloquean consultas automatizadas.
• JSON para metadatos: fácil de inspeccionar y versionar.
• notas.md intocable: la automatización no debe borrar trabajo personal.
• Salida separada del portafolio: el proyecto vive en 08_Proyectos; el material en 03_Fundamentos/Material.

8. Dependencias sugeridas

Dependencia	Uso	Obligatoria
Python estándar	CLI, JSON, HTTP, pruebas	Sí
yt-dlp	Búsqueda de videos	No
ddgs	Búsqueda web opcional	No

9. Git

El proyecto debe versionarse desde el inicio:

M0: git init + README + .gitignore
M1: lector + pruebas
M2: renderizador
M3: documentación curada
M4: Wikipedia
M5: GitHub + YouTube
M6: índice
M7: ranking + opcionales
M8: systemd
M9: documentación final

.gitignore debe incluir .venv/, __pycache__/, *.pyc y archivos temporales.

10. Disparador automático

En Linux, usar systemd de usuario:

• buscador-material.path vigila 03_Fundamentos/Material/temas.md.
• buscador-material.service ejecuta run.sh.
• No requiere sudo.
• Los archivos están en systemd/.
• La instalación se hace con systemd/instalar.sh.
• Estado actual: instalado y activo en este PC; apunta a run.sh. Mientras no exista buscar_material.py, el disparador no hace nada y termina sin error.

En Windows queda como mejora posterior: Programador de tareas cada cierto tiempo o un vigilante con PowerShell.

11. Riesgos

Riesgo	Mitigación
GitHub limita búsquedas	Manejar 403, esperar o usar GITHUB_TOKEN
DuckDuckGo bloquea	Mantenerlo opcional y no bloquear el flujo
YouTube cambia su interfaz	Aislar el proveedor y permitir omitirlo
Resultados de baja calidad	Priorizar documentación oficial y revisión manual
El script sobrescribe notas	Escribir notas.md solo si no existe
Syncthing sincroniza .venv	Ignorarlo en .stignore y .gitignore
El path del vault cambia	Usar %h en systemd o rutas configurables

12. Próximo paso

Implementar M0 y M1:

1. Inicializar Git.
2. Crear buscar_material.py con el esqueleto de la CLI.
3. Implementar el lector de temas y el slug.
4. Escribir las primeras pruebas sin red.
5. Hacer el primer commit.

Enlaces

• README
• systemd
• referencia
• 08 Proyectos
• 00 Material