Executando verificação de segurança...
1
pcbrom
10 min de leitura ·

[IA-R-Stat] community-skills v0.1.0: envelopando pacotes como skills invocáveis por agentes (com bgumbel como primeiro pacote envelopado)

Cinco anos no CRAN. Cerca de +48k downloads acumulados. Dez papers citam o artigo subjacente. Mesmo assim, para chamar bgumbel de dentro de uma sessão Claude Code, Codex ou OpenCode, o desenvolvedor ainda copia código de cola: parser de argumentos no prompt, subprocesso ad hoc, marshalling numérico, parser de saída, esperando que nada quebre. Isso não é uma falha específica do bgumbel. Acontece com qualquer pacote R, Python, Julia ou Stata no momento em que um agente LLM tenta invocá-lo autonomamente.

community-skills é um hub público que fecha essa lacuna. Documenta um padrão único e entrega um exemplo funcional.

Três números, depois a lacuna

Otiniano, Vila, Brom e Bourguignon (2023) introduziram uma distribuição Gumbel bimodal de três parâmetros para modelar dados ambientais com dois regimes extremos (picos sazonais de temperatura, registros duais de cheia e estiagem). Comparado com uma mistura livre de cinco parâmetros de duas Gumbels, o modelo bimodal Gumbel atinge a bimodalidade com três parâmetros, (\mu, \sigma, \delta), mantendo identificabilidade. O paper saiu no Austrian Journal of Statistics; a implementação saiu no CRAN como bgumbel v0.0.3 no mesmo período.

Desde 2021-03-31, o pacote acumulou cerca de +48k downloads (cranlogs, snapshot 2026-05-01) e dez papers citantes (OpenAlex). Está no top 10% por citações no ano de publicação. Adoção não é o problema.

O problema é a costura entre o pacote e qualquer harness moderno de agente LLM. Documentação roxygen é para humanos. Vinhetas são para humanos. Manuais PDF são para humanos. Nenhum deles dá ao agente uma descrição machine-readable do que pode ser chamado, com qual formato de input, retornando qual output. Então o agente improvisa. Improvisação nesse contexto tem nome: código de cola que ninguém revisa, quebra silenciosamente e replica por pacote.

Por que envelopar e por que não portar

Há dois argumentos baratos para escrever o wrapper em vez de portar o algoritmo para a linguagem nativa do agente.

O primeiro é custo. Um wrap expõe código existente, validado por anos. As funções do bgumbel passam pela mesma suíte de testes que os mantenedores rodam em cada release CRAN; os papers citantes estressam a matemática indiretamente. Portar para Python ou Julia recomeça essa validação do zero. E cria um custo permanente de paridade: cada patch upstream precisa ser espelhado, ou o port silenciosamente diverge.

O segundo é evidência. Reprodução manual de erro é um ponto fraco conhecido em computação científica: o analista roda um comando, vê um número inesperado, copia para um caderno, e a trilha até o input original some. Um agente que invoca uma skill envelopada via subprocesso e JSON produz artefatos determinísticos e replayables. Cada input vai como JSON. Cada output vem como JSON. O par vira evidência que outra equipe pode reproduzir byte a byte. Reprodutibilidade deixa de ser uma aspiração na seção de métodos; passa a ser o default do harness.

Os dois argumentos (mais barato que reescrever, mais auditável que trabalho manual) são independentes. Um pacote pode valer o wrap pelo primeiro motivo (código legado, implementação madura) ou pelo segundo (workflow frágil que precisa de logs determinísticos). Quando ambos se aplicam, como em qualquer pacote estatístico bem citado, o caso é decisivo.

O padrão em três peças

community-skills documenta o mesmo padrão entre runtimes. Três peças, nada mais.

Um contrato SKILL.md. Cada skill declara o runtime no front matter YAML (r, python, julia, ...) e lista cada função exposta com schemas JSON de input e output. O contrato cabe na tela e é explícito o suficiente para um humano ou um agente auditar sem rodar código.

Uma bridge por runtime. O hub entrega bridges/r.py hoje, com placeholders para Python e Julia abertos a contribuição. A bridge é um adaptador Python fino que dispara o runtime, envia o JSON via stdin, captura stdout e stderr e parsa a resposta. Não há daemon, RPC, nem estado compartilhado entre chamadas. Cada invocação é um subprocesso novo.

Um dispatcher na linguagem nativa. Dentro de cada diretório skills/, um invoke.R (ou invoke.py, invoke.jl) lê o JSON do stdin, roteia no campo fn, chama a função envelopada e escreve um único objeto JSON em stdout. Falhas retornam {"ok": false, "error": "..."} com exit não-zero. O contrato é uniforme entre runtimes; só a linguagem do dispatcher muda.

A restrição deliberada do padrão é sua força. Embedding in-process (rpy2 para R, PyJulia para Julia) é tentador porque evita o custo de spawn por chamada. É também frágil: o Python chamador precisa ser ABI-compatível com o runtime alvo, dependências nativas precisam ser instaladas em build-time, e drift de versão produz crashes opacos. Para invocação agêntica, em que cada chamada é decisão deliberada e não inner loop, 100ms de spawn é irrelevante. O que não é irrelevante é portabilidade, debug manual e não ter que compilar extensões C num runner de CI.

