ml_research_tools.core

Core components for ML Research Tools.

class ml_research_tools.core.Config(logging=<factory>, redis=<factory>, llm_presets=<factory>)

Bases: object

Global application configuration.

Parameters:

• logging (LoggingConfig)

• redis (RedisConfig)

• llm_presets (LLMPresets)

classmethod from_dict(config_dict)

Create a Config object from a dictionary.

Parameters:

config_dict (Dict[str, Any]) – Dictionary containing configuration values.

Return type:

Config

Returns:

Config object.

property llm: LLMConfig

Backward compatibility property to get the default LLM config.

logging: LoggingConfig

redis: RedisConfig

llm_presets: LLMPresets

ml_research_tools.core.get_config(args=None)

Get configuration from file and command line arguments.

Parameters:

args (Optional[Namespace]) – Parsed command line arguments. If None, only uses the config file.

Return type:

Tuple[Config, Path]

Returns:

Config object.

class ml_research_tools.core.LLMConfig(base_url='https://api.openai.com/v1', model='gpt-3.5-turbo', max_tokens=None, temperature=0.01, top_p=1.0, retry_attempts=3, retry_delay=5, api_key=None, tier='standard')

Bases: object

LLM (Language Model) API configuration.

Parameters:

• base_url (str)

• model (str)

• max_tokens (int | None)

• temperature (float)

• top_p (float)

• retry_attempts (int)

• retry_delay (int)

• api_key (str | None)

• tier (str)

api_key: Optional[str] = None

base_url: str = 'https://api.openai.com/v1'

max_tokens: int | None = None

model: str = 'gpt-3.5-turbo'

retry_attempts: int = 3

retry_delay: int = 5

temperature: float = 0.01

tier: str = 'standard'

top_p: float = 1.0

class ml_research_tools.core.LLMPresets(default='standard', presets=<factory>)

Bases: object

Collection of LLM configurations with presets and tiering.

Parameters:

• default (str)

• presets (Dict[str, LLMConfig])

__post_init__()

Initialize with default presets if empty.

default: str = 'standard'

get_config(preset_name=None, tier=None)

Get an LLM configuration by name or tier.

Parameters:

• preset_name (Optional[str]) – Name of the preset to use (takes precedence over tier)

• tier (Optional[str]) – Tier of model to use (e.g., “standard”, “premium”)

Return type:

LLMConfig

Returns:

LLMConfig object

Raises:

ValueError – If no matching preset is found

presets: Dict[str, LLMConfig]

ml_research_tools.core.get_logger(name)

Get a logger with the specified name.

Parameters:

name (str) – Name of the logger.

Return type:

Logger

Returns:

Logger instance.

ml_research_tools.core.setup_logging(log_level, log_file=None)

Set up logging configuration.

Parameters:

• log_level (str) – Logging level.

• log_file (Optional[str]) – Path to log file. If None, only logs to console.

Return type:

None

class ml_research_tools.core.LLMClient(*, preset=None, tier=None, api_key=None, base_url=None, model=None, temperature=None, top_p=None, max_tokens=None, retry_attempts=None, retry_delay=None, config=None, redis_cache=None)

Bases: object

Client for interacting with Language Models with preset configurations and caching.

This class provides a unified interface for making LLM API calls with: - Configuration management (presets, tiers, parameter overrides) - Automatic retries with exponential backoff - Result caching - Simple and chat-based interfaces

config

The LLM configuration to use for API calls

Initialize an LLM client with the specified configuration.

Parameters:

• preset (Optional[str]) – Name of the preset configuration to use

• tier (Optional[str]) – Tier of model to use (e.g., “standard”, “premium”)

• api_key (Optional[str]) – API key override

• base_url (Optional[str]) – Base URL override

• model (Optional[str]) – Model name override

• temperature (Optional[float]) – Temperature override

• top_p (Optional[float]) – Top-p value override

• max_tokens (Optional[int]) – Max tokens override

• retry_attempts (Optional[int]) – Retry attempts override

• retry_delay (Optional[int]) – Retry delay override

• config (Union[Config, LLMConfig, LLMPresets, None]) – Configuration object (Config, LLMConfig, or LLMPresets)

• redis_cache (Optional[RedisCache]) – Redis cache instance for caching results

__init__(*, preset=None, tier=None, api_key=None, base_url=None, model=None, temperature=None, top_p=None, max_tokens=None, retry_attempts=None, retry_delay=None, config=None, redis_cache=None)

Initialize an LLM client with the specified configuration.

Parameters:

• preset (Optional[str]) – Name of the preset configuration to use

• tier (Optional[str]) – Tier of model to use (e.g., “standard”, “premium”)

• api_key (Optional[str]) – API key override

• base_url (Optional[str]) – Base URL override

• model (Optional[str]) – Model name override

• temperature (Optional[float]) – Temperature override

• top_p (Optional[float]) – Top-p value override

• max_tokens (Optional[int]) – Max tokens override

• retry_attempts (Optional[int]) – Retry attempts override

• retry_delay (Optional[int]) – Retry delay override

• config (Union[Config, LLMConfig, LLMPresets, None]) – Configuration object (Config, LLMConfig, or LLMPresets)

• redis_cache (Optional[RedisCache]) – Redis cache instance for caching results

call(messages, *, model=None, temperature=None, top_p=None, max_tokens=None, prefix='llm_chat', use_cache=True)

Call an LLM API with a complete chat history.

Parameters:

• messages (List[Message]) – List of chat messages

• model (Optional[str]) – Model name override

• temperature (Optional[float]) – Temperature override

• top_p (Optional[float]) – Top-p override

• max_tokens (Optional[int]) – Max tokens override

• prefix (str) – Prefix for cache keys

