temporal-ewma-worker 0.1.1__tar.gz

temporal_ewma_worker-0.1.1/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: temporal-ewma-worker
+Version: 0.1.1
+Summary: Temporal scheduled workflow worker for EWMA baseline updating and anomaly checking
+Requires-Python: >=3.11
+Requires-Dist: temporalio>=1.5.0
+Requires-Dist: clickhouse-connect>=0.7.0
+Requires-Dist: redis>=5.0.0
+Requires-Dist: psycopg[binary]>=3.1.0
+Requires-Dist: confluent-kafka>=2.3.0
+Requires-Dist: opentelemetry-sdk>=1.26.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.22.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Requires-Dist: ruff>=0.2.0; extra == "dev"
+Requires-Dist: httpx>=0.24.0; extra == "dev"

temporal_ewma_worker-0.1.1/README.md

@@ -0,0 +1,278 @@
+# Temporal EWMA Worker
+
+Temporal worker package for scheduled EWMA baseline updates and cost anomaly detection.
+
+---
+
+## Folder Structure
+
+```
+.
+├── build/
+│   └── Dockerfile
+├── contracts/
+│   ├── asyncapi/
+│   │   └── v1.yaml
+│   ├── changelog.md
+│   └── workflows/
+│       └── ewma_baseline_update.yaml
+├── database/
+│   ├── migrations/
+│   │   ├── 0001_init.rollback.sql
+│   │   └── 0001_init.sql
+│   └── schema.lock
+├── deploy/
+│   └── docker/
+│       └── docker-compose.yaml
+├── feature-registry.yaml
+├── pyproject.toml
+├── README.md
+├── scripts/
+│   ├── deploy_docker.sh
+│   ├── migrate.py
+│   ├── migrate.sh
+│   ├── run.sh
+│   └── test.sh
+├── src/
+│   ├── features/
+│   │   └── ewma_compute/
+│   │       ├── index.py
+│   │       └── service.py
+│   ├── infra/
+│   │   └── adapters/
+│   │       ├── clickhouse/
+│   │       │   └── clickhouse_adapter.py
+│   │       ├── kafka/
+│   │       │   └── kafka_alert_adapter.py
+│   │       ├── postgres/
+│   │       │   └── postgres_adapter.py
+│   │       └── redis/
+│   │           └── redis_adapter.py
+│   ├── shared/
+│   │   ├── contracts/
+│   │   │   └── validator.py
+│   │   ├── errors/
+│   │   │   └── base.py
+│   │   ├── ports/
+│   │   │   ├── clickhouse_port.py
+│   │   │   ├── postgres_port.py
+│   │   │   └── redis_port.py
+│   │   └── types/
+│   │       └── ewma_types.py
+│   └── worker/
+│       ├── activities.py
+│       ├── config.py
+│       ├── index.py
+│       ├── registry.py
+│       └── workflows.py
+├── tests/
+│   ├── integration/
+│   │   └── test_adapters.py
+│   └── unit/
+│       ├── test_config.py
+│       ├── test_contract.py
+│       ├── test_ewma_service.py
+│       └── test_workflow.py
+└── worker-registry.yaml
+```
+
+---
+
+## Work Execution & Decision Flow
+
+The following detailed decision tree outlines how the hourly workflow updates baselines and flags anomalies, with justification for each design choice:
+
+```
+[Hourly Cron Trigger (0 * * * *)]
+└── EwmaBaselineUpdate Workflow Starts
+    │
+    │   ► RATIONALE: Scheduled cron triggers workflow at off-peak hour intervals.
+    │
+    └── Activity: fetch_active_pairs()
+        │
+        │   ► RATIONALE: Scans ClickHouse log volumes for active (service, model) pairs 
+        │     in the last 7 days. This filters out millions of historical combinations, 
+        │     focusing computation ONLY on active traffic to minimize cost and execution time.
+        │
+        └── Loop over active (service, model) pairs concurrently:
+            │
+            │   ► RATIONALE: Temporal workflows run loops concurrently. Concurrency allows 
+            │     thousands of pairs to be evaluated in parallel without blocking.
+            │
+            ├── Activity: get_baseline(service, model, hour_of_week)
+            │   │
+            │   │   ► RATIONALE: Reads the current baseline record from PostgreSQL. PostgreSQL is
+            │   │     used here because it provides ACID compliance for historical baselines.
+            │   │
+            │   ├── Existing Baseline NOT found (Cold Start)
+            │   │   ├── Activity: fetch_global_model_avg(model)
+            │   │   │
+            │   │   │   ► RATIONALE: Lacking historical service/model pairing, we seed the baseline
+            │   │   │     using the global average cost for this specific model (e.g. gpt-4o) across 
+            │   │   │     all services. This prevents false positive anomaly triggers during cold starts.
+            │   │   │
+            │   │   └── Seed EWMA baseline value = Global Model Average
+            │   │
+            │   └── Existing Baseline found (Warm Status)
+            │       ├── Activity: fetch_cost_history(service, model, hour_of_week)
+            │       │   │
+            │       │   │   ► RATIONALE: Queries ClickHouse for the cost of the same hour_of_week (0-167)
+            │       │   │     over the last 4 weeks. ClickHouse is selected here because column-oriented 
+            │       │   │     storage allows ultra-fast aggregation of historical logs.
+            │       │   │
+            │       │   └── Fetch last 4 occurrences from ClickHouse
+            │       └── Compute EWMA baseline value using α=0.1:
+            │           EWMA_new = (1 - α) * EWMA_prev + α * Cost_current
+            │
+            ├── Activity: fetch_current_cost_1h(service, model)
+            │
+            ├── Activity: upsert_baseline(EwmaRecord)
+            │   │
+            │   │   ► RATIONALE: Persists the calculated baseline to PostgreSQL for persistent audit trail.
+            │   │
+            │   └── Persist updated baseline to PostgreSQL
+            │
+            ├── Write updated EWMA value to Redis Cache
+            │   │
+            │   │   ► RATIONALE: Anomaly-detection gateways on the ingestion path need ultra-low latency. 
+            │   │     Redis caches the calculated baseline under: ewma:cost:{service}:{model}:{hour_of_week}
+            │   │
+            │   └── Key: ewma:cost:{service}:{model}:{hour_of_week}
+            │
+            └── Decision: Is Cost_current > (3 * EWMA_baseline)?
+                │
+                ├── YES (Anomaly Detected)
+                │   ├── Activity: fetch_cost_by_cluster_1h(service, model)
+                │   │   │
+                │   │   │   ► RATIONALE: If cost spikes, we query ClickHouse to break down the cost 
+                │   │   │     contributions by Kubernetes cluster/namespace to locate the root cause.
+                │   │   │
+                │   │   └── Get cluster drilldown metrics
+                │   │
+                │   └── Activity: publish_anomaly_alert(AnomalyPayload)
+                │       │
+                │       │   ► RATIONALE: Publishes to Kafka topic 'cost-anomaly-alerts'. Using Kafka 
+                │       │     decouples anomaly detection from notification delivery (Slack, pager).
+                │       │
+                │       └── Emit alert JSON to Kafka topic
+                │
+                └── NO (Normal State)
+                    └── Do nothing
+```
+
+---
+
+## Sequencing & Dependency Map
+
+To run the worker successfully, you MUST spin up and configure dependencies in the following strict order:
+
+```
+[Step 1: Docker Containers] ---> [Step 2: Configuration] ---> [Step 3: DB Migrations] ---> [Step 4: Verification] ---> [Step 5: Start Worker]
+  • ClickHouse (8123)              • Copy .env.example          • ./scripts/migrate.sh       • ./scripts/test.sh         • ./scripts/run.sh
+  • PostgreSQL (5432)              • Set hosts & ports            (Applies SQL schemas)        (Ensures integrations       (Starts polling
+  • Redis Cache (6379)                                                                          and mock runs pass)         Temporal task queue)
+  • Kafka & Zookeeper (9092)
+  • Temporal Server (7233)
+```
+
+---
+
+## Setup & Running
+
+Follow these steps to set up the local development environment and run the worker:
+
+### 1. Prerequisites
+Ensure you have the following installed:
+- Python 3.11+
+- Docker & Docker Compose
+- Git
+
+### 2. Configure Virtual Environment & Dependencies
+Create a virtual environment and install the package along with development requirements:
+```bash
+# Create virtual environment
+python3 -m venv .venv
+
+# Activate virtual environment
+source .venv/bin/activate
+
+# Install package in editable mode with development dependencies
+pip install -e ".[dev]"
+```
+
+### 3. Spin Up Infrastructure
+Use the provided `docker-compose` to run ClickingHouse, Postgres, Redis, Kafka, and Temporal locally:
+```bash
+docker compose -f deploy/docker/docker-compose.yaml up -d
+```
+
+### 4. Configure Environment Variables
+Copy the template `.env.example` to `.env` and fill in custom connection strings if necessary:
+```bash
+cp .env.example .env
+```
+
+---
+
+## Database Migrations Guide
+
+The database schema is managed via light-weight migration scripts tracked under `database/migrations/` and verified using a `schema.lock` file.
+
+### How it Works
+The migration status is tracked inside `/database/migrations/schema.lock` containing the active version tag (e.g. `0001` or `0000`).
+
+### Apply Migrations (UP)
+To apply pending database schemas, run:
+```bash
+./scripts/migrate.sh up
+```
+This runs `0001_init.sql` against the configured PostgreSQL database and writes `0001` to `schema.lock`.
+
+### Rollback Migrations
+To revert schemas and return to baseline state, run:
+```bash
+./scripts/migrate.sh rollback
+```
+This executes the rollback SQL scripts and sets the `schema.lock` version to `0000`.
+
+### Creating a New Migration
+1. Add your SQL changes inside `database/migrations/` using a sequential identifier (e.g., `0002_add_index.sql` and `0002_add_index.rollback.sql`).
+2. Update the transition mappings inside `scripts/migrate.py` to support applying and rolling back your new script file.
+
+---
+
+## Running Verification & Worker
+
+### 1. Run Tests
+Verify configuration, domain services, and workflow behavior using the test script:
+```bash
+./scripts/test.sh
+```
+
+### 2. Run Worker
+Start the Temporal worker polling queue `ewma-tasks`:
+```bash
+./scripts/run.sh
+```
+
+---
+
+## Remote Management API (REST)
+
+The worker now includes a FastAPI management layer (port 8000 in prod).
+
+| Endpoint | Method | Description |
+| :--- | :--- | :--- |
+| `/health` | GET | Check worker status and config. |
+| `/trigger` | POST | Trigger the EWMA baseline update workflow on-demand. |
+
+### Example Execution
+
+```bash
+curl -X POST http://localhost:8000/trigger \
+  -H "Content-Type: application/json" \
+  -d '{
+    "force_hour": 42
+  }'
+```
+

