Referencia para desarrolladores de Sweepy
Sweepy se ejecuta como un proyecto Python pequeño con un motor plano. Esta página relaciona cada etapa del proceso con el módulo que la ejecuta, para que sepas dónde aplicar un cambio.
A quién va dirigida
Lee esta página si piensas cambiar el código de Sweepy o añadir una fuente de empleo. Los revisores pueden usarla para orientar una pull request. Solo cubre aspectos internos: módulos, dependencias y versiones de Python.
consejo
Omite esta página si quieres ejecutar barridos. Empieza por Instalación.
Etapas del proceso y módulos
swee.py ejecuta cinco etapas en orden. El terminal imprime cada etapa como [1/5] hasta [5/5].
| Etapa | Módulo | Qué hace |
|---|---|---|
| 1. Carga del perfil | engine/config.py | Carga y valida tu perfil YAML. El asistente del mismo módulo escribe uno. |
| 2. Descubrimiento de puestos | engine/discovery.py | Consulta los canales de agregadores con python-jobspy y clasifica cada plataforma. |
| 2. Descubrimiento de puestos | engine/sources/ | Obtiene las plataformas de Greenhouse, Ashby, Lever, Workable y Built In NYC desde endpoints públicos. |
| 2. Eliminación de duplicados | swee.py | Fusiona los resultados de agregadores y fuentes en una ficha por enlace de empleo. |
| 3. Validación de URL | engine/validator.py | Comprueba cada enlace con una solicitud HTTP HEAD y un GET como alternativa. Descarta las ofertas muertas. |
| 4. Puntuación con el currículum | engine/scorer.py | Extrae los términos de la oferta y del currículum y puntúa el solapamiento en requisitos y palabras clave. Etiqueta las ofertas que exigen respuestas escritas. |
| 5. Enrutado de canales de currículum | engine/enrich.py | Elige el canal con mayor solapamiento de términos y asigna el color de insignia correspondiente. |
| 5. Enriquecimiento de fichas | engine/enrich.py | Crea los resúmenes de las fichas, las líneas de remuneración y el texto de consejos personalizados. |
| 5. PDF de fichas predeterminado | engine/report.py | Renderiza el diseño de fichas, seis por página por defecto, y devuelve el número de páginas. |
| 5. PDF de tabla heredado | engine/pdf_builder.py | Renderiza el diseño de tabla cuando tu perfil define report.style: legacy. |
| 5. Exportaciones de datos | engine/exporter.py | Escribe archivos CSV y JSON. Rasteriza imágenes PNG de las páginas cuando lo pides. |
| 5. Seguimiento de candidaturas | engine/tracking.py | Añade las columnas de seguimiento y lee exportaciones anteriores para recuperar los valores que escribiste. |
engine/session.py contiene el almacén de fichas del flujo con estado del Model Context Protocol (MCP). Mantiene las fichas en un mapa seguro para hilos, indexado por un hash estable de cada enlace de empleo.
Dónde aplicar un cambio
| Si quieres cambiar | Empieza en |
|---|---|
| Una fuente de empleo o su endpoint | engine/sources/, más una lista semilla en data/sources/ |
| Cómo se puntúan las coincidencias | engine/scorer.py |
| Lo que muestra una ficha | engine/enrich.py y después engine/report.py |
| Cómo se comprueban los enlaces | engine/validator.py |
| Una bandera de línea de comandos | swee.py |
| Una herramienta MCP | server.py |
consejo
server.py importa los mismos módulos del motor que la herramienta de línea de comandos. Prueba la ruta MCP después de cualquier cambio en el motor, porque una sola corrección afecta a ambos puntos de entrada.
Referencia de módulos
Puntos de entrada
| Módulo | Propósito |
|---|---|
swee.py | Orquestador principal y punto de entrada de línea de comandos con argparse para el proceso de cinco etapas. |
server.py | Servidor del Model Context Protocol (stdio) que expone las herramientas del motor a los asistentes de IA. |
Módulos del motor
| Módulo | Propósito |
|---|---|
engine/config.py | Asistente interactivo, además de carga y validación de YAML. |
engine/discovery.py | Orquestación de extractores para python-jobspy y las fuentes deterministas, detección de sistemas de seguimiento de candidatos (ATS) y eliminación de duplicados. |
engine/validator.py | Comprobaciones de disponibilidad de enlaces con detección de 404 encubiertos. Los enlaces que no se pueden verificar siguen en la ejecución. |
engine/scorer.py | Extracción de términos del currículum, coincidencia porcentual, etiquetado y puntuación por canal. |
engine/enrich.py | Enriquecimiento de fichas para resúmenes, remuneración, enrutado de canales y consejos personalizados. |
engine/session.py | Almacén de fichas seguro para hilos con ID estables para el flujo MCP con estado. |
engine/report.py | PDF predeterminado con diseño de fichas. |
engine/pdf_builder.py | PDF heredado con diseño de tabla para report.style: legacy. |
engine/exporter.py | Exportaciones CSV y JSON, además de rasterización PNG de los PDF de informe. |
engine/tracking.py | Columnas de seguimiento y lectura de continuidad de exportaciones anteriores. |
engine/docx.py | Conversión de DOCX a PDF con python-docx y reportlab, además de una alternativa con Microsoft Word. |
engine/documents.py | Distribución de documentos para --convert y el conversor MCP, que cubre DOCX, DOC, texto, Markdown y PDF. |
engine/logging.py | Registros de depuración opcionales en logs/. |
engine/cache.py | Caché de scraping en SQLite indexada por consulta y conjunto de motores, con una hora de vigencia. |
engine/circuit_breaker.py | Cuenta los errores consecutivos de una fuente y pausa las llamadas durante un enfriamiento. |
engine/engine_defaults.py | Listas de sitios y ajustes de motor compartidos, sin importaciones para evitar ciclos. |
engine/engines.py | Registro de adaptadores e instalador de los motores opcionales hirehunt, openroles, apify y jobdrop. |
engine/history.py | Registro persistente de las ofertas ya informadas. Un barrido diario informa solo de puestos nuevos. |
engine/normalize.py | Normaliza las filas sin procesar de cada motor en las columnas de oferta compartidas. |
engine/salary.py | Extracción de la remuneración a partir del texto de la oferta cuando una plataforma omite los datos salariales estructurados. |
engine/sweep_config.py | Aplica los valores predeterminados compartidos del motor a los ajustes del perfil. |
engine/updater.py | Comprobación de actualizaciones basada en Git y reinstalación de dependencias del checkout. |
Fuentes deterministas
| Módulo | Propósito |
|---|---|
engine/sources/__init__.py | Exportaciones de los extractores y carga de listas semilla desde data/sources/. |
engine/sources/_common.py | Utilidades compartidas para cabeceras HTTP, prefilter de títulos y conversión de HTML a texto. |
engine/sources/greenhouse.py | Extractor de la plataforma de empleo de Greenhouse. |
engine/sources/ashby.py | Extractor de la plataforma de empleo de Ashby. |
engine/sources/lever.py | Extractor de las ofertas de Lever. |
engine/sources/workable.py | Extractor de la API de widgets de Workable. |
engine/sources/builtinnyc.py | Extractor de categorías de Built In NYC. |
Adaptadores de motor
| Módulo | Propósito |
|---|---|
engine/adapters/__init__.py | Registro que asigna cada nombre de motor a su adaptador. |
engine/adapters/base.py | Clase base ScraperAdapter, cabecera User-Agent compartida y utilidades de forma de resultado. |
engine/adapters/jobspy_adapter.py | Adaptador de agregadores python-jobspy para LinkedIn, Indeed, Glassdoor y ZipRecruiter. |
engine/adapters/ats_adapter.py | Adaptador sobre los extractores ATS deterministas de engine/sources/. |
engine/adapters/hirehunt_adapter.py | Adaptador del motor opcional hirehunt. |
engine/adapters/openroles_adapter.py | Adaptador del motor opcional openroles. |
engine/adapters/apify_adapter.py | Adaptador del actor opcional de Apify. |
engine/adapters/jobdrop_adapter.py | Adaptador del motor opcional jobdrop. |
Datos, scripts y pruebas
| Ruta | Propósito |
|---|---|
data/sources/*.txt | Listas semilla de plataformas, empresas, organizaciones y categorías. |
scripts/make_sample.py | Generador del informe de ejemplo que se guarda en docs/. |
tests/ | Suite de pytest con un archivo por área: adapters, config, documents, docx, engines, enrich, history, logging y report. Otros archivos cubren salary, scorer, server, session, sources, swee, tracking, updater y validator. |
nota
Añade un archivo de pruebas dedicado cuando cambies discovery.py, exporter.py o pdf_builder.py. Coloca el archivo en tests/.
Dependencias
Los paquetes de ejecución proceden de requirements.txt. Las versiones siguientes coinciden con ese archivo.
| Paquete | Versión | Qué aporta a Sweepy |
|---|---|---|
reportlab | 5.0.1 | Genera el informe PDF con estilo y enlaces activos. |
pymupdf | 1.28.2 | Extrae texto de los currículums en PDF y rasteriza las exportaciones PNG. |
python-docx | 1.2.0 | Lee currículums .docx y reconstruye su texto como PDF sin Word. |
requests | 2.32.5 | Accede a los endpoints ATS y comprueba que cada enlace de empleo responde. |
beautifulsoup4 | 4.15.0 | Analiza el HTML de las fuentes Greenhouse, Lever, Workable y Built In NYC. |
pyyaml | 6.0.3 | Lee y escribe perfiles YAML. |
questionary | 2.1.1 | Gestiona las preguntas del asistente interactivo. |
prompt-toolkit | 3.0.53 | Gestiona la entrada de texto interactiva del asistente. |
python-jobspy | 1.2.0 | Extrae ofertas de LinkedIn, Indeed, Glassdoor y ZipRecruiter sin credenciales de API. |
pandas | 2.2.3 | Estructura las ofertas y construye las exportaciones CSV y JSON. |
mcp | 1.30.0 | Ejecuta el servidor del Model Context Protocol. |
anyio | 4.12.1 | Gestiona el transporte asíncrono de MCP. |
requirements.txt también incluye un paquete opcional. Descomenta docx2pdf cuando quieras que Word genere el PDF.
docx2pdf(0.5.2, opcional) renderiza DOCX a PDF mediante Microsoft Word en Windows. Sweepy lo llama siempre que Microsoft Word existe en el equipo.
nota
mcp se mantiene en la versión 1.x a propósito. El SDK 2.x solo sirve a la era del protocolo 2026-07-28. Un cliente que sondea server/discover y después recurre al saludo initialize recibe un error -32022. VS Code Copilot sigue esa ruta alternativa.
consejo
pandas se mantiene en la versión 2.x a propósito. Pandas 3.x requiere Python 3.11 o posterior, y la matriz de CI todavía prueba Python 3.10.
Paquetes de desarrollo (requirements-dev.txt)
| Paquete | Versión | Qué hace |
|---|---|---|
pytest | 9.1.1 | Ejecuta la suite de pruebas de tests/. |
pytest-cov | 7.1.0 | Informa de la cobertura de swee.py, server.py y engine/scorer.py. |
ruff | 0.17.0 | Revisa el código y ordena las importaciones. |
tomli | 2.2.1 | Proporciona tomllib para las ejecuciones de prueba con Python 3.10. |
Terminal
pip install -r requirements.txt
pip install -r requirements-dev.txt
ruff check .
pytest -q
Requisitos y versiones de Python compatibles
| Aspecto | Detalle |
|---|---|
| Versión mínima | Sweepy requiere Python 3.10 o posterior y usa sintaxis de 3.10 en todos los módulos. |
| Rango probado | El flujo de trabajo de CI en .github/workflows/ci.yml ejecuta Python 3.10, 3.11 y 3.12 en Ubuntu. |
| Objetivo de lint | pyproject.toml define target-version = "py310" para ruff. Una construcción exclusiva de versiones más recientes hace fallar la tarea de lint. |
| Longitud de línea | Ruff aplica un límite de 100 caracteres e ignora E501. |
| Pasos de CI | La tarea instala ambos archivos de requisitos y ejecuta ruff check . antes de pytest. |
nota
pyproject.toml declara requires-python = ">=3.10", así que pip rechaza un intérprete anterior durante la instalación. La matriz de CI y el objetivo de ruff definen el rango probado. Python 3.13 funciona en la práctica, pero queda fuera de ese rango.
Python 3.13
El paquete pymupdf puede compilarse desde el código fuente cuando no existe una rueda precompilada. Instala las Microsoft C++ Build Tools y selecciona la carga de trabajo "Desarrollo para escritorio con C++" antes de instalar las dependencias.
Estructura del repositorio
Estructura del repositorio
swee.py Punto de entrada de la CLI y orquestador del barrido
server.py Servidor MCP sobre stdio
engine/ Módulos del proceso
engine/sources/ Obtenedores deterministas de ATS
engine/adapters/ Adaptadores de agregadores y motores opcionales
data/sources/ Listas semilla para cada obtenedor
profiles/ Perfiles de búsqueda en YAML
results/ Archivos PDF, CSV, JSON y PNG generados
logs/ Registros de depuración opcionales
styles/ Reglas de estilo Vale para la documentación
tests/ Suite de pytest
Cuando cambies la firma de una herramienta en server.py, actualiza la referencia de herramientas MCP en el mismo commit.