LLM Wrappers

The LLM Wrappers are a set of classes that provide a unified interface for different LLMs.

They are designed to be used with the Toponymy API and provide a consistent way to interact with different LLMs.

Local LLM Wrappers

These wrappers are designed to work with locally running LLMs.

class toponymy.llm_wrappers.HuggingFaceNamer(model: str, llm_specific_instructions=None, callback: Callable[[dict[str, Any]], None] | None = None, **kwargs)

Bases: LLMWrapper

Provides access to Huggingface models from Huggingface Hub with the Toponymy framework. For more information on Huggingface, see https://huggingface.co/docs/transformers/index. You will need the transformers library installed to make use of this wrapper, and you will need a model available on Huggingface Hub. This wrapper allows you to use models hosted on Huggingface Hub, rather than requiring a service API key. However, this does require you to have access to the model and suitable hardware to run it.

class toponymy.llm_wrappers.LlamaCppNamer(model_path: str, llm_specific_instructions=None, callback: Callable[[dict[str, Any]], None] | None = None, **kwargs)

Bases: LLMWrapper

Provides Access to LlamaCpp models with the Toponymy framework. For more information on LlamaCpp, see https://github.com/abetlen/llama-cpp-python. You will need llamma-cpp-python installed to make use of this wrapper, and you will need a local model file downloaded to use it. This Wrapper allows you to use local models, rather than requiring a service API key. However this does require you to have the model and suitable hardware to run it.

Note: This wrapper does not support system prompts, as LlamaCpp does not support them.

property supports_system_prompts: bool: Check if the LLM wrapper supports system prompts. By default, it does. Override in subclasses if not supported.

LLM Service Wrappers

class toponymy.llm_wrappers.OpenAINamer(api_key: str, model: str = 'gpt-4o-mini', base_url: str = None, http_client: Client | None = None, llm_specific_instructions=None, callback: Callable[[dict[str, Any]], None] | None = None)

Bases: LLMWrapper

Provides access to OpenAI’s LLMs with the Toponymy framework. For more information on OpenAI, see https://platform.openai.com/docs/models/overview. You will need an OpenAI API key to use this wrapper. The default model is “gpt-4o-mini”, which is a sufficiently powerful model for generating topic names and clusters, but inexpensive in terms of dollars per token. You can use more advanced models, but they have diminishing returns for this task, and are more expensive.

FAIL_FAST_EXCEPTIONS: tuple = (<class 'openai.AuthenticationError'>, <class 'openai.PermissionDeniedError'>, <class 'openai.BadRequestError'>, <class 'openai.NotFoundError'>, <class 'openai.UnprocessableEntityError'>)

class toponymy.llm_wrappers.CohereNamer(api_key: str, model: str = 'command-r-08-2024', base_url: str = None, httpx_client: Client | None = None, llm_specific_instructions=None, callback: Callable[[dict[str, Any]], None] | None = None)

Bases: LLMWrapper

Provides access to Cohere’s LLMs with the Toponymy framework. For more information on Cohere, see https://docs.cohere.com/docs/llm-overview. You will need a Cohere API key to use this wrapper. The default model is “command-r-08-2024”, which is a sufficiently powerful to do a good job of generating topic names and clusters, but inexpensive in terms of dollars per token. You can use more advanced models, but they have diminishing returns for this task, and are more expensive.

class toponymy.llm_wrappers.AnthropicNamer(api_key: str, model: str = 'claude-haiku-4-5-20251001', llm_specific_instructions=None, callback: Callable[[dict[str, Any]], None] | None = None)

Bases: LLMWrapper

Provides access to Anthropic’s LLMs with the Toponymy framework. For more information on Anthropic, see https://docs.anthropic.com/docs/overview. You will need an Anthropic API key to use this wrapper. The default model is “claude-haiku-4-5-20251001”, which is the smallest model available, but is generally more than sufficient for generating topic names and clusters. You can use more advanced models, but they have diminishing returns for this task, and are more expensive.

FAIL_FAST_EXCEPTIONS: tuple = (<class 'anthropic.AuthenticationError'>, <class 'anthropic.PermissionDeniedError'>, <class 'anthropic.BadRequestError'>, <class 'anthropic.NotFoundError'>)

class toponymy.llm_wrappers.AzureAINamer(api_key: str, endpoint: str, model: str, llm_specific_instructions=None, callback: Callable[[dict[str, Any]], None] | None = None)

Bases: LLMWrapper

Provides access to the Azure AI Foundry LLMs with the Toponymy framework. For more information on Azure AI, see https://learn.microsoft.com/en-us/azure/ai-services/overview. You will need an Azure API key for your Foundry model to use this wrapper. You will need to provide both the endpoint, and the model name per the instiated model on AI Foundry. For more information on creating models with Azure AI Foundry, see https://learn.microsoft.com/en-us/azure/ai-services/ai-foundry/create-models.