temporal_ewma_worker-0.1.1/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "temporal-ewma-worker"
+version = "0.1.1"
+description = "Temporal scheduled workflow worker for EWMA baseline updating and anomaly checking"
+requires-python = ">=3.11"
+dependencies = [
+    "temporalio>=1.5.0",
+    "clickhouse-connect>=0.7.0",
+    "redis>=5.0.0",
+    "psycopg[binary]>=3.1.0",
+    "confluent-kafka>=2.3.0",
+    "opentelemetry-sdk>=1.26.0",
+    "pydantic>=2.0.0",
+    "fastapi>=0.100.0",
+    "uvicorn>=0.22.0"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=4.1.0",
+    "pytest-asyncio>=0.23.0",
+    "mypy>=1.8.0",
+    "ruff>=0.2.0",
+    "httpx>=0.24.0"
+]
+
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+

temporal_ewma_worker-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

temporal_ewma_worker-0.1.1/src/api/index.py

@@ -0,0 +1,41 @@
+import time
+from temporalio.client import Client
+from worker.config import load_config
+from worker.workflows import EwmaWorkflowInput
+
+
+async def health(env: dict[str, str] | None = None) -> dict:
+    cfg = load_config(env)
+    return {
+        "status": "ok",
+        "temporal_host": cfg.temporal_host,
+        "temporal_namespace": cfg.temporal_namespace,
+        "temporal_task_queue": cfg.temporal_task_queue,
+        "redis_url": cfg.redis_url,
+        "kafka_bootstrap_servers": cfg.kafka_bootstrap_servers,
+    }
+
+
+async def trigger_workflow(
+    force_hour: int | None = None, env: dict[str, str] | None = None
+) -> dict:
+    cfg = load_config(env)
+    client = await Client.connect(cfg.temporal_host, namespace=cfg.temporal_namespace)
+    workflow_id = f"ewma-update-manual-{int(time.time())}"
+
+    workflow_input = (
+        EwmaWorkflowInput(force_hour=force_hour) if force_hour is not None else None
+    )
+
+    handle = await client.start_workflow(
+        "EwmaBaselineUpdate",
+        id=workflow_id,
+        task_queue=cfg.temporal_task_queue,
+        args=[workflow_input] if workflow_input else [],
+    )
+
+    return {
+        "status": "triggered",
+        "workflow_id": workflow_id,
+        "run_id": handle.first_execution_run_id,
+    }

