Hypogenic

Hypogenic

Visão Geral

Hypogenic oferece geração e testes automatizados de hipóteses usando modelos de linguagem grandes para acelerar a descoberta científica. O framework suporta três abordagens: HypoGeniC (geração de hipóteses orientada por dados), HypoRefine (integração sinérgica de literatura e dados) e métodos Union (combinação mecanicista de hipóteses de literatura e orientadas por dados).

Início Rápido

Comece com Hypogenic em minutos:

# Instalar o pacote
uv pip install hypogenic

# Clonar conjuntos de dados de exemplo
git clone https://github.com/ChicagoHAI/HypoGeniC-datasets.git ./data

# Executar geração básica de hipóteses
hypogenic_generation --config ./data/your_task/config.yaml --method hypogenic --num_hypotheses 20

# Executar inferência em hipóteses geradas
hypogenic_inference --config ./data/your_task/config.yaml --hypotheses output/hypotheses.json

Ou use a API Python:

from hypogenic import BaseTask

# Criar tarefa com sua configuração
task = BaseTask(config_path="./data/your_task/config.yaml")

# Gerar hipóteses
task.generate_hypotheses(method="hypogenic", num_hypotheses=20)

# Executar inferência
results = task.inference(hypothesis_bank="./output/hypotheses.json")

Quando Usar Esta Habilidade

Use esta habilidade ao trabalhar em:

• Geração de hipóteses científicas a partir de conjuntos de dados observacionais
• Testes sistemáticos de múltiplas hipóteses concorrentes
• Combinação de insights de literatura com padrões empíricos
• Aceleração da descoberta científica através de ideação automatizada de hipóteses
• Domínios que exigem análise orientada por hipóteses: detecção de engano, identificação de conteúdo gerado por IA, indicadores de saúde mental, modelagem preditiva ou outras pesquisas empíricas

Recursos Principais

Geração Automatizada de Hipóteses

• Gere 10-20+ hipóteses testáveis a partir de dados em minutos
• Refinamento iterativo com base no desempenho de validação
• Suporte para LLMs baseados em API (OpenAI, Anthropic) e locais

Integração de Literatura

• Extraia insights de artigos científicos via processamento de PDF
• Combine fundações teóricas com padrões empíricos
• Pipeline sistemático de literatura para hipótese com GROBID

Otimização de Desempenho

• Cache Redis reduz custos de API para experimentos repetidos
• Processamento paralelo para testes em larga escala de hipóteses
• Refinamento adaptativo focado em exemplos desafiadores

Configuração Flexível

• Engenharia de prompts baseada em templates com injeção de variáveis
• Extração de rótulos personalizada para tarefas específicas de domínio
• Arquitetura modular para fácil extensão

Resultados Comprovados

• Melhoria de 8,97% em relação a baselines com poucos exemplos
• Melhoria de 15,75% em relação a abordagens apenas de literatura
• Diversidade de hipóteses 80-84% (insights não redundantes)
• Avaliadores humanos relatam melhorias significativas na tomada de decisão

Capacidades Principais

1. HypoGeniC: Geração de Hipóteses Orientada por Dados

Gere hipóteses unicamente a partir de dados observacionais através de refinamento iterativo.

Processo:

1. Inicialize com um pequeno subconjunto de dados para gerar hipóteses candidatas
2. Refine iterativamente as hipóteses com base no desempenho
3. Substitua hipóteses com baixo desempenho por novas a partir de exemplos desafiadores

Melhor para: Pesquisa exploratória sem literatura existente, descoberta de padrões em conjuntos de dados novos

2. HypoRefine: Integração de Literatura e Dados

Combine sinergicamente literatura existente com dados empíricos através de um framework de agente.

Processo:

1. Extraia insights de artigos científicos relevantes (tipicamente 10 artigos)
2. Gere hipóteses fundamentadas em teoria a partir de literatura
3. Gere hipóteses orientadas por dados a partir de padrões observacionais
4. Refine ambos os bancos de hipóteses através de melhoria iterativa

Melhor para: Pesquisa com fundações teóricas estabelecidas, validação ou extensão de teorias existentes

3. Métodos Union

Combine mecanicisticamente hipóteses apenas de literatura com outputs do framework.

Variantes:

• Literature ∪ HypoGeniC: Combina hipóteses de literatura com geração orientada por dados
• Literature ∪ HypoRefine: Combina hipóteses de literatura com abordagem integrada

Melhor para: Cobertura abrangente de hipóteses, eliminação de redundância mantendo perspectivas diversas

Instalação

Instale via pip:

uv pip install hypogenic

Dependências opcionais:

