Configuration Models API

Overview

The HoneyHive SDK provides type-safe Pydantic configuration models that enable modern, validated configuration with IDE autocomplete support and graceful degradation.

Base Configuration Classes

BaseHoneyHiveConfig

class honeyhive.config.models.BaseHoneyHiveConfig(*, api_key=None, project=None, test_mode=False, verbose=False)[source]

Bases: BaseSettings

Base configuration model with common HoneyHive fields.

This base class contains fields that are commonly used across different parts of the SDK (tracer, API client, evaluation, etc.) to avoid duplication and ensure consistent validation.

Common Fields:

  • api_key: HoneyHive API key for authentication

  • project: Project name (required by backend API)

  • test_mode: Enable test mode (no data sent to backend)

  • verbose: Enable verbose logging

Example

This class is not used directly but inherited by domain-specific configs:

>>> class TracerConfig(BaseHoneyHiveConfig):
...     session_name: Optional[str] = None
...     source: str = "dev"
>>>
>>> config = TracerConfig(api_key="hh_...", project="my-project")
>>> print(config.api_key)  # Inherited from base
hh_...
Parameters:

  • api_key (str | None)

  • project (str | None)

  • test_mode (bool)

  • verbose (bool)

api_key: str | None
project: str | None
test_mode: bool
verbose: bool
model_config = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_exit_on_error': True, 'cli_flag_prefix_char': '-', 'cli_hide_none_type': False, 'cli_ignore_unknown_args': False, 'cli_implicit_flags': False, 'cli_kebab_case': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_shortcuts': None, 'cli_use_class_docs_for_groups': False, 'enable_decoding': True, 'env_file': None, 'env_file_encoding': None, 'env_ignore_empty': False, 'env_nested_delimiter': None, 'env_nested_max_split': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': '', 'extra': 'forbid', 'json_file': None, 'json_file_encoding': None, 'nested_model_default_partial_update': False, 'protected_namespaces': ('model_validate', 'model_dump', 'settings_customise_sources'), 'secrets_dir': None, 'toml_file': None, 'validate_assignment': True, 'validate_default': True, 'yaml_config_section': None, 'yaml_file': None, 'yaml_file_encoding': None}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod validate_api_key(v)[source]

Validate API key format with graceful degradation.

Parameters:

v (Any) – The API key value to validate

Returns:

The validated and normalized API key, or None if invalid

Return type:

str | None

classmethod validate_project(v)[source]

Validate project name format with graceful degradation.

Parameters:

v (Any) – The project name to validate

Returns:

The validated and normalized project name, or None if invalid

Return type:

str | None

classmethod validate_boolean_fields(v)[source]

Validate boolean fields with graceful degradation.

Parameters:

v (Any) – The value to validate as boolean

Returns:

The validated boolean value, or False if invalid

Return type:

bool

Base configuration class with common fields shared across all HoneyHive components.

Key Features:

  • Environment Variable Loading: Automatic loading via AliasChoices

  • Type Safety: Full Pydantic v2 validation

  • Graceful Degradation: Invalid values replaced with safe defaults

  • IDE Support: Complete autocomplete and type checking

Common Fields:

honeyhive.config.models.api_key: str

HoneyHive API key for authentication.

Environment Variable: HH_API_KEY

Required: Yes

Format: String starting with hh_

honeyhive.config.models.project: str

Project name (required by backend API).

Environment Variable: HH_PROJECT

Required: Yes

honeyhive.config.models.test_mode: bool = False

Enable test mode (no data sent to backend).

Environment Variable: HH_TEST_MODE

honeyhive.config.models.verbose: bool = False

Enable verbose logging output.

Environment Variable: HH_VERBOSE

Example Usage:

from honeyhive.config.models import BaseHoneyHiveConfig

# Direct instantiation
config = BaseHoneyHiveConfig(
    api_key="hh_1234567890abcdef",
    project="my-project",
    verbose=True
)

# Environment variable loading
import os
os.environ["HH_API_KEY"] = "hh_1234567890abcdef"
os.environ["HH_PROJECT"] = "my-project"

config = BaseHoneyHiveConfig()  # Loads from environment

Domain-Specific Configuration Classes

TracerConfig

class honeyhive.config.models.TracerConfig(*, api_key=None, project=None, test_mode=False, verbose=False, session_name=None, source='dev', server_url='https://api.honeyhive.ai', disable_http_tracing=True, disable_batch=False, disable_tracing=False, max_attributes=1024, max_events=1024, max_links=128, max_span_size=10485760, preserve_core_attributes=True, cache_enabled=True, cache_max_size=None, cache_ttl=None, cache_cleanup_interval=None, session_id=None, inputs=None, link_carrier=None, is_evaluation=False, run_id=None, dataset_id=None, datapoint_id=None)[source]