temporal_ewma_worker-0.1.1/src/api/rest/v1/app.py

@@ -0,0 +1,33 @@
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel, Field
+from api.index import health as get_health, trigger_workflow as trigger_ewma_workflow
+
+app = FastAPI(title="Temporal EWMA Worker API", version="1.0.0")
+
+
+class TriggerRequest(BaseModel):
+    force_hour: int | None = Field(default=None, ge=0, le=167)
+
+
+@app.get("/health")
+async def health() -> dict:
+    try:
+        return await get_health()
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/trigger")
+async def trigger_workflow(request: TriggerRequest | None = None) -> dict:
+    try:
+        force_hour = request.force_hour if request else None
+        res = await trigger_ewma_workflow(force_hour=force_hour)
+        return res
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)

temporal_ewma_worker-0.1.1/src/features/ewma_compute/index.py

@@ -0,0 +1,3 @@
+from features.ewma_compute.service import EwmaService
+
+__all__ = ["EwmaService"]

temporal_ewma_worker-0.1.1/src/features/ewma_compute/service.py

@@ -0,0 +1,40 @@
+from shared.types.ewma_types import EwmaRecord
+
+
+class EwmaService:
+    @staticmethod
+    def calculate_new_ewma(
+        current_value: float, previous_ewma: float, alpha: float = 0.1
+    ) -> float:
+        return (alpha * current_value) + ((1.0 - alpha) * previous_ewma)
+
+    @staticmethod
+    def process_update(
+        current_value: float,
+        existing_record: EwmaRecord | None,
+        global_model_avg: float,
+    ) -> EwmaRecord:
+        if existing_record is None:
+            return EwmaRecord(
+                service="",
+                model="",
+                hour_of_week=0,
+                ewma_value=global_model_avg,
+                sample_count=1,
+                is_cold_start=True,
+            )
+
+        new_sample_count = existing_record.sample_count + 1
+        new_ewma = EwmaService.calculate_new_ewma(
+            current_value, existing_record.ewma_value
+        )
+        new_is_cold_start = new_sample_count < 7
+
+        return EwmaRecord(
+            service=existing_record.service,
+            model=existing_record.model,
+            hour_of_week=existing_record.hour_of_week,
+            ewma_value=new_ewma,
+            sample_count=new_sample_count,
+            is_cold_start=new_is_cold_start,
+        )

temporal_ewma_worker-0.1.1/src/infra/adapters/clickhouse/clickhouse_adapter.py