• Servidor Redis (porta 6832): Ativa cache de respostas de LLM para reduzir significativamente custos de API durante geração iterativa de hipóteses
• s2orc-doc2json: Necessário para processar PDFs de literatura em workflows HypoRefine
• GROBID: Necessário para pré-processamento de PDF (veja seção Processamento de Literatura)

Clone conjuntos de dados de exemplo:

# Para exemplos HypoGeniC
git clone https://github.com/ChicagoHAI/HypoGeniC-datasets.git ./data

# Para exemplos HypoRefine/Union
git clone https://github.com/ChicagoHAI/Hypothesis-agent-datasets.git ./data

Formato de Conjunto de Dados

Conjuntos de dados devem seguir o formato HuggingFace datasets com convenções de nomenclatura específicas:

Arquivos obrigatórios:

• <TASK>_train.json: Dados de treinamento
• <TASK>_val.json: Dados de validação
• <TASK>_test.json: Dados de teste

Chaves obrigatórias em JSON:

• text_features_1 até text_features_n: Listas de strings contendo valores de features
• label: Lista de strings contendo rótulos de verdade fundamental

Exemplo (previsão de cliques em headlines):

{
  "headline_1": [
    "What Up, Comet? You Just Got *PROBED*",
    "Scientists Made a Breakthrough in Quantum Computing"
  ],
  "headline_2": [
    "Scientists Everywhere Were Holding Their Breath Today. Here's Why.",
    "New Quantum Computer Achieves Milestone"
  ],
  "label": [
    "Headline 2 has more clicks than Headline 1",
    "Headline 1 has more clicks than Headline 2"
  ]
}

Notas importantes:

• Todas as listas devem ter o mesmo comprimento
• O formato do rótulo deve corresponder ao formato de saída da função extract_label()
• As chaves de features podem ser customizadas para corresponder ao seu domínio (ex: review_text, post_content, etc.)

Configuração

Cada tarefa exige um arquivo config.yaml especificando:

Elementos obrigatórios:

• Caminhos de conjunto de dados (train/val/test)
• Templates de prompts para:
  • Geração de observações
  • Geração em lote de hipóteses
  • Inferência de hipóteses
  • Verificação de relevância
  • Métodos adaptativos (para HypoRefine)

Capacidades de template:

• Placeholders de conjunto de dados para injeção dinâmica de variáveis (ex: ${text_features_1}, ${num_hypotheses})
• Funções de extração de rótulos personalizadas para análise específica de domínio
• Estrutura de prompt baseada em papéis (papéis system, user, assistant)

Estrutura de configuração:

task_name: your_task_name

train_data_path: ./your_task_train.json
val_data_path: ./your_task_val.json
test_data_path: ./your_task_test.json

prompt_templates:
  # Chaves adicionais para componentes de prompt reutilizáveis
  observations: |
    Feature 1: ${text_features_1}
    Feature 2: ${text_features_2}
    Observation: ${label}
  
  # Templates obrigatórios
  batched_generation:
    system: "Your system prompt here"
    user: "Your user prompt with ${num_hypotheses} placeholder"
  
  inference:
    system: "Your inference system prompt"
    user: "Your inference user prompt"
  
  # Templates opcionais para features avançadas
  few_shot_baseline: {...}
  is_relevant: {...}
  adaptive_inference: {...}
  adaptive_selection: {...}

Consulte references/config_template.yaml para um exemplo de configuração completa.

Processamento de Literatura (HypoRefine/Union Methods)

Para usar geração de hipóteses baseada em literatura, você deve pré-processar artigos em PDF:

Passo 1: Configurar GROBID (primeira vez apenas)

bash ./modules/setup_grobid.sh

Passo 2: Adicionar arquivos PDF Coloque artigos científicos em literature/YOUR_TASK_NAME/raw/

Passo 3: Processar PDFs

# Inicie o serviço GROBID
bash ./modules/run_grobid.sh

# Processe PDFs para sua tarefa
cd examples
python pdf_preprocess.py --task_name YOUR_TASK_NAME

Isso converte PDFs para formato estruturado para extração de hipóteses. Busca automatizada de literatura será suportada em futuras releases.

Uso CLI

Geração de Hipóteses

hypogenic_generation --help

Parâmetros principais:

• Caminho do arquivo de configuração da tarefa
• Seleção de modelo (baseado em API ou local)
• Método de geração (HypoGeniC, HypoRefine ou Union)
• Número de hipóteses a gerar
• Diretório de output para bancos de hipóteses

Inferência de Hipóteses

hypogenic_inference --help

Parâmetros principais:

