Saphyens Manual Operativo

00 - Entender Saphyens

Primero entiende el producto, luego los comandos.

Saphyens no vende comandos ni automatización por sí misma. Su valor está en convertir fuentes dispersas en información filtrada, ordenada y entregable para un cliente que necesita vigilar temas importantes sin leer todo manualmente.

Idea central: Saphyens es una capa de inteligencia operativa: monitorea, filtra, prioriza y entrega reportes accionables.

Qué resuelve

Menos ruido, más señal

Reduce revisión manual y separa lo importante de lo irrelevante según el perfil del cliente.

Qué entrega

Digest útil

Produce reportes diarios o consolidados que pueden leerse como producto final, no como salida técnica.

Qué existe hoy

MVP operativo

Ingest real, scoring, artifacts, Ops Console, delivery modes, tests, daily run y lookback.

Qué falta

Madurez comercial

SMTP real, más clientes validados, operación varios días seguidos y onboarding más simple.

Estado actual del producto

Área	Estado	Lectura correcta
Core técnico	Funcional	El motor ya existe y puede producir resultados reales.
Cliente Brenda	Validado como vertical inicial	Legal / contratación pública Perú tiene señales comerciales reales.
Operación	Usable, aún joven	Se puede correr, revisar y entregar, pero debe probarse varios días seguidos.
Venta piloto	Posible	No es SaaS completo; sí es suficiente para pilotos controlados.

Cómo explicarlo a alguien no técnico

Saphyens revisa fuentes públicas, detecta documentos relevantes para un cliente, descarta ruido y genera un resumen listo para leer. En vez de revisar decenas o cientos de resultados, el sistema entrega una selección priorizada.

Qué no debe prometerse todavía

No debe venderse como plataforma SaaS completa, multi-cliente automática y totalmente autónoma. La promesa correcta hoy es piloto controlado con entrega real, aprendizaje rápido y mejora iterativa.

01 - Qué estás operando

Saphyens es un sistema de media intelligence.

Saphyens busca documentos o noticias relevantes, los analiza con reglas y scoring, decide qué pasa el filtro, y genera reportes entregables para un cliente.

Idea simple: Saphyens funciona como una máquina que convierte fuentes públicas en un digest útil para tomar decisiones.

Output

Digest

Es el reporte final que el cliente puede leer. Puede existir en HTML, Markdown o PDF.

Control

Ops Console

Es la pantalla donde navegas resultados, digest y artifacts sin usar comandos avanzados.

Motor

Pipeline

Es la cadena interna: ingest, normalize, rules, scoring, classification, artifact y delivery.

Recuperación

Lookback

Genera un resumen consolidado de las últimas horas o días. Sirve cuando hubo poca actividad o una fuente falló.

02 - Cómo funciona

El flujo mental correcto es simple.

No necesitas memorizar toda la arquitectura. Necesitas entender la secuencia operativa.

IngestEl sistema consulta fuentes reales como El Peruano, OSCE/OECE o gob.pe.

NormalizaciónConvierte resultados distintos en un formato común: título, URL, fecha, fuente y contenido.

Reglas + scoringEvalúa relevancia según el perfil del cliente y decide qué documentos pasan.

Artifact + digestGenera archivos auditables y un resumen legible para el cliente.

DeliveryEntrega por modo configurado: archivo, webhook o email cuando SMTP esté listo.

03 - Comandos esenciales

Empieza por el launcher.

El launcher es el acceso simple para operar Saphyens sin recordar toda la CLI interna. En este repo es ./run.sh.

Demo comercial segura

Usa datos congelados. No depende de internet. Ideal para mostrar el sistema.

./run.sh demo

Corrida diaria real

Ejecuta ingest real de red, scoring, digest y delivery configurado.

./run.sh today

Resumen de varios días

Usa lookback cuando necesitas una ventana más amplia: 72 horas, 3 días o 7 días.