Exemplo funcional: bgumbel como primeiro pacote envelopado

A primeira skill no hub envelopa as sete funções exportadas pelo pacote CRAN: dbgumbel (densidade), pbgumbel (CDF), qbgumbel (quantil), rbgumbel (amostragem), m1bgumbel e m2bgumbel (primeiro e segundo momentos em forma fechada) e mlebgumbel (ajuste por máxima verossimilhança). O SKILL.md da skill documenta cada uma com schemas; o dispatcher é um invoke.R único que cobre todas.

O wrap vai além de mapeamento um-para-um. MLE numérico do Gumbel bimodal é sensível a valores iniciais; passar um (0, 0, 0) degenerado para bgumbel::mlebgumbel faz o otimizador levantar valor inicial em 'vmmin' não é finito. Para um analista, isso significa reiniciar e tentar de novo. Para um agente, deveria significar tentar de novo de forma transparente e reportar o que foi tentado.

A skill expõe uma função dedicada init_theta que retorna um trio inicial robusto baseado nos dados: \mu = \mathrm{mediana}, \sigma = \mathrm{MAD} (reescalado para escala equivalente a uma Gumbel, com floor mínimo), \delta = 0.1 como semente quase-unimodal. O agente pode inspecionar a semente antes de ajustar.

O wrapper de mlebgumbel torna o auto-init o default. Se o caller não passa um theta, o dispatcher usa o heurístico do init_theta. Se o caller passa um theta que faz o otimizador divergir, o dispatcher tenta de novo com init_theta e reporta init_strategy: fallback_auto_after_user_failed na resposta. O modo de falha mais comum do MLE numérico (valores iniciais ruins) fica invisível para o agente caller.

Um exemplo completo, como aparece de dentro de uma sessão de agente:

echo '{"fn":"mlebgumbel","data":[<observações>]}' \
  | Rscript --vanilla skills/bgumbel/invoke.R

A resposta é um único objeto JSON: {"ok": true, "fn": "mlebgumbel", "result": {"estimate": {"mu": ..., "sigma": ..., "delta": ...}, "standard_error": ..., "loglik": ..., "n": ..., "init_strategy": "auto", "theta_used": ...}}. O agente recebe o ajuste, os erros-padrão, a log-verossimilhança, o tamanho da amostra e um campo de auditoria que registra qual caminho de inicialização foi tomado. Replay com o mesmo input retorna a mesma resposta bit a bit.

O que o exemplo ilustra além do bgumbel

A skill bgumbel não é o ponto. O ponto é a receita que a produziu. A mesma receita envelopa forecast, lme4, mgcv, randomForest: qualquer pacote que um analista carregue com library(...). A receita também generaliza para ecossistemas além do R. Uma skill Python entregaria invoke.py e rotearia por uma futura bridges/python.py que dispara o Python do sistema (ou um venv por skill). Uma skill Julia entregaria invoke.jl e rotearia por bridges/julia.py. O contrato SKILL.md é idêntico; só a bridge muda; o dispatcher fica na linguagem nativa do pacote.

Esse é o segundo argumento barato reformulado como arquitetura: portabilidade entre linguagens não é uma feature adicionada depois, é o que cai naturalmente de usar subprocesso e JSON desde o início. Cada nova bridge expande o alcance do hub sem mudar o contrato.

O que o trabalho citante confirma sobre o bgumbel

Os dez papers citando Otiniano et al. (2023) cobrem hidrologia, clima, teoria de confiabilidade e extensões metodológicas. Quintino e Rathie (2024) usaram a Gumbel bimodal para confiabilidade stress-strength (P(X < Y)). Anugrawati (2025) aplicou em dados de temperatura. Deger (2026) usou ferramentas correlatas de extremos para frequência de cheias na bacia do Yeşilırmak. Otiniano e Lisboa (2025, 2026) desenvolveram extensões tipo regressão e uma versão revisada da generalized extreme-value bimodal. Vila e Serra (2023) generalizaram a construção para uma classe trimodal. O pacote serve pesquisa downstream real; o wrap torna essa pesquisa uma chamada de subprocesso de distância de qualquer agente.

O hub: o que community-skills v0.1.0 entrega

O repositório é pcbrom/community-skills, MIT, com DOI Zenodo atribuído por release. A v0.1.0 entrega:

  • bridges/r.py: a bridge R, com timeout, falha graciosa quando Rscript está ausente, e reporte de erro JSON que o agente pode acionar.
  • bridges/__init__.py: auto-router que lê o campo runtime do SKILL.md e dispatcha para a bridge correspondente.
  • bridges/python.py e bridges/julia.py: placeholders que levantam NotImplementedError e linkam para o issue tracker. Contribuições da comunidade explicitamente convidadas.
  • skills/bgumbel/: primeiro pacote envelopado, com as oito funções listadas.
  • templates/new_r_skill/: scaffold de copiar e colar para futuras skills R.
  • docs/pattern.md, docs/architecture.md, docs/adding_r_skill.md: racional de design, diagrama do sistema, tutorial passo a passo de port.
  • tests/: 19 testes cobrindo a camada de bridge e a skill bgumbel end-to-end. Passam num runner de CI que acabou de instalar R + bgumbel.
  • CONTRIBUTING.md e .github/ISSUE_TEMPLATE/new_skill.yml: receita de cinco passos e issue template que captura o que o mantenedor precisa para avaliar uma proposta.

