Skip to contents

artgemini

Environment Variables

artgemini is configured entirely through environment variables. Set these before loading the package.

Required

Optional (with defaults)

  • ART_GEMINI_MODEL (default: gemini-3-pro-preview) Model to use for requests. Specify unprefixed model IDs; the package prepends models/ internally.

    Available models: | Model | Use Case | |——-|———-| | gemini-3-pro-preview | Multimodal, good balance of quality/speed (default) | | gemini-3-pro | Production multimodal | | gemini-2.5-pro | Maximum context window (1M tokens) | | gemini-2.5-flash | Fastest, lower cost |

    Model override: Use the ml parameter in any function to override the default:

    gemini_chat("Hello", ml = "gemini-2.5-flash")

    Validation: The package validates model IDs against an internal allowlist. Invalid models produce an error listing allowed values.

  • ART_GEMINI_BASE_URL (default: https://generativelanguage.googleapis.com/v1beta)
    Gemini API base URL. Change only if using a proxy or custom endpoint.

  • ART_GEMINI_TTL_SEC (default: package-defined)
    Default cache TTL in seconds for gemini_cache_create(). Override per-request via ttl_seconds parameter.

  • ART_GEMINI_TIMEOUT (default: package-defined) Default HTTP request timeout in seconds. Override per-request via timeout parameter.

  • ART_GEMINI_MAX_OUTPUT_TOKENS (default: 8192) Default maxOutputTokens cap sent to the Gemini generateContent API. Increase this if structured outputs (JSON schema) are being truncated (you may see finishReason="MAX_TOKENS" in the error). Override per-request via genconf = list(maxOutputTokens = 16384). Must be an integer >= 16.

Setting Environment Variables

In R session:

Sys.setenv(
  ART_GEMINI_KEY = "your-api-key",
  ART_GEMINI_MODEL = "gemini-2.5-flash",
  ART_GEMINI_MAX_OUTPUT_TOKENS = "16384"
)

In .Renviron file (persistent across sessions):

ART_GEMINI_KEY=your-api-key
ART_GEMINI_MODEL=gemini-2.5-flash
ART_GEMINI_MAX_OUTPUT_TOKENS=16384

Note: All function documentation and examples assume these environment variables are properly configured. See individual function help pages for parameter-level overrides (e.g., ml parameter).

Quick Example 

library(artgemini)

# Basic chat
response <- gemini_chat("Explain what makes Impressionism unique.", temp = 0.7)
print(response)

# Analyze artwork image
description <- gemini_describe_image("path/to/artwork.png")
print(description)

# Note: Artwork analysis moved to artcurator package
# See: https://docs.artalytics.dev/r/artcurator/

What is artgemini?

artgemini is an opinionated wrapper around Google’s Gemini generateContent endpoint, providing:

  • Text chat with configurable models, temperature, and thinking modes
  • Vision for image analysis with automatic base64 encoding
  • Tool support including Google Search grounding, code execution, and custom function calling
  • Conversation continuation with client-side history management
  • Context caching for efficient repeated queries against large payloads

See the Quickstart and Advanced Workflow vignettes for detailed usage.

Key Features

Thinking Mode (Gemini 3 only)

The max_think parameter enables extended reasoning on Gemini 3 models:

gemini_chat("Complex problem...", ml = "gemini-3-pro-preview", max_think = TRUE)
  • max_think = TRUE: Maps to thinkingLevel = "high" for complex reasoning
  • max_think = FALSE (default): Maps to thinkingLevel = "low" for faster responses
  • Ignored on non-Gemini-3 models (gemini-2.5-pro, gemini-2.5-flash)

Context Caching

Cache large payloads for repeated queries:

cache <- gemini_cache_create(
  userdata = large_data,
  displayName = "my-cache"  # Optional human-friendly label
)
gemini_chat_cached("Question?", cache = cache$name)

Important: - Minimum size: ~4096 estimated tokens (smaller payloads error before API call) - displayName: Optional metadata set at creation only; returned on get/list but not usable for lookup (use name/ID instead) - TTL: Default 12 hours; override via ttl_seconds or ART_GEMINI_TTL_SEC

Multi-Candidate Responses

By default, artgemini returns only the first candidate text. For multiple alternatives:

  1. Use gemini-2.5-flash or gemini-2.5-pro (Gemini 3 preview models may not support candidateCount > 1)
  2. Call the API directly with candidateCount in generationConfig
  3. Parse the candidates array from the response

See the Candidate Responses vignette for details.

Package structure and prompt workflow

  • R/ holds all code. Low-level API logic lives in R/gemini-api.R; env helpers in R/utils.R; prompt utilities in R/prompts.R.
  • inst/prompts/ stores plain-text prompt templates. Each file must carry a PROMPT_VERSION: vx.y line. Update wording here, not in code; render_prompt() will pick up the new version automatically.
  • Adding a prompt: drop <name>.txt into inst/prompts/ with a version tag; use render_prompt("<name>") in your function; add a short test that loads it.

What endpoint is used?

All calls hit Google’s POST /{model}:generateContent (REST v1beta). Docs: https://ai.google.dev/api/generate-content

Request payload includes: - contents (user or system+user turns) - generationConfig (temperature, thinkingConfig, responseMimeType) - tools (Google Search, code execution, custom functions) - safetySettings (optional) - system_instruction (for system prompts) - cachedContent (when reusing a cache via gemini_chat_cached)

Not implemented: Streaming responses, files API, embeddings, text-to-image, audio modes.

Limitations

  • Single system instruction: Gemini accepts one system_instruction; multiple system messages will error (combine them upstream)
  • Minimum cache size: Explicit caching requires ~4096 estimated tokens; smaller payloads error before API call
  • First candidate only: gemini_generate() returns only the first candidate text; use direct API calls for multi-candidate
  • No retries: Error handling surfaces status/context but does not retry automatically
  • Vision resizing: Images are resized to 1000px width (PNG format) to reduce payload size

Documentation

Development

For AI agent instructions and coding standards, see AGENTS.md.

devtools::test()
devtools::check()

General Best Practice Notes

  • Temperature: Use temp = 0 for structured/deterministic outputs; higher values (0.7) for creative generation
  • Model selection: Use gemini-2.5-flash for speed/cost; gemini-2.5-pro for large context; gemini-3-pro-preview for multimodal
  • Thinking mode: Enable max_think = TRUE only for complex reasoning (Gemini 3 models only)
  • Health checks: Run artgemini_health_check() before batch operations
  • Timeouts: Set explicit timeout values for production pipelines
  • Conversation continuation: Pass previous response directly to gemini_continue() - history is preserved automatically
  • Long/structured outputs: If responses are truncated (finishReason=MAX_TOKENS), increase ART_GEMINI_MAX_OUTPUT_TOKENS (default 8192) or pass genconf = list(maxOutputTokens = 16384) per-request

Proprietary - Do Not Distribute