podcast-kit — habilidade de agente

O que podcast-kit — habilidade de agente faz?

Propósito

Publicar um episódio é um conjunto de pequenos trabalhos de cópia a partir de um conjunto de fatos: as notas, os capítulos do YouTube, o arquivo de capítulos do Podcasting 2.0 e a busca pelo momento digno de clipe. Esta ferramenta recebe UM JSON de episódio e produz todos eles, de modo que os fatos existem exatamente uma vez. Biblioteca padrão pura do Python; apenas local; o arquivo de episódio é a única coisa que ela lê.

O núcleo de honestidade desta ferramenta: uma lista de capítulos é exportada apenas quando é válida — players ignoram silenciosamente listas quebradas, portanto entregar uma exportação quebrada é pior do que não entregar nenhuma — e uma pontuação de audiograma é um ranking de onde olhar primeiro, calculado apenas a partir do texto da transcrição. Nunca é uma previsão de que um momento terá desempenho, e um plano nunca é um audiograma renderizado.

Quando usar / não usar

Use quando:

• Um episódio existe como (ou pode ser escrito como) um JSON de episódio: finalizá-lo significa produzir notas de episódio, capítulos para YouTube e aplicativos de podcast, e decidir o que clipe.
• Um pipeline precisa de uma validação sim/não para capítulos: chapters com exit 0 = a lista é válida e as exportações estão na saída; exit 1 = não publique os capítulos como estão.
• Um editor quer os cinco timestamps que valem a pena ouvir antes de percorrer uma gravação inteira.

NÃO use quando:

• Você precisa de transcrição — a transcrição é uma entrada aqui. Produza segmentos primeiro com uma ferramenta de transcrição.
• Você precisa de áudio ou vídeo renderizados — audiogram-plan é um plano (timestamps + palavras + razões). Leve-o para um editor ou uma ferramenta de renderização.
• Você precisa de RSS, hospedagem ou processamento em lote — esta ferramenta finaliza um arquivo de episódio por vez, deliberadamente.

Comandos

Todo comando recebe o arquivo de episódio como argumento posicional e suporta --json.

# Notas de episódio — Markdown (padrão) ou texto plano
python3 src/podcast_kit.py show-notes EPISODE.json \
    [--format md|text]

# Validar + exportar capítulos (exit 1 + nenhuma exportação quando inválido)
python3 src/podcast_kit.py chapters EPISODE.json \
    [--format youtube|json|both]

# Ranquear os momentos dignos de clipe (exit 1 quando nenhum se qualifica)
python3 src/podcast_kit.py audiogram-plan EPISODE.json \
    [--top 5]

Campos do episódio: show (opcional), episode (int opcional), title (obrigatório para show-notes), published (opcional, imprimido como está), duration_seconds (obrigatório para chapters; segundos ou uma string de timestamp), summary (obrigatório para show-notes), guests — lista de {"name", "role"?}, links — lista de {"label", "url"}, chapters — lista de {"start", "title"}, transcript — lista de {"start", "end", "speaker"?, "text"}. Timestamps aceitam segundos (754), "M:SS" ou "H:MM:SS" em todos os lugares. O arquivo é validado a cada leitura; problemas estruturais (campos ausentes, timestamps ruins, um segmento terminando antes de começar, um segmento ultrapassando a duração) são erros com exit 2 que nomeiam o capítulo ou segmento ofensor.

Validação de capítulos (exata)

Problemas (exit 1, nenhuma exportação): o primeiro capítulo não começa em 0; um início não é estritamente após o início anterior; um início está em ou após duration_seconds (um início em duration − 1 é válido); um título está vazio.

Avisos (reportados, exportação ainda é produzida): menos de 3 capítulos; um capítulo com menos de 10 segundos. Ambos são regras do YouTube, não do Podcasting 2.0 — a exportação é válida de qualquer forma, YouTube pode ignorá-la.

Exportações: linhas do YouTube são MM:SS Título (ou H:MM:SS quando o episódio dura uma hora ou mais). O Podcasting 2.0 é {"version": "1.2.0", "chapters": [{"startTime", "title", "endTime"}]} — o endTime de cada capítulo é o startTime do próximo capítulo, e o endTime do último capítulo é a duração.

