alleleforge

## O que é AlleleForge é um framework de design orientado à pesquisa para edição genômica CRISPR que começa a partir de um alelo quebrado, em vez de um guia. Você fornece uma variante — entrada ClinVar, rsID, HGVS, VCF ou coordenadas brutas — e o pipeline a resolve, a encaminha para as químicas de edição elegíveis, enumera guias/pegRNAs candidatos, os pontua e retorna um menu ranqueado de edições candidatas. Três químicas são cobertas: nuclease SpCas9, editores de base (ABE/CBE) e edição prime, que o projeto trata como sua modalidade principal. Cada candidato carrega um resultado de edição previsto, um intervalo de incerteza e um relatório de off-target. Tudo é exposto através de três shells sobre um núcleo: uma biblioteca Python, uma interface de linha de comando `aforge` e uma UI web (backend FastAPI com frontend Next.js). ## Relatórios de incerteza e segurança As previsões nunca são floats simples. Cada resultado numérico é enviado com um intervalo, o método que o produziu e uma flag `calibrated` indicando se o intervalo foi ajustado contra a cobertura retida. Por padrão, os valores iniciais sem peso são heurísticas e reportam `calibrated=False`. A recalibração de intervalo usa métodos split-conformal e a calibração de probabilidade usa regressão isotônica, com `empirical_coverage`/ECE surgindo quando qualquer um é necessário. A análise de off-target é consciente de população e haplótipo, mas explicitamente opcional: o projeto não fornece dados gnomAD, portanto, uma varredura estratificada por ancestralidade requer que o usuário forneça uma fonte de frequência (`--gnomad`, `--haplotypes`, `--patient-vcf`). Sem isso, a varredura é apenas de referência e a saída assim o declara. O risco de ancestralidade é relatado como a população mais afetada, em vez de uma média, com um limite de transporte aplicado identicamente nos caminhos de população e haplótipo. A nomeação combina dois modelos de especificidade (CFD e MIT), registrando ambas as pontuações por site. Um cache de off-target entre execuções é protegido por segurança para buscas de apenas referência e pontuadores padrão. ## Reprodutibilidade e postura de engenharia As decisões de design documentadas no README enfatizam a reprodutibilidade: resultados endereçados por conteúdo, splits e caches (com reverificação de integridade), ambientes fixos, sementes determinísticas e checkpoints com hash de conteúdo. Um hash de artefato `null` bloqueia um download por design. Os modelos são carregados através de um portão de consentimento/licença/checksum; o backbone padrão (Nucleotide Transformer v2 500M) é CC-BY-NC-SA-4.0 e é recusado para uso comercial no momento do carregamento, sem pesos reais fornecidos. Existe um caminho de exportação ONNX para o backbone. Um crate Rust/PyO3 (`aforge_native`) fornece kernels de aceleração opcionais — busca BWT FM-index, seeding de k-mer, caminhada de haplótipo e alinhamento bulged — cada um com um fallback puro em Python idêntico em bytes e testes de paridade; a biblioteca instala e funciona sem o crate. Notavelmente, o benchmarking levou o projeto a deixar o pré-filtro de FM-index e seed de k-mer como opcional em vez de padrão, já que ambos foram medidos como um custo líquido ao nível de varredura. ## Benchmark e status Um benchmark público, CRISPR-Bench, fornece tarefas, splits congelados, métricas, um executor e um leaderboard; um script de estudo de calibração/generalização regenera ECE por tarefa, lacuna de generalização entre tipos de células e relatórios de recalibração. Figuras SVG reprodutíveis são geradas por um renderizador livre de dependências. Todas as quinze fases do roadmap v0.1.0 estão marcadas como concluídas (tipos core, acesso ao genoma, registro de dados, resolvedor de variantes, motor de off-target, zoo de modelos/pontuação, as três químicas, designer, relatórios, CLI, web, benchmark, docs). As trilhas pós-v0.1.0 em direção à v1.0 estão listadas como em andamento ou não iniciadas, incluindo a fixação de hashes de artefatos reais e um estudo de validação/calibração. ## Estrutura de instalação A instalação core é deliberadamente leve (modelos tipados, config, parsing de model-card) com extras opcionais para `core`, `genome`, `variant`, `cli`, `web`, `ml`, `cas9-rs3`, `docs` e `dev`. É necessário Python ≥ 3.11. O extra `variant` precisa de headers do cliente PostgreSQL porque `hgvs` depende de `psycopg2`; o README observa que isso anteriormente tornava impossível executar um comando de instalação documentado. O projeto afirma claramente que é uma ferramenta de pesquisa, não um dispositivo médico, e que as nomeações de off-target são computacionais e devem ser validadas experimentalmente.