TGemini (Google Gemini)

Source: source/classes/tgemini.prg

TGemini is FiveWin's client for the Google Gemini API. It provides access to Google's Gemini family of models with support for text chat, streaming responses, image and file analysis (PNG, JPEG, PDF, TXT, CSV, PRG), and file uploads to Google's file service. The class uses Harbour's hb_curl library for HTTPS communication. API keys can be passed explicitly or read from the GEMINI_API_KEY environment variable.

Architecture

flowchart LR subgraph "FiveWin Application" A[TGemini] end subgraph "libcurl" B[hb_curl
HTTPS] end subgraph "Google Gemini API" C["generativelanguage.googleapis.com/v1beta/models"] end A --> B B --> C

Key DATA Members

DATA	Type	Default	Description
`cKey`	Character	`""`	Gemini API key. Reads `GEMINI_API_KEY` env var if empty.
`cModel`	Character	`"gemini-2.0-flash"`	Gemini model identifier
`cResponse`	Character		Raw JSON response from the API
`cUrl`	Character	`"https://generativelanguage.googleapis.com/v1beta/models"`	API base endpoint
`cUploadUrl`	Character	`"https://generativelanguage.googleapis.com/upload/v1beta/files"`	File upload endpoint
`hCurl`	Handle		libcurl easy handle
`nError`	Numeric	`0`	curl error code (0 = `HB_CURLE_OK`)
`nHttpCode`	Numeric	`0`	HTTP response status code
`nTemperature`	Numeric	`0`	Sampling temperature (0.0 - 1.0)

Methods

Method	Description
`New( cKey, cModel )`	Create a TGemini instance. Reads `GEMINI_API_KEY` from environment if `cKey` is empty. Initializes the libcurl handle.
`Send( uContent, [cPrompt], [bCallback] )`	Core method accepting flexible input. `uContent` can be a text string, a file path, or an array of file paths. `cPrompt` supplies optional text alongside files. `bCallback` enables streaming via codeblock. Returns raw JSON.
`GetValue()`	Extract the response text from `cResponse` JSON. Navigates path `candidates[1].content.parts[1].text`. Returns error info on failure.
`GetTokens( cBuffer )`	Parse a streaming response chunk and extract the text token. Handles both array-style and object-style JSON chunks.
`UploadFile( cFileName, lDeleteAfter )`	Upload a file to Google's file API. Returns the file URI string. Optionally deletes `cFileName` when `lDeleteAfter` is `.T.`.
`End()`	Clean up the libcurl handle. Called automatically by the destructor.

Example: Text Chat

#include "FiveWin.ch"

function Main()

   local oAI := TGemini():New( "your-gemini-api-key" )

   oAI:Send( "What are the key features of the Harbour language?" )

   if oAI:nError == 0 .and. oAI:nHttpCode == 200
      MsgInfo( oAI:GetValue() )
   else
      MsgStop( "Error: " + oAI:cResponse )
   endif

   oAI:End()

return nil

Example: Image / File Analysis

#include "FiveWin.ch"

function Main()

   local oAI := TGemini():New( "your-gemini-api-key" )

   // Single image
   oAI:Send( "C:\photos\chart.png", "Describe this chart." )

   if oAI:nError == 0
      MsgInfo( oAI:GetValue() )
   endif

   // Multi-file analysis
   oAI:Send( { "C:\docs\invoice.pdf", "C:\docs\photo.jpg" }, ;
      "Compare and summarize." )

   if oAI:nError == 0
      MsgInfo( oAI:GetValue() )
   endif

   oAI:End()

return nil

Example: Streaming Response

#include "FiveWin.ch"

function Main()

   local oAI := TGemini():New( "your-gemini-api-key" )
   local cFull := ""

   // Pass a codeblock as 3rd parameter to activate streaming
   oAI:Send( "Write a short story about AI.", , ;
      { |cChunk| cFull += cChunk, QOut( cChunk ) } )

   if oAI:nError == 0
      MsgInfo( "Complete:" + CRLF + cFull )
   endif

   oAI:End()

return nil

Notes

Requires the hb_curl library. Include #include "hbcurl.ch" for curl constants.
SSL verification is disabled by default (HB_CURLOPT_SSL_VERIFYPEER = .F.).
Send() automatically detects files by their extension and base64-encodes them for inline submission. Supported types: PNG, JPEG, PDF, TXT, CSV, PRG, CH.
Streaming is enabled by passing a codeblock as the third parameter to Send(). The endpoint switches from :generateContent to :streamGenerateContent.
UploadFile() uses Google's dedicated file upload service and returns a URI for later reference in multi-turn conversations.