sibi-dst 2025.8.6__py3-none-any.whl → 2025.8.8__py3-none-any.whl

sibi_dst/utils/log_utils.py

@@ -363,349 +363,3 @@ class Logger:
         self._otel_initialized_names.add(self.logger_name)
         self._core_logger.info("OpenTelemetry logging/tracing initialized.")
 
-# from __future__ import annotations
-#
-# import logging
-# import os
-# import sys
-# import time
-# from contextlib import contextmanager
-# from logging import LoggerAdapter
-# from logging.handlers import RotatingFileHandler
-# from typing import Optional, Dict, Any
-#
-# # OpenTelemetry imports
-# from opentelemetry import trace
-# from opentelemetry._logs import set_logger_provider
-# from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter
-# from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
-# from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
-# from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
-# from opentelemetry.sdk.resources import Resource
-# from opentelemetry.sdk.trace import TracerProvider
-# from opentelemetry.sdk.trace.export import BatchSpanProcessor
-# from opentelemetry.trace import Tracer as OTelTracer
-#
-#
-# class Logger:
-#     """
-#     Handles the creation and management of logging, with optional OpenTelemetry integration.
-#     """
-#
-#     DEBUG = logging.DEBUG
-#     INFO = logging.INFO
-#     WARNING = logging.WARNING
-#     ERROR = logging.ERROR
-#     CRITICAL = logging.CRITICAL
-#
-#     def __init__(
-#         self,
-#         log_dir: str,
-#         logger_name: str,
-#         log_file: str,
-#         log_level: int = logging.DEBUG,
-#         enable_otel: bool = False,
-#         otel_service_name: Optional[str] = None,
-#         otel_stream_name: Optional[str] = None,
-#         otel_endpoint: str = "0.0.0.0:4317",
-#         otel_insecure: bool = False,
-#     ):
-#         self.log_dir = log_dir
-#         self.logger_name = logger_name
-#         self.log_file = log_file
-#         self.log_level = log_level
-#
-#         self.enable_otel = enable_otel
-#         self.otel_service_name = (otel_service_name or logger_name).strip() or "app"
-#         self.otel_stream_name = (otel_stream_name or "").strip() or None
-#         self.otel_endpoint = otel_endpoint
-#         self.otel_insecure = otel_insecure
-#
-#         self.logger_provider: Optional[LoggerProvider] = None
-#         self.tracer_provider: Optional[TracerProvider] = None
-#         self.tracer: Optional[OTelTracer] = None
-#
-#         # Internal logger vs public (adapter) logger
-#         self._core_logger: logging.Logger = logging.getLogger(self.logger_name)
-#         self.logger: logging.Logger | LoggerAdapter = self._core_logger
-#
-#         self._setup()
-#
-#     # -------------------------
-#     # Public API
-#     # -------------------------
-#
-#     @classmethod
-#     def default_logger(
-#         cls,
-#         log_dir: str = "./logs/",
-#         logger_name: Optional[str] = None,
-#         log_file: Optional[str] = None,
-#         log_level: int = logging.INFO,
-#         enable_otel: bool = False,
-#         otel_service_name: Optional[str] = None,
-#         otel_stream_name: Optional[str] = None,
-#         otel_endpoint: str = "0.0.0.0:4317",
-#         otel_insecure: bool = False,
-#     ) -> "Logger":
-#         try:
-#             frame = sys._getframe(1)
-#             caller_name = frame.f_globals.get("__name__", "default_logger")
-#         except (AttributeError, ValueError):
-#             caller_name = "default_logger"
-#
-#         logger_name = logger_name or caller_name
-#         log_file = log_file or logger_name
-#
-#         return cls(
-#             log_dir=log_dir,
-#             logger_name=logger_name,
-#             log_file=log_file,
-#             log_level=log_level,
-#             enable_otel=enable_otel,
-#             otel_service_name=otel_service_name,
-#             otel_stream_name=otel_stream_name,
-#             otel_endpoint=otel_endpoint,
-#             otel_insecure=otel_insecure,
-#         )
-#
-#     def shutdown(self):
-#         """Flush and shut down logging and tracing providers, then Python logging."""
-#         try:
-#             if self.enable_otel:
-#                 if self.logger_provider:
-#                     try:
-#                         self._core_logger.info("Flushing OpenTelemetry logs...")
-#                         self.logger_provider.force_flush()
-#                     except Exception:
-#                         pass
-#                     try:
-#                         self._core_logger.info("Shutting down OpenTelemetry logs...")
-#                         self.logger_provider.shutdown()
-#                     except Exception:
-#                         pass
-#
-#                 if self.tracer_provider:
-#                     try:
-#                         self._core_logger.info("Flushing OpenTelemetry traces...")
-#                         self.tracer_provider.force_flush()
-#                     except Exception:
-#                         pass
-#                     try:
-#                         self._core_logger.info("Shutting down OpenTelemetry traces...")
-#                         self.tracer_provider.shutdown()
-#                     except Exception:
-#                         pass
-#         finally:
-#             logging.shutdown()
-#
-#     def set_level(self, level: int):
-#         """Set the logging level for the logger."""
-#         self._core_logger.setLevel(level)
-#
-#     # passthrough convenience methods
-#     def _log(self, level: int, msg: str, *args, **kwargs):
-#         extra = kwargs.pop("extra", None)
-#         if extra is not None:
-#             # Always emit via an adapter so extras survive to OTel attributes
-#             if isinstance(self.logger, LoggerAdapter):
-#                 merged = {**self.logger.extra, **extra}
-#                 LoggerAdapter(self.logger.logger, merged).log(level, msg, *args, **kwargs)
-#             else:
-#                 LoggerAdapter(self.logger, extra).log(level, msg, *args, **kwargs)
-#         else:
-#             self.logger.log(level, msg, *args, **kwargs)
-#
-#     def debug(self, msg: str, *args, **kwargs):
-#         self._log(logging.DEBUG, msg, *args, **kwargs)
-#
-#     def info(self, msg: str, *args, **kwargs):
-#         self._log(logging.INFO, msg, *args, **kwargs)
-#
-#     def warning(self, msg: str, *args, **kwargs):
-#         self._log(logging.WARNING, msg, *args, **kwargs)
-#
-#     def error(self, msg: str, *args, **kwargs):
-#         self._log(logging.ERROR, msg, *args, **kwargs)
-#
-#     def critical(self, msg: str, *args, **kwargs):
-#         self._log(logging.CRITICAL, msg, *args, **kwargs)
-#
-#
-#     def bind(self, **extra: Any) -> LoggerAdapter:
-#         """
-#         Return a new LoggerAdapter bound with extra context, merging with existing extras if present.
-#         Example:
-#             api_log = logger.bind(component="api", request_id=req.id)
-#             api_log.info("processing")
-#         """
-#         if isinstance(self.logger, LoggerAdapter):
-#             merged = {**self.logger.extra, **extra}
-#             return LoggerAdapter(self.logger.logger, merged)
-#         return LoggerAdapter(self.logger, extra)
-#
-#     @contextmanager
-#     def bound(self, **extra: Any):
-#         """
-#         Context manager that yields a bound adapter for temporary context.
-#         Example:
-#             with logger.bound(order_id=oid) as log:
-#                 log.info("starting")
-#                 ...
-#         """
-#         adapter = self.bind(**extra)
-#         try:
-#             yield adapter
-#         finally:
-#             # nothing to clean up; adapter is ephemeral
-#             pass
-#
-#     def start_span(self, name: str, attributes: Optional[Dict[str, Any]] = None):
-#         """
-#         Start a span as a context manager.
-#
-#         Usage:
-#             with logger.start_span("my-task", {"key": "value"}) as span:
-#                 ...
-#         """
-#         if not self.enable_otel or not self.tracer:
-#             self.warning("Tracing is disabled or not initialized. Cannot start span.")
-#             from contextlib import nullcontext
-#             return nullcontext()
-#
-#         cm = self.tracer.start_as_current_span(name)
-#
-#         class _SpanCtx:
-#             def __enter__(_self):
-#                 span = cm.__enter__()
-#                 if attributes:
-#                     for k, v in attributes.items():
-#                         try:
-#                             span.set_attribute(k, v)
-#                         except Exception:
-#                             pass
-#                 return span
-#
-#             def __exit__(_self, exc_type, exc, tb):
-#                 return cm.__exit__(exc_type, exc, tb)
-#
-#         return _SpanCtx()
-#
-#     def trace_function(self, span_name: Optional[str] = None):
-#         """Decorator to trace a function with an optional custom span name."""
-#         def decorator(func):
-#             def wrapper(*args, **kwargs):
-#                 name = span_name or func.__name__
-#                 with self.start_span(name):
-#                     return func(*args, **kwargs)
-#             return wrapper
-#         return decorator
-#
-#     # -------------------------
-#     # Internal setup
-#     # -------------------------
-#
-#     def _setup(self):
-#         """Set up core logger, handlers, and optional OTel."""
-#         # Configure base logger
-#         self._core_logger = logging.getLogger(self.logger_name)
-#         self._core_logger.setLevel(self.log_level)
-#         self._core_logger.propagate = False
-#
-#         # Standard (file + console) handlers
-#         self._setup_standard_handlers()
-#
-#         # OTel handlers (logs + traces)
-#         if self.enable_otel:
-#             self._setup_otel_handler()
-#
-#         # Public-facing logger (optionally wrapped with adapter extras)
-#         if self.enable_otel and self.otel_stream_name:
-#             attributes = {
-#                 "log_stream": self.otel_stream_name,
-#                 "log_service_name": self.otel_service_name,
-#                 "logger_name": self.logger_name,
-#             }
-#             self.logger = LoggerAdapter(self._core_logger, extra=attributes)
-#         else:
-#             self.logger = self._core_logger
-#
-#     def _setup_standard_handlers(self):
-#         """Sets up file and console handlers with deduping."""
-#         os.makedirs(self.log_dir, exist_ok=True)
-#         calling_script = os.path.splitext(os.path.basename(sys.argv[0]))[0]
-#         log_file_path = os.path.join(self.log_dir, f"{self.log_file}_{calling_script}.log")
-#
-#         formatter = logging.Formatter(
-#             "[%(asctime)s] [%(levelname)s] [%(name)s] %(message)s",
-#             datefmt="%Y-%m-%d %H:%M:%S",
-#         )
-#         formatter.converter = time.gmtime  # UTC timestamps
-#
-#         # File handler (dedupe by filename)
-#         if not any(
-#             isinstance(h, RotatingFileHandler) and getattr(h, "baseFilename", "") == os.path.abspath(log_file_path)
-#             for h in self._core_logger.handlers
-#         ):
-#             file_handler = RotatingFileHandler(
-#                 log_file_path, maxBytes=5 * 1024 * 1024, backupCount=5, delay=True
-#             )
-#             file_handler.setFormatter(formatter)
-#             self._core_logger.addHandler(file_handler)
-#
-#         # Console handler (dedupe by stream)
-#         if not any(
-#             isinstance(h, logging.StreamHandler) and getattr(h, "stream", None) is sys.stdout
-#             for h in self._core_logger.handlers
-#         ):
-#             console_handler = logging.StreamHandler(sys.stdout)
-#             console_handler.setFormatter(formatter)
-#             self._core_logger.addHandler(console_handler)
-#
-#     def _normalize_otlp_endpoint(self, ep: str) -> str:
-#         """Ensure OTLP gRPC endpoint has a scheme."""
-#         if "://" not in ep:
-#             ep = ("http://" if self.otel_insecure else "https://") + ep
-#         return ep
-#
-#     def _setup_otel_handler(self):
-#         """
-#         Configure OpenTelemetry providers, exporters, and attach a LoggingHandler.
-#         - service.name: used by most backends (incl. OpenObserve) to group streams/services.
-#         - log.stream: extra attribute you can filter on in the backend.
-#         """
-#         resource_attrs = {
-#             "service.name": self.otel_service_name,
-#             "logger.name": self.logger_name,
-#         }
-#         if self.otel_stream_name:
-#             resource_attrs["log.stream"] = self.otel_stream_name
-#
-#         resource = Resource.create(resource_attrs)
-#
-#         # Logs provider
-#         self.logger_provider = LoggerProvider(resource=resource)
-#         set_logger_provider(self.logger_provider)
-#
-#         # Traces provider
-#         self.tracer_provider = TracerProvider(resource=resource)
-#         trace.set_tracer_provider(self.tracer_provider)
-#
-#         endpoint = self._normalize_otlp_endpoint(self.otel_endpoint)
-#
-#         # Logs exporter + processor
-#         log_exporter = OTLPLogExporter(endpoint=endpoint, insecure=self.otel_insecure)
-#         self.logger_provider.add_log_record_processor(BatchLogRecordProcessor(log_exporter))
-#
-#         # Traces exporter + processor
-#         span_exporter = OTLPSpanExporter(endpoint=endpoint, insecure=self.otel_insecure)
-#         self.tracer_provider.add_span_processor(BatchSpanProcessor(span_exporter))
-#         self.tracer = trace.get_tracer(self.logger_name, tracer_provider=self.tracer_provider)
-#
-#         # Attach OTel LoggingHandler once
-#         if not any(type(h).__name__ == "LoggingHandler" for h in self._core_logger.handlers):
-#             otel_handler = LoggingHandler(level=logging.NOTSET, logger_provider=self.logger_provider)
-#             self._core_logger.addHandler(otel_handler)
-#
-#         self._core_logger.info("OpenTelemetry logging and tracing enabled and attached.")
-#

