haystack-enterprise-sdk 0.1.0__py3-none-any.whl

haystack_enterprise_sdk/README.md

@@ -0,0 +1,42 @@
+# Software development kit for the deepset API
+
+This package is split into multiple layers:
+- API layer
+- Client layer
+- Service layer
+- Workflow layer
+
+
+### API layer
+This layer is the lowest level of abstraction and contains the API definition, including all HTTP methods. It takes care of the authentication.
+You can find this layer in the `haystack_enterprise_sdk/_api/haystack_enterprise_api.py` file. We should implement reties on this lowest layer.
+
+### Client layer
+This layer adds a thin wrapper around the API layer and provides a more convenient interface to the API. It includes explicit methods
+for endpoints by specifying the HTTP methods and endpoints for example for uploading files.
+
+### Service layer
+This layer takes care of combining client methods to provide more complex functionality. Within this layer, we can add functionalities like
+creating sessions, uploading files, and closing sessions.
+
+### Workflow layer
+Public methods for users. These workflows are split into async and sync implementation.
+
+
+## Software architecture principles
+
+### Factories
+We are using factories implemented like this:
+```python
+@classmethod
+async def factory(cls, config: CommonConfig) -> YourClass:
+    """Create a new instance of the API client.
+
+    :param config: CommonConfig object.
+    """
+    yield cls(config)
+```
+
+### Tests
+We are using the classical pyramid of tests: unit tests (for each layer), integration tests. The goal is to gradually test each layer and
+then test the whole stack once within the integration tests.

haystack_enterprise_sdk/__init__.py

@@ -0,0 +1,89 @@
+"""This is the entrypoint for the package."""
+
+import logging
+
+import structlog
+
+from haystack_enterprise_sdk._api.deployments import (
+    DeploymentMode,
+    DeploymentServiceLevel,
+    PipelineValidationError,
+    PipelineValidationIssue,
+    PipelineValidationResult,
+)
+from haystack_enterprise_sdk._api.pipeline_run import PipelineRunError
+from haystack_enterprise_sdk._api.shared_prototypes import (
+    FailedToCreateSharedPrototypeError,
+    SharedPrototype,
+)
+from haystack_enterprise_sdk._service.deployment_service import (
+    CreateOptions,
+    DeploymentFailedError,
+    DeployResult,
+    ServiceNotFoundError,
+    ShareOptions,
+)
+from haystack_enterprise_sdk._service.pipeline_service import (
+    ErrorDetail,
+    HaystackEnterpriseValidationError,
+)
+from haystack_enterprise_sdk._service.pipeline_transform import (
+    PipelineSettings,
+    PipelineTransformError,
+)
+from haystack_enterprise_sdk.models import (
+    BaseConfig,
+    IndexConfig,
+    IndexInputs,
+    IndexOutputs,
+    PipelineConfig,
+    PipelineInputs,
+    PipelineOutputs,
+    PipelineOutputType,
+)
+from haystack_enterprise_sdk.workflows.async_client.async_pipeline_client import (
+    AsyncPipelineClient,
+)
+from haystack_enterprise_sdk.workflows.async_client.deployment_client import (
+    AsyncDeploymentClient,
+)
+from haystack_enterprise_sdk.workflows.sync_client.deployment_client import DeploymentClient
+from haystack_enterprise_sdk.workflows.sync_client.pipeline_client import PipelineClient
+
+structlog.configure(
+    wrapper_class=structlog.make_filtering_bound_logger(logging.INFO),
+)
+
+log = structlog.get_logger()
+
+__all__ = [
+    "AsyncPipelineClient",
+    "BaseConfig",
+    "ErrorDetail",
+    "PipelineClient",
+    "PipelineConfig",
+    "PipelineInputs",
+    "PipelineOutputs",
+    "IndexConfig",
+    "IndexInputs",
+    "IndexOutputs",
+    "HaystackEnterpriseValidationError",
+    "PipelineOutputType",
+    "DeploymentClient",
+    "AsyncDeploymentClient",
+    "CreateOptions",
+    "DeploymentMode",
+    "DeploymentServiceLevel",
+    "DeployResult",
+    "ShareOptions",
+    "SharedPrototype",
+    "DeploymentFailedError",
+    "ServiceNotFoundError",
+    "FailedToCreateSharedPrototypeError",
+    "PipelineSettings",
+    "PipelineTransformError",
+    "PipelineValidationError",
+    "PipelineValidationResult",
+    "PipelineValidationIssue",
+    "PipelineRunError",
+]

haystack_enterprise_sdk/_api/config.py

