Class HuggingFaceModel

java.lang.Object

uno.anahata.asi.agi.provider.AbstractModel

uno.anahata.asi.openai.compatible.OpenAiCompatibleModel

uno.anahata.asi.huggingface.HuggingFaceModel

public class HuggingFaceModel
extends OpenAiCompatibleModel

A specialized model instance that encapsulates its own metadata discovery from the Hugging Face Hub.

Fetches and parses architectural specifications (config.json), chat templates and tokenizer settings (tokenizer_config.json), and sampling parameters (generation_config.json) in parallel, enriching generation requests with explicit max_tokens limits.

Author:

anahata

Field Summary

Fields

Modifier and Type	Field	Description
private com.fasterxml.jackson.databind.JsonNode	generationConfig	The raw JSON from the model's 'generation_config.json', used to extract default sampling parameters like temperature and top-p.
private com.fasterxml.jackson.databind.JsonNode	hubConfig	The raw JSON from the model's 'config.json', containing architectural details and token limits.
private com.fasterxml.jackson.databind.JsonNode	tokenizerConfig	The raw JSON from the model's 'tokenizer_config.json', used to discover chat templates and tool support markers.

Fields inherited from class AbstractModel

defaultTemperature, defaultTopK, defaultTopP, description, enabled, MARKUP_TABLE_HEADER, provider, rawDescription, supportedActions, supportedResponseModalities, tokenizerType