sibi_dst/utils/parquet_saver.py

@@ -1,5 +1,7 @@
 import warnings
 
+from pandas.api.types import is_period_dtype, is_bool_dtype, is_string_dtype
+import pandas as pd
 import dask.dataframe as dd
 import pyarrow as pa
 
@@ -15,6 +17,7 @@ class ParquetSaver(ManagedResource):
 
     Assumes `df_result` is a Dask DataFrame.
     """
+    logger_extra = {"sibi_dst_component": __name__}
 
     def __init__(
         self,
@@ -32,6 +35,10 @@ class ParquetSaver(ManagedResource):
         if "://" in self.parquet_storage_path:
             self.protocol = self.parquet_storage_path.split(":", 1)[0]
 
+        self.persist = kwargs.get("persist",True)
+        self.write_index = kwargs.get("write_index", False)
+        self.write_metadata_file = kwargs.get("write_metadata_file", True)
+
     def save_to_parquet(self, output_directory_name: str = "default_output", overwrite: bool = True):
         """
         Saves the Dask DataFrame to a Parquet dataset.
@@ -42,17 +49,19 @@ class ParquetSaver(ManagedResource):
         full_path = f"{self.parquet_storage_path}/{output_directory_name}"
 
         if overwrite and self.fs and self.fs.exists(full_path):