• Caminho do arquivo de configuração da tarefa
• Caminho do arquivo do banco de hipóteses
• Caminho do conjunto de dados de teste
• Método de inferência (padrão ou multi-hipótese)
• Arquivo de output para resultados

Uso da API Python

Para controle programático e workflows customizados, use Hypogenic diretamente no seu código Python:

Geração Básica HypoGeniC

from hypogenic import BaseTask

# Clone conjuntos de dados de exemplo primeiro
# git clone https://github.com/ChicagoHAI/HypoGeniC-datasets.git ./data

# Carregue sua tarefa com função extract_label customizada
task = BaseTask(
    config_path="./data/your_task/config.yaml",
    extract_label=lambda text: extract_your_label(text)
)

# Gerar hipóteses
task.generate_hypotheses(
    method="hypogenic",
    num_hypotheses=20,
    output_path="./output/hypotheses.json"
)

# Executar inferência
results = task.inference(
    hypothesis_bank="./output/hypotheses.json",
    test_data="./data/your_task/your_task_test.json"
)

Métodos HypoRefine/Union

# Para abordagens integradas com literatura
# git clone https://github.com/ChicagoHAI/Hypothesis-agent-datasets.git ./data

# Gerar com HypoRefine
task.generate_hypotheses(
    method="hyporefine",
    num_hypotheses=15,
    literature_path="./literature/your_task/",
    output_path="./output/"
)
# Isto gera 3 bancos de hipóteses:
# - HypoRefine (abordagem integrada)
# - Hipóteses apenas de literatura
# - Literature∪HypoRefine (union)

Inferência de Multi-Hipótese

from examples.multi_hyp_inference import run_multi_hypothesis_inference

# Teste múltiplas hipóteses simultaneamente
results = run_multi_hypothesis_inference(
    config_path="./data/your_task/config.yaml",
    hypothesis_bank="./output/hypotheses.json",
    test_data="./data/your_task/your_task_test.json"
)

Extração de Rótulo Customizada

A função extract_label() é crítica para análise de outputs de LLM. Implemente-a com base em sua tarefa:

def extract_label(llm_output: str) -> str:
    """Extraia rótulo predito do texto de inferência do LLM.
    
    Comportamento padrão: procura por padrão 'final answer:\s+(.*)'.
    Customize para formato de output específico de seu domínio.
    """
    import re
    match = re.search(r'final answer:\s+(.*)', llm_output, re.IGNORECASE)
    if match:
        return match.group(1).strip()
    return llm_output.strip()

Importante: Os rótulos extraídos devem corresponder ao formato dos valores de label no seu conjunto de dados para cálculo correto de acurácia.

Exemplos de Workflow

Exemplo 1: Geração de Hipóteses Orientada por Dados (HypoGeniC)

Cenário: Detectar conteúdo gerado por IA sem framework teórico prévio

Passos:

1. Prepare conjunto de dados com amostras de texto e rótulos (humano vs. gerado por IA)
2. Crie config.yaml com templates de prompts apropriados
3. Execute geração de hipóteses:

   hypogenic_generation --config config.yaml --method hypogenic --num_hypotheses 20
   

4. Execute inferência no conjunto de teste:

   hypogenic_inference --config config.yaml --hypotheses output/hypotheses.json --test_data data/test.json
   

5. Analise resultados para padrões como formalidade, precisão gramatical e diferenças de tom

Exemplo 2: Testes de Hipóteses Informados por Literatura (HypoRefine)

Cenário: Detecção de engano em avaliações de hotel com base em pesquisa existente

Passos:

1. Colete 10 artigos relevantes sobre sinais linguísticos de engano
2. Prepare conjunto de dados com avaliações genuínas e fraudulentas
3. Configure config.yaml com templates de processamento de literatura e geração de dados
4. Execute HypoRefine:

   hypogenic_generation --config config.yaml --method hyporefine --papers papers/ --num_hypotheses 15
   

5. Teste hipóteses examinando frequência de pronomes, especificidade de detalhes e outros padrões linguísticos
6. Compare desempenho de hipóteses baseadas em literatura e orientadas por dados

Exemplo 3: Cobertura Abrangente de Hipóteses (Método Union)

Cenário: Detecção de estresse mental maximizando diversidade de hipóteses

Passos:

1. Gere hipóteses de literatura a partir de artigos de pesquisa em saúde mental
2. Gere hipóteses orientadas por dados a partir de posts em redes sociais
3. Execute método Union para combinar e desduplicar:

   hypogenic_generation --config config.yaml --method union --literature_hypotheses lit_hyp.json
   

4. Inferência captura tanto construtos teóricos (mudanças no comportamento de postagem) quanto padrões de dados (mudanças em linguagem emocional)