Bases: BaseHoneyHiveConfig

Core tracer configuration with validation.

This class defines the primary configuration parameters for initializing a HoneyHive tracer instance. It inherits common fields from BaseHoneyHiveConfig and adds tracer-specific parameters.

Inherited Fields:

  • api_key: HoneyHive API key for authentication

  • project: Project name (required by backend API)

  • test_mode: Enable test mode (no data sent to backend)

  • verbose: Enable verbose logging output

Tracer-Specific Fields:

  • session_name: Human-readable session identifier

  • source: Source environment identifier

  • server_url: Custom HoneyHive server URL (from HH_API_URL env var)

  • disable_http_tracing: Disable HTTP request tracing (disabled by default)

  • disable_batch: Disable batch processing of spans

Example

>>> config = TracerConfig(
...     api_key="hh_1234567890abcdef",
...     project="my-llm-project",
...     session_name="user-chat-session",
...     source="production",
...     verbose=True
... )
>>> tracer = HoneyHiveTracer(config=config)

# Backwards compatible usage still works: >>> tracer = HoneyHiveTracer( … api_key=”hh_1234567890abcdef”, … project=”my-llm-project”, … verbose=True … )

Parameters:

  • api_key (str | None)

  • project (str | None)

  • test_mode (bool)

  • verbose (bool)

  • session_name (str | None)

  • source (str)

  • server_url (str)

  • disable_http_tracing (bool)

  • disable_batch (bool)

  • disable_tracing (bool)

  • max_attributes (int)

  • max_events (int)

  • max_links (int)

  • max_span_size (int)

  • preserve_core_attributes (bool)

  • cache_enabled (bool)

  • cache_max_size (int | None)

  • cache_ttl (float | None)

  • cache_cleanup_interval (float | None)

  • session_id (str | None)

  • inputs (Dict[str, Any] | None)

  • link_carrier (Dict[str, Any] | None)

  • is_evaluation (bool)

  • run_id (str | None)

  • dataset_id (str | None)

  • datapoint_id (str | None)

session_name: str | None
source: str
server_url: str
disable_http_tracing: bool
disable_batch: bool
disable_tracing: bool
max_attributes: int
max_events: int
max_span_size: int
preserve_core_attributes: bool
cache_enabled: bool
cache_max_size: int | None
cache_ttl: float | None
cache_cleanup_interval: float | None
session_id: str | None
inputs: Dict[str, Any] | None
is_evaluation: bool
run_id: str | None
dataset_id: str | None
datapoint_id: str | None
model_config = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_exit_on_error': True, 'cli_flag_prefix_char': '-', 'cli_hide_none_type': False, 'cli_ignore_unknown_args': False, 'cli_implicit_flags': False, 'cli_kebab_case': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_shortcuts': None, 'cli_use_class_docs_for_groups': False, 'enable_decoding': True, 'env_file': None, 'env_file_encoding': None, 'env_ignore_empty': False, 'env_nested_delimiter': None, 'env_nested_max_split': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': '', 'extra': 'forbid', 'json_file': None, 'json_file_encoding': None, 'nested_model_default_partial_update': False, 'protected_namespaces': ('model_validate', 'model_dump', 'settings_customise_sources'), 'secrets_dir': None, 'toml_file': None, 'validate_assignment': True, 'validate_default': True, 'yaml_config_section': None, 'yaml_file': None, 'yaml_file_encoding': None}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod validate_server_url(v)[source]

Validate server URL format with graceful degradation.

Parameters:

v (Any) – The server URL to validate

Returns:

The validated and normalized server URL, or default if invalid

Return type:

str

classmethod validate_source(v)[source]

Validate source environment with graceful degradation.

Parameters:

v (Any) – The source environment to validate

Returns:

The validated source environment, or “dev” if invalid

Return type:

str

classmethod validate_session_id(v)[source]

Validate session ID format with graceful degradation.

Parameters:

v (Any) – The session ID to validate

Returns:

The validated and normalized session ID, or None if invalid

Return type:

str | None

classmethod validate_ids(v)[source]

Validate ID fields with graceful degradation.

Parameters:

v (Any) – The ID value to validate

Returns:

The validated ID, or None if invalid

Return type:

str | None

Primary configuration class for HoneyHive tracer initialization.

Inherits all fields from BaseHoneyHiveConfig and adds tracer-specific parameters.

Tracer-Specific Fields:

honeyhive.config.models.source: str = "dev"

Source environment identifier.

Environment Variable: HH_SOURCE

Examples: "production", "staging", "development"

