lss4py 0.1.0__py3-none-any.whl

lss4py/__init__.py

@@ -0,0 +1,53 @@
+from lss4py.domain import (
+    EventLog,
+    EventLogBindingsIR,
+    LeadTimeBindingIR,
+    MetricBindingsIR,
+    MetricSemanticsIR,
+    ProcessEdgeIR,
+    ProcessModelIR,
+    ProcessStepIR,
+    StageBindingsIR,
+    validate_event_log,
+)
+from lss4py.errors import AdapterError, LSS4PyError, ValidationError, WorkflowError
+from lss4py.workflows import map_process
+from lss4py.yellow_belt import (
+    booked_to_completed_yield,
+    created_to_booked_yield,
+    lead_time,
+    process_cycle_efficiency,
+    rolled_yield,
+    takt_time,
+    wait_time,
+)
+
+__all__ = [
+    "AdapterError",
+    "EventLogBindingsIR",
+    "EventLog",
+    "LSS4PyError",
+    "ValidationError",
+    "WorkflowError",
+    "booked_to_completed_yield",
+    "created_to_booked_yield",
+    "lead_time",
+    "LeadTimeBindingIR",
+    "main",
+    "map_process",
+    "MetricBindingsIR",
+    "MetricSemanticsIR",
+    "ProcessEdgeIR",
+    "ProcessModelIR",
+    "ProcessStepIR",
+    "process_cycle_efficiency",
+    "rolled_yield",
+    "StageBindingsIR",
+    "takt_time",
+    "validate_event_log",
+    "wait_time",
+]
+
+
+def main() -> None:
+    print("lss4py scaffold ready")

lss4py/adapters/__init__.py

@@ -0,0 +1,4 @@
+from .event_log import load_event_log
+from .tabular import load_tabular_records
+
+__all__ = ["load_event_log", "load_tabular_records"]

lss4py/adapters/event_log.py

@@ -0,0 +1,8 @@
+from pathlib import Path
+
+from lss4py.domain.models import EventLog
+
+
+def load_event_log(path: str | Path) -> EventLog:
+    _ = path
+    raise NotImplementedError("Event-log adapter is not implemented yet.")

lss4py/adapters/tabular.py

@@ -0,0 +1,7 @@
+from pathlib import Path
+from typing import Any
+
+
+def load_tabular_records(path: str | Path) -> list[dict[str, Any]]:
+    _ = path
+    raise NotImplementedError("Tabular adapter is not implemented yet.")

lss4py/analytics/__init__.py

@@ -0,0 +1,3 @@
+"""Experimental analytics modules live here until a stable Yellow Belt API is defined."""
+
+__all__: list[str] = []

lss4py/analytics/capability.py

@@ -0,0 +1,6 @@
+from lss4py.domain.models import AssumptionReport, EventLog
+
+
+def capability_report(event_log: EventLog) -> AssumptionReport:
+    _ = event_log
+    raise NotImplementedError("Capability reporting is not implemented yet.")

lss4py/analytics/descriptive.py

@@ -0,0 +1,8 @@
+from lss4py.domain.models import EventLog, PercentileProfile
+
+
+def summarize_cycle_time(
+    event_log: EventLog, percentiles: tuple[int, ...] = (50, 90, 95, 99)
+) -> PercentileProfile:
+    _ = (event_log, percentiles)
+    raise NotImplementedError("Cycle-time percentile summarization is not implemented yet.")

lss4py/analytics/spc.py

@@ -0,0 +1,6 @@
+from lss4py.domain.models import AssumptionReport, EventLog
+
+
+def spc_report(event_log: EventLog) -> AssumptionReport:
+    _ = event_log
+    raise NotImplementedError("SPC reporting is not implemented yet.")

lss4py/cli.py

@@ -0,0 +1,16 @@
+import click
+from rich.console import Console
+
+from lss4py.observability import configure_logging
+
+
+@click.group()
+@click.option("--debug", is_flag=True, default=False, help="Enable debug logging.")
+def main(debug: bool) -> None:
+    configure_logging(debug=debug)
+
+
+@main.command("doctor")
+def doctor() -> None:
+    console = Console()
+    console.print("[green]lss4py[/green] scaffold is ready.")

lss4py/domain/__init__.py

@@ -0,0 +1,37 @@
+from .models import (
+    AssumptionNote,
+    AssumptionReport,
+    ComparisonSlice,
+    EventLog,
+    EventLogBindingsIR,
+    LeadTimeBindingIR,
+    MetricBindingsIR,
+    MetricResult,
+    MetricSemanticsIR,
+    PercentileProfile,
+    ProcessEdgeIR,
+    ProcessModelIR,
+    ProcessStepIR,
+    ProcessWindow,
+    StageBindingsIR,
+)
+from .validation import validate_event_log
+
+__all__ = [
+    "AssumptionNote",
+    "AssumptionReport",
+    "ComparisonSlice",
+    "EventLogBindingsIR",
+    "EventLog",
+    "LeadTimeBindingIR",
+    "MetricBindingsIR",
+    "MetricSemanticsIR",
+    "MetricResult",
+    "PercentileProfile",
+    "ProcessEdgeIR",
+    "ProcessModelIR",
+    "ProcessStepIR",
+    "ProcessWindow",
+    "StageBindingsIR",
+    "validate_event_log",
+]

