honeyhive

HoneyHive Python SDK - LLM Observability and Evaluation Platform

HoneyHive

Main HoneyHive API client.

Provides an ergonomic interface to the HoneyHive API with both sync and async methods.

Example::

client = HoneyHive(api_key="your-api-key")

# Sync
configs = client.configurations.list()

# Async
configs = await client.configurations.list_async()

Attributes:

Name	Type	Description
configurations		API for managing configurations.
datapoints		API for managing datapoints.
datasets		API for managing datasets.
events		API for managing events.
experiments		API for managing experiment runs.
metrics		API for managing metrics.
sessions		API for managing sessions.

Source code in src/honeyhive/api/client.py

class HoneyHive:
    """Main HoneyHive API client.

    Provides an ergonomic interface to the HoneyHive API with both
    sync and async methods.

    Example::

        client = HoneyHive(api_key="your-api-key")

        # Sync
        configs = client.configurations.list()

        # Async
        configs = await client.configurations.list_async()

    Attributes:
        configurations: API for managing configurations.
        datapoints: API for managing datapoints.
        datasets: API for managing datasets.
        events: API for managing events.
        experiments: API for managing experiment runs.
        metrics: API for managing metrics.
        sessions: API for managing sessions.
    """

    def __init__(
        self,
        api_key: Optional[str] = None,
        # `project` sits at positional slot #2 to mirror the legacy SDK shape
        # — pre-1.0 callers wrote `HoneyHive("key", "project-name")` positionally.
        # Keeping the slot reserved means those calls still execute (with a
        # DeprecationWarning) instead of binding the value to `base_url` or
        # raising TypeError. The argument is otherwise ignored.
        project: Optional[str] = None,
        *,
        # Primary URL parameter
        base_url: Optional[str] = None,
        # Backwards compatible alias for base_url
        server_url: Optional[str] = None,
        # Backwards compatible parameters (accepted but not used in new client)
        cp_base_url: Optional[str] = None,
        timeout: Optional[float] = None,
        retry_config: Optional[Any] = None,
        rate_limit_calls: Optional[int] = None,
        rate_limit_window: Optional[float] = None,
        max_connections: Optional[int] = None,
        max_keepalive: Optional[int] = None,
        test_mode: Optional[bool] = None,
        verbose: Optional[bool] = None,
        tracer_instance: Optional[Any] = None,
    ) -> None:
        """Initialize the HoneyHive client.

        Args:
            api_key: HoneyHive API key (typically starts with ``hh_``).
                     Falls back to HH_API_KEY environment variable.
            project: Deprecated. Accepted for backwards compatibility only;
                the backend infers project context from the API key and session.
                Ignored when constructing the client.
            base_url: API base URL for HoneyHive.
                      Falls back to HH_API_URL env var, then https://api.dp1.us.honeyhive.ai.
            server_url: Deprecated alias for base_url (for backwards compatibility).
            cp_base_url: Deprecated. Accepted for backwards compatibility but ignored;
                the SDK now uses a single base_url for all operations.
            timeout: Request timeout in seconds. Falls back to the HH_API_TIMEOUT
                env var, then to the SDK default of 5s. Pass a larger value when
                fetching large payloads (e.g. datasets.list for many datasets).
            retry_config: Retry configuration (accepted for backwards compat, not used).
            rate_limit_calls: Max calls per time window (accepted for backwards compat).
            rate_limit_window: Time window in seconds (accepted for backwards compat).
            max_connections: Max connections in pool (accepted for backwards compat).
            max_keepalive: Max keepalive connections (accepted for backwards compat).
            test_mode: Enable test mode (accepted for backwards compat, not used).
            verbose: Enable verbose logging (accepted for backwards compat, not used).
            tracer_instance: Tracer instance (accepted for backwards compat, not used).
        """
        import os

        if project is not None:
            warnings.warn(
                "The 'project' argument to HoneyHive() is deprecated and ignored; "
                "it will be removed in v2.0. Remove it from HoneyHive() calls.",
                DeprecationWarning,
                stacklevel=2,
            )

        if cp_base_url is not None:
            warnings.warn(
                "The 'cp_base_url' parameter is no longer used and will be removed "
                "in v2.0. The SDK now uses a single base_url for all operations.",
                DeprecationWarning,
                stacklevel=2,
            )

        # Resolve API key from parameter or environment
        self._api_key = api_key or os.environ.get("HH_API_KEY", "")

        # Resolve base URL: base_url > server_url (legacy) > env var > default
        resolved_base_url = (
            base_url
            or server_url  # Legacy parameter
            or os.environ.get("HH_API_URL")
            or "https://api.dp1.us.honeyhive.ai"
        )

        # Store backwards compat params (silently accepted)
        self._timeout = timeout
        self._test_mode = test_mode if test_mode is not None else False
        self._verbose = verbose if verbose is not None else False
        self._tracer_instance = tracer_instance

        # Create API config. The request timeout is resolved from the explicit
        # arg > HH_API_TIMEOUT env var; when neither is set we omit the key so
        # the APIConfig default (5.0s) is preserved. Note: passing timeout=None
        # to HoneyHive() keeps the default (None means "unset" here), whereas
        # APIConfig(timeout=None) disables timeouts at the low level.
        api_config_kwargs: Dict[str, Any] = {
            "base_path": resolved_base_url,
            "access_token": self._api_key,
        }
        resolved_timeout = _resolve_api_timeout(timeout)
        if resolved_timeout is not None:
            api_config_kwargs["timeout"] = resolved_timeout
        self._api_config = APIConfig(**api_config_kwargs)

        # Initialize API namespaces
        self.charts = ChartsAPI(self._api_config)
        self.configurations = ConfigurationsAPI(self._api_config)
        self.datapoints = DatapointsAPI(self._api_config)
        self.datasets = DatasetsAPI(self._api_config)
        self.events = EventsAPI(self._api_config)
        self.experiments = ExperimentsAPI(self._api_config)
        self.metrics = MetricsAPI(self._api_config)
        self.metric_versions = MetricVersionsAPI(self._api_config)
        self.sessions = SessionsAPI(self._api_config)

        # Alias for backwards compatibility
        self.evaluations = self.experiments

    @property
    def test_mode(self) -> bool:
        """Return whether client is in test mode."""
        return self._test_mode

    @property
    def verbose(self) -> bool:
        """Return whether verbose mode is enabled."""
        return self._verbose

    @property
    def timeout(self) -> Optional[float]:
        """Return the configured timeout."""
        return self._timeout

    @property
    def api_config(self) -> APIConfig:
        """Access the underlying API configuration."""
        return self._api_config

    @property
    def api_key(self) -> str:
        """Get the HoneyHive API key."""
        return self._api_key

    @property
    def server_url(self) -> str:
        """Get the HoneyHive API server URL."""
        return self._api_config.base_path

    @server_url.setter
    def server_url(self, value: str) -> None:
        """Set the HoneyHive API server URL."""
        self._api_config.base_path = value

charts instance-attribute

charts = ChartsAPI(self._api_config)

configurations instance-attribute

configurations = ConfigurationsAPI(self._api_config)

datapoints instance-attribute

datapoints = DatapointsAPI(self._api_config)

datasets instance-attribute

datasets = DatasetsAPI(self._api_config)

events instance-attribute

events = EventsAPI(self._api_config)

experiments instance-attribute

experiments = ExperimentsAPI(self._api_config)

metrics instance-attribute

metrics = MetricsAPI(self._api_config)

metric_versions instance-attribute

metric_versions = MetricVersionsAPI(self._api_config)

sessions instance-attribute

sessions = SessionsAPI(self._api_config)

evaluations instance-attribute

evaluations = self.experiments

test_mode property

test_mode: bool

Return whether client is in test mode.

verbose property

verbose: bool

Return whether verbose mode is enabled.

timeout property

timeout: Optional[float]

Return the configured timeout.

api_config property

api_config: APIConfig

Access the underlying API configuration.

api_key property

api_key: str

Get the HoneyHive API key.

server_url property writable

server_url: str

Get the HoneyHive API server URL.