honeyhive.config.models.server_url: str = "https://api.honeyhive.ai"

Custom HoneyHive server URL.

Environment Variable: HH_API_URL

honeyhive.config.models.disable_http_tracing: bool = True

Disable automatic HTTP request tracing.

Environment Variable: HH_DISABLE_HTTP_TRACING

honeyhive.config.models.disable_batch: bool = False

Disable span batching for immediate export.

Environment Variable: HH_DISABLE_BATCH

honeyhive.config.models.disable_tracing: bool = False

Completely disable tracing (emergency override).

Environment Variable: HH_DISABLE_TRACING

honeyhive.config.models.cache_enabled: bool = True

Enable response caching.

Environment Variable: HH_CACHE_ENABLED

honeyhive.config.models.cache_max_size: int = 1000

Maximum cache size (number of entries).

Environment Variable: HH_CACHE_MAX_SIZE

honeyhive.config.models.cache_ttl: int = 3600

Cache time-to-live in seconds.

Environment Variable: HH_CACHE_TTL

honeyhive.config.models.cache_cleanup_interval: int = 300

Cache cleanup interval in seconds.

Environment Variable: HH_CACHE_CLEANUP_INTERVAL

Example Usage:

from honeyhive import HoneyHiveTracer
from honeyhive.config.models import TracerConfig

# Full configuration
config = TracerConfig(
    api_key="hh_1234567890abcdef",
    project="my-llm-project",
    source="production",
    verbose=True,
    disable_http_tracing=False,
    cache_enabled=True,
    cache_max_size=2000
)

tracer = HoneyHiveTracer(config=config)

SessionConfig

class honeyhive.config.models.SessionConfig(*, api_key=None, project=None, test_mode=False, verbose=False, session_id=None, inputs=None, link_carrier=None)[source]

Bases: BaseHoneyHiveConfig

Session-specific configuration parameters.

This class handles configuration related to session management, including session linking and input/output data.

Example

>>> session_config = SessionConfig(
...     session_id="550e8400-e29b-41d4-a716-446655440000",
...     inputs={"user_id": "123", "query": "Hello world"}
... )
>>> tracer = HoneyHiveTracer(
...     config=tracer_config,
...     session_config=session_config
... )
Parameters:
session_id: str | None
inputs: Dict[str, Any] | None
model_config = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_exit_on_error': True, 'cli_flag_prefix_char': '-', 'cli_hide_none_type': False, 'cli_ignore_unknown_args': False, 'cli_implicit_flags': False, 'cli_kebab_case': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_shortcuts': None, 'cli_use_class_docs_for_groups': False, 'enable_decoding': True, 'env_file': None, 'env_file_encoding': None, 'env_ignore_empty': False, 'env_nested_delimiter': None, 'env_nested_max_split': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': '', 'extra': 'forbid', 'json_file': None, 'json_file_encoding': None, 'nested_model_default_partial_update': False, 'protected_namespaces': ('model_validate', 'model_dump', 'settings_customise_sources'), 'secrets_dir': None, 'toml_file': None, 'validate_assignment': True, 'validate_default': True, 'yaml_config_section': None, 'yaml_file': None, 'yaml_file_encoding': None}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod validate_session_id(v)[source]

Validate session ID format with graceful degradation.

Parameters:

v (Any) – The session ID to validate

Returns:

The validated and normalized session ID, or None if invalid

Return type:

str | None

Session-specific configuration for tracer initialization.

Session Fields:

honeyhive.config.models.session_name: str | None = None

Custom session name for grouping related traces.

honeyhive.config.models.session_id: str | None = None

Explicit session identifier.

honeyhive.config.models.inputs: Dict[str, Any] | None = None

Session input parameters.

honeyhive.config.models.outputs: Dict[str, Any] | None = None

Session output parameters.

honeyhive.config.models.metadata: Dict[str, Any] | None = None

Additional session metadata.

Example Usage:

from honeyhive import HoneyHiveTracer
from honeyhive.config.models import TracerConfig, SessionConfig

tracer_config = TracerConfig(
    api_key="hh_1234567890abcdef",
    project="my-project"
)

session_config = SessionConfig(
    session_name="user-chat-session",
    inputs={"user_id": "123", "query": "Hello world"},
    metadata={"version": "1.0", "environment": "production"}
)

tracer = HoneyHiveTracer(
    config=tracer_config,
    session_config=session_config
)

EvaluationConfig

class honeyhive.config.models.EvaluationConfig(*, api_key=None, project=None, test_mode=False, verbose=False, is_evaluation=False, run_id=None, dataset_id=None, datapoint_id=None)[source]