lss4py/domain/models.py

@@ -0,0 +1,126 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Literal
+
+
+@dataclass(slots=True)
+class AssumptionNote:
+    code: str
+    message: str
+    severity: str = "info"
+
+
+@dataclass(slots=True)
+class AssumptionReport:
+    assumptions: list[AssumptionNote] = field(default_factory=list)
+    warnings: list[AssumptionNote] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class ProcessWindow:
+    name: str
+    start: datetime | None = None
+    end: datetime | None = None
+
+
+ValueClassification = Literal["value_add", "non_value_add", "required_non_value_add"]
+EdgeKind = Literal["sequence", "parallel_split", "parallel_join", "rework"]
+ParallelTiming = Literal["critical_path", "sum_all_branches"]
+ObservedDataShape = Literal["event_log_rows"]
+
+
+@dataclass(slots=True)
+class LeadTimeBindingIR:
+    start_column: str | None = None
+    end_column: str | None = None
+    unit: Literal["seconds", "minutes", "hours", "days"] = "hours"
+
+
+@dataclass(slots=True)
+class StageBindingsIR:
+    created: str | None = None
+    booked: str | None = None
+    completed: str | None = None
+
+
+@dataclass(slots=True)
+class EventLogBindingsIR:
+    case_id_column: str | None = None
+    step_id_column: str | None = None
+    started_at_column: str | None = None
+    completed_at_column: str | None = None
+
+
+@dataclass(slots=True)
+class MetricBindingsIR:
+    lead_time: LeadTimeBindingIR = field(default_factory=LeadTimeBindingIR)
+    stages: StageBindingsIR = field(default_factory=StageBindingsIR)
+    event_log: EventLogBindingsIR = field(default_factory=EventLogBindingsIR)
+
+
+@dataclass(slots=True)
+class MetricSemanticsIR:
+    parallel_timing: ParallelTiming = "critical_path"
+    observed_data_shape: ObservedDataShape = "event_log_rows"
+
+
+@dataclass(slots=True)
+class ProcessStepIR:
+    id: str
+    name: str
+    cycle_time_column: str | None = None
+    value_classification: ValueClassification = "value_add"
+    role_label: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class ProcessEdgeIR:
+    source_step_id: str
+    target_step_id: str
+    kind: EdgeKind = "sequence"
+    condition: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class ProcessModelIR:
+    name: str
+    schema_version: str = "1.0"
+    steps: list[ProcessStepIR] = field(default_factory=list)
+    edges: list[ProcessEdgeIR] = field(default_factory=list)
+    bindings: MetricBindingsIR = field(default_factory=MetricBindingsIR)
+    metric_semantics: MetricSemanticsIR = field(default_factory=MetricSemanticsIR)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class EventLog:
+    events: list[dict[str, Any]]
+    required_fields: tuple[str, ...] = ("case_id", "activity", "timestamp")
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class ComparisonSlice:
+    before: EventLog
+    after: EventLog
+    label: str = "before_after"
+
+
+@dataclass(slots=True)
+class MetricResult:
+    name: str
+    value: float | None
+    unit: str | None = None
+    notes: list[AssumptionNote] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class PercentileProfile:
+    p50: float | None
+    p90: float | None
+    p95: float | None
+    p99: float | None
+    count: int

lss4py/domain/validation.py

@@ -0,0 +1,30 @@
+from .models import AssumptionNote, AssumptionReport, EventLog
+
+
+def validate_event_log(event_log: EventLog) -> AssumptionReport:
+    if not event_log.events:
+        return AssumptionReport(
+            warnings=[
+                AssumptionNote(
+                    code="empty_event_log",
+                    message="Event log contains zero rows.",
+                    severity="warning",
+                )
+            ]
+        )
+
+    sample_event = event_log.events[0]
+    missing = [field for field in event_log.required_fields if field not in sample_event]
+
+    if missing:
+        return AssumptionReport(
+            warnings=[
+                AssumptionNote(
+                    code="missing_required_fields",
+                    message=f"Missing required fields: {', '.join(missing)}",
+                    severity="warning",
+                )
+            ]
+        )
+
+    return AssumptionReport()

lss4py/errors.py

@@ -0,0 +1,14 @@
+class LSS4PyError(Exception):
+    """Base exception for lss4py."""
+
+
+class ValidationError(LSS4PyError):
+    """Raised when input data fails validation checks."""
+
+
+class AdapterError(LSS4PyError):
+    """Raised when adapter-level IO or parsing fails."""
+
+
+class WorkflowError(LSS4PyError):
+    """Raised when workflow orchestration fails."""

lss4py/observability/__init__.py

@@ -0,0 +1,4 @@
+from .logging import configure_logging, get_logger
+from .telemetry import configure_telemetry, get_tracer
+
+__all__ = ["configure_logging", "configure_telemetry", "get_logger", "get_tracer"]

