Teste ac_plot_top_terms() gera ggplot valido (em
test-plots-snapshot.R:56) usava
"labels" %in% names(p) como sanidade. Em ggplot2 4.x a
estrutura interna do objeto ggplot mudou (nova base S7) e a checagem por
nome de slot passou a retornar FALSE, quebrando o test na
CRAN r-release-macos e r-oldrel-macos (post-acceptance check, deadline
2026-08-21). Substituido por
expect_no_error(ggplot2::ggplot_build(p)) – teste de
buildabilidade real, independente de versao do ggplot2.
Referencias ao modelo Groq llama-3.3-70b-versatile
(e ao par llama-3.1-8b-instant) foram atualizadas para
openai/gpt-oss-120b (e openai/gpt-oss-20b) em
exemplos, vignettes, README, testes de integracao e na tabela de
ac_qual_recommend_model(). A Groq descontinuou os modelos
Llama em 2026-06-17; chamadas com o nome antigo retornam HTTP 404. Nao
afeta usuarios da CRAN diretamente (sao apenas defaults sugeridos e
testes com skip_if() de API key), mas evita quebra de
exemplos e de CI com GROQ_API_KEY configurada.
ac_qual_report_full() (novo) –
relatorio consolidado multi-variavel. Aceita uma lista nomeada de
resultados (coded + codebook +
reliability opcional) e gera um unico
arquivo (Markdown ou HTML) com uma secao por variavel, tabela sumaria no
topo (k categorias, n docs, multilabel por variavel), mesmo idioma
(pt/en) e formato consistente com
[ac_qual_report()]. Atende ao caso de uso comum de analise de conteudo
com N variaveis, que antes exigia consolidador ad hoc.
Campo label opcional em cada categoria do
codebook. Cada entrada de categories em
[ac_qual_codebook()] agora aceita label = "..." como rotulo
humano para exibicao (paralelo a definition,
examples_pos, etc.). Se ausente, o rotulo defaults para o
proprio slug (chave da lista). A saida de [ac_qual_code()] ganha coluna
nova categoria_label com o rotulo
traduzido; em multilabel, os labels vem unidos por " | "
(espaco dos dois lados), enquanto a coluna categoria mantem
"|" sem espaco como chave estavel de comparacao. Preservado
tambem em ac_qual_save_codebook() /
ac_qual_load_codebook() (YAML).
Tres bugs encontrados no ac_qual_code() e funcoes
internas durante uso em producao (Gemini/Groq/OpenAI) foram
corrigidos:
live = "terminal" travava no primeiro
documento com “Cannot find progress bar”
(R/ac_qual_live.R). A cli::cli_progress_bar()
era criada sem .envir, amarrando o ciclo de vida da barra
ao frame de .ac_live_start() – que retorna imediatamente.
cli destruia a barra antes de ac_qual_code()
conseguir chamar cli_progress_update(). Fix:
.ac_live_start() (e .ac_live_finish()) agora
aceita argumento .envir (padrao
parent.frame()), amarrando a barra ao frame do chamador –
tipicamente ac_qual_code().
temperature de ac_qual_code()
era aceito mas nunca usado (R/ac_qual_code.R,
.ac_classify_one()). O parametro formal era ignorado no
corpo, entao as k_consistency rodadas de self-consistency
(Wang et al., 2023) usavam sempre a temperatura padrao do provedor –
variacao estocastica esperada nao acontecia, inflando
confidence_score espuriamente. Fix:
temperature agora e injetada via
ellmer::params(temperature = ...) no argumento
params do chat (respeita params explicitos
passados pelo usuario via ...). Para o caminho
chat = <Chat pre-configurado>, o Chat e reconstruido
com o novo params via get_provider() +
get_model(), com fallback graceful para o clone antigo se a
reconstrucao falhar.
ac_qual_report(path = <relativo>)
falhava com “The directory ‘X’ does not exist” mesmo com a
pasta criada, e derrubava loops sem tryCatch. Causa:
rmarkdown::render() muda o cwd durante o knit, e
normalizePath(path, mustWork = FALSE) nao converte
confiavelmente paths relativos inexistentes em absolutos. Fix:
.ac_report_absolute_path() resolve para absoluto contra o
cwd atual antes de qualquer render(), e a pasta destino e
criada com dir.create(recursive = TRUE) se
necessario.
multilabel = TRUE quebrava com “Result must
be length 1, not N” quando o modelo devolvia array JSON
(R/ac_qual_code.R, .ac_build_system_prompt() +
.ac_build_result_tibble()). O prompt nao instruia
explicitamente que "categoria" deve ser sempre uma string
(mesmo em multilabel), e o parser assumia que
main$categoria era escalar. Um documento com array
["a","b"] quebrava a purrr::map() inteira,
derrubando a classificacao de TODOS os documentos daquela variavel. Fix:
(a) prompt multilabel agora instrui a devolver “tecnica|politica”
(string pipe-separada) e proibe explicitamente array JSON; (b) parser
defensivo faz sempre
paste(as.character(main$categoria), collapse = "|"),
absorvendo arrays quando o modelo ignora a instrucao.
ac_cluster_documents() (novo) —
clustering nao supervisionado de documentos com hierarquico (Ward.D2),
k-means ou PAM. Features configuraveis (TF-IDF ou contagens), distancias
cosine/euclidean, escolha automatica de
k por silhueta (usa cluster de
Suggests). Retorna S3 ac_cluster com metodo
print.ac_plot_cluster() (novo) — tres tipos
de visualizacao para objetos ac_cluster:
dendrogram (default para hclust), scatter
(projecao PCA 2D com labels) e heatmap (matriz de
dissimilaridade ordenada pelo dendrograma).vignette("cluster"):
“Agrupamento nao supervisionado de documentos”. Explica as tres familias
(hard/soft clustering e LDA) com tabela de quando usar cada uma,
apresenta seis visualizacoes complementares (dendrograma, PCA, heatmap,
top termos por cluster, curva de silhueta e comparacao lado-a-lado hard
vs. LDA/gamma), valida a particao contra um tema_real
mantido fora do modelo e integra o clustering ao pipeline
qualitativo._pkgdown.yml
(menu de vignettes e secao “Pipeline quantitativo”) apontam para a nova
vignette; acentos corrigidos nas entradas visiveis do menu.ac_plot_wordcloud_comparative() agora
aceita N grupos (>= 2) em vez de somente 2. Cada
grupo vira uma faceta; nas duas implementacoes
(backend = "ggwordcloud" e backend = "ggplot")
o layout usa facet_wrap(). Cores padrao passam a vir de
ac_palette(N). A validacao antiga
(length(grupos) != 2L) foi substituida por
length(grupos) < 2L.qualitativo-llm.Rmd (nova secao “Quando usar LLM (e quando
NAO usar)” com tabela decisoria, tabela de custo por modelo e
“Diagnosticando problemas comuns” com 4 modos de falha);
quantitativo.Rmd (nova secao “Qual metrica responde qual
pergunta”); lda.Rmd (comparativo LDA vs. clustering vs. LLM
e heatmap gamma com referencia cruzada ao cluster). Roxygen de
ac_qual_codebook(), ac_qual_code(),
ac_qual_reliability(), ac_import(),
ac_qual_report(), ac_qual_irr(),
ac_tokenize() e ac_count() expandidos com
framing teorico e faixas interpretativas. @examples mais
realistas em ac_keyness(), ac_tf_idf(),
ac_cooccurrence() e ac_sentiment().quantitativo e roxygen de ac_keyness()
descrevem grupos genericamente (qualquer variavel categorica: partido,
periodo, tema, regiao, condicao experimental) em vez do exemplo “governo
x oposicao” que havia ossificado como canonico.ac_cluster.R (67% -> 91%),
ac_qual_codebook.R (43% -> 48%) e
ac_qual_reliability.R.ac_wordcloud(),
ac_plot_wordcloud_comparative() e
ac_qual_sample() agora expoem argumento seed
(padrao 42L; NULL usa o RNG corrente). A
semente e escopada via withr::with_seed() – nao altera o
.Random.seed do usuario apos o retorno.<<- em
.ac_report_build_md() (ac_qual_report.R): o
buffer de linhas agora vive em um environment() local..GlobalEnv em
ac_plot_wordcloud_comparative(); RNG passa a ser escopado
exclusivamente via withr::with_seed().withr movido de Suggests para
Imports (usado em codigo principal).ac_plot_wordcloud_comparative() —
layout reproduzivel via novo argumento seed (padrao
42L), com salvaguarda do RNG global; cores padrao agora vem
de ac_palette(2L) em vez de codigos fixos. Novo argumento
backend
("auto"/"ggwordcloud"/"ggplot"):
quando ggwordcloud esta instalado, usa
geom_text_wordcloud com facets lado a lado; caso contrario,
mantem o layout jitter original.ac_plot_xray() — corrigido caso de
divisao por zero em documentos com apenas 1 token (posicao passa a ser
0.5); warning agora identifica quais termos ficaram sem
ocorrencia, nao apenas o caso extremo de nenhum encontrado.ac_import() — a ordem dos documentos
no corpus resultante agora preserva a ordem de entrada em
path, mesmo misturando arquivos OCR e texto;
doc_id duplicados sao desambiguados automaticamente com
sufixos (_2, _3, …) e um aviso; erros migrados
para cli::cli_abort (padrao do pacote). Loop de OCR ganhou
barra de progresso via cli::cli_progress_bar().ac_export(),
ac_qual_irr(), theme_ac(),
ac_palette() e is_ac_corpus().theme_ac() — tema
ggplot2 minimalista e consistente, usado por todos os
ac_plot_*(). Deriva de theme_minimal() com
ajustes editoriais: títulos em negrito, gridlines suaves, tipografia
compacta.
ac_palette() — paleta categórica de
8 cores (adaptada de Okabe-Ito para compatibilidade WCAG AA e
daltonismo).
ac_wordcloud(backend = ...) —
reescrita para preferir ggwordcloud (retorna
ggplot, layout mais agradável, tipografia editorial), com
fallback para wordcloud clássico. Novos argumentos
backend e title.
ac_plot_xray() — refinada com
theme_ac() + ac_palette(), facet_grid com
label do documento à esquerda, barras verticais mais espessas e
arredondadas.
Vignettes do site pkgdown reorganizadas em 3 blocos (“Comece por aqui”, “Pipeline qualitativo (LLMs)”, “Pipeline quantitativo”). “Análise de proposições” agora aparece como sub-item de “Codificação com LLMs”, esclarecendo a relação entre guia e estudo de caso.
Diagrama SVG do pipeline redesenhado: Etapas 5 e 6 em layout de duas linhas (título + funções empilhados) resolvendo vazamento de texto.
test-ac_ellmer_chat, test-ac_qual_report,
test-ac_qual_live,
test-ac_qual_code-live).Nova vignette replicabilidade.Rmd —
pipeline completo em 6 etapas (corpus → codebook → code + live → sample
→ reliability → report), com exemplo executável de
ac_qual_report().
Todas as vignettes usam
ac_clean(remove_stopwords = "pt") — antes top-terms e
keyness apareciam poluídos por artigos e preposições.
Vignettes lda.Rmd e sentimento.Rmd
reescritas com corpus real e chunks 100% executáveis (antes usavam
eval=FALSE + outputs falsos).
ac_plot_sentiment(type = "line"): conflito de escala
de cor resolvido (linha em cinza neutro, pontos coloridos por
sentimento).
.ac_ellmer_chat(): sempre usa dispatch direto ao
invés de delegar a ellmer::chat(), garantindo resolução
consistente de aliases (gemini → chat_google_gemini,
claude → chat_anthropic,
azure → chat_azure_openai,
bedrock → chat_aws_bedrock).
ac_qual_report() — gera relatório
de replicabilidade em Markdown ou HTML autocontido (bilíngue PT/EN),
documentando codebook completo, histórico de modificações, configuração
da LLM, distribuição de resultados, métricas de confiabilidade
(opcional) e referências metodológicas. Pronto para colar em
artigo/relatório.
ac_qual_code(live = ...) — novo
argumento com três modos:
"off" (padrão): sem live view;"terminal": barra de progresso com doc atual,
categoria, confiança e início do raciocínio a cada iteração (via
cli::cli_progress_bar);"shiny": janela Shiny em background com tabela
atualizando em tempo real (requer shiny e
callr em Suggests).Migrado o acesso ao ellmer para a nova API baseada
em chat_<provider>() (chat_anthropic(),
chat_groq(), chat_openai(), etc.). A função
ellmer::chat() foi removida em versões recentes do
ellmer; o novo helper interno
.ac_ellmer_chat() roteia strings no formato
"provider/model" para o dispatcher correto, mantendo
fallback para ellmer::chat() quando disponível
(retrocompatível).
ellmer movido de Imports para
Suggests: o pacote agora carrega o ellmer
apenas quando o usuário chama uma função qualitativa, reduzindo a
superfície de dependência para quem usa apenas os módulos
quantitativos.
Language: en-US adicionado ao
DESCRIPTION.inst/WORDLIST semeado com termos técnicos e nomes
próprios; teste de ortografia não-bloqueante em
tests/spelling.R.^vignettes$ removido do .Rbuildignore); as 6
vinhetas compilam sem rede/LLM (chunks LLM com
eval=FALSE).vignettes/introducao-acR.Rmd reescrita como tutorial
offline completo.Additional_repositories
(apontava para URL github.com, não aceita pela CRAN).+16 testes cobrindo I/O Excel
(ac_qual_export_for_review,
ac_qual_import_human, roundtrip com
tempfile()) e helpers internos de modelos
(.ac_models_db, .ac_score_models,
.ac_model_justification,
.ac_list_models_live).
Testes online de ac_qual_codebook_translate() e
ac_qual_codebook_hybrid() ganham skip_if()
defensivo para versões do ellmer sem
chat().
Total: 688 pass, 4 skips justificados.
R CMD check: 0 errors, 0 warnings, 1 note inofensiva
(clock).
ac_qual_codebook_hybrid() — enriquece definições de
categorias com referências bibliográficas buscadas via LLM, combinando
fundamento manual com ancora teórica induzida da literatura.
ac_qual_codebook_merge() — funde dois objetos
ac_codebook em um único, com controle de conflitos de nomes
(error, keep_first, keep_second,
rename_second).
ac_qual_codebook_translate() — traduz instruções,
definições e exemplos de um codebook para outro idioma via LLM
("pt" ↔︎ "en").
ac_qual_codebook_history() — retorna o histórico de
modificações de um ac_codebook (adições, remoções, merges,
traduções, enriquecimentos).
as_prompt() / as_prompt.ac_codebook() —
converte um ac_codebook em system prompt formatado para uso
direto com objetos Chat do ellmer, com suporte
a raciocínio estruturado (reasoning_length).
as_prompt.default() — método default com mensagem de
erro informativa para objetos que não são
ac_codebook.
Corrigido warning non-ASCII characters em
R/ac_qual_codebook.R: escapes \uXXXX agora
usados no código R; UTF-8 real mantido nos blocos roxygen.
Corrigido warning missing documentation entries:
todas as 5 novas funções do Bloco B agora têm blocos roxygen completos
com título, @param e @return.
Corrigido mismatch de documentação: check_overlap
adicionado ao .Rd de
ac_qual_codebook().
Corrigido vignettes/sentimento.Rmd:
eval=FALSE adicionado a todos os chunks que faziam download
externo, prevenindo falha no CI sem internet.
tests/testthat/test-ac_qual_codebook.R, cobrindo todas as
funções do Bloco B. Testes com LLM real usam
skip_if_offline() e skip_on_cran().README.md atualizado com tabela de funções de gestão
de codebook, referências completas (12 entradas) e bloco de citação com
ORCID e afiliação CEM-Cepid/USP.
vignettes/qualitativo-llm.Rmd reescrita com pipeline
completo do Bloco B: criação, enriquecimento, fusão, tradução, histórico
e geração de system prompt.
vignettes/analise-proposicoes.Rmd atualizada com
seção 3b demonstrando refinamento iterativo do codebook com as novas
funções.
_pkgdown.yml atualizado: seção “Codificacao
qualitativa via LLM” agora lista todas as 12 funções do módulo
qualitativo.