Bases: BaseHoneyHiveConfig

Evaluation-specific configuration parameters.

This class handles configuration for evaluation scenarios, including dataset and run management.

Example

>>> eval_config = EvaluationConfig(
...     is_evaluation=True,
...     run_id="eval-run-123",
...     dataset_id="dataset-456",
...     datapoint_id="datapoint-789"
... )
>>> tracer = HoneyHiveTracer(
...     config=tracer_config,
...     evaluation_config=eval_config
... )
Parameters:

  • api_key (str | None)

  • project (str | None)

  • test_mode (bool)

  • verbose (bool)

  • is_evaluation (bool)

  • run_id (str | None)

  • dataset_id (str | None)

  • datapoint_id (str | None)

is_evaluation: bool
run_id: str | None
dataset_id: str | None
datapoint_id: str | None
model_config = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_exit_on_error': True, 'cli_flag_prefix_char': '-', 'cli_hide_none_type': False, 'cli_ignore_unknown_args': False, 'cli_implicit_flags': False, 'cli_kebab_case': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_shortcuts': None, 'cli_use_class_docs_for_groups': False, 'enable_decoding': True, 'env_file': None, 'env_file_encoding': None, 'env_ignore_empty': False, 'env_nested_delimiter': None, 'env_nested_max_split': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': '', 'extra': 'forbid', 'json_file': None, 'json_file_encoding': None, 'nested_model_default_partial_update': False, 'protected_namespaces': ('model_validate', 'model_dump', 'settings_customise_sources'), 'secrets_dir': None, 'toml_file': None, 'validate_assignment': True, 'validate_default': True, 'yaml_config_section': None, 'yaml_file': None, 'yaml_file_encoding': None}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod validate_ids(v)[source]

Validate ID fields with graceful degradation.

Parameters:

v (Any) – The ID value to validate

Returns:

The validated ID, or None if invalid

Return type:

str | None

Evaluation-specific configuration parameters.

Evaluation Fields:

honeyhive.config.models.is_evaluation: bool = False

Mark this as an evaluation run.

honeyhive.config.models.run_id: str | None = None

Evaluation run identifier.

honeyhive.config.models.dataset_id: str | None = None

Dataset identifier for evaluation.

honeyhive.config.models.datapoint_id: str | None = None

Specific datapoint identifier.

Example Usage:

from honeyhive.config.models import EvaluationConfig

eval_config = EvaluationConfig(
    is_evaluation=True,
    run_id="eval_run_123",
    dataset_id="dataset_456"
)

APIClientConfig

class honeyhive.config.models.APIClientConfig(*, server_url='https://api.honeyhive.ai', api_key=None, project=None, test_mode=False, verbose=False, http_config=<factory>)[source]

Bases: BaseHoneyHiveConfig, ServerURLMixin

Configuration for HoneyHive API client.

This class defines configuration parameters for API client initialization to reduce argument count while maintaining backwards compatibility. It inherits common fields from BaseHoneyHiveConfig and composes HTTPClientConfig for transport-level settings.

Inherited Fields:

  • api_key: HoneyHive API key for authentication

  • project: Project name (required by backend API)

  • test_mode: Enable test mode (no data sent to backend)

  • verbose: Enable verbose logging output

API Client-Specific Fields:

  • server_url: Server URL for requests (from HH_API_URL env var)

  • http_config: HTTP transport configuration

Example

>>> # Simple usage
>>> config = APIClientConfig(
...     api_key="hh_1234567890abcdef",
...     server_url="https://api.honeyhive.ai"
... )

>>> # Advanced usage with HTTP config
>>> http_config = HTTPClientConfig(timeout=60.0, max_connections=50)
>>> config = APIClientConfig(
...     api_key="hh_1234567890abcdef",
...     server_url="https://api.honeyhive.ai",
...     http_config=http_config
... )

>>> # Future usage:
>>> # client = HoneyHive(config=config)

# Current backwards compatible usage: >>> client = HoneyHive( … bearer_auth=”hh_1234567890abcdef”, … server_url=”https://api.honeyhive.ai”, … timeout_ms=30000 … )

Parameters:
http_config: HTTPClientConfig
model_config = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_exit_on_error': True, 'cli_flag_prefix_char': '-', 'cli_hide_none_type': False, 'cli_ignore_unknown_args': False, 'cli_implicit_flags': False, 'cli_kebab_case': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_shortcuts': None, 'cli_use_class_docs_for_groups': False, 'enable_decoding': True, 'env_file': None, 'env_file_encoding': None, 'env_ignore_empty': False, 'env_nested_delimiter': None, 'env_nested_max_split': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': '', 'extra': 'forbid', 'json_file': None, 'json_file_encoding': None, 'nested_model_default_partial_update': False, 'protected_namespaces': ('model_validate', 'model_dump', 'settings_customise_sources'), 'secrets_dir': None, 'toml_file': None, 'validate_assignment': True, 'validate_default': True, 'yaml_config_section': None, 'yaml_file': None, 'yaml_file_encoding': None}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Configuration for HoneyHive API client settings.