lss4py/observability/logging.py

@@ -0,0 +1,35 @@
+import logging
+import sys
+from typing import Any
+
+import structlog
+
+
+def configure_logging(debug: bool = False) -> None:
+    log_level = logging.DEBUG if debug else logging.INFO
+
+    logging.basicConfig(
+        format="%(message)s",
+        stream=sys.stdout,
+        level=log_level,
+    )
+
+    processors: list[Any] = [
+        structlog.contextvars.merge_contextvars,
+        structlog.processors.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso", utc=True),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.format_exc_info,
+        structlog.processors.JSONRenderer(),
+    ]
+
+    structlog.configure(
+        processors=processors,
+        wrapper_class=structlog.make_filtering_bound_logger(log_level),
+        logger_factory=structlog.PrintLoggerFactory(file=sys.stdout),
+        cache_logger_on_first_use=True,
+    )
+
+
+def get_logger(name: str | None = None) -> structlog.stdlib.BoundLogger:
+    return structlog.get_logger(name)

lss4py/observability/telemetry.py

@@ -0,0 +1,19 @@
+from typing import Final
+
+from opentelemetry import trace
+from opentelemetry.sdk.resources import SERVICE_NAME, Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
+
+DEFAULT_SERVICE_NAME: Final[str] = "lss4py"
+
+
+def configure_telemetry(service_name: str = DEFAULT_SERVICE_NAME) -> None:
+    resource = Resource.create({SERVICE_NAME: service_name})
+    provider = TracerProvider(resource=resource)
+    provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
+    trace.set_tracer_provider(provider)
+
+
+def get_tracer(name: str = DEFAULT_SERVICE_NAME):
+    return trace.get_tracer(name)

lss4py/reporting/__init__.py

@@ -0,0 +1,3 @@
+from .bundles import AnalysisBundle, to_markdown
+
+__all__ = ["AnalysisBundle", "to_markdown"]

lss4py/reporting/bundles.py

@@ -0,0 +1,14 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class AnalysisBundle:
+    title: str
+    sections: list[dict[str, Any]] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+def to_markdown(bundle: AnalysisBundle) -> str:
+    _ = bundle
+    raise NotImplementedError("Markdown bundle rendering is not implemented yet.")

lss4py/workflows/__init__.py

@@ -0,0 +1,3 @@
+from .process_map import map_process
+
+__all__ = ["map_process"]

lss4py/workflows/bottleneck.py

@@ -0,0 +1,6 @@
+from lss4py.domain.models import EventLog
+
+
+def bottleneck_report(event_log: EventLog) -> dict[str, object]:
+    _ = event_log
+    raise NotImplementedError("Bottleneck workflow is not implemented yet.")

lss4py/workflows/comparison.py

@@ -0,0 +1,6 @@
+from lss4py.domain.models import ComparisonSlice
+
+
+def compare_before_after(comparison: ComparisonSlice) -> dict[str, object]:
+    _ = comparison
+    raise NotImplementedError("Before/after comparison workflow is not implemented yet.")

lss4py/workflows/process_map.py

@@ -0,0 +1,49 @@
+from collections import defaultdict
+from datetime import datetime
+from typing import Any, TypedDict
+
+from lss4py.domain.models import EventLog
+
+
+class ProcessMapResult(TypedDict):
+    nodes: list[str]
+    edges: dict[str, dict[str, int]]
+
+
+def _parse_timestamp(value: Any) -> datetime:
+    if isinstance(value, datetime):
+        return value
+
+    if isinstance(value, str):
+        return datetime.fromisoformat(value)
+
+    raise TypeError("Event timestamps must be datetime objects or ISO-8601 strings.")
+
+
+def map_process(event_log: EventLog) -> ProcessMapResult:
+    grouped_events: dict[str, list[dict[str, Any]]] = defaultdict(list)
+
+    for event in event_log.events:
+        case_id = str(event["case_id"])
+        grouped_events[case_id].append(event)
+
+    nodes: set[str] = set()
+    edges: dict[str, dict[str, int]] = {}
+
+    for case_events in grouped_events.values():
+        ordered_events = sorted(case_events, key=lambda event: _parse_timestamp(event["timestamp"]))
+
+        for event in ordered_events:
+            nodes.add(str(event["activity"]))
+
+        for current_event, next_event in zip(ordered_events, ordered_events[1:], strict=False):
+            current_activity = str(current_event["activity"])
+            next_activity = str(next_event["activity"])
+            edges.setdefault(current_activity, {})
+            transition_count = edges[current_activity].get(next_activity, 0) + 1
+            edges[current_activity][next_activity] = transition_count
+
+    return {
+        "nodes": sorted(nodes),
+        "edges": edges,
+    }

lss4py/workflows/simulation.py

@@ -0,0 +1,6 @@
+from lss4py.domain.models import EventLog
+
+
+def redesign_simulation(event_log: EventLog) -> dict[str, object]:
+    _ = event_log
+    raise NotImplementedError("Simulation workflow is not implemented yet.")