TGrok (xAI)

Source: source/classes/tgrok.prg

TGrok is FiveWin's client for the xAI Grok API. It provides access to Grok language models with support for text chat, streaming responses, and image analysis (including both local file uploads and image URLs). The class uses Harbour's hb_curl library for HTTPS communication with the xAI API endpoint. API keys can be passed explicitly or read from the XAI_API_KEY environment variable.

Architecture

flowchart LR subgraph "FiveWin Application" A[TGrok] end subgraph "libcurl" B[hb_curl
HTTPS] end subgraph "xAI API" C["api.x.ai/v1/chat/completions"] end A --> B B --> C

Key DATA Members

DATA	Type	Default	Description
`cKey`	Character	`""`	xAI API key. Reads `XAI_API_KEY` env var if empty.
`cModel`	Character	`"grok-3-latest"`	Grok model to use
`cPrompt`	Character		Last prompt sent to the API
`cResponse`	Character		Raw JSON response from the API
`cUrl`	Character		API endpoint URL (auto-set to xAI endpoint)
`hCurl`	Handle		libcurl easy handle
`nError`	Numeric	`0`	curl error code (`HB_CURLE_OK` = 0 = success)
`nHttpCode`	Numeric	`0`	HTTP response status code
`nTemperature`	Numeric	`0.5`	Sampling temperature (0.0 - 2.0)

Methods

Method	Description
`New( cKey, cModel )`	Create a TGrok instance. If `cKey` is empty, reads `XAI_API_KEY` from the environment. Initializes the libcurl handle.
`Send( cPrompt )`	Send a text prompt to the Grok API. Stores the raw JSON response in `cResponse`.
`SendStream( cPrompt, bCallback )`	Send a prompt with streaming enabled. The `bCallback` codeblock receives each data chunk as it arrives.
`SendImage( cImageFile, cPrompt )`	Send a local image file with a text prompt for vision analysis. Encodes the image as base64.
`SendImageURL( cImageUrl, cPrompt )`	Send an image URL with a text prompt for vision analysis.
`GetValue()`	Extract the text response from the JSON in `cResponse`. Returns the message content or error info.
`End()`	Clean up the libcurl handle. Automatically called by the destructor.

Example: Text Chat

#include "FiveWin.ch"

function Main()

   local oAI := TGrok():New( "your-xai-key-here" )

   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: Streaming Response

#include "FiveWin.ch"

function Main()

   local oAI := TGrok():New( "your-xai-key-here" )
   local cBuffer := ""

   oAI:SendStream( "Write a short story about AI.", ;
      { |cChunk| cBuffer += cChunk, QOut( cChunk ) } )

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

   oAI:End()

return nil

Example: Image Analysis

#include "FiveWin.ch"

function Main()

   local oAI := TGrok():New( "your-xai-key-here", "grok-3-latest" )

   // Analyze a local image
   oAI:SendImage( "C:\photos\chart.png", "Describe this chart in detail." )

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

   // Analyze an image by URL
   oAI:SendImageURL( "https://example.com/photo.jpg", ;
      "What objects are in this photo?" )

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

   oAI:End()

return nil

Notes

TGrok requires the hb_curl library. Include #include "hbcurl.ch" for curl constants.
SSL verification is disabled by default (HB_CURLOPT_SSL_VERIFYPEER = .F.) for compatibility.
The API key can be read from the XAI_API_KEY environment variable by passing an empty key to New().
GetValue() navigates the JSON response path choices[1].message.content to extract the text. If an error occurred, it returns the error object instead.
The SendImage() method reads the file from disk, encodes it as base64, and sends it inline with the request.