Skip to contents

Generate themes by grouping codes into AI-judged clusters

Source: R/13_themes.R
generate_themes_iterative.Rd

Dispatches to the configured theme algorithm. The default (algorithm = "v2") is an embedding-free, multi-pass AI clustering: the model sees all codes at once, proposes a partition into clusters, and on each further pass either groups clusters again or declares the partition converged. There are no hardcoded pass counts or size thresholds, and clustering depth is the AI's dynamic call (C1). Codes are grouped, never combined into new codes (C2); theme and subtheme names are assigned in a dedicated labeling pass after convergence. The earlier algorithm = "v1" – code-name embeddings, hierarchical agglomerative clustering (ward.D2), and an AI-judged dendrogram walk – has been removed; pinning algorithm = "v1" (or any value other than "v2") is honored as v2 with a one-time deprecation notice.

Usage

generate_themes_iterative(
  coding_state,
  provider,
  config = list(),
  learning_context = NULL,
  research_focus = "",
  concepts = NULL,
  audit_log = NULL,
  response_cache = NULL,
  live_tracker = NULL,
  methodology_override = NULL
)

Arguments

coding_state

ProgressiveCodingState

provider

AIProvider object

config

Theme config section (most legacy knobs are now ignored; the algorithm has no merge-pass parameters)

learning_context

Optional LearningContext

research_focus

Research focus string

concepts

Optional character vector of core research concepts

audit_log

Optional AuditLog for recording each AI decision

response_cache

Optional ResponseCache for raw response capture

live_tracker

Optional LiveTracker. When provided, the cluster snapshot is rewritten after every AI decision so a researcher can cat outputs/<run>/live/code_to_cluster.json mid-run.

methodology_override

Optional character. When non-NULL, replaces the provider's default methodology rules in every internal ai_complete call for this walk. Used by the emergent-themes pass to inject the Mode 3 inductive variant; NULL for normal Mode 2 + Mode 3 deductive callers.

Value

ThemeSet S3 object. Its merge_history records the multi-pass partition history (per-pass clusters + the AI's decisions) for replay / audit.

Details

The function name retains its earlier form for back-compat with the single production caller (R/18_pipeline.R) and existing test fixtures. A future release may rename it to generate_themes().