# How to Configure CreativeMath for Different LLM Models: A Complete Guide

> Learn to configure CreativeMath for various LLM models by modifying config.json and extending model logic in API or local model files for seamless integration.

- Repository: [Junyi Ye/creativemath](https://github.com/junyiye/creativemath)
- Tags: how-to-guide
- Published: 2026-03-05

---

**Configure CreativeMath for different LLM models by updating the `model_version` mapping in [`config.json`](https://github.com/junyiye/creativemath/blob/main/config.json) and optionally extending the conditional logic in [`src/models/api_models.py`](https://github.com/junyiye/creativemath/blob/main/src/models/api_models.py) or [`src/models/local_models.py`](https://github.com/junyiye/creativemath/blob/main/src/models/local_models.py) to support new API or local Hugging Face models.**

CreativeMath is an open-source mathematical reasoning framework that supports multiple large language model backends. Whether you need to configure CreativeMath for different LLM models from cloud providers like OpenAI and Anthropic or run specialized local models via Hugging Face, the architecture uses a centralized `ModelWrapper` class to abstract model loading and generation.

## Understanding the ModelWrapper Architecture

The `ModelWrapper` class in [`src/models/model_loader.py`](https://github.com/junyiye/creativemath/blob/main/src/models/model_loader.py) serves as the central abstraction for all LLM interactions. When instantiated, it checks whether the requested model name belongs to the **API-model list** (such as `claude-3-opus` or `gpt-4`) or is a **local model** (such as `Deepseek-math-7b-rl`).

This design allows you to switch between cloud and local inference without changing your application code—only the model name passed to `ModelWrapper` needs to change.

## Configuration File Structure

CreativeMath reads all model settings from [`config.json`](https://github.com/junyiye/creativemath/blob/main/config.json) at runtime. The wrapper imports the configuration at load time via `from config import config`, meaning changes to [`config.json`](https://github.com/junyiye/creativemath/blob/main/config.json) take effect immediately on the next program run.

The three critical sections for LLM configuration are:

- **`model_version`** – Maps friendly names (e.g., `"gpt-4"`) to actual provider identifiers (e.g., `"gpt-4-turbo-preview"`).
- **`api_keys`** – Stores authentication tokens for cloud providers (OpenAI, Anthropic, Google, etc.).
- **`model_config`** – Contains generation hyperparameters such as `max_tokens`, `temperature`, `top_p`, and `top_k` used by both API and local modules.

## API vs Local Model Loading

CreativeMath handles cloud and local inference through separate modules, each loaded conditionally based on the model name provided to `ModelWrapper`.

### API-Based Models (OpenAI, Anthropic, Google)

API models are loaded by the `load_api_model` function in [`src/models/api_models.py`](https://github.com/junyiye/creativemath/blob/main/src/models/api_models.py). This function reads the model-specific ID from [`config.json`](https://github.com/junyiye/creativemath/blob/main/config.json) → `model_version` and the required API key from [`config.json`](https://github.com/junyiye/creativemath/blob/main/config.json) → `api_keys`.

The module creates client objects (such as `Anthropic`, `OpenAI`, or `google.generativeai`) and later uses `generate_api_response` to send chat requests. Generation settings are pulled from the global `model_config` dictionary defined at the top of [`api_models.py`](https://github.com/junyiye/creativemath/blob/main/api_models.py).

### Local Hugging Face Models

Local models are loaded by `load_local_model` in [`src/models/local_models.py`](https://github.com/junyiye/creativemath/blob/main/src/models/local_models.py). This function pulls the Hugging Face model identifier from the same `model_version` mapping and constructs a tokenizer and model via the 🤗 Transformers library.

Generation is performed by `generate_local_response`, which adapts the call pattern for each model’s specific requirements, such as chat templates or special EOS tokens. Like the API module, [`local_models.py`](https://github.com/junyiye/creativemath/blob/main/local_models.py) reads global generation parameters from `model_config` at the top of the file.

## Step-by-Step Configuration Guide

To add or switch to a different LLM in CreativeMath, you only need to update [`config.json`](https://github.com/junyiye/creativemath/blob/main/config.json) and optionally extend the provider-specific logic.

### Adding an API Model

Suppose you want to add support for a hypothetical `"llama-3-8b-instruct"` model hosted on a new provider API.

1. **Update [`config.json`](https://github.com/junyiye/creativemath/blob/main/config.json)** to map the friendly name to the provider identifier:

```json
{
  "model_version": {
    "gpt-4": "gpt-4-turbo-preview",
    "claude-3-opus": "claude-3-opus-20240229",
    "llama-3-8b-instruct": "meta-llama/Meta-Llama-3-8B-Instruct"
  },
  "api_keys": {
    "OPENAI_API_KEY": "sk-...",
    "ANTHROPIC_API_KEY": "sk-...",
    "LLAMA_API_KEY": "your-llama-key-here"
  }
}

```

2. **Extend [`src/models/api_models.py`](https://github.com/junyiye/creativemath/blob/main/src/models/api_models.py)** to recognize the new model name and initialize the appropriate client:

```python
elif model_name == "llama-3-8b-instruct":
    client = OpenAI(
        api_key=api_keys["LLAMA_API_KEY"],
        base_url="https://api.llama.com"
    )

```

Now `ModelWrapper("llama-3-8b-instruct")` will route requests to your new provider automatically.

### Adding a Local Model

To add a local Hugging Face model such as Microsoft’s Phi-3-mini:

1. **Update [`config.json`](https://github.com/junyiye/creativemath/blob/main/config.json)** with the Hugging Face model identifier:

```json
{
  "model_version": {
    "phi-3-mini": "microsoft/phi-3-mini-4k-instruct"
  }
}

```

2. **Update [`src/models/local_models.py`](https://github.com/junyiye/creativemath/blob/main/src/models/local_models.py)** to handle the specific loading requirements:

```python
if model_name == "phi-3-mini":
    tokenizer = AutoTokenizer.from_pretrained(model_id)
    model = AutoModelForCausalLM.from_pretrained(
        model_id,
        torch_dtype=torch.bfloat16,
        device_map="auto",
    )

```

The `generate_local_response` function will automatically apply the global `model_config` settings (temperature, max tokens, etc.) to your new local model.

## Runtime Model Selection

You can switch between configured models at runtime without restarting your application, as long as you create a new `ModelWrapper` instance:

```python
from src.models.model_loader import ModelWrapper

# Use GPT-4 via OpenAI API

wrapper = ModelWrapper("gpt-4")
api_response = wrapper.generate_response("Solve the equation x^2 + 5x + 6 = 0")

# Switch to a local mathematical reasoning model

wrapper = ModelWrapper("Deepseek-math-7b-rl")
local_response = wrapper.generate_response("Prove that the sum of angles in a triangle is 180 degrees")

```

The wrapper reads the `model_version` mapping from [`config.json`](https://github.com/junyiye/creativemath/blob/main/config.json) to determine whether to invoke `load_api_model` or `load_local_model`, ensuring the correct backend is used for each query.

## Key Files Reference

| File | Role |
|------|------|
| [`src/models/model_loader.py`](https://github.com/junyiye/creativemath/blob/main/src/models/model_loader.py) | Central `ModelWrapper` class that routes requests to API or local backends |
| [`src/models/api_models.py`](https://github.com/junyiye/creativemath/blob/main/src/models/api_models.py) | Loads cloud clients (OpenAI, Anthropic, Google) and handles `generate_api_response` |
| [`src/models/local_models.py`](https://github.com/junyiye/creativemath/blob/main/src/models/local_models.py) | Loads Hugging Face transformers and handles `generate_local_response` |
| [`src/config.py`](https://github.com/junyiye/creativemath/blob/main/src/config.py) | Imports and exposes the `config` dictionary from [`config.json`](https://github.com/junyiye/creativemath/blob/main/config.json) at runtime |
| [`config.json`](https://github.com/junyiye/creativemath/blob/main/config.json) | User-editable mappings for `model_version`, `api_keys`, and `model_config` |

## Summary

- **Centralized configuration** for CreativeMath lives in [`config.json`](https://github.com/junyiye/creativemath/blob/main/config.json), which maps friendly model names to provider identifiers via the `model_version` key.
- **ModelWrapper** in [`src/models/model_loader.py`](https://github.com/junyiye/creativemath/blob/main/src/models/model_loader.py) automatically selects API or local backends based on the model name provided.
- **API models** require entries in `api_keys` and conditional logic in [`src/models/api_models.py`](https://github.com/junyiye/creativemath/blob/main/src/models/api_models.py) to initialize provider-specific clients.
- **Local models** require Hugging Face identifiers in `model_version` and loading logic in [`src/models/local_models.py`](https://github.com/junyiye/creativemath/blob/main/src/models/local_models.py) to handle tokenizers and model weights.
- **Global generation settings** (temperature, max tokens, top-p) are controlled via `model_config` in [`config.json`](https://github.com/junyiye/creativemath/blob/main/config.json) and apply to both API and local inference.

## Frequently Asked Questions

### What configuration file does CreativeMath use to manage LLM settings?

CreativeMath uses [`config.json`](https://github.com/junyiye/creativemath/blob/main/config.json) located in the repository root to manage all LLM settings. This file contains three critical sections: `model_version` for mapping friendly names to provider identifiers, `api_keys` for authentication tokens, and `model_config` for generation hyperparameters like temperature and max tokens. The configuration is loaded at import time via [`src/config.py`](https://github.com/junyiye/creativemath/blob/main/src/config.py), so changes take effect on the next program run without requiring code modifications.

### Can I use both API and local models simultaneously in CreativeMath?

Yes, you can use both API and local models simultaneously by creating separate `ModelWrapper` instances for each model type. The `ModelWrapper` class in [`src/models/model_loader.py`](https://github.com/junyiye/creativemath/blob/main/src/models/model_loader.py) determines whether to use API or local backends based on the model name provided during instantiation. You can alternate between cloud providers like OpenAI or Anthropic and local Hugging Face models such as `Deepseek-math-7b-rl` simply by passing different model names to new wrapper instances.

### How do I add a custom local model to CreativeMath?

To add a custom local model, first add an entry to the `model_version` section in [`config.json`](https://github.com/junyiye/creativemath/blob/main/config.json) mapping a friendly name to the Hugging Face model identifier. Then modify [`src/models/local_models.py`](https://github.com/junyiye/creativemath/blob/main/src/models/local_models.py) to add a conditional branch in `load_local_model` that initializes the tokenizer and model with any specific parameters required (such as `torch_dtype` or `device_map`). The `generate_local_response` function will automatically apply global generation settings from `model_config` to your new model.

### Where are the API keys stored in CreativeMath?

API keys are stored in the `api_keys` section of [`config.json`](https://github.com/junyiye/creativemath/blob/main/config.json). This section uses key-value pairs where the key identifies the provider (such as `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`) and the value contains the actual authentication token. The `load_api_model` function in [`src/models/api_models.py`](https://github.com/junyiye/creativemath/blob/main/src/models/api_models.py) reads these keys when initializing provider-specific clients, ensuring that sensitive credentials are centralized in the configuration file rather than hardcoded in the source code.