@@ -0,0 +1,135 @@
+"""Config for loading env variables and setting default values."""
+
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+import structlog
+from dotenv import load_dotenv
+
+logger = structlog.get_logger(__name__)
+
+ENV_FILE_PATH = Path.home() / ".haystack-enterprise" / ".env"
+
+# The deepset platform base URL (without a version suffix).
+PLATFORM_URL = "https://api.cloud.deepset.ai"
+
+# The API version path appended to the base URL when building requests.
+API_VERSION_PATH = "api/v1"
+
+# Matches a trailing version segment like `/api/v1`, `/v1`, `/v2`, ... (case-insensitive),
+# optionally followed by a trailing slash.
+_VERSION_SUFFIX_RE = re.compile(r"/(?:api/)?v\d+/?$", re.IGNORECASE)
+
+
+def normalize_base_url(url: str) -> str:
+    """Normalize an API URL to a bare base URL without a version suffix.
+
+    Strips a trailing version segment (`/api/v1`, `/v1`, `/v2`, ...) and any trailing slash,
+    so both fresh base URLs and legacy full URLs (or pasted URLs including the version) resolve
+    to the same base. The SDK appends the version (:data:`API_VERSION_PATH`) when building requests.
+
+    :param url: The API URL to normalize.
+    :return: The base URL without a trailing version segment or slash.
+    """
+    url = _VERSION_SUFFIX_RE.sub("", url)
+    return url.rstrip("/")
+
+
+def load_environment(show_warnings: bool = True) -> bool:
+    """Load environment variables using a cascading fallback model.
+
+    1. Load local .env file in current directory if it exists
+    2. Load from global ~/.haystack-enterprise/.env to supplement local .env file
+    3. Environment variables can override both local and global .env files
+
+    :param show_warnings: Whether to show warnings about missing files/variables
+    :return: True if required environment variables were loaded successfully, False otherwise.
+    """
+    current_path_env = Path.cwd() / ".env"
+    local_loaded = current_path_env.is_file() and load_dotenv(current_path_env)
+    global_loaded = ENV_FILE_PATH.is_file() and load_dotenv(ENV_FILE_PATH, override=False)
+
+    # These success messages are gated on ``show_warnings`` so the import-time call
+    # (``show_warnings=False``) stays silent, before structlog is even configured.
+    if show_warnings:
+        if local_loaded:
+            logger.info(f"Environment variables successfully loaded from local .env file at {current_path_env}.")
+        if global_loaded:
+            if local_loaded:
+                logger.info(f"Loaded global .env file at {ENV_FILE_PATH} to supplement local .env file.")
+            else:
+                logger.info(f"Environment variables successfully loaded from global .env file at {ENV_FILE_PATH}.")
+
+    if not (local_loaded or global_loaded) and show_warnings:
+        logger.warning(
+            "No .env files found. Run `haystack-enterprise login` to create a global configuration file. "
+            "You can also create a custom local .env file in your project directory."
+        )
+        return False
+
+    # Check for required environment variables
+    required_vars = ["API_KEY", "API_URL", "DEFAULT_WORKSPACE_NAME"]
+    missing_vars = [var for var in required_vars if not os.getenv(var)]
+
+    if missing_vars and show_warnings:
+        logger.warning(
+            f"Missing required environment variables: {', '.join(missing_vars)}. "
+            "Run `haystack-enterprise login` to set up your configuration or set these variables "
+            "manually in your .env file."
+        )
+        return False
+
+    return True
+
+
+# Load environment variables silently at import time to support CLI commands that depend on .env files.
+# Warnings are only shown later in CommonConfig when users don't provide explicit parameters
+# and the config values fall back to global defaults.
+load_environment(show_warnings=False)
+
+# connection to Haystack Enterprise Platform
+API_URL: str = os.getenv("API_URL", PLATFORM_URL)
+
+API_KEY: str = os.getenv("API_KEY", "")
+
+# configuration to use a selected workspace
+DEFAULT_WORKSPACE_NAME: str = os.getenv("DEFAULT_WORKSPACE_NAME", "")
+
+ASYNC_CLIENT_TIMEOUT: int = int(os.getenv("ASYNC_CLIENT_TIMEOUT", "300"))
+
+
+@dataclass
+class CommonConfig:
+    """Common config for connecting to the Haystack Enterprise Platform.
+
+    Configuration is loaded in the following order of precedence:
+    1. Explicit parameters passed to this class
+    2. Environment variables
+    3. Local .env file in project root
+    4. Global .env file in ~/.haystack-enterprise/ (supplements local .env)
+    5. Built-in defaults
+    """
+
+    api_key: str = ""
+    api_url: str = ""
+    safe_mode: bool = False
+
+    def __post_init__(self) -> None:
+        """Validate config."""
+        # Only try loading from environment if user didn't provide explicit parameters)
+        if not self.api_key or not self.api_url:
+            load_environment(show_warnings=True)
+            if not self.api_key:
+                self.api_key = os.getenv("API_KEY", "")
+            if not self.api_url:
+                self.api_url = os.getenv("API_URL", PLATFORM_URL)
+
+        if not self.api_key:
+            raise ValueError(
+                "API key is required. Either set the API_KEY environment variable or pass api_key parameter. Go to [API Keys](https://cloud.deepset.ai/settings/api-keys) in Haystack Enterprise Platform to get an API key."
+            )
+
+        # Normalize to a bare base URL; the version suffix is appended when building requests.
+        self.api_url = normalize_base_url(self.api_url)