% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rhetorical_moves.R
\name{classify_rhetorical_moves}
\alias{classify_rhetorical_moves}
\title{Classify Rhetorical Moves in Scientific Text}
\usage{
classify_rhetorical_moves(
  text,
  api_key = NULL,
  model = "2.5-flash",
  use_llm = TRUE,
  batch_size = 20
)
}
\arguments{
\item{text}{Named list of sections (from \code{split_into_sections()}) or a
single character string. Section names are used to select the appropriate
rhetorical move taxonomy.}

\item{api_key}{Character or NULL. Google Gemini API key. If NULL, uses the
\code{GEMINI_API_KEY} environment variable.}

\item{model}{Character. Gemini model version. Default is "2.5-flash".}

\item{use_llm}{Logical. If TRUE (default), uses Gemini LLM for classification
in addition to rule-based methods. Set to FALSE for rule-based only.}

\item{batch_size}{Integer. Number of sentences per Gemini API call. Default is 20.}
}
\value{
A list with class \code{"rhetorical_move_analysis"} containing:
\itemize{
\item \code{sentences}: Tibble with sentence-level classification
(sentence_id, section, text, position_pct, move, step, confidence, method)
\item \code{move_blocks}: Tibble with aggregated consecutive move blocks
(block_id, section, move, step, start_sentence, end_sentence,
n_sentences, text_preview, avg_confidence)
\item \code{summary}: List with move distribution, step distribution,
flow pattern, sections analyzed, total sentences, and method breakdown
}
}
\description{
Identifies and classifies rhetorical moves (Swales CARS model and extensions)
at the sentence level in scientific papers. Supports Introduction (CARS model),
Literature Review, and Discussion/Conclusion sections.

Uses a hybrid approach: rule-based classification via cue phrase dictionaries,
optionally enhanced with LLM classification via Google Gemini API.
}
\details{
The function processes the following section types:
\itemize{
\item \strong{Introduction}: Uses Swales' CARS (Create a Research Space) model
with 3 moves: Establishing a territory, Establishing a niche, Occupying the niche
\item \strong{Literature Review / Background / Related Work}: Uses 3 moves:
Establishing context, Reviewing prior work, Evaluating prior work
\item \strong{Discussion / Conclusion}: Uses 3 moves:
Consolidating results, Evaluating the study, Looking forward
}

Sections matching "Results", "Findings", "References", "Appendix", or
"Acknowledgments" are automatically excluded.
}
\examples{
\dontrun{
# From a PDF
text <- pdf2txt_auto("paper.pdf")
sections <- split_into_sections(text)
moves <- classify_rhetorical_moves(sections)

# View sentence-level results
moves$sentences

# View aggregated blocks
moves$move_blocks

# View summary
moves$summary

# Rule-based only (no API needed)
moves <- classify_rhetorical_moves(sections, use_llm = FALSE)
}

}