@@ -0,0 +1,95 @@
+from typing import List, Tuple
+import clickhouse_connect
+from shared.ports.clickhouse_port import ClickHousePort
+from shared.types.ewma_types import ClusterCost
+
+
+class ClickHouseAdapter(ClickHousePort):
+    def __init__(
+        self, host: str, port: int, username: str, password: str, database: str
+    ):
+        self.client = clickhouse_connect.get_client(
+            host=host,
+            port=port,
+            username=username,
+            password=password,
+            database=database,
+        )
+
+    def get_active_pairs(self) -> List[Tuple[str, str]]:
+        query = """
+        SELECT DISTINCT service, model
+        FROM cost_by_dimension
+        WHERE timestamp >= now() - INTERVAL 7 DAY
+        """
+        result = self.client.query(query)
+        return [(str(row[0]), str(row[1])) for row in result.result_rows]
+
+    def get_cost_history(
+        self, service: str, model: str, hour_of_week: int
+    ) -> List[float]:
+        query = """
+        SELECT sum(cost) as hourly_cost
+        FROM cost_by_dimension
+        WHERE service = %(service)s
+          AND model = %(model)s
+          AND ((toDayOfWeek(timestamp) - 1) * 24 + toHour(timestamp)) = %(hour_of_week)s
+          AND timestamp >= now() - INTERVAL 28 DAY
+        GROUP BY toStartOfHour(timestamp)
+        ORDER BY toStartOfHour(timestamp) DESC
+        LIMIT 4
+        """
+        result = self.client.query(
+            query, {"service": service, "model": model, "hour_of_week": hour_of_week}
+        )
+        return [float(row[0]) for row in result.result_rows if row[0] is not None]
+
+    def get_global_model_avg(self, model: str, hour_of_week: int) -> float:
+        query = """
+        SELECT avg(hourly_cost)
+        FROM (
+            SELECT sum(cost) as hourly_cost
+            FROM cost_by_dimension
+            WHERE model = %(model)s
+              AND ((toDayOfWeek(timestamp) - 1) * 24 + toHour(timestamp)) = %(hour_of_week)s
+              AND timestamp >= now() - INTERVAL 28 DAY
+            GROUP BY toStartOfHour(timestamp)
+        )
+        """
+        result = self.client.query(
+            query, {"model": model, "hour_of_week": hour_of_week}
+        )
+        rows = result.result_rows
+        if rows and rows[0][0] is not None:
+            return float(rows[0][0])
+        return 0.0
+
+    def get_current_cost_1h(self, service: str, model: str) -> float:
+        query = """
+        SELECT sum(cost)
+        FROM cost_by_dimension
+        WHERE service = %(service)s
+          AND model = %(model)s
+          AND timestamp >= now() - INTERVAL 1 HOUR
+        """
+        result = self.client.query(query, {"service": service, "model": model})
+        rows = result.result_rows
+        if rows and rows[0][0] is not None:
+            return float(rows[0][0])
+        return 0.0
+
+    def get_cost_by_cluster_1h(self, service: str, model: str) -> List[ClusterCost]:
+        query = """
+        SELECT cluster_id, sum(cost) as cost
+        FROM cost_by_dimension
+        WHERE service = %(service)s
+          AND model = %(model)s
+          AND timestamp >= now() - INTERVAL 1 HOUR
+        GROUP BY cluster_id
+        """
+        result = self.client.query(query, {"service": service, "model": model})
+        return [
+            ClusterCost(cluster_id=str(row[0]), cost=float(row[1]))
+            for row in result.result_rows
+            if row[0] is not None and row[1] is not None
+        ]

temporal_ewma_worker-0.1.1/src/infra/adapters/kafka/kafka_alert_adapter.py

@@ -0,0 +1,20 @@
+import json
+from dataclasses import asdict
+from confluent_kafka import Producer
+from shared.ports.alert_publisher_port import AlertPublisherPort
+from shared.types.ewma_types import AnomalyPayload
+
+
+class KafkaAlertAdapter(AlertPublisherPort):
+    def __init__(self, bootstrap_servers: str):
+        self.producer = Producer({"bootstrap.servers": bootstrap_servers})
+
+    def publish_anomaly(self, payload: AnomalyPayload) -> None:
+        topic = "alerts.cost.anomaly"
+        payload_dict = asdict(payload)
+        self.producer.produce(
+            topic=topic,
+            key=f"{payload.service}:{payload.model}",
+            value=json.dumps(payload_dict).encode("utf-8"),
+        )
+        self.producer.flush()

temporal_ewma_worker-0.1.1/src/infra/adapters/postgres/postgres_adapter.py

@@ -0,0 +1,58 @@
+import psycopg
+from shared.ports.postgres_port import PostgresPort
+from shared.types.ewma_types import EwmaRecord
+
+
+class PostgresAdapter(PostgresPort):
+    def __init__(self, dsn: str):
+        self.dsn = dsn
+
+    def get_baseline(
+        self, service: str, model: str, hour_of_week: int
+    ) -> EwmaRecord | None:
+        query = """
+        SELECT service, model, hour_of_week, ewma_value, sample_count, is_cold_start, updated_at
+        FROM ewma_baselines
+        WHERE service = %s AND model = %s AND hour_of_week = %s
+        """
+        with psycopg.connect(self.dsn) as conn:
+            with conn.cursor() as cur:
+                cur.execute(query, (service, model, hour_of_week))
+                row = cur.fetchone()
+                if row:
+                    return EwmaRecord(
+                        service=row[0],
+                        model=row[1],
+                        hour_of_week=row[2],
+                        ewma_value=float(row[3]),
+                        sample_count=int(row[4]),
+                        is_cold_start=bool(row[5]),
+                        updated_at=row[6],
+                    )
+        return None
+
+    def upsert_baseline(self, record: EwmaRecord) -> None:
+        query = """
+        INSERT INTO ewma_baselines (service, model, hour_of_week, ewma_value, sample_count, is_cold_start, updated_at)
+        VALUES (%s, %s, %s, %s, %s, %s, CURRENT_TIMESTAMP)
+        ON CONFLICT (service, model, hour_of_week)
+        DO UPDATE SET
+            ewma_value = EXCLUDED.ewma_value,
+            sample_count = EXCLUDED.sample_count,
+            is_cold_start = EXCLUDED.is_cold_start,
+            updated_at = CURRENT_TIMESTAMP
+        """
+        with psycopg.connect(self.dsn) as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    query,
+                    (
+                        record.service,
+                        record.model,
+                        record.hour_of_week,
+                        record.ewma_value,
+                        record.sample_count,
+                        record.is_cold_start,
+                    ),
+                )
+            conn.commit()