• use_cache (bool) – Whether to use caching for this call

Return type:

str

Returns:

The LLM response text

get_openai_client()

Get the raw OpenAI client.

Return type:

OpenAI

Returns:

The underlying OpenAI client instance

property model

Get the model name from the configuration.

simple_call(text, system_prompt, *, model=None, temperature=None, top_p=None, max_tokens=None, prefix='llm', use_cache=True)

Call an LLM with a simple system prompt + user text pattern.

Parameters:

• text (str) – The user text to process

• system_prompt (str) – Instructions for the LLM (system message)

• model (Optional[str]) – Model name override

• temperature (Optional[float]) – Temperature override

• top_p (Optional[float]) – Top-p override

• max_tokens (Optional[int]) – Max tokens override

• prefix (str) – Prefix for cache keys

• use_cache (bool) – Whether to use caching for this call

Return type:

str

Returns:

The LLM response text

ml_research_tools.core.create_llm_client(*, preset=None, tier=None, api_key=None, base_url=None, model=None, temperature=None, top_p=None, max_tokens=None, retry_attempts=None, retry_delay=None, config=None, redis_cache=None)

Create an LLMClient instance with the specified configuration.

This is a factory function that creates an LLMClient with the appropriate configuration.

Parameters:

• preset (Optional[str]) – Name of the preset configuration to use

• tier (Optional[str]) – Tier of model to use (e.g., “standard”, “premium”)

• api_key (Optional[str]) – API key override

• base_url (Optional[str]) – Base URL override

• model (Optional[str]) – Model name override

• temperature (Optional[float]) – Temperature override

• top_p (Optional[float]) – Top-p value override

• max_tokens (Optional[int]) – Max tokens override

• retry_attempts (Optional[int]) – Retry attempts override

• retry_delay (Optional[int]) – Retry delay override

• config (Union[Config, LLMConfig, LLMPresets, None]) – Configuration object (Config, LLMConfig, or LLMPresets)

• redis_cache (Optional[RedisCache]) – Redis cache instance

Return type:

LLMClient

Returns:

An initialized LLMClient instance

ml_research_tools.core.generate_completion_params(*, llm_client, **additional_params)

Generate parameters for completion API calls based on configuration.

This function resolves LLM configuration based on presets/tiers and returns a dictionary of parameters suitable for passing to the OpenAI completion API calls.

Return type:

Dict[str, Any]

Returns:

Dictionary of parameters for OpenAI API calls

Parameters:

• llm_client (LLMClient)

• additional_params (Any)

class ml_research_tools.core.ServiceProvider(config)

Bases: object

A service provider that manages dependencies and services.

This class implements the service locator pattern, allowing services to be registered and retrieved. It supports lazy initialization of services and singleton instances.

Initialize the service provider with a configuration.

Parameters:

config (Config) – The application configuration

__init__(config)

Initialize the service provider with a configuration.

Parameters:

config (Config) – The application configuration

get(name)

Get a service by name.

Parameters:

name (str) – The name of the service to retrieve

Return type:

Any

Returns:

The service instance

Raises:

KeyError – If the service is not registered

get_config()

Get the configuration object.

Return type:

Config

Returns:

The configuration object

get_or_create(name, factory)

Get a service by name, or create it if it doesn’t exist.

Parameters:

• name (str) – The name of the service to retrieve

• factory (Callable[[], TypeVar(T)]) – A callable that creates the service if needed

Return type:

TypeVar(T)

Returns:

The service instance

get_typed(name, expected_type)

Get a service by name with type checking.

Parameters:

• name (str) – The name of the service to retrieve

• expected_type (Type[TypeVar(T)]) – The expected type of the service

Return type:

TypeVar(T)

Returns:

The service instance

Raises:

TypeError – If the service is not of the expected type

has(name)

Check if a service is registered.

Parameters:

name (str) – The name of the service to check

Return type:

bool

Returns:

True if the service is registered, False otherwise

register(name, instance)

Register a service instance with the provider.

Parameters:

• name (str) – The name to register the service under

• instance (Any) – The service instance

Return type:

None

register_factory(name, factory)

Register a factory function for lazy initialization of a service.

Parameters:

• name (str) – The name to register the service under

• factory (Callable[[], Any]) – A callable that creates the service when needed

Return type:

None

ml_research_tools.core.register_common_services(service_provider, default_llm_preset=None, default_llm_tier=None)

Register common services with the service provider.

Parameters:

service_provider (ServiceProvider) – The service provider to register services with

Return type:

None

ml_research_tools.core.create_redis_cache(config)

Create a Redis cache instance from configuration.

Parameters:

config (Config) – Application configuration

Return type:

Optional[RedisCache]

Returns:

Redis cache instance or None if Redis is disabled

ml_research_tools.core.create_default_llm_client(config, redis_cache=None)

Create a default LLM client from configuration.

Parameters:

• config (Config) – Application configuration

• redis_cache (Optional[RedisCache]) – Optional Redis cache for caching results

Return type:

LLMClient

Returns:

LLM client instance

ml_research_tools.core.setup_services(config, default_llm_preset=None, default_llm_tier=None)

Set up a service provider with common services.

Parameters:

config (Config) – Application configuration

Return type:

ServiceProvider

Returns:

Configured service provider

Submodules

• BaseTool
• LoggingConfig
• RedisConfig
• LLMConfig
• LLMPresets
• Config
• load_config_file()
• add_config_args()
• get_config()
• Message
• get_llm_config()
• LLMClient
• create_llm_client()
• generate_completion_params()
• get_console()
• setup_logging()
• get_logger()
• register_common_services()
• create_redis_cache()
• create_default_llm_client()
• setup_services()
• ServiceProvider