./run.sh lookback 72h
./run.sh lookback 3d
./run.sh lookback 7d

Abrir consola

Sirve para revisar outputs sin regenerar nada.

./run.sh console

Validar que nada se rompió

Corre la suite de tests. Úsalo después de cambios de Claude Code.

./run.sh test

CLI interna confirmada

Úsala para control fino, debugging o automatización. No es necesario para demos normales.

python -m app.cli run-client client_id
python -m app.cli run-all
python -m app.cli status
python -m app.cli status client_id
python -m app.cli start-scheduler
python -m app.cli live status
python -m app.cli live run
python -m app.cli live brenda-today
python -m app.cli live lookback
python -m app.cli console serve

04 - Qué usar según situación

No todos los comandos sirven para lo mismo.

Situación	Usa	Por qué
Quiero mostrar Saphyens sin riesgo	`./run.sh demo`	Usa dataset congelado y abre la consola.
Quiero correr el monitoreo real de hoy	`./run.sh today`	Ejecuta flujo live con fuentes reales.
Hoy salió poco o 0 aprobado	`./run.sh lookback 3d`	Amplía la ventana y puede recuperar valor.
Quiero un resumen semanal	`./run.sh lookback 7d`	Entrega una vista consolidada útil para cliente.
Quiero ver resultados previos	`./run.sh console`	No vuelve a correr ingest ni modifica outputs.
Claude cambió código	`./run.sh test`	Verifica regresiones antes de seguir.

05 - Glosario humano

Conceptos sin jerga innecesaria.

Launcher

Es el acceso rápido del sistema. En vez de escribir comandos largos, usas ./run.sh con una palabra: demo, today, console, test o lookback.

CLI

Significa command-line interface. Es la capa avanzada para operar el sistema con más control. Normalmente la usa Claude, un developer o un operador técnico.

Digest

Es el reporte final que resume los resultados aprobados. Es lo que más se parece al producto que un cliente recibe.

Artifact

Es el paquete auditable que deja evidencia de la corrida: qué entró, qué pasó, qué fue rechazado y por qué.

Lookback

Es una corrida hacia atrás. En vez de mirar solo el día actual, mira las últimas horas o días y genera un resumen consolidado.

Scheduler

Es el componente que permite correr el sistema automáticamente según una frecuencia configurada.

06 - Problemas comunes

Qué hacer cuando algo se ve raro.

Salieron 0 aprobados

No concluyas que el sistema falló. Primero revisa si era domingo, festivo, baja actividad o ventana demasiado corta. Luego corre ./run.sh lookback 3d.

OSCE/OECE falló por timeout

Si El Peruano siguió funcionando, el sistema degradó correctamente. Corre lookback luego para recuperar una ventana más amplia cuando la fuente vuelva.

Claude quiere auditar todo otra vez

Pídele auditoría incremental: solo archivos relevantes, no repo completo. Esto reduce costo y evita loops.

Quiero saber si algo se rompió

Corre ./run.sh test. Si los tests pasan, tienes una base objetiva para continuar.

La consola no abre

Verifica si el puerto 8765 está ocupado. Puedes usar la variable SAPHYENS_PORT para cambiarlo si está soportado por el entorno.

07 - Nivel técnico

Superficie operativa confirmada.

Estos comandos existen en el estado actual auditado. El launcher es la capa recomendada para operación normal; la CLI interna es la capa de control.

Capa	Comando	Uso
Launcher	`./run.sh demo`	Demo con dataset congelado + console.
Launcher	`./run.sh today`	Live daily para Brenda con delivery.
Launcher	`./run.sh lookback Nh\|Nd`	Digest consolidado de N horas o días.
Launcher	`./run.sh console`	Ops Console sin regeneración.
Launcher	`./run.sh test`	Suite completa.
CLI	`python -m app.cli live lookback`	Lookback con flags técnicos.
CLI	`python -m app.cli start-scheduler`	Runner programado bloqueante.