Inherits from BaseHoneyHiveConfig.

Example Usage:

from honeyhive.config.models import APIClientConfig

api_config = APIClientConfig(
    api_key="hh_1234567890abcdef",
    project="my-project",
    server_url="https://custom.honeyhive.com"
)

HTTPClientConfig

class honeyhive.config.models.HTTPClientConfig(*, api_key=None, project=None, test_mode=False, verbose=False, timeout=30.0, max_connections=10, max_keepalive_connections=20, keepalive_expiry=30.0, pool_timeout=10.0, rate_limit_calls=100, rate_limit_window=60.0, max_retries=3, http_proxy=None, https_proxy=None, no_proxy=None, verify_ssl=True, follow_redirects=True)[source]

Bases: BaseHoneyHiveConfig

HTTP client configuration settings.

This class extends BaseHoneyHiveConfig with HTTP-specific settings for connection pooling, timeouts, retry behavior, proxy settings, and SSL configuration. Supports both HH_* and standard HTTP_* environment variables.

Example

>>> config = HTTPClientConfig(
...     timeout=30.0,
...     max_connections=50,
...     http_proxy="http://proxy.company.com:8080"
... )
>>> # Or load from environment variables:
>>> # export HH_TIMEOUT=30.0
>>> # export HH_MAX_CONNECTIONS=50
>>> config = HTTPClientConfig()
Parameters:

  • api_key (str | None)

  • project (str | None)

  • test_mode (bool)

  • verbose (bool)

  • timeout (float)

  • max_connections (int)

  • max_keepalive_connections (int)

  • keepalive_expiry (float)

  • pool_timeout (float)

  • rate_limit_calls (int)

  • rate_limit_window (float)

  • max_retries (int)

  • http_proxy (str | None)

  • https_proxy (str | None)

  • no_proxy (str | None)

  • verify_ssl (bool)

  • follow_redirects (bool)

timeout: float
max_connections: int
max_keepalive_connections: int
keepalive_expiry: float
pool_timeout: float
rate_limit_calls: int
rate_limit_window: float
max_retries: int
http_proxy: str | None
https_proxy: str | None
no_proxy: str | None
verify_ssl: bool
follow_redirects: bool
model_config = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_exit_on_error': True, 'cli_flag_prefix_char': '-', 'cli_hide_none_type': False, 'cli_ignore_unknown_args': False, 'cli_implicit_flags': False, 'cli_kebab_case': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_shortcuts': None, 'cli_use_class_docs_for_groups': False, 'enable_decoding': True, 'env_file': None, 'env_file_encoding': None, 'env_ignore_empty': False, 'env_nested_delimiter': None, 'env_nested_max_split': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': '', 'extra': 'forbid', 'json_file': None, 'json_file_encoding': None, 'nested_model_default_partial_update': False, 'protected_namespaces': ('model_validate', 'model_dump', 'settings_customise_sources'), 'secrets_dir': None, 'toml_file': None, 'validate_assignment': True, 'validate_default': True, 'yaml_config_section': None, 'yaml_file': None, 'yaml_file_encoding': None}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod validate_positive_float(v)[source]

Validate that float values are positive with graceful degradation.

Parameters:

v (Any)

Return type:

float

classmethod validate_positive_int(v)[source]

Validate that integer values are positive with graceful degradation.

Parameters:

v (Any)

Return type:

int

classmethod validate_proxy_url(v)[source]

Validate proxy URL format with graceful degradation.

Parameters:

v (str | None)

Return type:

str | None

HTTP client configuration including connection pooling and retry settings.

HTTP Configuration Fields:

honeyhive.config.models.timeout: float = 30.0

Request timeout in seconds.

Environment Variable: HH_TIMEOUT

honeyhive.config.models.max_connections: int = 100

Maximum number of HTTP connections.

Environment Variable: HH_MAX_CONNECTIONS

honeyhive.config.models.max_keepalive_connections: int = 20

Maximum number of keep-alive connections.

Environment Variable: HH_MAX_KEEPALIVE_CONNECTIONS

honeyhive.config.models.keepalive_expiry: float = 30.0

Keep-alive connection expiry time in seconds.

Environment Variable: HH_KEEPALIVE_EXPIRY

honeyhive.config.models.pool_timeout: float = 10.0