temporal_ewma_worker-0.1.1/src/infra/adapters/redis/redis_adapter.py

@@ -0,0 +1,21 @@
+import redis
+from shared.ports.redis_port import RedisPort
+
+
+class RedisAdapter(RedisPort):
+    def __init__(self, url: str):
+        self.client = redis.from_url(url)
+
+    def get_ewma(self, service: str, model: str, hour_of_week: int) -> float | None:
+        key = f"ewma:cost:{service}:{model}:{hour_of_week}"
+        val = self.client.get(key)
+        if val is not None:
+            if isinstance(val, (str, bytes)):
+                return float(val)
+        return None
+
+    def set_ewma(
+        self, service: str, model: str, hour_of_week: int, value: float
+    ) -> None:
+        key = f"ewma:cost:{service}:{model}:{hour_of_week}"
+        self.client.set(key, str(value))

temporal_ewma_worker-0.1.1/src/shared/contracts/validator.py

@@ -0,0 +1,53 @@
+import os
+import re
+from pathlib import Path
+from shared.errors.base import ValidationError
+
+BASE_DIR = Path(__file__).resolve().parents[3]
+CONTRACT_FILE: Path = Path(
+    os.getenv(
+        "CONTRACTS_PATH",
+        BASE_DIR / "contracts" / "workflows" / "ewma_baseline_update.yaml",
+    )
+)
+
+if not CONTRACT_FILE.exists():
+    CONTRACT_FILE = Path("/app/contracts/workflows/ewma_baseline_update.yaml")
+
+
+def _extract_val(text: str, pattern: str) -> str:
+    m = re.search(pattern, text, re.MULTILINE)
+    if not m:
+        raise ValidationError(f"Missing expected pattern in contract: {pattern}")
+    return m.group(1).strip()
+
+
+def load_workflow_contract() -> dict:
+    path = Path(CONTRACT_FILE)
+    if not path.exists():
+        raise ValidationError(f"Contract file not found at {path}")
+    text = path.read_text()
+    validate_workflow_contract(text)
+    return {
+        "workflow": "ewma_baseline_update",
+        "version": int(_extract_val(text, r"^version:\s*(\d+)\s*$")),
+        "cron": _extract_val(text, r"^schedule:\s*\n\s*cron:\s*\"(.*)\"\s*$"),
+    }
+
+
+def validate_workflow_contract(text: str) -> None:
+    required_fragments = [
+        "workflow: ewma_baseline_update",
+        'cron: "0 * * * *"',
+        "activities:",
+        "fetch_active_pairs:",
+        "upsert_baseline:",
+        "publish_anomaly_alert:",
+    ]
+    for fragment in required_fragments:
+        if fragment not in text:
+            raise ValidationError(f"Missing required contract fragment: {fragment}")
+
+    version = int(_extract_val(text, r"^version:\s*(\d+)\s*$"))
+    if version < 1:
+        raise ValidationError("Contract version must be positive integer")

temporal_ewma_worker-0.1.1/src/shared/errors/base.py

@@ -0,0 +1,14 @@
+class WorkerError(Exception):
+    pass
+
+
+class ValidationError(WorkerError):
+    pass
+
+
+class ClickHouseQueryError(WorkerError):
+    pass
+
+
+class DatabaseConnectionError(WorkerError):
+    pass

temporal_ewma_worker-0.1.1/src/shared/ports/alert_publisher_port.py

@@ -0,0 +1,6 @@
+from typing import Protocol
+from shared.types.ewma_types import AnomalyPayload
+
+
+class AlertPublisherPort(Protocol):
+    def publish_anomaly(self, payload: AnomalyPayload) -> None: ...

temporal_ewma_worker-0.1.1/src/shared/ports/clickhouse_port.py

@@ -0,0 +1,16 @@
+from typing import Protocol, Tuple, List
+from shared.types.ewma_types import ClusterCost
+
+
+class ClickHousePort(Protocol):
+    def get_active_pairs(self) -> List[Tuple[str, str]]: ...
+
+    def get_cost_history(
+        self, service: str, model: str, hour_of_week: int
+    ) -> List[float]: ...
+
+    def get_global_model_avg(self, model: str, hour_of_week: int) -> float: ...
+
+    def get_current_cost_1h(self, service: str, model: str) -> float: ...
+
+    def get_cost_by_cluster_1h(self, service: str, model: str) -> List[ClusterCost]: ...

temporal_ewma_worker-0.1.1/src/shared/ports/postgres_port.py