-            self.logger.info(f"Overwrite is True, clearing destination path: {full_path}")
+            self.logger.info(f"Overwrite is True, clearing destination path: {full_path}", extra=self.logger_extra)
             self._clear_directory_safely(full_path)
 
         # Ensure the base directory exists after clearing
         self.fs.mkdirs(full_path, exist_ok=True)
 
         schema = self._define_schema()
-        self.logger.info(f"Saving DataFrame to Parquet dataset at: {full_path}")
+        self.logger.info(f"Saving DataFrame to Parquet dataset at: {full_path}", extra=self.logger_extra)
+        # 1) Normalize to declared schema (fixes bool→string, Period→string, etc.)
+        ddf = self._coerce_ddf_to_schema(self.df_result, schema)
 
-        # persist then write (lets the graph be shared if the caller reuses it)
-        ddf = self.df_result.persist()
+        # 2) Persist after coercion so all partitions share the coerced dtypes
+        ddf = ddf.persist() if self.persist else ddf
 
         try:
             ddf.to_parquet(
@@ -61,11 +70,12 @@ class ParquetSaver(ManagedResource):
                 schema=schema,
                 overwrite=False,         # we've handled deletion already
                 filesystem=self.fs,
-                write_index=False,
+                write_index=self.write_index,  # whether to write the index
+                write_metadata_file=self.write_metadata_file,  # write _metadata for easier reading later
             )
