Samara 0.3__tar.gz → 0.4__tar.gz

{samara-0.3 → samara-0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Samara
-Version: 0.3
+Version: 0.4
 Summary: Config Driven ETL Framework
 License-File: LICENSE
 Author: Krijn van der Burg
@@ -9,7 +9,6 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: click (>=8.1.0,<9.0.0)
-Requires-Dist: email-validator (>=2.2.0,<3.0.0)
 Requires-Dist: numpy (<2.0.0)
 Requires-Dist: opentelemetry-api (>=1.37.0,<2.0.0)
 Requires-Dist: opentelemetry-exporter-otlp (>=1.37.0,<2.0.0)
@@ -74,7 +73,6 @@ poetry install
 ### Run an example pipeline
 ```bash
 python -m samara run \
-  --alert-filepath="examples/yaml_products_cleanup/alert.yaml" \
   --workflow-filepath="examples/yaml_products_cleanup/job.yaml"
 ```
 
@@ -86,7 +84,6 @@ Samara's documentation guides you through installation, configuration, and devel
 - **[CLI Reference](./docs/cli.md)** - Command-line interface options and examples
 - **[Configuration Reference](./docs/README.md)** - Complete syntax guide for all configuration options
   - **[Workflow System](./docs/workflow/README.md)** - ETL pipeline configuration (extracts, transforms, loads)
-  - **[Alert System](./docs/alert/README.md)** - Error handling and notification configuration
 - **[Architecture](./docs/architecture.md)** - Design principles and framework structure
 - **[Custom Extensions](./docs/architecture.md#extending-with-custom-transforms)** - Building your own transforms
 

{samara-0.3 → samara-0.4}/README.md

@@ -46,7 +46,6 @@ poetry install
 ### Run an example pipeline
 ```bash
 python -m samara run \
-  --alert-filepath="examples/yaml_products_cleanup/alert.yaml" \
   --workflow-filepath="examples/yaml_products_cleanup/job.yaml"
 ```
 
@@ -58,7 +57,6 @@ Samara's documentation guides you through installation, configuration, and devel
 - **[CLI Reference](./docs/cli.md)** - Command-line interface options and examples
 - **[Configuration Reference](./docs/README.md)** - Complete syntax guide for all configuration options
   - **[Workflow System](./docs/workflow/README.md)** - ETL pipeline configuration (extracts, transforms, loads)
-  - **[Alert System](./docs/alert/README.md)** - Error handling and notification configuration
 - **[Architecture](./docs/architecture.md)** - Design principles and framework structure
 - **[Custom Extensions](./docs/architecture.md#extending-with-custom-transforms)** - Building your own transforms
 

{samara-0.3 → samara-0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "Samara"
-version = "0.3"
+version = "0.4"
 description = "Config Driven ETL Framework"
 authors = ["Krijn van der Burg"]
 readme = "README.md"
@@ -17,7 +17,6 @@ requests = "^2.32.5"
 structlog = "^25.4.0"
 pydantic = "^2.11.9"
 pydantic-settings = "^2.8.0"
-email-validator = "^2.2.0"
 pyjson5 = "^1.6.9"
 click = "^8.1.0"
 # OpenTelemetry core packages - using compatible versions

{samara-0.3 → samara-0.4}/src/samara/__init__.py

@@ -7,7 +7,6 @@ engines and extensible components.
 
 Key capabilities:
     - Define pipelines via configuration (sources, transforms, destinations)
-    - Configurable alert system with multiple notification channels
     - Event-triggered custom actions at pipeline stages
     - Engine-agnostic configuration supporting different backends
 
@@ -21,7 +20,6 @@ Example:
 
 See Also:
     - Configuration format documentation in docs/
-    - Alert system setup in docs/alert/
     - Available transforms and operations documentation
 """
 
@@ -38,6 +36,7 @@ from abc import ABC
 from datetime import datetime, timezone
 
 from pydantic import BaseModel as PydanticBaseModel
+from pydantic import ConfigDict
 
 # Generate a run identifier as early as possible so the entire application
 # can reference the same run id. This is created at import time and is
@@ -98,3 +97,6 @@ class BaseModel(PydanticBaseModel, ABC):
     See Also:
         pydantic.BaseModel: For configuration validation framework details
     """
+
+    # Consider enabling extra="forbid"
+    model_config = ConfigDict()

{samara-0.3 → samara-0.4}/src/samara/cli.py

@@ -2,24 +2,20 @@
 
 This module provides command-line interface commands for managing ETL pipelines
 through configuration files. It focuses on three core operations: validating
-pipeline configurations with optional alert testing, executing pipelines with
-integrated alerting, and exporting JSON schemas for configuration documentation.
+pipeline configurations, executing pipelines, and exporting JSON schemas for
+configuration documentation.
 
 All commands support detailed error handling and proper exit codes to facilitate
 CI/CD integration and operational monitoring.
 """
 
 import json
-import os
 from pathlib import Path
 
 import click
 
-from samara.alert import AlertController
 from samara.exceptions import (
     ExitCode,
-    SamaraAlertConfigurationError,
-    SamaraAlertTestError,
     SamaraIOError,
     SamaraValidationError,
     SamaraWorkflowConfigurationError,
@@ -76,7 +72,7 @@ def cli(
 
     Build and execute data workflows through declarative JSON/YAML configuration
     instead of writing code. Define extracts, transforms, and loads with built-in
-    support for alerts, validation, and schema management.
+    support for validation and schema management.
 
     Args:
         log_level: The logging level as a string. Must be one of DEBUG, INFO,
@@ -94,7 +90,7 @@ def cli(
 
     Commands:
         validate: Validate workflow configurations without execution
-        run: Execute workflow with integrated alerting
+        run: Execute workflow
         export-schema: Generate JSON schema for workflow configs
     """
     settings = get_settings()
@@ -112,120 +108,46 @@ def cli(
 
 
 @cli.command()
-@click.option(
-    "--alert-filepath",
-    required=True,
-    type=click.Path(exists=False, path_type=Path),
-    help="Path to alert configuration file",
-)
 @click.option(
     "--workflow-filepath",
     required=True,
     type=click.Path(exists=False, path_type=Path),
     help="Path to workflow configuration file",
 )
-@click.option(
-    "--test-exception",
-    type=str,
-    default=None,
-    help="Test exception message to trigger alert testing",
-)
-@click.option(
-    "--test-env-var",
-    multiple=True,
-    type=str,
-    help="Test env vars (KEY=VALUE)",
-)
 @trace_span("validate_workflow")
 def validate(
-    alert_filepath: Path,
     workflow_filepath: Path,
-    test_exception: str | None,
-    test_env_var: tuple[str, ...],
 ) -> None:
-    """Validate workflow configuration files with optional alert testing.
+    """Validate workflow configuration files.
 
-    Load and validate both alert and workflow configuration files to ensure they
-    conform to expected schemas and contain valid settings. This command performs
-    fail-fast validation without alerting on configuration errors (unlike the run
-    command), making it suitable for local development and CI/CD workflows where
-    validation failures should not trigger alerts.
-
-    Optionally trigger a test alert to verify alert system functionality using
-    a test exception message or environment variables.
+    Load and validate the workflow configuration file to ensure it conforms
+    to the expected schema and contains valid settings. This command performs
+    fail-fast validation, making it suitable for local development and CI/CD
+    workflows.
 
     Args:
-        alert_filepath: Path to the alert configuration file in JSON or YAML
-            format. The file must exist and contain valid alert configuration
-            with triggers and channels.
         workflow_filepath: Path to the workflow configuration file in JSON
             or YAML format. The file must exist and define valid workflow
             extracts, transforms, and loads.
-        test_exception: Optional test exception message string. When provided,
-            triggers a test alert to verify alert system functionality. If
-            provided with test_env_var, this takes precedence for the message.
-        test_env_var: Optional environment variables to set before validation
-            in KEY=VALUE format. Useful for testing environment-dependent
-            configurations without affecting system environment permanently.
 
     Raises:
         click.exceptions.Exit: Exits with appropriate exit code on error.
-
-    Note:
-        This command does NOT send alerts on configuration errors, only on
-        test alerts if explicitly requested. This prevents alert fatigue
-        during development and validation cycles. For the actual workflow
-        execution with alert integration, use the 'run' command.
     """
     try:
         logger.info("Starting `validate` command")
         logger.info("Workflow config: %s", str(workflow_filepath))
-        logger.info("Alert config: %s", str(alert_filepath))
-
-        # Parse test env vars
-        test_env_vars = None
-        if test_env_var:
-            test_env_vars = {}
-            for env_var_str in test_env_var:
-                key, value = env_var_str.split("=", 1)
-                test_env_vars[key] = value
-
-        # Set test env vars if provided
-        if test_env_vars:
-            for key, value in test_env_vars.items():
-                os.environ[key] = value
-
-        try:
-            alert = AlertController.from_file(filepath=alert_filepath)
-        except SamaraIOError as e:
-            logger.error("Cannot access alert configuration file: %s", e)
-            raise click.exceptions.Exit(e.exit_code)
-        except SamaraAlertConfigurationError as e:
-            logger.error("Alert configuration is invalid: %s", e)
-            raise click.exceptions.Exit(e.exit_code)
 
         try:
             _ = WorkflowController.from_file(filepath=workflow_filepath)
-            # Not alerting on exceptions as a validate command is often run locally or from CICD
-            # and thus an alert would be drowning out real alerts
         except SamaraIOError as e:
             logger.error("Cannot access workflow configuration file: %s", e)
-            raise click.exceptions.Exit(e.exit_code)
+            raise click.exceptions.Exit(e.exit_code) from e
         except SamaraWorkflowConfigurationError as e:
             logger.error("Workflow configuration is invalid: %s", e)
-            raise click.exceptions.Exit(e.exit_code)
+            raise click.exceptions.Exit(e.exit_code) from e
         except SamaraValidationError as e:
             logger.error("Validation failed: %s", e)
-            raise click.exceptions.Exit(e.exit_code)
-
-        # Trigger test exception if specified (either message or env vars)
-        if test_exception or test_env_vars:
-            try:
-                message = test_exception or "Test alert triggered"
-                raise SamaraAlertTestError(message)
-            except SamaraAlertTestError as e:
-                alert.evaluate_trigger_and_alert(title="Test Alert", body="Test alert", exception=e)
-                raise click.exceptions.Exit(e.exit_code)
+            raise click.exceptions.Exit(e.exit_code) from e
 
         logger.info("Workflow validation completed successfully")
         logger.info("Command executed successfully with exit code %d (%s).", ExitCode.SUCCESS, ExitCode.SUCCESS.name)
@@ -243,12 +165,6 @@ def validate(
 
 
 @cli.command()
-@click.option(
-    "--alert-filepath",
-    required=True,
-    type=click.Path(exists=False, path_type=Path),
-    help="Path to alert configuration file",
-)
 @click.option(
     "--workflow-filepath",
     required=True,
@@ -257,47 +173,25 @@ def validate(
 )
 @trace_span("run_pipeline")
 def run(
-    alert_filepath: Path,
     workflow_filepath: Path,
 ) -> None:
-    """Execute the workflow with integrated alert monitoring.
+    """Execute the workflow.
 
-    Load workflow and alert configurations, then execute the complete workflow.
+    Load the workflow configuration, then execute the complete workflow.
     The workflow processes all defined jobs in sequence, applying configured
     transforms to ingest, transform, and load data according to specifications.
-    Errors during workflow execution are captured and alerts are sent based on
-    configured alert rules and triggers.
 
     Args:
-        alert_filepath: Path to the alert configuration file in JSON or YAML
-            format. Defines alert channels (email, HTTP, file) and trigger rules
-            that determine when and how alerts are sent during execution.
         workflow_filepath: Path to the workflow configuration file in JSON or YAML
             format. Defines the complete workflow including data sources,
             transformation chains, and output destinations.
 
     Raises:
         click.exceptions.Exit: Exits with appropriate exit code on error.
-
-    Note:
-        All exceptions during workflow execution trigger alert evaluation,
-        allowing configured alert rules to send notifications based on
-        error type and severity. This enables operational visibility into
-        workflow failures and automating incident response workflows.
     """
     try:
         logger.info("Starting `run` command")
         logger.info("Workflow config: %s", str(workflow_filepath))
-        logger.info("Alert config: %s", str(alert_filepath))
-
-        try:
-            alert = AlertController.from_file(filepath=alert_filepath)
-        except SamaraIOError as e:
-            logger.error("Cannot access alert configuration file: %s", e)
-            raise click.exceptions.Exit(e.exit_code)
-        except SamaraAlertConfigurationError as e:
-            logger.error("Alert configuration is invalid: %s", e)
-            raise click.exceptions.Exit(e.exit_code)
 
         try:
             workflow = WorkflowController.from_file(filepath=workflow_filepath)
@@ -309,30 +203,16 @@ def run(
             )
         except SamaraIOError as e:
             logger.error("Cannot access workflow configuration file: %s", e)
-            alert.evaluate_trigger_and_alert(
-                title="Workflow Configuration File Error",
-                body="Failed to read workflow configuration file",
-                exception=e,
-            )
-            raise click.exceptions.Exit(e.exit_code)
+            raise click.exceptions.Exit(e.exit_code) from e
         except SamaraWorkflowConfigurationError as e:
             logger.error("Workflow configuration is invalid: %s", e)
-            alert.evaluate_trigger_and_alert(
-                title="Workflow Configuration Error", body="Invalid workflow configuration", exception=e
-            )
-            raise click.exceptions.Exit(e.exit_code)
+            raise click.exceptions.Exit(e.exit_code) from e
         except SamaraValidationError as e:
             logger.error("Configuration validation failed: %s", e)
-            alert.evaluate_trigger_and_alert(
-                title="Workflow Validation Error", body="Configuration validation failed", exception=e
-            )
-            raise click.exceptions.Exit(e.exit_code)
+            raise click.exceptions.Exit(e.exit_code) from e
         except SamaraWorkflowError as e:
             logger.error("Workflow job failed: %s", e)
-            alert.evaluate_trigger_and_alert(
-                title="Workflow Execution Error", body="Workflow error during execution", exception=e
-            )
-            raise click.exceptions.Exit(e.exit_code)
+            raise click.exceptions.Exit(e.exit_code) from e
 
     except click.exceptions.Exit:
         # Re-raise Click's Exit exceptions (these are our controlled exits with proper codes)

{samara-0.3 → samara-0.4}/src/samara/exceptions.py

@@ -28,11 +28,10 @@ class ExitCode(enum.IntEnum):
     INVALID_ARGUMENTS = 10
     IO_ERROR = 20
     CONFIGURATION_ERROR = 30
-    ALERT_CONFIGURATION_ERROR = 31
     WORKFLOW_CONFIGURATION_ERROR = 32
     VALIDATION_ERROR = 40
-    ALERT_TEST_ERROR = 41
     JOB_ERROR = 50
+    ACTION_ERROR = 51
     KEYBOARD_INTERRUPT = 98
     UNEXPECTED_ERROR = 99
 
@@ -79,22 +78,6 @@ class SamaraIOError(SamaraError):
         super().__init__(message=message, exit_code=ExitCode.IO_ERROR)
 
 
-class SamaraAlertConfigurationError(SamaraError):
-    """Raise when alert configuration is invalid.
-
-    Indicates issues with alert definition JSON/YAML including invalid
-    channels, triggers, or template configuration.
-    """
-
-    def __init__(self, message: str) -> None:
-        """Initialize the exception.
-
-        Args:
-            message: Description of the configuration error
-        """
-        super().__init__(message=message, exit_code=ExitCode.CONFIGURATION_ERROR)
-
-
 class SamaraWorkflowConfigurationError(SamaraError):
     """Raise when workflow configuration is invalid.
 
@@ -127,33 +110,34 @@ class SamaraValidationError(SamaraError):
         super().__init__(message=message, exit_code=ExitCode.VALIDATION_ERROR)
 
 
-class SamaraAlertTestError(SamaraError):
-    """Raise when alert system testing fails.
+class SamaraWorkflowError(SamaraError):
+    """Raise when ETL job execution fails.
 
-    Indicates failure during alert channel validation or test execution,
-    including delivery failures or notification errors.
+    Covers errors during data extraction, transformation, or loading phases
+    including engine failures or transformation logic errors.
     """
 
     def __init__(self, message: str) -> None:
         """Initialize the exception.
 
         Args:
-            message: Description of the alert test error
+            message: Description of the job execution error
         """
-        super().__init__(message=message, exit_code=ExitCode.ALERT_TEST_ERROR)
+        super().__init__(message=message, exit_code=ExitCode.JOB_ERROR)
 
 
-class SamaraWorkflowError(SamaraError):
-    """Raise when ETL job execution fails.
+class SamaraActionError(SamaraError):
+    """Raise when a lifecycle hook action fails to execute.
 
-    Covers errors during data extraction, transformation, or loading phases
-    including engine failures or transformation logic errors.
+    Wraps any exception raised by an action's implementation (e.g. HTTP,
+    email, file actions) so callers can catch a single, specific type
+    instead of a bare `Exception`.
     """
 
     def __init__(self, message: str) -> None:
         """Initialize the exception.
 
         Args:
-            message: Description of the job execution error
+            message: Description of the action execution error
         """
-        super().__init__(message=message, exit_code=ExitCode.JOB_ERROR)
+        super().__init__(message=message, exit_code=ExitCode.ACTION_ERROR)

{samara-0.3 → samara-0.4}/src/samara/settings.py

@@ -27,8 +27,9 @@ Typical Usage:
 """
 
 from functools import lru_cache
+from typing import Literal
 
-from pydantic import Field
+from pydantic import AnyHttpUrl, Field, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
@@ -142,13 +143,31 @@ class AppSettings(BaseSettings):
         case_sensitive=False,
     )
 
-    log_level: str | None = Field(default=None, description="Logging level of the system")
+    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | None = Field(
+        default=None, description="Logging level of the system"
+    )
     environment: str | None = Field(default=None, description="Deployment environment (dev, test, acc, prod)")
     trace_parent: str | None = Field(default=None, description="W3C Trace Context traceparent for distributed tracing")
     trace_state: str | None = Field(default=None, description="W3C Trace Context tracestate for distributed tracing")
     otlp_traces_endpoint: str | None = Field(default=None, description="OTLP endpoint for exporting traces")
     otlp_logs_endpoint: str | None = Field(default=None, description="OTLP endpoint for exporting logs")
 
+    @field_validator("log_level", mode="before")
+    @classmethod
+    def _normalize_log_level(cls, value: str | None) -> str | None:
+        """Uppercase the log level so env values like 'debug' validate."""
+        if isinstance(value, str):
+            return value.upper()
+        return value
+
+    @field_validator("otlp_traces_endpoint", "otlp_logs_endpoint")
+    @classmethod
+    def _validate_url(cls, value: str | None) -> str | None:
+        """Reject OTLP endpoints that are not valid HTTP(S) URLs."""
+        if value is not None:
+            AnyHttpUrl(value)  # raises pydantic.ValidationError on invalid URL
+        return value
+
 
 @lru_cache
 def get_settings() -> AppSettings:

{samara-0.3 → samara-0.4}/src/samara/utils/http.py

@@ -1,10 +1,9 @@
 """HTTP utilities for Samara's configuration-driven data pipeline framework.
 
-Provides reusable HTTP functionality for alert channels and event hook actions,
-enabling reliable communication through configurable retry logic, timeout handling,
-and standardized request execution. Supports the declarative configuration model
-by allowing HTTP endpoints and behaviors to be specified in configuration files
-rather than code.
+Provides reusable HTTP functionality for event hook actions, enabling reliable
+communication through configurable retry logic, timeout handling, and standardized
+request execution. Supports the declarative configuration model by allowing HTTP
+endpoints and behaviors to be specified in configuration files rather than code.
 """
 
 import json
@@ -53,13 +52,13 @@ class Retry(BaseModel):
 
 
 class HttpBase(BaseModel):
-    """Base HTTP configuration for alerts and event hooks in Samara pipelines.
+    """Base HTTP configuration for event hooks in Samara pipelines.
 
-    Provides shared HTTP request handling for alert notifications and event-triggered
-    actions. Supports the framework's configuration-driven model by allowing HTTP
-    endpoints, methods, headers, and retry behavior to be defined in configuration
-    files. Used by alert channels and actions to communicate with external HTTP
-    endpoints, webhooks, and services.
+    Provides shared HTTP request handling for event-triggered actions. Supports
+    the framework's configuration-driven model by allowing HTTP endpoints,
+    methods, headers, and retry behavior to be defined in configuration files.
+    Used by actions to communicate with external HTTP endpoints, webhooks, and
+    services.
 
     Attributes:
         url: HTTP endpoint URL for sending requests.
@@ -113,8 +112,8 @@ class HttpBase(BaseModel):
         """Execute an HTTP request with configurable retry logic and error handling.
 
         Sends an HTTP request with the configured method, headers, timeout, and retry
-        behavior. Handles transient failures gracefully through exponential backoff
-        retry logic. On success, logs the request completion; on final failure after
+        behavior. Handles transient failures gracefully through fixed-delay retry
+        logic. On success, logs the request completion; on final failure after
         all retries, logs the error and raises the underlying exception.
 
         Args:
@@ -151,3 +150,4 @@ class HttpBase(BaseModel):
                     time.sleep(self.retry.delay_in_seconds)
                 else:
                     logger.error("HTTP request failed after %d attempts: %s", self.retry.max_attempts + 1, e)
+                    raise

{samara-0.3 → samara-0.4}/src/samara/workflow/actions/base.py

@@ -81,6 +81,10 @@ class ActionBase(BaseModel):
             ...     recipients=["user@example.com"]
             ... )
             >>> action.execute()  # Executes the email action
+
+        Raises:
+            SamaraActionError: If the action's implementation fails. Implementations
+                must catch their own specific exception types and raise this.
         """
         if not self.enabled:
             logger.debug("Action '%s' is disabled; skipping execution.", self.id_)
@@ -96,11 +100,10 @@ class ActionBase(BaseModel):
         writing to files).
 
         Raises:
-            NotImplementedError: When called on ActionBase directly or if subclass
-                does not provide an implementation.
+            SamaraActionError: Implementations must catch their own known failure
+                modes (e.g. `requests.RequestException`, `OSError`) and raise this
+                so callers can rely on a single, specific exception type.
 
         Note:
             This method is only called by execute() if the action is enabled.
-            Implementation should handle any failures appropriately, using logging
-            for debugging and raising exceptions for unexpected errors.
         """

{samara-0.3 → samara-0.4}/src/samara/workflow/actions/http.py

@@ -8,9 +8,11 @@ payloads, timeouts, and retry logic for robust external integrations.
 
 from typing import Any, Literal
 
+import requests
 from pydantic import Field
 from typing_extensions import override
 
+from samara.exceptions import SamaraActionError
 from samara.telemetry import trace_span
 from samara.utils.http import HttpBase
 from samara.utils.logger import get_logger
@@ -118,9 +120,9 @@ class HttpAction(HttpBase, ActionBase):
         successful requests and failures for observability.
 
         Raises:
-            requests.RequestException: If the HTTP request fails after exhausting
-                all configured retry attempts, including connection errors,
-                timeouts, or non-2xx HTTP responses.
+            SamaraActionError: If the HTTP request fails after exhausting all
+                configured retry attempts, including connection errors, timeouts,
+                or non-2xx HTTP responses.
 
         Note:
             Even if this action fails, the pipeline continues execution as
@@ -128,5 +130,8 @@ class HttpAction(HttpBase, ActionBase):
             details if requests fail unexpectedly.
         """
         logger.info("Executing HTTP action: %s", self.id_)
-        self._make_http_request(self.payload)
+        try:
+            self._make_http_request(self.payload)
+        except requests.RequestException as e:
+            raise SamaraActionError(f"Action '{self.id_}' failed: {e}") from e
         logger.info("HTTP action completed: %s", self.id_)