Otimização de Desempenho

Cache: Ative cache Redis para reduzir custos de API e tempo de computação para chamadas repetidas de LLM

Processamento Paralelo: Aproveite múltiplos workers para geração em larga escala e testes de hipóteses

Refinamento Adaptativo: Use exemplos desafiadores para melhorar iterativamente a qualidade das hipóteses

Resultados Esperados

Pesquisa usando hypogenic demonstrou:

• Melhoria de 14,19% de acurácia em tarefas de detecção de conteúdo IA
• Melhoria de 7,44% de acurácia em tarefas de detecção de engano
• 80-84% dos pares de hipóteses oferecem insights distintos não redundantes
• Altas classificações de utilidade de avaliadores humanos em múltiplos domínios de pesquisa

Solução de Problemas

Problema: Hipóteses geradas são muito genéricas Solução: Refine templates de prompts em config.yaml para solicitar hipóteses mais específicas e testáveis

Problema: Desempenho fraco de inferência Solução: Garanta que o conjunto de dados tenha exemplos de treinamento suficientes, ajuste parâmetros de geração de hipóteses ou aumente número de hipóteses

Problema: Falhas de extração de rótulo Solução: Implemente função extract_label() customizada para análise de output específica de domínio

Problema: Falha de processamento de PDF do GROBID Solução: Garanta que o serviço GROBID está em execução (bash ./modules/run_grobid.sh) e PDFs são artigos científicos válidos

Criando Tarefas Customizadas

Para adicionar uma nova tarefa ou conjunto de dados ao Hypogenic:

Passo 1: Prepare Seu Conjunto de Dados

Crie três arquivos JSON seguindo o formato obrigatório:

• your_task_train.json
• your_task_val.json
• your_task_test.json

Cada arquivo deve ter chaves para features de texto (text_features_1, etc.) e label.

Passo 2: Crie config.yaml

Defina a configuração de sua tarefa com:

• Nome da tarefa e caminhos de conjunto de dados
• Templates de prompts para observações, geração, inferência
• Qualquer chave adicional para componentes de prompt reutilizáveis
• Variáveis placeholder (ex: ${text_features_1}, ${num_hypotheses})

Passo 3: Implemente Função extract_label

Crie uma função de extração de rótulo customizada que analisa outputs de LLM para seu domínio:

from hypogenic import BaseTask

def extract_my_label(llm_output: str) -> str:
    """Extração de rótulo customizada para sua tarefa.
    
    Deve retornar rótulos no mesmo formato que o campo 'label' do conjunto de dados.
    """
    # Exemplo: Extrair de formato específico
    if "Final prediction:" in llm_output:
        return llm_output.split("Final prediction:")[-1].strip()
    
    # Fallback para padrão padrão
    import re
    match = re.search(r'final answer:\s+(.*)', llm_output, re.IGNORECASE)
    return match.group(1).strip() if match else llm_output.strip()

# Use sua tarefa customizada
task = BaseTask(
    config_path="./your_task/config.yaml",
    extract_label=extract_my_label
)

Passo 4: (Opcional) Processe Literatura

Para métodos HypoRefine/Union:

1. Crie diretório literature/your_task_name/raw/
2. Adicione PDFs de artigos científicos relevantes
3. Execute pré-processamento GROBID
4. Processe com pdf_preprocess.py

Passo 5: Gere e Teste

Execute geração de hipóteses e inferência usando CLI ou API Python:

# Abordagem CLI
hypogenic_generation --config your_task/config.yaml --method hypogenic --num_hypotheses 20
hypogenic_inference --config your_task/config.yaml --hypotheses output/hypotheses.json

# Ou use API Python (veja seção Uso da API Python)

Estrutura do Repositório

Compreendendo o layout do repositório:

hypothesis-generation/
├── hypogenic/              # Código do pacote principal
├── hypogenic_cmd/          # Pontos de entrada CLI
├── hypothesis_agent/       # Framework de agente HypoRefine
├── literature/            # Utilitários de processamento de literatura
├── modules/               # Módulos GROBID e pré-processamento
├── examples/              # Scripts de exemplo
│   ├── generation.py      # Geração HypoGeniC básica
│   ├── union_generation.py # Geração HypoRefine/Union
│   ├── inference.py       # Inferência de hipótese única
│   ├── multi_hyp_inference.py # Inferência de múltiplas hipóteses
│   └── pdf_preprocess.py  # Processamento de PDF de literatura
├── data/                  # Conjuntos de dados de exemplo (clone separadamente)
├── tests/                 # Testes unitários
└── IO_prompting/          # Templates de prompts e experimentos

