Source code for qilisdk.settings

# Copyright 2025 Qilimanjaro Quantum Tech
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

from enum import Enum
from functools import lru_cache
from pathlib import Path

import numpy as np
from pydantic import Field, SecretStr
from pydantic_settings import BaseSettings, SettingsConfigDict



[docs]
def default_logging_config_path() -> Path:
    return Path(__file__).with_name("logging_config.yaml").resolve()




[docs]
class Precision(str, Enum):

[docs]
    COMPLEX_64 = "COMPLEX_64"


[docs]
    COMPLEX_128 = "COMPLEX_128"


    @property

[docs]
    def dtype(self) -> np.dtype:
        """
        Resolve the numpy dtype associated with this complex precision.

        Returns:
            np.dtype: The corresponding numpy complex dtype.
        """
        match self:
            case Precision.COMPLEX_64:
                return np.complex64  # ty:ignore[invalid-return-type]
            case _:
                return np.complex128  # ty:ignore[invalid-return-type]





[docs]
class QiliSDKSettings(BaseSettings):
    """
    Environment-based configuration settings for QiliSDK.

    These settings are automatically loaded from environment variables
    prefixed with `QILISDK_`, or from a local `.env` file if present.
    """


[docs]
    model_config = SettingsConfigDict(
        env_prefix="qilisdk_", env_file=".env", env_file_encoding="utf-8", dotenv_filtering="match_prefix"
    )



[docs]
    complex_precision: Precision = Field(default=Precision.COMPLEX_128, description="[env: QILISDK_COMPLEX_PRECISION]")


[docs]
    logging_config_path: Path = Field(
        default_factory=default_logging_config_path,
        description="YAML file used for logging configuration. [env: QILISDK_LOGGING_CONFIG_PATH]",
    )


[docs]
    speqtrum_username: str | None = Field(
        default=None,
        description="SpeQtrum username used for authentication. [env: QILISDK_SPEQTRUM_USERNAME]",
    )


[docs]
    speqtrum_apikey: SecretStr | None = Field(
        default=None,
        description="SpeQtrum API key associated with the user account. [env: QILISDK_SPEQTRUM_APIKEY]",
    )


[docs]
    speqtrum_api_url: str = Field(
        default="https://qilimanjaro.ddns.net/public-api/api/v1",
        description="Base URL of the SpeQtrum API endpoint. [env: QILISDK_SPEQTRUM_API_URL]",
    )


[docs]
    speqtrum_audience: str = Field(
        default="urn:qilimanjaro.tech:public-api:beren",
        description="Audience claim expected in the JWT used for authentication. [env: QILISDK_SPEQTRUM_AUDIENCE]",
    )


[docs]
    atol: float = Field(
        default=1e-10,
        description="Numerical tolerance below which values are considered zero. [env: QILISDK_ATOL]",
        gt=0.0,
        lt=1.0,
    )


[docs]
    rtol: float = Field(
        default=1e-5,
        description="Numerical relative tolerance below which values are considered zero. [env: QILISDK_RTOL]",
        gt=0.0,
        lt=1.0,
    )




@lru_cache(maxsize=1)

[docs]
def get_settings() -> QiliSDKSettings:
    """
    Returns a singleton instance of QiliSDKSettings.

    This function caches the parsed environment-based settings to avoid
    redundant re-parsing across the application lifecycle.

    Returns:
        QiliSDKSettings: The cached configuration object populated from environment variables.
    """
    return QiliSDKSettings()