Connection pool timeout in seconds.

Environment Variable: HH_POOL_TIMEOUT

honeyhive.config.models.rate_limit_calls: int = 100

Rate limit: maximum calls per window.

Environment Variable: HH_RATE_LIMIT_CALLS

honeyhive.config.models.rate_limit_window: int = 60

Rate limit window in seconds.

Environment Variable: HH_RATE_LIMIT_WINDOW

honeyhive.config.models.max_retries: int = 3

Maximum number of retry attempts.

Environment Variable: HH_MAX_RETRIES

honeyhive.config.models.http_proxy: str | None = None

HTTP proxy URL.

Environment Variable: HTTP_PROXY

honeyhive.config.models.https_proxy: str | None = None

HTTPS proxy URL.

Environment Variable: HTTPS_PROXY

honeyhive.config.models.no_proxy: str | None = None

Comma-separated list of hosts to bypass proxy.

Environment Variable: NO_PROXY

honeyhive.config.models.verify_ssl: bool = True

Enable SSL certificate verification.

Environment Variable: HH_VERIFY_SSL

honeyhive.config.models.follow_redirects: bool = True

Follow HTTP redirects.

Environment Variable: HH_FOLLOW_REDIRECTS

Example Usage:

from honeyhive.config.models import HTTPClientConfig

http_config = HTTPClientConfig(
    timeout=60.0,
    max_connections=200,
    rate_limit_calls=200,
    rate_limit_window=60,
    http_proxy="http://proxy.company.com:8080"
)

ExperimentConfig

class honeyhive.config.models.ExperimentConfig(*, api_key=None, project=None, test_mode=False, verbose=False, experiment_id=None, experiment_name=None, experiment_variant=None, experiment_group=None, experiment_metadata=None)[source]

Bases: BaseHoneyHiveConfig

Experiment and evaluation configuration settings.

This class extends BaseHoneyHiveConfig with experiment-specific settings for A/B testing, feature flags, and experimental features. Supports multiple experiment tracking platforms (MLflow, W&B, Comet, etc.).

Example

>>> config = ExperimentConfig(
...     experiment_id="exp_12345",
...     experiment_name="model-comparison",
...     experiment_variant="baseline",
...     experiment_group="control"
... )
>>> # Or load from environment variables:
>>> # export HH_EXPERIMENT_ID=exp_12345
>>> # export MLFLOW_EXPERIMENT_NAME=model-comparison
>>> config = ExperimentConfig()
Parameters:

  • api_key (str | None)

  • project (str | None)

  • test_mode (bool)

  • verbose (bool)

  • experiment_id (str | None)

  • experiment_name (str | None)

  • experiment_variant (str | None)

  • experiment_group (str | None)

  • experiment_metadata (Dict[str, Any] | None)

experiment_id: str | None
experiment_name: str | None
experiment_variant: str | None
experiment_group: str | None
experiment_metadata: Dict[str, Any] | None
model_config = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_exit_on_error': True, 'cli_flag_prefix_char': '-', 'cli_hide_none_type': False, 'cli_ignore_unknown_args': False, 'cli_implicit_flags': False, 'cli_kebab_case': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_shortcuts': None, 'cli_use_class_docs_for_groups': False, 'enable_decoding': True, 'env_file': None, 'env_file_encoding': None, 'env_ignore_empty': False, 'env_nested_delimiter': None, 'env_nested_max_split': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': '', 'extra': 'forbid', 'json_file': None, 'json_file_encoding': None, 'nested_model_default_partial_update': False, 'protected_namespaces': ('model_validate', 'model_dump', 'settings_customise_sources'), 'secrets_dir': None, 'toml_file': None, 'validate_assignment': True, 'validate_default': True, 'yaml_config_section': None, 'yaml_file': None, 'yaml_file_encoding': None}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod validate_experiment_strings(v)[source]

Validate experiment string fields with graceful degradation.

Parameters:

v (str | None)

Return type:

str | None

classmethod validate_experiment_metadata(v)[source]

Validate experiment metadata format with graceful degradation.

Parameters:

v (Dict[str, Any] | None)

Return type:

Dict[str, Any] | None

Experiment-specific configuration parameters.

Experiment Fields:

honeyhive.config.models.experiment_id: str | None = None

Unique experiment identifier.

Environment Variable: HH_EXPERIMENT_ID

honeyhive.config.models.experiment_name: str | None = None

Human-readable experiment name.

Environment Variable: HH_EXPERIMENT_NAME

honeyhive.config.models.experiment_variant: str | None = None

Experiment variant identifier.

Environment Variable: HH_EXPERIMENT_VARIANT