A pontuação do audiograma (exata)

Por segmento de transcrição, apenas a partir de seu texto:

• pontos de interrogação: +2 cada, limitado a +4
• números (sequências de dígitos, ex. 18, 1.900): +2 cada, limitado a +4
• pontos de exclamação: +1 cada, limitado a +2
• frases fortes — a lista fixa "the truth is", "biggest mistake", "nobody tells you", "everyone gets wrong", "never", "always", "secret", "myth" (palavra inteira, insensível a maiúsculas/minúsculas): +3 cada, limitado a +6
• comprimento do segmento entre 15 e 60 segundos inclusive: +2

Piso: um segmento precisa de um total de 5 para ser listado. Ordem: pontuação decrescente, empates pelo início mais cedo. --top N limita a lista (0 ou negativo = todo segmento qualificado). Cada momento listado imprime suas razões com os sinais reais encontrados — uma pontuação sem razões não existe nesta ferramenta.

Esquema JSON de saída (--json)

Campos comuns: tool ("podcast-kit"), version, command, episode_file (nome do arquivo).

show-notes: title, format ("markdown" ou "text"), notes — as notas renderizadas como uma string, exatamente o que a visão de texto imprime. chapters: title, duration_seconds, valid (bool), problems (lista de strings), warnings (lista de strings), chapters — cada {start_seconds, start, title, end_seconds, end, length_seconds} — youtube (o texto de exportação, ou null quando inválido), podcasting20 (o objeto de exportação, ou null quando inválido). audiogram-plan: title, segments_scanned, floor (5), moments — cada {rank, start_seconds, start, end_seconds, end, duration_seconds, speaker, text, score, reasons}. Quando nenhum segmento se qualifica, moments é [] e um campo note explica que o piso não foi atingido (exit 1).

Em caso de erro, stdout é um único objeto: {"error": "<mensagem>"} com código de saída 2 — incluindo erros de uso do argparse no modo --json. Nunca texto plano, nunca um traceback.

Códigos de saída

• 0 — comando bem-sucedido; para audiogram-plan, pelo menos um segmento ultrapassou o piso.
• 1 — um achado: chapters encontrou problemas de validação (nenhuma exportação foi produzida), ou audiogram-plan não encontrou nenhum segmento digno de clipe. Nenhum dos dois é uma falha — aja com base no achado.
• 2 — ERRO: arquivo de episódio ausente ou não é JSON válido, um campo obrigatório ausente, um timestamp inválido, um capítulo ou segmento malformado, uma flag inválida. Nenhum fato de saída pode ser citado de uma execução com falha.

Limites e regras de honestidade que o agente deve respeitar

• Capítulos inválidos não exportam nada. Quando chapters sai com código 1, não reconstrua uma exportação a partir do array chapters na saída JSON e publique-a — os problemas listados são exatamente por que os players a ignorariam. Corrija o arquivo de episódio e execute novamente.
• Avisos não são problemas. Uma lista válida com avisos pode ser publicada; diga claramente que o YouTube pode não exibir os capítulos (muito poucos, ou um muito curto) enquanto os aplicativos de podcast o farão.
• Uma pontuação não é uma previsão. Relate um momento como "classificado em primeiro lugar pelos sinais de texto", nunca como "o melhor momento" ou "o clipe que terá desempenho". A ferramenta não consegue ouvir a gravação; a entrega pode tornar um segmento de baixa pontuação o clipe certo, e o plano diz isso.
• Exit 1 do audiogram-plan não é um episódio vazio. Significa que nenhum segmento carregou os sinais classificados. Nunca relate como "nenhum bom momento" sem a ressalva de que a ferramenta lê apenas texto.
• Um plano não é um arquivo. audiogram-plan produz timestamps e texto. Nunca diga ao usuário que um audiograma existe até que uma ferramenta de renderização tenha realmente criado um a partir do plano.
• Apenas local: a ferramenta lê apenas o arquivo de episódio nomeado na linha de comando e não envia nada para lugar nenhum.