# acR 0.3.3

## Compatibilidade

* 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.

## Nova funcionalidade

* **`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).

## Bug fixes -- modulo qualitativo (pipeline LLM)

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.

# acR 0.3.2

## Novidades

* **`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).
* **Nova vignette** — `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.
* **Documentacao** — README, `_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`.
* **Polimento de documentacao** — reescrita de `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()`.
* **Generalizacao do keyness** — README, vignette `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.
* **Cobertura de testes** subiu de ~55% (0.3.1) para ~66%. Testes novos
  em `ac_cluster.R` (67% -> 91%), `ac_qual_codebook.R` (43% -> 48%) e
  `ac_qual_reliability.R`.

## Adequacao CRAN (correcoes de resubmissao)

* `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.
* Removido uso de `<<-` em `.ac_report_build_md()` (`ac_qual_report.R`):
  o buffer de linhas agora vive em um `environment()` local.
* Removidas escritas ao `.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).

# acR 0.3.1

## Ajustes

* **`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()`.

## Testes

* Nova cobertura para `ac_export()`, `ac_qual_irr()`, `theme_ac()`,
  `ac_palette()` e `is_ac_corpus()`.

# acR 0.3.0

## Novas funcionalidades — Visualização e Tema

* **`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.

## Menu e navegação

* 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.

## Testes e cobertura

* +87 assertions em 4 arquivos novos (`test-ac_ellmer_chat`,
  `test-ac_qual_report`, `test-ac_qual_live`, `test-ac_qual_code-live`).
* Cobertura global: **55% → ~64%**.
* Total agora: 741+ testes pass, 5 skips justificados.

## Documentação

* 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).

## Bug fixes

* `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`).

# acR 0.2.2

## Novas funcionalidades — Replicabilidade e transparência

* **`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`).

## Compatibilidade

* 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.

## Preparação para CRAN

* `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`.
* Vinhetas voltam a ser empacotadas no tarball (`^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.
* Removida a linha inválida `Additional_repositories` (apontava para URL
  `github.com`, não aceita pela CRAN).

## Testes

* +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).

# acR 0.2.1

## Novas funções

* `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`.

## Correções

* 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.

## Testes

* 63 testes passando em `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()`.

## Documentação

* `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.

# acR 0.2.0

* Versão inicial com módulos qualitativo e quantitativo completos.
