podcast-kit — habilidad de agente

¿Qué hace podcast-kit — habilidad de agente?

Propósito

Publicar un episodio es un conjunto de pequeños trabajos de copia a partir de un mismo conjunto de datos: las notas, los capítulos de YouTube, el archivo de capítulos de Podcasting 2.0 y la búsqueda del momento digno de clip. Esta herramienta toma UN único JSON de episodio y produce todos ellos, de modo que los datos existan exactamente una vez. Biblioteca estándar de Python puro; solo local; el archivo del episodio es lo único que lee.

El núcleo de honestidad de esta herramienta: una lista de capítulos solo se exporta cuando es válida — los reproductores ignoran silenciosamente las listas rotas, por lo que entregar una exportación rota es peor que no entregar ninguna — y una puntuación de audiograma es una clasificación de dónde mirar primero, calculada únicamente a partir del texto de la transcripción. Nunca es una predicción de que un momento tendrá éxito, y un plan nunca es un audiograma renderizado.

Cuándo usar / no usar

Usar cuando:

• Un episodio existe como (o se puede escribir como) un único JSON de episodio: finalizarlo significa producir notas del programa, capítulos para YouTube y aplicaciones de podcast, y decidir qué recortar.
• Un pipeline necesita una compuerta de sí/no para capítulos: chapters salida 0 = la lista es válida y las exportaciones están en la salida; salida 1 = no publicar los capítulos tal como están.
• Un editor quiere las cinco marcas de tiempo que vale la pena escuchar antes de revisar toda una grabación.

NO usar cuando:

• Necesitas transcripción — la transcripción es una entrada aquí. Produce segmentos con una herramienta de transcripción primero.
• Necesitas audio o video renderizado — audiogram-plan es un plan (marcas de tiempo + palabras + razones). Llévalo a un editor o a una herramienta de renderizado.
• Necesitas RSS, alojamiento o procesamiento por lotes — esta herramienta finaliza un archivo de episodio a la vez, deliberadamente.

Comandos

Cada comando toma el archivo del episodio como argumento posicional y soporta --json.

# Notas del programa — Markdown (por defecto) o texto plano
python3 src/podcast_kit.py notas EPISODE.json \
    [--formato md|text]

# Validar + exportar capítulos (salida 1 + sin exportación cuando es inválido)
python3 src/podcast_kit.py chapters EPISODE.json \
    [--formato youtube|json|both]

# Clasificar los momentos dignos de clip (salida 1 cuando ninguno califica)
python3 src/podcast_kit.py audiogram-plan EPISODE.json \
    [--top 5]

Campos del episodio: show (opcional), episode (opcional int), title (requerido por show-notes), published (opcional, se imprime tal cual), duration_seconds (requerido por chapters; segundos o una cadena de marca de tiempo), summary (requerido por show-notes), guests — lista de {"name", "role"?}, links — lista de {"label", "url"}, chapters — lista de {"start", "title"}, transcript — lista de {"start", "end", "speaker"?, "text"}. Las marcas de tiempo aceptan segundos (754), "M:SS" o "H:MM:SS" en todas partes. El archivo se valida en cada lectura; los problemas estructurales (campos faltantes, marcas de tiempo incorrectas, un segmento que termina antes de comenzar, un segmento que excede la duración) son errores de salida 2 que nombran el capítulo o segmento infractor.

Validación de capítulos (exacta)

Problemas (salida 1, sin exportación): el primer capítulo no comienza en 0; un inicio no es estrictamente posterior al inicio anterior; un inicio está en o después de duration_seconds (un inicio en duración − 1 es válido); un título está vacío.

Advertencias (reportadas, la exportación aún se produce): menos de 3 capítulos; un capítulo de menos de 10 segundos. Ambas son reglas de YouTube, no de Podcasting 2.0 — la exportación es válida de cualquier manera, YouTube puede ignorarla.

Exportaciones: las líneas de YouTube son MM:SS Título (o H:MM:SS cuando el episodio dura una hora o más). Podcasting 2.0 es {"version": "1.2.0", "chapters": [{"startTime", "title", "endTime"}]} — el endTime de cada capítulo es el startTime del siguiente capítulo, y el endTime del último capítulo es la duración.

