Heratio Framework API Reference

AiGatewayClient
in package

AI Gateway Client — canonical, fleet-compliant entry point for AI calls.

Every application AI call (embeddings, chat/RAG generation, model probes) MUST route through the AHG AI gateway at https://ai.theahg.co.za/ai/v1/... — never directly to a GPU node's inference port. The gateway enforces the API key + gateway scope + per-key quota, logs every call for metering, and does DB-driven node selection / failover. See the host-wide gateway rule.

This client deliberately rides the gateway's Ollama passthrough (/ai/v1/ollama/...), which is the live, KM-proven surface:

  • embeddings : POST /ai/v1/ollama/api/embeddings {"model","prompt"}
  • chat : POST /ai/v1/ollama/api/chat {"model","messages",...}
  • generate : POST /ai/v1/ollama/api/generate {"model","prompt",...}
  • health : GET /ai/v1/health

It uses HttpClientService, whose SSRF guard blocks private IPs — so a misconfiguration pointing back at a node IP (192.168.x) fails closed rather than silently bypassing the gateway.

Configuration (ahg_ai_settings, feature='gateway'), with safe fallbacks to the existing feature='general' api_key so it works the moment a gateway key is provisioned, without a schema change: base_url default https://ai.theahg.co.za/ai/v1 api_key (falls back to feature='general' api_key) timeout default 120 (seconds) embedding_model default nomic-embed-text chat_model default qwen3:14b

Tags
author

The Archive and Heritage Group

Table of Contents

Constants

DEFAULT_BASE_URL  = 'https://ai.theahg.co.za/ai/v1'
DEFAULT_CHAT_MODEL  = 'qwen3:14b'
DEFAULT_EMBEDDING_MODEL  = 'nomic-embed-text'

Methods

__construct()  : mixed
chat()  : array{success: bool, text: string, model: string, error: ?string, raw: ?array}
Chat / RAG completion via the gateway's Ollama passthrough.
embed()  : array<string|int, float>|null
Generate an embedding vector for a single piece of text.
embedBatch()  : array<int, array<string|int, float>|null>
Embed several texts. Ollama's embeddings endpoint is single-input, so this loops; a null entry marks a failed item (callers can filter).
fromSettings()  : self
Build a client from ahg_ai_settings. feature='gateway' is authoritative; api_key falls back to feature='general' (the existing key location) so the client is usable the moment any gateway-scoped key is configured.
generate()  : array<string|int, mixed>
Single-prompt generation convenience over chat().
getChatModel()  : string
getEmbeddingModel()  : string
isAvailable()  : bool
Liveness probe. GET /ai/v1/health (no auth required upstream).
isConfigured()  : bool
True when an API key is present. Callers should check this and fall back to their legacy path (or degrade gracefully) when the gateway key has not been provisioned yet.
translate()  : array<string, mixed>|null
Translate text via the gateway's worker route (POST /ai/v1/translate).
translateLanguages()  : array<string, mixed>|null
List supported translation languages (GET /ai/v1/translate/languages).
visionGenerate()  : array{success: bool, text: string, model: string, error: ?string, raw: ?array}
Vision generation via the gateway's Ollama passthrough — POST /ai/v1/ollama/api/generate with base64 image(s). Native Ollama "generate" shape; returns the same contract as chat().

Constants

DEFAULT_BASE_URL

public mixed DEFAULT_BASE_URL = 'https://ai.theahg.co.za/ai/v1'

DEFAULT_EMBEDDING_MODEL

public mixed DEFAULT_EMBEDDING_MODEL = 'nomic-embed-text'

Methods

__construct()

public __construct([array<string|int, mixed> $config = [] ]) : mixed
Parameters
$config : array<string|int, mixed> = []

chat()

Chat / RAG completion via the gateway's Ollama passthrough.

public chat(array<string|int, mixed> $messages[, array<string|int, mixed> $options = [] ]) : array{success: bool, text: string, model: string, error: ?string, raw: ?array}
Parameters
$messages : array<string|int, mixed>

[['role'=>'system','content'=>'...'], ['role'=>'user','content'=>'...']]

$options : array<string|int, mixed> = []

model, temperature, max_tokens (num_predict), num_ctx, timeout

Return values
array{success: bool, text: string, model: string, error: ?string, raw: ?array}

embed()

Generate an embedding vector for a single piece of text.

public embed(string $text[, string|null $model = null ]) : array<string|int, float>|null
Parameters
$text : string
$model : string|null = null
Return values
array<string|int, float>|null —

The embedding vector, or null on failure / no key.

embedBatch()

Embed several texts. Ollama's embeddings endpoint is single-input, so this loops; a null entry marks a failed item (callers can filter).

public embedBatch(array<string|int, string> $texts[, string|null $model = null ]) : array<int, array<string|int, float>|null>
Parameters
$texts : array<string|int, string>
$model : string|null = null
Return values
array<int, array<string|int, float>|null>

fromSettings()

Build a client from ahg_ai_settings. feature='gateway' is authoritative; api_key falls back to feature='general' (the existing key location) so the client is usable the moment any gateway-scoped key is configured.

public static fromSettings() : self
Return values
self

generate()

Single-prompt generation convenience over chat().

public generate(string $prompt[, string|null $system = null ][, array<string|int, mixed> $options = [] ]) : array<string|int, mixed>
Parameters
$prompt : string
$system : string|null = null
$options : array<string|int, mixed> = []
Return values
array<string|int, mixed>

getEmbeddingModel()

public getEmbeddingModel() : string
Return values
string

isAvailable()

Liveness probe. GET /ai/v1/health (no auth required upstream).

public isAvailable() : bool
Return values
bool

isConfigured()

True when an API key is present. Callers should check this and fall back to their legacy path (or degrade gracefully) when the gateway key has not been provisioned yet.

public isConfigured() : bool
Return values
bool

translate()

Translate text via the gateway's worker route (POST /ai/v1/translate).

public translate(string $text, string $sourceLang, string $targetLang[, int|null $maxLength = null ]) : array<string, mixed>|null
Parameters
$text : string
$sourceLang : string
$targetLang : string
$maxLength : int|null = null
Return values
array<string, mixed>|null —

Decoded response (worker shape: {success, translated, error}), or null on failure / no key.

translateLanguages()

List supported translation languages (GET /ai/v1/translate/languages).

public translateLanguages() : array<string, mixed>|null
Return values
array<string, mixed>|null —

Decoded response, or null on failure / no key.

visionGenerate()

Vision generation via the gateway's Ollama passthrough — POST /ai/v1/ollama/api/generate with base64 image(s). Native Ollama "generate" shape; returns the same contract as chat().

public visionGenerate(string $prompt, array<string|int, string> $base64Images[, string|null $model = null ][, array<string|int, mixed> $options = [] ]) : array{success: bool, text: string, model: string, error: ?string, raw: ?array}
Parameters
$prompt : string
$base64Images : array<string|int, string>

raw base64 (no "data:" prefix)

$model : string|null = null
$options : array<string|int, mixed> = []

temperature, seed, num_predict (→ max_tokens), timeout

Return values
array{success: bool, text: string, model: string, error: ?string, raw: ?array} 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results