Communitygithub.com

THETA Workflow

Skill de fluxo de trabalho portátil para modelagem de tópicos com THETA.

O que é THETA Workflow?

Este skill fornece um fluxo de trabalho portátil e seguro para agentes de IA realizarem modelagem de tópicos com o framework THETA. Ele orienta o agente desde a identificação da intenção do usuário até a interpretação dos resultados, seguindo um protocolo de segurança rigoroso que distingue operações somente leitura (como inspeção de arquivos, verificação de ambiente e recomendações) de operações que modificam arquivos, ambiente, custos ou estado do git. Para operações mutáveis, o agente deve solicitar confirmação explícita do usuário usando um formato padronizado. O skill suporta fluxos zero_shot (que podem usar embeddings em nuvem mediante confirmação) e fluxos supervised/unsupervised (que exigem modelos locais). O workflow recomendado inclui verificação da existência do repositório THETA, coleta de informações do dataset, inspeção do ambiente, geração de comandos, execução com confirmação e análise dos resultados. O skill é independente de plataforma (pode ser usado com Claude Code, Cursor, Codex, etc.) e se adapta ao idioma do usuário (inglês ou chinês).

Funciona com✓Claude Code✓Codex CLI~Cursor
npx skills add CodeSoul-co/theta-skill

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Fluxo de Trabalho THETA

Use este skill de fluxo de trabalho portátil para guiar usuários através do trabalho de modelagem de tópicos com THETA, desde a clarificação da intenção até a interpretação dos resultados. Corresponda ao idioma do usuário: use português para solicitações em português e inglês para solicitações em inglês. Não presuma APIs específicas do Codex; o fluxo de trabalho principal depende de leitura de arquivos, pedido de confirmação, execução de comandos comuns do shell quando confirmado e uso do script auxiliar Python pré-voo somente leitura.

Protocolo de Segurança Principal

Distinga inspeção somente leitura de operações que modificam arquivos, ambientes, custo, computação ou estado do git.

Inspeção somente leitura e aconselhamento não precisam de confirmação extra:

  • Leia README, docs, scripts, templates de configuração e arquivos de resultados.
  • Verifique estrutura do repositório, existência de arquivos, versão do Python, presença do conda, presença de .env, presença do caminho do modelo, status do git e comandos disponíveis.
  • Inspecione esquema do dataset, número de linhas, nomes de colunas, texto faltante, texto duplicado, comprimento do texto, colunas de tempo e colunas de covariáveis.
  • Recomende modelos, parâmetros, designs de experimentos e linhas de comando.
  • Resuma métricas existentes, palavras dos tópicos, tabelas de tópicos, visualizações e sugestões de ajuste.

Operações que exigem confirmação explícita do usuário antes da execução:

  • Clonar ou fazer pull do repositório THETA, trocar de branch, commitar, mesclar ou fazer push.
  • Criar ambientes conda, instalar dependências ou executar scripts/env_setup.sh.
  • Criar ou editar .env; nunca imprima, armazene ou exiba chaves de API no chat.
  • Configurar ou usar provedores de embedding em nuvem; chamadas de API na nuvem podem incorrer em custos e expor texto a um serviço externo.
  • Baixar Qwen, SBERT ou outros modelos locais.
  • Modificar, limpar, converter ou escrever datasets; prefira criar um novo arquivo derivado e nunca modifique dados originais por padrão.
  • Executar treinamento THETA ou de baseline, comparações multi-modelo, varreduras de ajuste, grandes modelos locais, trabalhos pesados de GPU ou comandos que escrevem resultados.
  • Gerar arquivos de relatório, sobrescrever saídas, excluir caches, excluir modelos, excluir dados ou limpar diretórios de resultados.

Quando a confirmação for necessária, use este formato:

Estou me preparando para executar a seguinte ação:

Ação:
<ação breve>

Comando:
<comando, se houver>

Arquivos ou diretórios afetados:
<caminhos>

Possível consumo de recursos:
<computação local / GPU / armazenamento / custo de API / nenhum>

Isso sobrescreverá arquivos existentes:
<sim / não>

Por favor, confirme se deseja continuar.

Para usuários que preferem inglês, use o formato em inglês correspondente:

I am preparing to perform the following action:

Action:
<brief action>

Command:
<command, if any>

Affected files or directories:
<paths>

Potential resource usage:
<local compute / GPU / storage / API cost / none>

Will this overwrite existing files:
<yes / no>

Please confirm whether to continue.

Proceda somente após uma confirmação explícita como confirmado, pode, continue, execute, yes, proceed ou run it. Se a resposta for ambígua, pergunte novamente no idioma do usuário.