-            self.logger.info(f"Successfully saved Parquet dataset to: {full_path}")
+            self.logger.info(f"Successfully saved Parquet dataset to: {full_path}", extra=self.logger_extra)
         except Exception as e:
-            self.logger.error(f"Failed to save Parquet dataset to {full_path}: {e}")
+            self.logger.error(f"Failed to save Parquet dataset to {full_path}: {e}", extra=self.logger_extra)
             raise
 
     def _clear_directory_safely(self, directory: str):
@@ -91,7 +101,7 @@ class ParquetSaver(ManagedResource):
                     else:
                         self.fs.rm(path, recursive=False)
                 except Exception as e:
-                    self.logger.warning(f"Failed to delete '{path}': {e}")
+                    self.logger.warning(f"Failed to delete '{path}': {e}", extra=self.logger_extra)
             # remove the (now empty) directory if present
             try:
                 self.fs.rm(directory, recursive=False)
@@ -120,4 +130,95 @@ class ParquetSaver(ManagedResource):
             pa.field(c, pandas_dtype_to_pa.get(str(d), pa.string()))
             for c, d in self.df_result.dtypes.items()
         ]
-        return pa.schema(fields)
+        return pa.schema(fields)
+
+
+    def _coerce_ddf_to_schema(self, ddf: dd.DataFrame, schema: pa.Schema) -> dd.DataFrame:
+        """
+        Coerce Dask DataFrame columns to match the provided PyArrow schema.
+        - Ensures cross-partition consistency.
+        - Converts troublesome dtypes (Period, mixed object/bool) to the declared type.
+        """
+        # Build a map: name -> target kind
+        target = {field.name: field.type for field in schema}
+
+        def _coerce_partition(pdf: pd.DataFrame) -> pd.DataFrame:
+            for col, typ in target.items():
+                if col not in pdf.columns:
+                    continue
+
+                pa_type = typ
+
+                # String targets
+                if pa.types.is_string(pa_type) or pa.types.is_large_string(pa_type):
+                    # Convert Period or any dtype to string with NA-preservation
+                    s = pdf[col]
+                    if is_period_dtype(s):
+                        pdf[col] = s.astype(str)
+                    elif not is_string_dtype(s):
+                        # astype("string") keeps NA; str(s) can produce "NaT" strings
+                        try:
+                            pdf[col] = s.astype("string")
+                        except Exception:
+                            pdf[col] = s.astype(str).astype("string")
+                    continue
+
+                # Boolean targets
+                if pa.types.is_boolean(pa_type):
+                    s = pdf[col]
+                    # Allow object/bool mixtures; coerce via pandas nullable boolean then to bool
+                    try:
+                        pdf[col] = s.astype("boolean").astype(bool)
+                    except Exception:
+                        pdf[col] = s.astype(bool)
+                    continue
+
+                # Integer targets
+                if pa.types.is_integer(pa_type):
+                    s = pdf[col]
+                    # Go through pandas nullable Int64 to preserve NA, then to int64 if clean
+                    s2 = pd.to_numeric(s, errors="coerce").astype("Int64")
+                    # If there are no nulls, downcast to numpy int64 for speed
+                    if not s2.isna().any():
+                        s2 = s2.astype("int64")
+                    pdf[col] = s2
+                    continue
+
+                # Floating targets
+                if pa.types.is_floating(pa_type):
+                    pdf[col] = pd.to_numeric(pdf[col], errors="coerce").astype("float64")
+                    continue
+
+                # Timestamp[ns] (optionally with tz)
+                if pa.types.is_timestamp(pa_type):
+                    # If tz in Arrow type, you may want to localize; here we just ensure ns
+                    pdf[col] = pd.to_datetime(pdf[col], errors="coerce")
+                    continue
+
+                # Fallback: leave as-is
+            return pdf
+
+        # Provide a meta with target dtypes to avoid meta mismatch warnings
+        meta = {}
+        for name, typ in target.items():
+            # Rough meta mapping; Arrow large_string vs string both → 'string'
+            if pa.types.is_string(typ) or pa.types.is_large_string(typ):
+                meta[name] = pd.Series([], dtype="string")
+            elif pa.types.is_boolean(typ):
+                meta[name] = pd.Series([], dtype="bool")
+            elif pa.types.is_integer(typ):
+                meta[name] = pd.Series([], dtype="Int64")  # nullable int
+            elif pa.types.is_floating(typ):
+                meta[name] = pd.Series([], dtype="float64")
+            elif pa.types.is_timestamp(typ):
+                meta[name] = pd.Series([], dtype="datetime64[ns]")
+            else:
+                meta[name] = pd.Series([], dtype="object")
+
+        # Start from current meta and update known columns
+        new_meta = ddf._meta.copy()
+        for k, v in meta.items():
+            if k in new_meta.columns:
+                new_meta[k] = v
+
+        return ddf.map_partitions(_coerce_partition, meta=new_meta)