@@ -0,0 +1,10 @@
+from typing import Protocol
+from shared.types.ewma_types import EwmaRecord
+
+
+class PostgresPort(Protocol):
+    def get_baseline(
+        self, service: str, model: str, hour_of_week: int
+    ) -> EwmaRecord | None: ...
+
+    def upsert_baseline(self, record: EwmaRecord) -> None: ...

temporal_ewma_worker-0.1.1/src/shared/ports/redis_port.py

@@ -0,0 +1,9 @@
+from typing import Protocol
+
+
+class RedisPort(Protocol):
+    def get_ewma(self, service: str, model: str, hour_of_week: int) -> float | None: ...
+
+    def set_ewma(
+        self, service: str, model: str, hour_of_week: int, value: float
+    ) -> None: ...

temporal_ewma_worker-0.1.1/src/shared/types/ewma_types.py

@@ -0,0 +1,32 @@
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass
+class EwmaRecord:
+    service: str
+    model: str
+    hour_of_week: int
+    ewma_value: float
+    sample_count: int
+    is_cold_start: bool
+    updated_at: datetime | None = None
+
+
+@dataclass
+class ClusterCost:
+    cluster_id: str
+    cost: float
+
+
+@dataclass
+class AnomalyPayload:
+    service: str
+    model: str
+    hour_of_week: int
+    current_cost: float
+    ewma_value: float
+    threshold_value: float
+    sample_count: int
+    timestamp: str
+    cluster_drilldown: list[ClusterCost]

temporal_ewma_worker-0.1.1/src/temporal_ewma_worker.egg-info/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: temporal-ewma-worker
+Version: 0.1.1
+Summary: Temporal scheduled workflow worker for EWMA baseline updating and anomaly checking
+Requires-Python: >=3.11
+Requires-Dist: temporalio>=1.5.0
+Requires-Dist: clickhouse-connect>=0.7.0
+Requires-Dist: redis>=5.0.0
+Requires-Dist: psycopg[binary]>=3.1.0
+Requires-Dist: confluent-kafka>=2.3.0
+Requires-Dist: opentelemetry-sdk>=1.26.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.22.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Requires-Dist: ruff>=0.2.0; extra == "dev"
+Requires-Dist: httpx>=0.24.0; extra == "dev"

temporal_ewma_worker-0.1.1/src/temporal_ewma_worker.egg-info/SOURCES.txt

@@ -0,0 +1,27 @@
+README.md
+pyproject.toml
+src/api/index.py
+src/api/rest/v1/app.py
+src/features/ewma_compute/index.py
+src/features/ewma_compute/service.py
+src/infra/adapters/clickhouse/clickhouse_adapter.py
+src/infra/adapters/kafka/kafka_alert_adapter.py
+src/infra/adapters/postgres/postgres_adapter.py
+src/infra/adapters/redis/redis_adapter.py
+src/shared/contracts/validator.py
+src/shared/errors/base.py
+src/shared/ports/alert_publisher_port.py
+src/shared/ports/clickhouse_port.py
+src/shared/ports/postgres_port.py
+src/shared/ports/redis_port.py
+src/shared/types/ewma_types.py
+src/temporal_ewma_worker.egg-info/PKG-INFO
+src/temporal_ewma_worker.egg-info/SOURCES.txt
+src/temporal_ewma_worker.egg-info/dependency_links.txt
+src/temporal_ewma_worker.egg-info/requires.txt
+src/temporal_ewma_worker.egg-info/top_level.txt
+src/worker/activities.py
+src/worker/config.py
+src/worker/index.py
+src/worker/registry.py
+src/worker/workflows.py

temporal_ewma_worker-0.1.1/src/temporal_ewma_worker.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

temporal_ewma_worker-0.1.1/src/temporal_ewma_worker.egg-info/requires.txt

@@ -0,0 +1,17 @@
+temporalio>=1.5.0
+clickhouse-connect>=0.7.0
+redis>=5.0.0
+psycopg[binary]>=3.1.0
+confluent-kafka>=2.3.0
+opentelemetry-sdk>=1.26.0
+pydantic>=2.0.0
+fastapi>=0.100.0
+uvicorn>=0.22.0
+
+[dev]
+pytest>=8.0
+pytest-cov>=4.1.0
+pytest-asyncio>=0.23.0
+mypy>=1.8.0
+ruff>=0.2.0
+httpx>=0.24.0

temporal_ewma_worker-0.1.1/src/temporal_ewma_worker.egg-info/top_level.txt

@@ -0,0 +1,5 @@
+api
+features
+infra
+shared
+worker

temporal_ewma_worker-0.1.1/src/worker/activities.py