honeyhive.config.models.experiment_group: str | None = None

Experiment group for A/B testing.

Environment Variable: HH_EXPERIMENT_GROUP

honeyhive.config.models.experiment_metadata: Dict[str, Any] | None = None

Additional experiment metadata.

Environment Variable: HH_EXPERIMENT_METADATA (JSON string)

Example Usage:

from honeyhive.config.models import ExperimentConfig

experiment_config = ExperimentConfig(
    experiment_id="exp_123",
    experiment_name="LLM Response Quality Test",
    experiment_variant="variant_a",
    experiment_group="control",
    experiment_metadata={"model": "gpt-4", "temperature": 0.7}
)

OTLPConfig

class honeyhive.config.models.OTLPConfig(*, api_key=None, project=None, test_mode=False, verbose=False, otlp_enabled=True, otlp_endpoint=None, otlp_headers=None, otlp_protocol='http/json', batch_size=100, flush_interval=5.0, max_export_batch_size=512, export_timeout=30.0)[source]

Bases: BaseHoneyHiveConfig

OTLP (OpenTelemetry Protocol) configuration settings.

This class extends BaseHoneyHiveConfig with OTLP-specific settings for batch processing, export intervals, and performance tuning.

Example

>>> config = OTLPConfig(
...     batch_size=200,
...     flush_interval=1.0,
...     otlp_endpoint="https://custom.otlp.endpoint"
... )
>>> # Or load from environment variables:
>>> # export HH_BATCH_SIZE=200
>>> # export HH_FLUSH_INTERVAL=1.0
>>> config = OTLPConfig()
Parameters:

  • api_key (str | None)

  • project (str | None)

  • test_mode (bool)

  • verbose (bool)

  • otlp_enabled (bool)

  • otlp_endpoint (str | None)

  • otlp_headers (Dict[str, Any] | None)

  • otlp_protocol (str)

  • batch_size (int)

  • flush_interval (float)

  • max_export_batch_size (int)

  • export_timeout (float)

otlp_enabled: bool
otlp_endpoint: str | None
otlp_headers: Dict[str, Any] | None
otlp_protocol: str
batch_size: int
flush_interval: float
max_export_batch_size: int
export_timeout: float
model_config = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_exit_on_error': True, 'cli_flag_prefix_char': '-', 'cli_hide_none_type': False, 'cli_ignore_unknown_args': False, 'cli_implicit_flags': False, 'cli_kebab_case': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_shortcuts': None, 'cli_use_class_docs_for_groups': False, 'enable_decoding': True, 'env_file': None, 'env_file_encoding': None, 'env_ignore_empty': False, 'env_nested_delimiter': None, 'env_nested_max_split': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': '', 'extra': 'forbid', 'json_file': None, 'json_file_encoding': None, 'nested_model_default_partial_update': False, 'protected_namespaces': ('model_validate', 'model_dump', 'settings_customise_sources'), 'secrets_dir': None, 'toml_file': None, 'validate_assignment': True, 'validate_default': True, 'yaml_config_section': None, 'yaml_file': None, 'yaml_file_encoding': None}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod validate_otlp_endpoint(v)[source]

Validate OTLP endpoint URL format with graceful degradation.

Parameters:

v (str | None)

Return type:

str | None

classmethod validate_batch_sizes(v)[source]

Validate batch size values with graceful degradation.

Parameters:

v (Any)

Return type:

int

classmethod validate_timeouts(v)[source]

Validate timeout values with graceful degradation.

Parameters:

v (Any)

Return type:

float

classmethod validate_otlp_headers(v)[source]

Validate OTLP headers format with graceful degradation.

Parameters:

v (Dict[str, Any] | None)

Return type:

Dict[str, Any] | None

OTLP (OpenTelemetry Protocol) export configuration parameters.

OTLP Fields:

honeyhive.config.models.otlp_enabled: bool = True

Enable OTLP export.

Environment Variable: HH_OTLP_ENABLED

honeyhive.config.models.otlp_endpoint: str | None = None

Custom OTLP endpoint URL.

Environment Variable: HH_OTLP_ENDPOINT

honeyhive.config.models.otlp_headers: Dict[str, Any] | None = None

OTLP headers in JSON format.

Environment Variable: HH_OTLP_HEADERS (JSON string)

honeyhive.config.models.otlp_protocol: str = "http/json"

OTLP protocol format: "http/json" (default) or "http/protobuf".

Environment Variables: HH_OTLP_PROTOCOL or OTEL_EXPORTER_OTLP_PROTOCOL

honeyhive.config.models.batch_size: int = 100

OTLP batch size for performance optimization.

Environment Variable: HH_BATCH_SIZE