Diretórios principais:

• hypogenic/: Pacote principal com BaseTask e lógica de geração
• examples/: Implementações de referência para workflows comuns
• literature/: Ferramentas para processamento de PDF e extração de literatura
• modules/: Integrações de ferramentas externas (GROBID, etc.)

Publicações Relacionadas

HypoBench (2025)

Liu, H., Huang, S., Hu, J., Zhou, Y., & Tan, C. (2025). HypoBench: Towards Systematic and Principled Benchmarking for Hypothesis Generation. arXiv preprint arXiv:2504.11524.

• Paper: https://arxiv.org/abs/2504.11524
• Description: Framework de benchmarking para avaliação sistemática de métodos de geração de hipóteses

BibTeX:

@misc{liu2025hypobenchsystematicprincipledbenchmarking,
      title={HypoBench: Towards Systematic and Principled Benchmarking for Hypothesis Generation}, 
      author={Haokun Liu and Sicong Huang and Jingyu Hu and Yangqiaoyu Zhou and Chenhao Tan},
      year={2025},
      eprint={2504.11524},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2504.11524}, 
}

Literature Meets Data (2024)

Liu, H., Zhou, Y., Li, M., Yuan, C., & Tan, C. (2024). Literature Meets Data: A Synergistic Approach to Hypothesis Generation. arXiv preprint arXiv:2410.17309.

• Paper: https://arxiv.org/abs/2410.17309
• Code: https://github.com/ChicagoHAI/hypothesis-generation
• Description: Apresenta HypoRefine e demonstra combinação sinérgica de geração de hipóteses baseada em literatura e orientada por dados

BibTeX:

@misc{liu2024literaturemeetsdatasynergistic,
      title={Literature Meets Data: A Synergistic Approach to Hypothesis Generation}, 
      author={Haokun Liu and Yangqiaoyu Zhou and Mingxuan Li and Chenfei Yuan and Chenhao Tan},
      year={2024},
      eprint={2410.17309},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2410.17309}, 
}

Hypothesis Generation with Large Language Models (2024)

Zhou, Y., Liu, H., Srivastava, T., Mei, H., & Tan, C. (2024). Hypothesis Generation with Large Language Models. In Proceedings of EMNLP Workshop of NLP for Science.

• Paper: https://aclanthology.org/2024.nlp4science-1.10/
• Description: Framework HypoGeniC original para geração de hipóteses orientada por dados

BibTeX:

@inproceedings{zhou2024hypothesisgenerationlargelanguage,
      title={Hypothesis Generation with Large Language Models}, 
      author={Yangqiaoyu Zhou and Haokun Liu and Tejes Srivastava and Hongyuan Mei and Chenhao Tan},
      booktitle = {Proceedings of EMNLP Workshop of NLP for Science},
      year={2024},
      url={https://aclanthology.org/2024.nlp4science-1.10/},
}

Recursos Adicionais

Links Oficiais

• Repositório GitHub: https://github.com/ChicagoHAI/hypothesis-generation
• Pacote PyPI: https://pypi.org/project/hypogenic/
• Licença: MIT License
• Issues & Suporte: https://github.com/ChicagoHAI/hypothesis-generation/issues

Conjuntos de Dados de Exemplo

Clone estes repositórios para exemplos prontos para uso:

# Exemplos HypoGeniC (apenas orientado por dados)
git clone https://github.com/ChicagoHAI/HypoGeniC-datasets.git ./data

# Exemplos HypoRefine/Union (literatura + dados)
git clone https://github.com/ChicagoHAI/Hypothesis-agent-datasets.git ./data

Comunidade & Contribuições

• Contribuidores: 7+ colaboradores ativos
• Stars: 89+ no GitHub
• Tópicos: research-tool, interpretability, hypothesis-generation, scientific-discovery, llm-application

Para contribuições ou dúvidas, visite o repositório GitHub e verifique a página de issues.

Recursos Locais

references/

config_template.yaml - Arquivo de configuração de exemplo completo com todos os templates de prompts obrigatórios e parâmetros. Isto inclui:

• Estrutura YAML completa para configuração de tarefa
• Templates de prompts de exemplo para todos os métodos
• Documentação de variáveis placeholder
• Exemplos de prompt baseado em papéis

scripts/

Diretório de scripts está disponível para:

• Utilitários de preparação de dados customizados
• Ferramentas de conversão de formato
• Scripts de análise e avaliação
• Integração com ferramentas externas

assets/

Diretório de assets está disponível para:

• Conjuntos de dados de exemplo e templates
• Bancos de hipóteses de exemplo
• Outputs de visualização
• Suplementos de documentação