Modifier and Type	Field	Description
protected Float	defaultTemperature	The default temperature setting for this model, or null if unspecified.
protected Integer	defaultTopK	The default Top-K setting for this model, or null if unspecified.
protected Float	defaultTopP	The default Top-P setting for this model, or null if unspecified.
protected String	description	Human-readable description of this model's capabilities and limitations.
protected boolean	enabled	Whether this model is enabled and offered in model selectors and tool listings.
static final String	MARKUP_TABLE_HEADER	Markdown table header for model listings.
protected AbstractAiProvider	provider	The parent AI provider that owns this model instance.
protected String	rawDescription	The raw description or raw JSON representation of the model as received from the remote API endpoint.
protected List<String>	supportedActions	The list of API actions supported by this model (e.g.
protected List<ResponseModality>	supportedResponseModalities	The list of response modalities supported by this model (e.g., TEXT, IMAGE, AUDIO, VIDEO).
protected TokenizerType	tokenizerType	The optional model-specific tokenizer.

Constructor Summary

Constructors

Constructor	Description
HuggingFaceModel(HuggingFaceProvider provider, String modelId, String displayName)	Constructs a new Hugging Face model instance.

Method Summary

Modifier and Type	Method	Description
String	buildHubHtmlDescription()	Builds a rich HTML view combining architecture, tokenizer class, and deep-inspected sampling parameters.
protected void	enrichPayload(com.fasterxml.jackson.databind.node.ObjectNode payload, GenerationRequest request)	Hook for subclasses to add or modify payload parameters before sending the request.
private com.fasterxml.jackson.databind.JsonNode	fetchHubJson(String filename, String apiKey)	Helper to fetch a JSON file from the Hugging Face Hub's main branch.
HuggingFaceProvider	getProvider()	Returns the parent OpenAiChatCompletionsProvider instance owning this model.
void	inspect(String apiKey)	Performs deep inspection of this model by fetching its configuration files from the Hugging Face Hub sequentially in a single thread, using a pre-resolved API key.

Methods inherited from class OpenAiCompatibleModel

buildParametersNode, countTokens, countTokens, countTokens, countTokens, createModelMessage, createResponseWithEstimatedUsage, generateContent, generateContentStream, getAvailableServerTools, getDefaultServerTools, getEndpoint, getToolDeclarationJson, isSupportsBatchEmbeddings, isSupportsCachedContent, isSupportsContentGeneration, isSupportsEmbeddings, isSupportsFunctionCalling, preparePayload

Modifier and Type	Method	Description
protected com.fasterxml.jackson.databind.node.ObjectNode	buildParametersNode(AbstractTool<?,?> tool, boolean strict)	Builds the JSON Schema parameters node for a tool.
int	countTokens(byte[] data, String mimeType)	Counts the number of tokens consumed by raw binary data based on its MIME type and model-specific multimodal billing rules.
int	countTokens(String text)	Counts the number of tokens in the given text string using this model's specific tokenizer.
int	countTokens(AbstractToolCall<?,?> toolCall)	Counts the number of tokens consumed by the given tool call in the context window.
int	countTokens(AbstractToolResponse<?> toolResponse)	Counts the number of tokens consumed by the given tool execution response.
OpenAiCompatibleModelMessage	createModelMessage(Agi agi)	Instantiates an OpenAI-compatible message container.
protected OpenAiCompatibleResponse	createResponseWithEstimatedUsage(Agi agi, String modelId, String jsonPayload, String historyJson, int estimatedPromptTokens, int estimatedCompletionTokens, TokenizerType tokenizerType)	Creates an OpenAiResponse with estimated usage metadata when the API doesn't provide it.
Response	generateContent(GenerationRequest request)	The core method for interacting with an AI model.
void	generateContentStream(GenerationRequest request, StreamObserver<Response<? extends AbstractModelMessage>> observer)	Generates content asynchronously using token streaming.
List<ServerTool>	getAvailableServerTools()	Gets the list of server-side tools available for this model.
List<ServerTool>	getDefaultServerTools()	Gets the list of server-side tools that should be enabled by default for this model.
protected String	getEndpoint()	Gets the relative endpoint URL for Chat Completion requests.
String	getToolDeclarationJson(AbstractTool<?,?> tool, RequestConfig config)	Gets the provider-specific JSON representation of a tool's declaration.
boolean	isSupportsBatchEmbeddings()	Checks if this model supports batch embedding generation.
boolean	isSupportsCachedContent()	Checks if this model supports content caching.
boolean	isSupportsContentGeneration()	Checks if this model supports content generation.
boolean	isSupportsEmbeddings()	Checks if this model supports single content embedding generation.
boolean	isSupportsFunctionCalling()	Checks if this model supports native function calling (tools).
protected com.fasterxml.jackson.databind.node.ObjectNode	preparePayload(GenerationRequest request, boolean stream)	Prepares the final JSON request payload combining system instructions, history, tools, and temperature.

Methods inherited from class AbstractModel

getModelId, getProviderId, getTokenizerType, hasDiscrepancy, isRegistered, matches, persist, remove, resetFromApi, toMarkupRow, toSafeModelFileName, toString

Modifier and Type	Method	Description
abstract String	getModelId()	Gets the unique identifier for this model (e.g., "models/gemini-1.5-pro").
final String	getProviderId()	Delegate method to get the id of this models provider.
TokenizerType	getTokenizerType()	Gets the effective tokenizer type for this model.
boolean	hasDiscrepancy()	Checks if this locally registered model entity has different configuration values compared to its corresponding cached API model in the provider.
boolean	isRegistered()	Checks if this model is registered in its parent provider's master persisted models list.
boolean	matches(Pattern queryPattern, Set<ResponseModality> targetModalities)	Checks if this model matches a search query (regex or substring) AND all target response modalities.
void	persist()	Persists this model entity directly to disk in its parent provider's models directory (~/.anahata/asi/<provider>/models/<model_id>.kryo).
void	remove()	Deletes the persisted .kryo file for this model from disk and removes it from its parent provider.
void	resetFromApi()	Resets this locally registered model entity from its cached API model counterpart and persists changes to disk.
String	toMarkupRow()	Formats this model as a Markdown table row for model listing and discovery tools.
static String	toSafeModelFileName(String modelId)	Converts a model ID into a safe filename with .kryo extension.
String	toString()	Returning the display name

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

hubConfig

private com.fasterxml.jackson.databind.JsonNode hubConfig

The raw JSON from the model's 'config.json', containing architectural details and token limits.

tokenizerConfig

private com.fasterxml.jackson.databind.JsonNode tokenizerConfig

The raw JSON from the model's 'tokenizer_config.json', used to discover chat templates and tool support markers.

generationConfig

private com.fasterxml.jackson.databind.JsonNode generationConfig

The raw JSON from the model's 'generation_config.json', used to extract default sampling parameters like temperature and top-p.

Constructor Details

HuggingFaceModel

public HuggingFaceModel(HuggingFaceProvider provider,
 String modelId,
 String displayName)

Constructs a new Hugging Face model instance.

Parameters:

provider - The owning HF provider.

modelId - The full repo ID.

displayName - The display name.

Method Details

getProvider

public HuggingFaceProvider getProvider()

Returns the parent OpenAiChatCompletionsProvider instance owning this model.

Returns the typed parent HuggingFaceProvider owning this model.

Overrides:

getProvider in class OpenAiCompatibleModel

Returns:

The OpenAI-compatible provider instance.

inspect

public void inspect(String apiKey)

Performs deep inspection of this model by fetching its configuration files from the Hugging Face Hub sequentially in a single thread, using a pre-resolved API key.

Parameters:

apiKey - The pre-resolved API key to avoid lock contention with the provider.

fetchHubJson

private com.fasterxml.jackson.databind.JsonNode fetchHubJson(String filename,
 String apiKey)

Helper to fetch a JSON file from the Hugging Face Hub's main branch.

Parameters:

filename - The config filename (e.g. 'config.json').

apiKey - The pre-resolved Bearer token.

Returns:

The parsed JSON or null if not found/error.

enrichPayload

protected void enrichPayload(com.fasterxml.jackson.databind.node.ObjectNode payload,
 GenerationRequest request)

Hook for subclasses to add or modify payload parameters before sending the request.

Implementation details: Ensures that max_tokens is populated in the request payload so Hugging Face router does not truncate generations at its low server default.

Overrides:

enrichPayload in class OpenAiCompatibleModel

Parameters:

payload - The JSON payload being constructed.

request - The generation request.

buildHubHtmlDescription

public String buildHubHtmlDescription()

Builds a rich HTML view combining architecture, tokenizer class, and deep-inspected sampling parameters.

Returns:

The formatted HTML summary string.