sibi_dst/utils/progress/__init__.py

@@ -0,0 +1,5 @@
+from .sse_runner import SSERunner, _as_sse_msg
+
+__all__ = [
+    "SSERunner", "_as_sse_msg"
+]

sibi_dst/utils/progress/jobs.py

@@ -0,0 +1,82 @@
+# jobs.py
+import asyncio, json, uuid
+import contextlib
+import os
+
+import redis.asyncio as redis
+from fastapi import APIRouter
+from sse_starlette.sse import EventSourceResponse
+host = os.getenv("REDIS_HOST", "0.0.0.0")
+port = int(os.getenv("REDIS_PORT", 6379))
+db = int(os.getenv("REDIS_DB", 0))
+router = APIRouter(prefix="/jobs", tags=["Jobs"])
+r = redis.Redis(host=host, port=port, db=db, decode_responses=True)  # strings for pubsub
+
+CHANNEL = lambda job_id: f"job:{job_id}:events"
+KEY_STATUS = lambda job_id: f"job:{job_id}:status"   # JSON blob with state/progress
+KEY_RESULT = lambda job_id: f"job:{job_id}:result"   # final payload
+
+async def publish(job_id: str, event: str, data: dict):
+    msg = json.dumps({"event": event, "data": data})
+    await r.publish(CHANNEL(job_id), msg)
+    # store last status
+    await r.set(KEY_STATUS(job_id), json.dumps({"event": event, "data": data}))
+
+# ---- Worker entry (can live in a separate process) ----
+async def run_job(job_id: str):
+    try:
+        await publish(job_id, "progress", {"message": "Initializing..."})
+        # ... do actual work, emit more progress
+        await asyncio.sleep(0.2)
+        # compute result
+        result = [{"id": 1, "ok": True}]
+        await r.set(KEY_RESULT(job_id), json.dumps(result), ex=3600)
+        await publish(job_id, "complete", {"records": len(result)})
+    except Exception as e:
+        await publish(job_id, "error", {"detail": str(e)})
+
+# ---- API ----
+@router.post("/start")
+async def start_job():
+    job_id = str(uuid.uuid4())
+    # enqueue: prefer Celery/RQ/etc. For demo we detach a task.
+    asyncio.create_task(run_job(job_id))
+    return {"job_id": job_id}
+
+@router.get("/{job_id}/stream")
+async def stream(job_id: str):
+    pubsub = r.pubsub()
+    await pubsub.subscribe(CHANNEL(job_id))
+
+    async def gen():
+        try:
+            # emit latest known status immediately, if any
+            if (s := await r.get(KEY_STATUS(job_id))):
+                yield {"event": "progress", "data": s}
+            while True:
+                msg = await pubsub.get_message(ignore_subscribe_messages=True, timeout=30.0)
+                if msg and msg["type"] == "message":
+                    payload = msg["data"]  # already a JSON string
+                    yield {"event": "message", "data": payload}
+                await asyncio.sleep(0.01)
+        finally:
+            with contextlib.suppress(Exception):
+                await pubsub.unsubscribe(CHANNEL(job_id))
+                await pubsub.close()
+
+    return EventSourceResponse(
+        gen(),
+        ping=15,
+        headers={"Cache-Control": "no-cache, no-transform", "X-Accel-Buffering": "no"},
+    )
+
+@router.get("/{job_id}/status")
+async def status(job_id: str):
+    s = await r.get(KEY_STATUS(job_id))
+    done = await r.exists(KEY_RESULT(job_id))
+    return {"job_id": job_id, "status": json.loads(s) if s else None, "done": bool(done)}
+
+@router.get("/{job_id}/result")
+async def result(job_id: str):
+    data = await r.get(KEY_RESULT(job_id))
+    return {"job_id": job_id, "result": json.loads(data) if data else None}

