% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/semantic_analysis.R
\name{analyze_sentiment_llm}
\alias{analyze_sentiment_llm}
\title{LLM-based Sentiment Analysis}
\usage{
analyze_sentiment_llm(
  texts,
  doc_names = NULL,
  provider = c("openai", "gemini"),
  model = NULL,
  api_key = NULL,
  batch_size = 5,
  include_explanation = FALSE,
  verbose = TRUE
)
}
\arguments{
\item{texts}{Character vector of texts to analyze.}

\item{doc_names}{Optional character vector of document names (default: text1, text2, ...).}

\item{provider}{AI provider to use: "openai" (default) or "gemini".}

\item{model}{Model name. If NULL, uses provider defaults: "gpt-4.1-mini" (OpenAI),
"gemini-2.5-flash-lite" (Gemini).}

\item{api_key}{API key for OpenAI or Gemini. If NULL, uses environment variable.}

\item{batch_size}{Number of texts to process per API call (default: 5).
Larger batches are more efficient but may hit token limits.}

\item{include_explanation}{Logical, if TRUE includes natural language explanation
for each sentiment classification (default: FALSE).}

\item{verbose}{Logical, if TRUE prints progress messages (default: TRUE).}
}
\value{
A list containing:
\describe{
\item{document_sentiment}{Data frame with document-level sentiment scores}
\item{summary_stats}{Summary statistics of the analysis}
\item{model_used}{Model name used for analysis}
\item{provider}{AI provider used}
}
}
\description{
Analyzes sentiment using Large Language Models (OpenAI or Gemini).
Provides nuanced sentiment understanding including sarcasm detection,
mixed emotions, and contextual interpretation that lexicon-based methods miss.

Requests use temperature 0, which makes outputs near-deterministic but
not fully reproducible across runs or model versions; record the returned
\code{model_used} field when reporting results.
}
\details{
LLM-based sentiment analysis offers several advantages over lexicon methods:
\itemize{
\item Understands context and nuance
\item Detects sarcasm and irony
\item Handles mixed emotions
\item Works across domains without retraining
}
}
\examples{
if (interactive()) {
  abstracts <- TextAnalysisR::SpecialEduTech$abstract[1:5]

  sentiment_openai <- analyze_sentiment_llm(abstracts, provider = "openai")

  sentiment_gemini <- analyze_sentiment_llm(abstracts, provider = "gemini",
                                             include_explanation = TRUE)
}
}
\concept{sentiment}