@@ -0,0 +1,62 @@
+from typing import List, Tuple
+from temporalio import activity
+from shared.ports.clickhouse_port import ClickHousePort
+from shared.ports.redis_port import RedisPort
+from shared.ports.postgres_port import PostgresPort
+from shared.ports.alert_publisher_port import AlertPublisherPort
+from shared.types.ewma_types import EwmaRecord, ClusterCost, AnomalyPayload
+
+
+class EwmaActivities:
+    def __init__(
+        self,
+        clickhouse: ClickHousePort,
+        redis: RedisPort,
+        postgres: PostgresPort,
+        alert_publisher: AlertPublisherPort,
+    ):
+        self.clickhouse = clickhouse
+        self.redis = redis
+        self.postgres = postgres
+        self.alert_publisher = alert_publisher
+
+    @activity.defn(name="fetch_active_pairs")
+    async def fetch_active_pairs(self) -> List[Tuple[str, str]]:
+        return self.clickhouse.get_active_pairs()
+
+    @activity.defn(name="fetch_cost_history")
+    async def fetch_cost_history(
+        self, service: str, model: str, hour_of_week: int
+    ) -> List[float]:
+        return self.clickhouse.get_cost_history(service, model, hour_of_week)
+
+    @activity.defn(name="fetch_global_model_avg")
+    async def fetch_global_model_avg(self, model: str, hour_of_week: int) -> float:
+        return self.clickhouse.get_global_model_avg(model, hour_of_week)
+
+    @activity.defn(name="fetch_current_cost_1h")
+    async def fetch_current_cost_1h(self, service: str, model: str) -> float:
+        return self.clickhouse.get_current_cost_1h(service, model)
+
+    @activity.defn(name="fetch_cost_by_cluster_1h")
+    async def fetch_cost_by_cluster_1h(
+        self, service: str, model: str
+    ) -> List[ClusterCost]:
+        return self.clickhouse.get_cost_by_cluster_1h(service, model)
+
+    @activity.defn(name="get_baseline")
+    async def get_baseline(
+        self, service: str, model: str, hour_of_week: int
+    ) -> EwmaRecord | None:
+        return self.postgres.get_baseline(service, model, hour_of_week)
+
+    @activity.defn(name="upsert_baseline")
+    async def upsert_baseline(self, record: EwmaRecord) -> None:
+        self.postgres.upsert_baseline(record)
+        self.redis.set_ewma(
+            record.service, record.model, record.hour_of_week, record.ewma_value
+        )
+
+    @activity.defn(name="publish_anomaly_alert")
+    async def publish_anomaly_alert(self, payload: AnomalyPayload) -> None:
+        self.alert_publisher.publish_anomaly(payload)

temporal_ewma_worker-0.1.1/src/worker/config.py

@@ -0,0 +1,53 @@
+import os
+from dataclasses import dataclass
+from shared.errors.base import ValidationError
+
+
+@dataclass(frozen=True)
+class WorkerConfig:
+    temporal_host: str
+    temporal_namespace: str
+    temporal_task_queue: str
+    clickhouse_host: str
+    clickhouse_port: int
+    clickhouse_username: str
+    clickhouse_password: str
+    clickhouse_database: str
+    redis_url: str
+    postgres_dsn: str
+    kafka_bootstrap_servers: str
+
+
+def _int_val(raw: str, key: str) -> int:
+    try:
+        return int(raw)
+    except ValueError as exc:
+        raise ValidationError(f"{key} must be an integer") from exc
+
+
+def load_config(env: dict[str, str] | None = None) -> WorkerConfig:
+    source = env or os.environ
+
+    postgres_user = source.get("POSTGRES_USER", "postgres")
+    postgres_password = source.get("POSTGRES_PASSWORD", "postgres")
+    postgres_host = source.get("POSTGRES_HOST", "localhost")
+    postgres_port = source.get("POSTGRES_PORT", "5439")
+    postgres_db = source.get("POSTGRES_DB", "ewma_db")
+
+    postgres_dsn = f"postgresql://{postgres_user}:{postgres_password}@{postgres_host}:{postgres_port}/{postgres_db}"
+
+    return WorkerConfig(
+        temporal_host=source.get("TEMPORAL_HOST", "localhost:7239"),
+        temporal_namespace=source.get("TEMPORAL_NAMESPACE", "default"),
+        temporal_task_queue=source.get("TEMPORAL_TASK_QUEUE", "ewma-tasks"),
+        clickhouse_host=source.get("CLICKHOUSE_HOST", "localhost"),
+        clickhouse_port=_int_val(
+            source.get("CLICKHOUSE_PORT", "8129"), "CLICKHOUSE_PORT"
+        ),
+        clickhouse_username=source.get("CLICKHOUSE_USERNAME", "default"),
+        clickhouse_password=source.get("CLICKHOUSE_PASSWORD", ""),
+        clickhouse_database=source.get("CLICKHOUSE_DATABASE", "default"),
+        redis_url=source.get("REDIS_URL", "redis://localhost:6389/0"),
+        postgres_dsn=source.get("POSTGRES_DSN", postgres_dsn),
+        kafka_bootstrap_servers=source.get("KAFKA_BOOTSTRAP_SERVERS", "localhost:9099"),
+    )

temporal_ewma_worker-0.1.1/src/worker/index.py

