Configuration & Provider Registry

config.config

Script

config.py

Purpose

Unified configuration management for Hillstar.

Handles: - Loading default registry from provider_registry.default.json - Merging user overrides from user config - Validating provider configurations against registry schema - Compliance checks for provider configurations - Managing user-level API keys and settings

Author: Julen Gamboa <julen.gamboa.ds@gmail.com>

Created

2026-02-07

Last Edited

2026-02-22

class config.config.HillstarConfig

Bases: object

Unified configuration management for Hillstar.

Combines registry-based provider configuration with user-level API key management. Provides methods for: - Loading and merging configurations - Validating provider configurations - Managing user API keys and settings - Checking compliance requirements

USER_CONFIG_DIR = PosixPath('/home/runner/.hillstar')

USER_CONFIG_FILE = PosixPath('/home/runner/.hillstar/provider_registry.json')

USER_OVERRIDE_PATH = PosixPath('/home/runner/.hillstar/provider_registry.json')

__init__()

Initialize HillstarConfig with user and default configurations.

set_provider_key(provider, api_key)

Store API key for a provider.

Parameters:

• provider (str) – Provider name (e.g., ‘anthropic’, ‘openai’)

• api_key (str) – API key value

Raises:

ValueError – If provider name or api_key is empty

Return type:

None

get_provider_key(provider)

Retrieve API key for a provider.

Parameters:

provider (str) – Provider name

Returns:

API key if configured, None otherwise

Return type:

str | None

list_configured_providers()

List providers that have API keys configured.

Returns:

List of provider names with keys configured

Return type:

list[str]

list_missing_providers(all_providers=None)

List providers not yet configured.

Parameters:

• all_providers (list[str] | None) – List of provider names to check against.

• None (If)

• list. (uses default provider)

Returns:

List of provider names without keys configured

Return type:

list[str]

validate_key(provider, api_key)

Validate that an API key is non-empty and reasonably formatted.

This is basic validation (non-empty, reasonable length). Full validation (API call) deferred to runtime.

Parameters:

• provider (str) – Provider name

• api_key (str) – API key to validate

Returns:

True if key passes basic validation, False otherwise

Return type:

bool

save_config()

Write configuration to ~/.hillstar/provider_registry.json.

Creates the directory if it doesn’t exist.

Raises:

IOError – If unable to write file

Return type:

None

load_config()

Load configuration from ~/.hillstar/provider_registry.json.

Creates empty config if file doesn’t exist.

Return type:

None

get_merged_registry()

Get the complete registry with user overrides applied.

Return type:

ProviderRegistry

validate_provider_config(provider, config)

Validate provider configuration against registry.

Parameters:

• provider (str) – Provider name

• config (dict[str, Any]) – Provider configuration dict

Returns:

List of validation error messages (empty if valid)

Return type:

list[str]

check_compliance(provider, config)

Check compliance requirements for a provider.

Parameters:

• provider (str) – Provider name

• config (dict[str, Any]) – Provider configuration

Returns:

bool, issues: List[str])

Return type:

(is_compliant

get_provider_info(provider)

Get full provider configuration from registry.

Parameters:

provider (str)

Return type:

dict[str, Any] | None

list_available_providers()

List all available providers from registry.

Return type:

list[str]

list_available_models(provider)

List all available models for a provider.

Parameters:

provider (str)

Return type:

list[str]

merge_configs(user_config, workflow_config)

Merge user configuration with workflow configuration.

Workflow configuration takes precedence over user config.

Parameters:

• user_config (dict[str, Any]) – User provider configuration overrides

• workflow_config (dict[str, Any]) – Workflow-specific model configuration

Returns:

Merged configuration dictionary

Return type:

dict[str, Any]

config.model_selector

config.provider_registry

Script

provider_registry.py

Path

python/hillstar/config/provider_registry.py

Purpose

Provider Registry: Central registry for LLM providers, models, and compliance rules.

Provides a ProviderRegistry class that loads provider configurations from JSON and provides lookup methods for model selection, cost estimation, and compliance verification. Supports package defaults with user overrides for customization.

Inputs

Provider registry JSON files (default + optional user override)

Outputs

Registry instance with lookup methods for providers, models, and compliance

Assumptions

• Default registry file exists at package location

• User override follows same schema as default

Parameters

None (per-query)

Failure Modes

• Missing default registry FileNotFoundError

• Malformed JSON JSONDecodeError

• Invalid provider/model Returns None

Author: Julen Gamboa <julen.gamboa.ds@gmail.com>

Created

2026-02-14

Last Edited

2026-02-14 (initial implementation)

class config.provider_registry.ProviderRegistry

Bases: object

Load and query the provider registry with fallback to user overrides.

The registry is loaded from: 1. Package default: python/hillstar/config/provider_registry.default.json 2. User override: ~/.hillstar/provider_registry.json (optional)

DEFAULT_REGISTRY_PATH = PosixPath('/home/runner/work/hillstar-orchestrator/hillstar-orchestrator/config/provider_registry.default.json')

USER_OVERRIDE_PATH = PosixPath('/home/runner/.hillstar/provider_registry.json')

__init__(custom_registry_path=None)

Initialize the provider registry.

Parameters:

• custom_registry_path (str | None) – Optional path to a custom registry file.

• provided (If)

• override. (this takes precedence over both default and user)

property version: str

Get registry version.

property last_updated: str

Get last update timestamp.

list_providers(provider_type=None)

List available providers, optionally filtered by type.

Parameters:

provider_type (str | None) – Optional filter: “cloud_api”, “local”, “local_proxy”

Returns:

List of provider names

Return type:

List[str]

get_provider(provider_name)

Get full provider configuration.

Parameters:

provider_name (str)

Return type:

Dict[str, Any] | None

get_provider_compliance(provider_name)

Get compliance rules for a provider.

Parameters:

provider_name (str)

Return type:

Dict[str, Any] | None

get_model(provider_name, model_id)

Get model configuration.

Parameters:

• provider_name (str) – Provider identifier (e.g., “anthropic”)

• model_id (str) – Model identifier (e.g., “claude-opus-4-6”)

Returns:

Model configuration dict or None

Return type:

Dict[str, Any] | None

find_models(capabilities=None, max_tier=None, provider_type=None, require_ollama=None)

Find models matching criteria.

Parameters:

• capabilities (List[str] | None) – List of required capabilities (e.g., [“coding”, “reasoning”])

• max_tier (str | None) – Maximum cost tier (e.g., “cheap”, “standard”)

• provider_type (str | None) – Filter by provider type (e.g., “cloud_api”, “local”)

• require_ollama (bool | None) – If True, only return models requiring Ollama

Returns:

List of matching model configs with provider context

Return type:

List[Dict[str, Any]]

get_cheapest_model(capabilities=None, provider_preference=None)

Get the cheapest model matching criteria, respecting provider preference.

Parameters:

• capabilities (List[str] | None) – Required capabilities

• provider_preference (List[str] | None) – Preferred provider order (e.g., [“anthropic”, “openai”])

Returns:

Tuple of (provider, model_id, model_config) or None

Return type:

Tuple[str, str, Dict[str, Any]] | None

estimate_cost(provider_name, model_id, input_tokens, output_tokens)

Estimate cost for a model call.

Parameters:

• provider_name (str) – Provider identifier

• model_id (str) – Model identifier

• input_tokens (int) – Number of input tokens

• output_tokens (int) – Number of output tokens

Returns:

Estimated cost in USD

Return type:

float

get_fallback_chain(complexity, provider_preference=None)

Get provider fallback chain for a complexity level.

Parameters:

• complexity (str) – Task complexity (“simple”, “moderate”, “complex”, “critical”)

• provider_preference (List[str] | None) – Preferred providers (highest priority first)

Returns:

List of providers in fallback order

Return type:

List[str]

is_usage_compliant(provider_name, use_case)

Check if a use case is compliant for a provider.

Parameters:

• provider_name (str) – Provider identifier

• use_case (str) – Intended use case (e.g., “research”, “commercial”)

Returns:

Tuple of (is_compliant, reason)

Return type:

Tuple[bool, str]

get_model_sampling_params(provider_name, model_id)

Get default sampling parameters for a model.

Parameters:

• provider_name (str)

• model_id (str)

Return type:

Dict[str, Any]

get_all_models_flat()

Get a flat dictionary of all (provider, model_id) -> model_config.

Return type:

Dict[Tuple[str, str], Dict[str, Any]]

describe()

Get a human-readable description of the registry.

Return type:

str

config.provider_registry.get_registry()

Get the global registry instance.

Return type:

ProviderRegistry

config.provider_registry.reset_registry()

Reset the global registry instance (useful for testing).

Return type:

None

config.setup_wizard