sibi_dst/utils/progress/sse_runner.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+import asyncio, contextlib, inspect, json
+from typing import Any, Awaitable, Callable, Dict, Optional, Union
+from fastapi import Request
+from sse_starlette.sse import EventSourceResponse
+from sibi_dst.utils import Logger
+
+Payload = Union[str, bytes, dict, list, None]
+Task2 = Callable[[asyncio.Queue, str], Awaitable[Payload]]
+Task3 = Callable[[asyncio.Queue, str, Dict[str, Any]], Awaitable[Payload]]
+TaskFn = Union[Task2, Task3]
+
+def _as_sse_msg(event: str, data: Any) -> dict:
+    return {"event": event, "data": json.dumps(data) if not isinstance(data, (str, bytes)) else data}
+
+class SSERunner:
+    def __init__(self, *, task: TaskFn, logger: Logger, ping: int = 15,
+                 headers: Optional[dict] = None, auto_complete: bool = True) -> None:
+        self.task = task
+        self.logger = logger
+        self.ping = ping
+        self.headers = headers or {"Cache-Control": "no-cache, no-transform", "X-Accel-Buffering": "no"}
+        self.auto_complete = auto_complete
+        self._expects_ctx = len(inspect.signature(task).parameters) >= 3
+
+    async def _call_task(self, queue: asyncio.Queue, task_id: str, ctx: Dict[str, Any]) -> Payload:
+        if self._expects_ctx:
+            return await self.task(queue, task_id, ctx)  # type: ignore[misc]
+        return await self.task(queue, task_id)           # type: ignore[misc]
+
+    async def _worker(self, queue: asyncio.Queue, task_id: str, ctx: Dict[str, Any]) -> None:
+        self.logger.info(f"SSE {task_id}: start")
+        try:
+            await queue.put(_as_sse_msg("progress", {"message": "Task started"}))
+            payload = await self._call_task(queue, task_id, ctx)
+            if self.auto_complete:
+                final = payload if payload is not None else {"status": "complete"}
+                await queue.put(_as_sse_msg("complete", final))
+            self.logger.info(f"SSE {task_id}: complete")
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            self.logger.error(f"SSE {task_id} failed: {e}", exc_info=True)
+            await queue.put(_as_sse_msg("error", {"detail": str(e)}))
+        finally:
+            await queue.put(None)
+
+    def endpoint(self):
+        async def handler(request: Request):  # <-- only Request
+            queue: asyncio.Queue = asyncio.Queue()
+            task_id = str(asyncio.get_running_loop().time()).replace(".", "")
+
+            ctx: Dict[str, Any] = {
+                "path": dict(request.path_params),          # <-- pull path params here
+                "query": dict(request.query_params),
+                "method": request.method,
+            }
+            if request.headers.get("content-type", "").startswith("application/json"):
+                try:
+                    ctx["body"] = await request.json()
+                except Exception:
+                    ctx["body"] = None
+
+            worker = asyncio.create_task(self._worker(queue, task_id, ctx))
+
+            async def gen():
+                try:
+                    while True:
+                        msg = await queue.get()
+                        if msg is None:
+                            break
+                        yield msg
+                finally:
+                    if not worker.done():
+                        worker.cancel()
+                        with contextlib.suppress(Exception):
+                            await worker
+
+            return EventSourceResponse(gen(), ping=self.ping, headers=self.headers)
+        return handler
+
+__all__ = ["SSERunner", "_as_sse_msg"]