Se você mantém um pacote no CRAN, no PyPI ou no registry geral do Julia e quer que ele seja agent-callable sem reescrever, a receita está a um read de distância. Abra issue com o template new_skill, copie o scaffold, preencha o SKILL.md, adapte o dispatcher, adicione um teste de fumaça, abra um PR. O CI instala seu pacote e roda seu teste. Se passa verde, o mantenedor revisa e merge. O trabalho que um agente não conseguia fazer sozinho um ano atrás vira contribuição de uma tarde.

Genealogia e o que vem depois

Esse hub continua uma linha de tooling de agentes que o mantenedor começou com autoresearch (DOI 10.5281/zenodo.19772195), por sua vez generalização do pattern autoresearch de Karpathy. Autoresearch generaliza o loop autônomo de pesquisa com crítico LLM constrained por JSON Schema. community-skills generaliza o wrap de pacote como skill. Os dois compõem: um agente rodando autoresearch loop pode invocar qualquer community-skill como passo dentro de uma proposta de mudança. JSON e subprocesso são o tecido conjuntivo.

O que vem depois depende de contribuições. Short-list realista para v0.2.0+: bridge Python (o design espelha a R, dispara um interpretador, troca JSON, opcionalmente dentro de venv por skill), bridge Julia (analogamente) e uma segunda skill R que mostre que o padrão não é específico do bgumbel. Candidatos da bancada do mantenedor: forecast para forecasting de séries temporais, lme4 para modelos mistos lineares, mgcv para modelos aditivos generalizados. Cada um é um wrap de uma tarde que abre uma superfície metodológica inteira para invocação agêntica.

Se você tem um pacote e um caso de uso, o issue tracker está aberto.

Discussão e próximos releases

Acompanho discussão técnica e anúncios de próximos releases do hub no LinkedIn. Para conectar e seguir o trabalho: linkedin.com/in/pcbrom.

Referências

O pacote R envelopado:

O paper canônico introduzindo o modelo:

  • Otiniano, C. E. G.; Vila, R.; Brom, P. C.; Bourguignon, M. (2023). On the bimodal Gumbel model with application to environmental data. Austrian Journal of Statistics, 52, 45-65. DOI 10.17713/ajs.v52i2.1392.

Background em teoria de extremos:

  • Gumbel, E. J. (1958). Statistics of extremes. Columbia University Press. DOI 10.7312/gumb92958.
  • Coles, S. (2001). An introduction to statistical modeling of extreme values. Springer. DOI 10.1007/978-1-4471-3675-0.

Papers selecionados que citam Otiniano et al. (2023):

  • Otiniano, C. E. G.; Lisboa, M. N. S. (2026). A regression-type model for bimodal extreme-valued data. Test. DOI 10.1007/s11749-026-01005-y.
  • Otiniano, C. E. G.; Lisboa, M. N. S. (2025). A revised bimodal generalized extreme value distribution. Entropy. DOI 10.3390/e27070749.
  • Alzaghal, A.; Aldeni, M. (2025). New families of the Gumbel distribution: bimodality, regression. Hacettepe Journal of Mathematics and Statistics. DOI 10.15672/hujms.1707784.
  • Quintino, F.; Rathie, P. N. (2024). Estimation of P(X<Y) stress-strength reliability measures. Symmetry, 16, art. 837. DOI 10.3390/sym16070837.
  • Otiniano, C. E. G.; Oliveira, Y. S. (2024). Probability distribution of extreme events in complex systems. Symmetry, 16, art. 1639. DOI 10.3390/sym16121639.
  • Vila, R.; Serra, V. (2023). A general class of trimodal distributions: properties and inference. Journal of Applied Statistics. DOI 10.1080/02664763.2023.2207785.
  • Otiniano, C. E. G.; Silva, E. B. (2023). Bridging extremes: the invertible bimodal Gumbel distribution. Entropy. DOI 10.3390/e25121598.
  • Anugrawati, S. D. (2025). Application of extreme value distribution on temperature data. Makara Journal of Science. DOI 10.24252/msa.v13i1.60223.
  • Deger, İ. H. (2026). Flood frequency and temporal variability analysis of Yeşilırmak basin. Engineering Perspective. DOI 10.64808/engineeringperspective.1896337.
  • Yu, F.; Feng, W. (2023). Techno-economic analysis of residential building heating strategies. iScience. DOI 10.1016/j.isci.2023.107541.

Genealogia:

O hub:

  • Brom, P. C. (2026). community-skills: a community hub for wrapping packages as agent-callable skills (v0.1.0). github.com/pcbrom/community-skills. DOI Zenodo atribuído na primeira release.
Carregando publicação patrocinada...