TEmbeddings

Source: source/classes/tembeddings.prg

TEmbeddings is FiveWin's class for generating and comparing text embeddings (vector representations of text). It supports both HuggingFace (via the Inference API feature-extraction pipeline) and OpenAI embeddings API. Embeddings convert text into high-dimensional vectors that capture semantic meaning, enabling operations like semantic similarity search, clustering, and classification.

Architecture

flowchart LR subgraph "FiveWin Application" A[TEmbeddings] B[Distance Calculation] end subgraph "Provider" C[HuggingFace
Inference API] D[OpenAI
Embeddings API] end A -->|"HuggingFace model"| C A -->|"OpenAI model"| D A --> B

Key DATA Members

DATA	Type	Default	Description
`cModel`	Character	`"sentence-transformers/all-MiniLM-L6-v2"`	Embeddings model name. HuggingFace model ID or OpenAI embedding model.
`cKey`	Character		API key. Reads `HF_API_KEY` first, then `OPENAI_API_KEY`.
`aEmbeddings`	Array		The embedding vector returned by the API (array of numeric values)
`cResponse`	Character		Raw JSON response from the API
`cUrl`	Character		API endpoint URL (auto-set based on model prefix)
`nError`	Numeric	`0`	curl error code
`nHttpCode`	Numeric	`0`	HTTP response status code

Methods

Method	Description
`New( cModel, cKey )`	Create a TEmbeddings instance. Defaults to HuggingFace MiniLM model. Reads API key from `HF_API_KEY` then `OPENAI_API_KEY` env vars if not provided.
`GetEmbeddings( cText )`	Generate embeddings for the given text. Stores the vector in `aEmbeddings`. Returns the raw vector array.
`Distance( aVector, lCosine )`	Compute distance between `aEmbeddings` and another vector. Default uses cosine distance. Set `lCosine := .F.` for Euclidean distance.
`DistanceFrom( oEmbeddings )`	Compute distance to another TEmbeddings object by comparing their `aEmbeddings` vectors.
`End()`	Clean up the libcurl handle.

Example: Semantic Similarity

#include "FiveWin.ch"

function Main()

   local oE1 := TEmbeddings():New()
   local oE2 := TEmbeddings():New()
   local oE3 := TEmbeddings():New()
   local nSimilarity1, nSimilarity2

   // Generate embeddings for three phrases
   oE1:GetEmbeddings( "I feel very well" )
   oE2:GetEmbeddings( "How are you?" )
   oE3:GetEmbeddings( "I saw Peter" )

   // Cosine distance: lower = more similar
   nSimilarity1 := oE1:DistanceFrom( oE2 )  // Low distance (similar topic)
   nSimilarity2 := oE1:DistanceFrom( oE3 )  // High distance (different topic)

   QOut( "Similarity between 'feel well' and 'How are you':", nSimilarity1 )
   QOut( "Similarity between 'feel well' and 'saw Peter':", nSimilarity2 )

   // Using the OPERATOR "-" syntax (equivalent to DistanceFrom)
   ? oE1 - oE2   // Same as oE1:DistanceFrom( oE2 )
   ? oE1 - oE3   // Same as oE1:DistanceFrom( oE3 )

   oE1:End()
   oE2:End()
   oE3:End()

return nil

Example: Euclidean Distance

#include "FiveWin.ch"

function Main()

   local oE1 := TEmbeddings():New()
   local oE2 := TEmbeddings():New()

   oE1:GetEmbeddings( "Machine learning is fascinating" )
   oE2:GetEmbeddings( "Deep learning and AI are interesting" )

   // Euclidean distance instead of cosine
   ? "Euclidean distance:", oE1:Distance( oE2:aEmbeddings, .F. )

   oE1:End()
   oE2:End()

return nil

Notes

The default model is sentence-transformers/all-MiniLM-L6-v2 from HuggingFace. Changing the model name switches between providers automatically: if the model name contains "openai" or "text-embedding-", it uses the OpenAI endpoint; otherwise it uses HuggingFace.
When using HuggingFace, set the HF_API_KEY environment variable. When using OpenAI, set OPENAI_API_KEY.
The Distance() method supports two metrics: cosine distance (default) ranges from 0 (identical) to 1 (completely different); Euclidean distance measures the straight-line distance between vectors.
The OPERATOR "-" allows intuitive syntax: oE1 - oE2 computes the distance between two TEmbeddings objects. This is equivalent to calling oE1:DistanceFrom( oE2 ).
Both vectors must have the same length. The Distance() method returns -1 on error.