@@ -0,0 +1,69 @@
+import asyncio
+import uvicorn
+from api.rest.v1.app import app
+from temporalio.client import Client
+from temporalio.worker import Worker
+from worker.config import load_config
+from worker.activities import EwmaActivities
+from worker.workflows import EwmaBaselineUpdate
+from infra.adapters.clickhouse.clickhouse_adapter import ClickHouseAdapter
+from infra.adapters.redis.redis_adapter import RedisAdapter
+from infra.adapters.postgres.postgres_adapter import PostgresAdapter
+from infra.adapters.kafka.kafka_alert_adapter import KafkaAlertAdapter
+
+
+async def main() -> None:
+    config = load_config()
+
+    clickhouse = ClickHouseAdapter(
+        host=config.clickhouse_host,
+        port=config.clickhouse_port,
+        username=config.clickhouse_username,
+        password=config.clickhouse_password,
+        database=config.clickhouse_database,
+    )
+
+    redis = RedisAdapter(url=config.redis_url)
+    postgres = PostgresAdapter(dsn=config.postgres_dsn)
+    alert_publisher = KafkaAlertAdapter(
+        bootstrap_servers=config.kafka_bootstrap_servers
+    )
+
+    activities = EwmaActivities(
+        clickhouse=clickhouse,
+        redis=redis,
+        postgres=postgres,
+        alert_publisher=alert_publisher,
+    )
+
+    client = await Client.connect(
+        config.temporal_host, namespace=config.temporal_namespace
+    )
+
+    worker = Worker(
+        client,
+        task_queue=config.temporal_task_queue,
+        workflows=[EwmaBaselineUpdate],
+        activities=[
+            activities.fetch_active_pairs,
+            activities.fetch_cost_history,
+            activities.fetch_global_model_avg,
+            activities.fetch_current_cost_1h,
+            activities.fetch_cost_by_cluster_1h,
+            activities.get_baseline,
+            activities.upsert_baseline,
+            activities.publish_anomaly_alert,
+        ],
+    )
+
+    server_config = uvicorn.Config(app, host="0.0.0.0", port=8000, log_level="info")
+    server = uvicorn.Server(server_config)
+
+    await asyncio.gather(
+        worker.run(),
+        server.serve(),
+    )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

temporal_ewma_worker-0.1.1/src/worker/registry.py

@@ -0,0 +1,22 @@
+from dataclasses import dataclass
+from shared.contracts.validator import load_workflow_contract
+from worker.workflows import EwmaBaselineUpdate
+
+
+@dataclass(frozen=True)
+class WorkflowDefinition:
+    name: str
+    handler: type
+    contract: dict
+
+
+def build_registry() -> dict[str, WorkflowDefinition]:
+    contract = load_workflow_contract()
+    return {
+        "ewma_baseline_update": WorkflowDefinition(
+            name="ewma_baseline_update", handler=EwmaBaselineUpdate, contract=contract
+        )
+    }
+
+
+WORKFLOW_REGISTRY = build_registry()

temporal_ewma_worker-0.1.1/src/worker/workflows.py

@@ -0,0 +1,102 @@
+import asyncio
+from dataclasses import dataclass
+from datetime import timedelta
+from temporalio import workflow
+from shared.types.ewma_types import EwmaRecord, AnomalyPayload
+from features.ewma_compute.service import EwmaService
+
+
+@dataclass
+class EwmaWorkflowInput:
+    force_hour: int | None = None
+
+
+@workflow.defn(name="EwmaBaselineUpdate")
+class EwmaBaselineUpdate:
+    @workflow.run
+    async def run(self, workflow_input: EwmaWorkflowInput | None = None) -> None:
+        if workflow_input and workflow_input.force_hour is not None:
+            hour_of_week = workflow_input.force_hour
+        else:
+            current_time = workflow.now()
+            hour_of_week = current_time.weekday() * 24 + current_time.hour
+
+        active_pairs = await workflow.execute_activity(
+            "fetch_active_pairs", start_to_close_timeout=timedelta(seconds=60)
+        )
+
+        tasks = [
+            self._process_pair(service, model, hour_of_week)
+            for service, model in active_pairs
+        ]
+        await asyncio.gather(*tasks)
+
+    async def _process_pair(self, service: str, model: str, hour_of_week: int) -> None:
+        existing_record = await workflow.execute_activity(
+            "get_baseline",
+            args=[service, model, hour_of_week],
+            result_type=EwmaRecord,
+            start_to_close_timeout=timedelta(seconds=10),
+        )
+
+        if existing_record is None:
+            global_avg = await workflow.execute_activity(
+                "fetch_global_model_avg",
+                args=[model, hour_of_week],
+                start_to_close_timeout=timedelta(seconds=30),
+            )
+
+            new_record = EwmaService.process_update(0.0, None, global_avg)
+            new_record.service = service
+            new_record.model = model
+            new_record.hour_of_week = hour_of_week
+
+            await workflow.execute_activity(
+                "upsert_baseline",
+                args=[new_record],
+                start_to_close_timeout=timedelta(seconds=15),
+            )
+        else:
+            current_cost = await workflow.execute_activity(
+                "fetch_current_cost_1h",
+                args=[service, model],
+                start_to_close_timeout=timedelta(seconds=30),
+            )
+
+            is_anomaly = (
+                not existing_record.is_cold_start
+                and current_cost > 3.0 * existing_record.ewma_value
+            )
+
+            if is_anomaly:
+                cluster_drilldown = await workflow.execute_activity(
+                    "fetch_cost_by_cluster_1h",
+                    args=[service, model],
+                    start_to_close_timeout=timedelta(seconds=30),
+                )
+
+                alert_payload = AnomalyPayload(
+                    service=service,
+                    model=model,
+                    hour_of_week=hour_of_week,
+                    current_cost=current_cost,
+                    ewma_value=existing_record.ewma_value,
+                    threshold_value=3.0 * existing_record.ewma_value,
+                    sample_count=existing_record.sample_count,
+                    timestamp=workflow.now().isoformat(),
+                    cluster_drilldown=cluster_drilldown,
+                )
+
+                await workflow.execute_activity(
+                    "publish_anomaly_alert",
+                    args=[alert_payload],
+                    start_to_close_timeout=timedelta(seconds=20),
+                )
+
+            new_record = EwmaService.process_update(current_cost, existing_record, 0.0)
+
+            await workflow.execute_activity(
+                "upsert_baseline",
+                args=[new_record],
+                start_to_close_timeout=timedelta(seconds=15),
+            )