honeyhive.config.models.flush_interval: float = 5.0

OTLP flush interval in seconds.

Environment Variable: HH_FLUSH_INTERVAL

honeyhive.config.models.max_export_batch_size: int = 512

Maximum export batch size.

Environment Variable: HH_MAX_EXPORT_BATCH_SIZE

honeyhive.config.models.export_timeout: float = 30.0

Export timeout in seconds.

Environment Variable: HH_EXPORT_TIMEOUT

Example Usage:

from honeyhive.config.models import OTLPConfig

# Use JSON format for OTLP export
otlp_config = OTLPConfig(
    otlp_protocol="http/json",
    batch_size=200,
    flush_interval=1.0
)

# Or via environment variable
# export HH_OTLP_PROTOCOL=http/json
otlp_config = OTLPConfig()  # Loads from HH_OTLP_PROTOCOL

Environment Variable Integration

All configuration models support automatic environment variable loading using Pydantic’s AliasChoices feature.

Environment Variable Patterns:

  • Core Settings: HH_API_KEY, HH_PROJECT, HH_SOURCE

  • Operational: HH_TEST_MODE, HH_VERBOSE, HH_DISABLE_TRACING

  • Performance: HH_TIMEOUT, HH_MAX_CONNECTIONS, HH_RATE_LIMIT_*

  • Caching: HH_CACHE_ENABLED, HH_CACHE_MAX_SIZE, HH_CACHE_TTL

  • Experiments: HH_EXPERIMENT_ID, HH_EXPERIMENT_NAME

  • OTLP: HH_OTLP_ENABLED, HH_OTLP_ENDPOINT, HH_OTLP_PROTOCOL, HH_OTLP_HEADERS, HH_BATCH_SIZE, HH_FLUSH_INTERVAL

Priority Order:

  1. Direct Parameters: Values passed to config constructors

  2. Environment Variables: HH_* prefixed variables

  3. Default Values: Built-in configuration defaults

Example:

# Set environment variables
export HH_API_KEY="hh_1234567890abcdef"
export HH_PROJECT="my-project"
export HH_VERBOSE="true"
export HH_CACHE_MAX_SIZE="2000"

from honeyhive.config.models import TracerConfig

# Loads all values from environment variables
config = TracerConfig()

# Override specific values
config = TracerConfig(verbose=False)  # Overrides HH_VERBOSE

Error Handling and Validation

All configuration models use Pydantic v2 validation with graceful degradation:

Validation Features:

  • Type Safety: Automatic type conversion and validation

  • Format Validation: API key format, URL validation, UUID validation

  • Range Validation: Numeric ranges, positive values

  • Graceful Degradation: Invalid values replaced with safe defaults

  • Clear Error Messages: Detailed validation error reporting

API Key Validation:

from honeyhive.config.models import TracerConfig

# Valid API key
config = TracerConfig(api_key="hh_1234567890abcdef")

# Invalid API key - validation error with clear message
try:
    config = TracerConfig(api_key="invalid_key")
except ValueError as e:
    print(f"Validation error: {e}")

URL Validation:

# Valid URL
config = TracerConfig(server_url="https://api.honeyhive.ai")

# Invalid URL - graceful degradation to default
config = TracerConfig(server_url="not-a-url")
# config.server_url will be "https://api.honeyhive.ai"

Numeric Validation:

# Valid values
config = TracerConfig(cache_max_size=1000, cache_ttl=3600)

# Invalid values - graceful degradation
config = TracerConfig(cache_max_size=-100, cache_ttl="invalid")
# config.cache_max_size will be 1000 (default)
# config.cache_ttl will be 3600 (default)

Migration from Legacy Configuration

The new configuration models provide 100% backwards compatibility with existing parameter-based initialization:

Legacy Pattern (Still Works):

from honeyhive import HoneyHiveTracer

tracer = HoneyHiveTracer(
    api_key="hh_1234567890abcdef",
    project="my-project",
    verbose=True,
    disable_http_tracing=True
)

Modern Pattern (Recommended):

from honeyhive import HoneyHiveTracer
from honeyhive.config.models import TracerConfig

config = TracerConfig(
    api_key="hh_1234567890abcdef",
    project="my-project",
    verbose=True,
    disable_http_tracing=True
)

tracer = HoneyHiveTracer(config=config)

Mixed Pattern (Flexible):

config = TracerConfig(
    api_key="hh_1234567890abcdef",
    project="my-project"
)

# Individual parameters override config values
tracer = HoneyHiveTracer(
    config=config,
    verbose=True,  # Overrides config.verbose
    disable_http_tracing=True  # Overrides config.disable_http_tracing
)

See Also