Para fluxos de confirmação completos, exemplos e tabelas de confirmação, leia references/confirmation-flow.pt.md para português ou references/confirmation-flow.en.md para inglês. Para perguntas de captação, leia references/user-questions.md.

Regra de Embedding

Use embedding em nuvem apenas para fluxos zero_shot e somente após confirmar custo da API, provedor, presença da chave e risco de saída de dados.

Para fluxos supervised, unsupervised ou qualquer fluxo que precise de fine-tuning, exija embeddings locais e caminhos de modelo local compatível com Qwen. Se o usuário solicitar embedding em nuvem para um modo que permite fine-tuning, explique que o THETA requer modelos locais para esse caminho e proponha configuração local.

Fluxo de Trabalho Recomendado

  1. Identifique se a solicitação pertence à modelagem de tópicos THETA. Nenhuma confirmação é necessária para esta decisão de roteamento.
  2. Imediatamente verifique se existe um repositório THETA utilizável antes da configuração do ambiente, conversão de dados ou planejamento de treinamento. Verifique a existência de README.md, .env.example, scripts/ e src/models/run_pipeline.py. Esta verificação somente leitura não requer confirmação.
  3. Se nenhum repositório THETA existir, a primeira ação é pedir confirmação para clonar https://github.com/CodeSoul-co/THETA.git. Não configure ambientes, instale dependências, crie .env, inspecione datasets ou gere comandos de treinamento até que o repositório exista.
  4. Após o repositório existir, faça apenas as perguntas necessárias sobre a tarefa no idioma do usuário: caminho do dataset, coluna de texto, idioma, coluna de tempo, covariáveis, resultado alvo e restrições de recursos.
  5. Inspecione o ambiente, o estado de .env e o dataset (somente leitura). Use scripts/inspect_theta_env.py quando uma verificação pré-voo determinística for útil.
  6. Recomende a família de modelos e parâmetros com base nos dados e no objetivo.
  7. Gere comandos para revisão sem executá-los.
  8. Antes de executar qualquer comando que seja mutável, caro, de longa duração, pesado em GPU ou que escreva arquivos, obtenha confirmação explícita usando o formato padrão.
  9. Após a execução, leia as saídas e explique qualidade dos tópicos, sobreposição, coerência, diversidade, exclusividade e próximos passos de ajuste.
  10. Confirme novamente antes de executar experimentos de ajuste adicionais, escrever arquivos de relatório, sobrescrever saídas ou excluir qualquer coisa.

Comportamento de Invocação

Quando um agente usa este skill, seja lendo SKILL.md, carregando o diretório skills/theta-workflow/ ou por invocação nomeada como $theta-workflow, trate o espaço de trabalho atual como o primeiro candidato a repositório THETA. Se o espaço de trabalho atual não for THETA, inspecione qualquer caminho fornecido pelo usuário. Se nenhum repositório utilizável for encontrado, pare na etapa de confirmação de clonagem. Não faça perguntas sobre o dataset nem proponha configuração de ambiente até que a condição do repositório seja satisfeita.

Bons primeiros prompts do usuário:

Use the THETA Workflow skill in skills/theta-workflow to help me run THETA topic modeling on a policy-text dataset.
Use o skill THETA Workflow em skills/theta-workflow para me ajudar a executar modelagem de tópicos THETA em um dataset de texto de políticas.

Se o runtime suportar sintaxe de skill nomeada, $theta-workflow também é aceitável.

Roteamento de Referências

  • Leia references/workflow.md para o fluxo de decisão completo de ponta a ponta.
  • Leia references/commands.md antes de gerar comandos THETA; ele lista pontos de entrada atuais do repositório e requisitos de confirmação.
  • Leia references/result-analysis.md ao interpretar arquivos de saída ou recomendar ajustes.
  • Leia references/user-questions.md ao perguntar ao usuário sobre dataset, idioma, objetivo, recursos ou preferências de saída.
  • Leia references/confirmation-flow.pt.md quando for necessária uma redação de confirmação detalhada em português ou exemplos.
  • Leia references/confirmation-flow.en.md quando for necessária uma redação de confirmação detalhada em inglês ou exemplos.

Script Pré-Voo

Execute este script apenas para inspeção somente leitura:

python skills/theta-workflow/scripts/inspect_theta_env.py \
  --dataset caminho/para/data.csv \
  --text-column conteudo \
  --mode zero_shot

Adicione --json quando for necessária saída estruturada. O script não deve escrever arquivos, instalar dependências, chamar APIs ou iniciar treinamento.

Habilidades Relacionadas