La puntuación del audiograma (exacta)

Por segmento de transcripción, solo a partir de su texto:

• signos de interrogación: +2 cada uno, tope +4
• números (secuencias de dígitos, p.ej. 18, 1,900): +2 cada uno, tope +4
• signos de exclamación: +1 cada uno, tope +2
• frases fuertes — la lista fija "la verdad es", "el mayor error", "nadie te dice", "todo el mundo se equivoca", "nunca", "siempre", "secreto", "mito" (palabra completa, sin distinción de mayúsculas/minúsculas): +3 cada una, tope +6
• longitud del segmento entre 15 y 60 segundos inclusive: +2

Umbral: un segmento necesita un total de 5 para ser listado. Orden: puntuación descendente, empates por inicio más temprano. --top N limita la lista (0 o negativo = todos los segmentos que califican). Cada momento listado imprime sus razones con las señales reales encontradas — una puntuación sin razones no existe en esta herramienta.

Esquema JSON de salida (--json)

Campos comunes: tool ("podcast-kit"), version, command, episode_file (nombre del archivo).

show-notes: title, format ("markdown" o "text"), notes — las notas renderizadas como una sola cadena, exactamente lo que imprime la vista de texto. chapters: title, duration_seconds, valid (bool), problems (lista de cadenas), warnings (lista de cadenas), chapters — cada uno {start_seconds, start, title, end_seconds, end, length_seconds} — youtube (el texto de exportación, o null cuando es inválido), podcasting20 (el objeto de exportación, o null cuando es inválido). audiogram-plan: title, segments_scanned, floor (5), moments — cada uno {rank, start_seconds, start, end_seconds, end, duration_seconds, speaker, text, score, reasons}. Cuando ningún segmento califica, moments es [] y un campo note explica que no se superó el umbral (salida 1).

En caso de error, la salida estándar es un solo objeto: {"error": "<mensaje>"} con código de salida 2 — incluyendo errores de uso de argparse en modo --json. Nunca texto plano, nunca un traceback.

Códigos de salida

• 0 — comando exitoso; para audiogram-plan, al menos un segmento superó el umbral.
• 1 — un hallazgo: chapters encontró problemas de validación (no se produjo exportación), o audiogram-plan no encontró ningún segmento digno de clip. Ninguno es un fallo — actúa sobre el hallazgo.
• 2 — ERROR: el archivo del episodio no existe o no es JSON válido, falta un campo requerido, una marca de tiempo incorrecta, un capítulo o segmento mal formado, un indicador inválido. No se pueden citar datos de salida de una ejecución fallida.

Límites y reglas de honestidad que el agente debe respetar

• Capítulos inválidos no exportan nada. Cuando chapters sale con 1, no reconstruyas una exportación a partir del array chapters en la salida JSON y la publiques — los problemas listados son exactamente por qué los reproductores la ignorarían. Corrige el archivo del episodio y vuelve a ejecutar.
• Las advertencias no son problemas. Una lista válida con advertencias puede publicarse; di claramente que YouTube podría no mostrar los capítulos (demasiado pocos, o uno demasiado corto) mientras que las aplicaciones de podcast sí lo harán.
• Una puntuación no es una predicción. Reporta un momento como "clasificado primero por las señales de texto", nunca como "el mejor momento" o "el clip que tendrá éxito". La herramienta no puede oír la grabación; la entrega puede hacer que un segmento con baja puntuación sea el clip correcto, y el plan así lo dice.
• La salida 1 de audiogram-plan no es un episodio vacío. Significa que ningún segmento portaba las señales clasificadas. Nunca lo reportes como "sin buenos momentos" sin el calificativo de que la herramienta solo lee texto.
• Un plan no es un archivo. audiogram-plan produce marcas de tiempo y texto. Nunca le digas al usuario que existe un audiograma hasta que una herramienta de renderizado haya creado uno a partir del plan.
• Solo local: la herramienta solo lee el archivo del episodio nombrado en la línea de comandos y no envía nada a ningún lado.