tempokat 0.1.0__py3-none-any.whl

tempokat/__init__.py

@@ -0,0 +1,16 @@
+"""tempokat — a VelociKat library."""
+
+__version__ = "0.1.0"
+
+from tempokat.factory import get_client, get_looper, get_worker
+from tempokat.schedule import TemporalScheduler
+from tempokat.worker import Looper, WorkerFactory
+
+__all__ = [
+    "Looper",
+    "TemporalScheduler",
+    "WorkerFactory",
+    "get_client",
+    "get_looper",
+    "get_worker",
+]

tempokat/api/__init__.py

@@ -0,0 +1 @@
+"""FastAPI integration for tempokat."""

tempokat/api/deps.py

@@ -0,0 +1,30 @@
+"""FastAPI dependencies for Temporal integration."""
+
+import logging
+from typing import Annotated
+
+from fastapi import Depends, Request
+from temporalio.client import Client
+
+from tempokat.factory import get_client
+
+logger = logging.getLogger(__name__)
+
+
+async def get_temporal_client(request: Request) -> Client:
+    """
+    FastAPI dependency that provides a cached Temporal client.
+
+    Expects `request.app.state.config` to be populated with a valid
+    configuration object containing `tempokat.temporalio`.
+    """
+    if not hasattr(request.app.state, "temporal_client"):
+        logger.info("Initializing Temporal client for FastAPI app")
+        cfg = request.app.state.config
+        client = await get_client(cfg.tempokat.temporalio)
+        request.app.state.temporal_client = client
+
+    return request.app.state.temporal_client
+
+
+TemporalClientDep = Annotated[Client, Depends(get_temporal_client)]

tempokat/api/routers/__init__.py

@@ -0,0 +1 @@
+"""FastAPI routers for tempokat."""

tempokat/api/routers/status_route.py

@@ -0,0 +1,29 @@
+"""Agnostic Temporal workflow status router."""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+from temporalio.client import Client
+
+from corekat.exceptions import UnauthorizedError
+from tempokat.api.deps import get_temporal_client
+from tempokat.models import AsyncResponse
+from tempokat.utils import wait_for_result_from_async_response
+
+router = APIRouter(prefix="/api/workflows", tags=["Temporal", "Status"])
+
+
+@router.post("/status", response_model=AsyncResponse)
+async def workflow_status(
+    client: Annotated[Client, Depends(get_temporal_client)],
+    data: AsyncResponse,
+    wait_for: int = 0,
+) -> AsyncResponse:
+    """
+    Retrieves the status of an asynchronous Temporal workflow.
+    Can optionally block and wait for the result if wait_for > 0.
+    """
+    if not data.check_signature():
+        raise UnauthorizedError("Callback signature mismatch")
+
+    return await wait_for_result_from_async_response(client=client, data=data, timeout=wait_for)

tempokat/cli/__init__.py

@@ -0,0 +1,4 @@
+# Generated by VelociKat — DO NOT EDIT
+# template: kat v0.3.1
+# file-hash: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
+

tempokat/cli/schedule.py

@@ -0,0 +1,73 @@
+"""Temporal schedule sync CLI commands."""
+
+import asyncio
+import logging
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from corekat.config import LoggingConfigSchema
+from tempokat.config import config as confload
+from tempokat.factory import get_client
+from tempokat.init import init
+from tempokat.schedule import TemporalScheduler
+
+app = typer.Typer()
+logger = logging.getLogger(__name__)
+
+
+@app.command(context_settings={"auto_envvar_prefix": "TEMPOKAT"})
+def sync(
+    config: Annotated[
+        Path,
+        typer.Option(
+            "--config", "-c", exists=True, help="Configuration file in YAML format.", envvar="TEMPOKAT_CONFIG"
+        ),
+    ],
+    host: Annotated[
+        str | None,
+        typer.Option("--host", help="Temporal server host.", envvar="TEMPOKAT_HOST"),
+    ] = None,
+    namespace: Annotated[
+        str | None,
+        typer.Option("--namespace", "-n", help="Temporal namespace.", envvar="TEMPOKAT_NAMESPACE"),
+    ] = None,
+    log_level: Annotated[
+        str | None,
+        typer.Option("--log-level", help="Log level.", case_sensitive=False, envvar="TEMPOKAT_LOG_LEVEL"),
+    ] = None,
+    use_colors: Annotated[
+        bool | None,
+        typer.Option("--use-colors/--no-use-colors", help="Colorized logging.", envvar="TEMPOKAT_USE_COLORS"),
+    ] = None,
+) -> None:
+    """Synchronize schedule definitions with the Temporal server."""
+    _config = confload(str(config))
+
+    if host is not None:
+        _config.tempokat.temporalio.host = host
+    if namespace is not None:
+        _config.tempokat.temporalio.namespace = namespace
+
+    if log_level is not None or use_colors is not None:
+        current = _config.schema.logging
+        _config.schema.logging = LoggingConfigSchema(
+            level=log_level if log_level else current.level,
+            log_config=current.log_config,
+            use_colors=use_colors if use_colors is not None else current.use_colors,
+        )
+
+    init(_config)
+
+    async def _run() -> None:
+        client = await get_client(_config.tempokat.temporalio)
+        scheduler = TemporalScheduler(client, _config.tempokat.schedules)
+        try:
+            await scheduler.sync_schedules()
+            logger.info("Schedule sync completed successfully")
+        except RuntimeError as e:
+            logger.error("Schedule sync failed: %s", e)
+            raise typer.Exit(code=1) from e
+
+    asyncio.run(_run())

tempokat/cli/worker.py

@@ -0,0 +1,116 @@
+"""Temporal worker CLI commands."""
+
+import asyncio
+import logging
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from corekat.config import LoggingConfigSchema
+from tempokat.config import WorkerConfigSchema
+from tempokat.factory import get_looper
+from tempokat.init import init
+
+app = typer.Typer()
+logger = logging.getLogger(__name__)
+
+
+def worker_command(
+    confload: Callable,
+) -> typer.models.CommandFunctionType:
+    """Creates a typer command to display default config."""
+
+    app = typer.Typer()
+
+    @app.command(context_settings={"auto_envvar_prefix": "TEMPOKAT"})
+    def looper(
+        config: Annotated[
+            Path | None,
+            typer.Option(
+                "--config", "-c", exists=True, help="Configuration file in YAML format.", envvar="TEMPOKAT_CONFIG"
+            ),
+        ] = None,
+        host: Annotated[
+            str | None,
+            typer.Option("--host", help="Temporal server host.", envvar="TEMPOKAT_HOST"),
+        ] = None,
+        namespace: Annotated[
+            str | None,
+            typer.Option("--namespace", "-n", help="Temporal namespace.", envvar="TEMPOKAT_NAMESPACE"),
+        ] = None,
+        worker_name: Annotated[
+            str | None,
+            typer.Option("--worker", "-w", help="Worker name to run (defaults to first/only worker)."),
+        ] = None,
+        queue: Annotated[
+            str | None,
+            typer.Option("--queue", "-q", help="Override task queue for ad-hoc single-worker run."),
+        ] = None,
+        workflow: Annotated[
+            list[str] | None,
+            typer.Option("--workflow", help="Workflow import path (module:Class). Repeatable."),
+        ] = None,
+        activity: Annotated[
+            list[str] | None,
+            typer.Option("--activity", "-a", help="Activity import path (module:fn). Repeatable."),
+        ] = None,
+        interceptor: Annotated[
+            list[str] | None,
+            typer.Option("--interceptor", "-i", help="Interceptor import path. Repeatable."),
+        ] = None,
+        log_level: Annotated[
+            str | None,
+            typer.Option("--log-level", help="Log level.", case_sensitive=False, envvar="TEMPOKAT_LOG_LEVEL"),
+        ] = None,
+        log_config: Annotated[
+            str | None,
+            typer.Option("--log-config", exists=True, help="Logging config file (.ini/.json/.yaml)."),
+        ] = None,
+        use_colors: Annotated[
+            bool | None,
+            typer.Option("--use-colors/--no-use-colors", help="Colorized logging.", envvar="TEMPOKAT_USE_COLORS"),
+        ] = None,
+    ) -> None:
+        """Run Temporal worker(s) from configuration."""
+        _config = confload(str(config) if config else None)
+
+        # Apply CLI overrides to temporalio settings
+        if host is not None:
+            _config.tempokat.temporalio.host = host
+        if namespace is not None:
+            _config.tempokat.temporalio.namespace = namespace
+            for w in _config.tempokat.temporalio.workers:
+                w.namespace = namespace
+        # Re-propagate inheritance after overrides
+        _config.tempokat.temporalio.inherit_worker_settings()
+
+        # Ad-hoc single worker from CLI flags (no config file workers)
+        if not _config.tempokat.temporalio.workers and (queue or workflow):
+            _config.schema.tempokat.temporalio.workers = [
+                WorkerConfigSchema(
+                    name="cli-worker",
+                    queue=queue or "default-queue",
+                    workflows=workflow or [],
+                    activities=activity or [],
+                    interceptors=interceptor or [],
+                )
+            ]
+            _config.tempokat.temporalio.inherit_worker_settings()
+
+        # Re-initialize logging with CLI overrides (same pattern as servekat)
+        if log_level is not None or log_config is not None or use_colors is not None:
+            current = _config.schema.logging
+            _config.schema.logging = LoggingConfigSchema(
+                level=log_level if log_level else current.level,
+                log_config=log_config if log_config is not None else current.log_config,
+                use_colors=use_colors if use_colors is not None else current.use_colors,
+            )
+
+        init(_config)
+        logger.info("Starting tempokat worker(s)")
+        looper = asyncio.run(get_looper(_config))
+        asyncio.run(looper.run())
+
+    return looper

tempokat/config.py

@@ -0,0 +1,179 @@
+import re
+from datetime import timedelta
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, model_validator
+from pydantic_settings import SettingsConfigDict
+
+from corekat.config import BaseConfig
+from corekat.config import Config as CoreKatConfig
+from corekat.config import ConfigSchema as CoreKatConfigSchema
+
+ENVPREFIX = "TEMPOKAT"
+
+TIMEINTERVAL_REGEX = re.compile(r"((?P<hours>\d+?)h)?((?P<minutes>\d+?)m)?((?P<seconds>\d+?)s)?$")
+
+
+def time_interval(time_str: str) -> timedelta:
+    """Parse time interval string like '1h30m45s' into timedelta."""
+    if not time_str:
+        raise ValueError(f"Invalid time string {time_str}")
+    parts = TIMEINTERVAL_REGEX.match(time_str)
+    if not parts:
+        raise ValueError(f"Invalid time string {time_str}")
+    parts = parts.groupdict()
+    time_params = {}
+    for name, param in parts.items():
+        if param:
+            time_params[name] = int(param)
+    return timedelta(**time_params)
+
+
+class TemporalIntervalSchema(BaseModel):
+    """Temporal schedule interval configuration."""
+
+    every: str = Field(default="86400s", description="Interval duration (e.g., '1h', '30m', '86400s').")
+    offset: str | None = Field(default=None, description="Offset from interval start.")
+
+    def every_timedelta(self) -> timedelta:
+        """Convert every field to timedelta."""
+        return time_interval(self.every)
+
+    def offset_timedelta(self) -> timedelta | None:
+        """Convert offset field to timedelta."""
+        if self.offset is None:
+            return None
+        return time_interval(self.offset)
+
+
+class TemporalScheduleSchema(BaseModel):
+    """Temporal schedule definition."""
+
+    workflow_id: str = Field(..., description="Unique workflow identifier.")
+    workflow: str = Field(..., description="Workflow import path (module:Class).")
+    input_schema: str = Field(default="", description="Input schema import path for validation.")
+    task_queue: str = Field(default="default-queue", description="Task queue name.")
+    interval: TemporalIntervalSchema = Field(default_factory=TemporalIntervalSchema, description="Schedule interval.")
+    comment: str = Field(default="", description="Schedule description/comment.")
+    payload: dict[str, Any] = Field(default_factory=dict, description="Workflow input payload.")
+    state: Literal["created", "paused", "deleted"] = Field(default="created", description="Schedule state.")
+
+
+class WorkerConfigSchema(BaseModel):
+    """Temporal worker configuration."""
+
+    name: str = Field(..., description="Worker name.")
+    queue: str = Field(..., description="Task queue to process.")
+    host: str | None = Field(default=None, description="Temporal server host (inherits from parent if not set).")
+    namespace: str | None = Field(default=None, description="Temporal namespace (inherits from parent if not set).")
+    factory: str | None = Field(default=None, description="Worker factory class path.")
+    workflows: list[str] = Field(default_factory=list, description="Workflow import paths or packages to discover.")
+    activities: list[str] = Field(default_factory=list, description="Activity import paths or packages to discover.")
+    discovery: bool = Field(default=True, description="Enable auto-discovery for module paths.")
+    discovery_recursive: bool = Field(default=True, description="Recursively scan submodules during discovery.")
+    interceptors: list[str] | None = Field(default=None, description="Interceptor import paths.")
+    converter: str | None = Field(default=None, description="Data converter import path.")
+    pre_init: list[str] | None = Field(default=None, description="Pre-initialization function paths.")
+    max_concurrent_activities: int = Field(default=100, description="Max concurrent activities.")
+    max_concurrent_workflow_tasks: int | None = Field(default=None, description="Max concurrent workflow tasks.")
+    metric_bind_address: str | None = Field(default=None, description="Prometheus metrics bind address.")
+    enable_metrics: bool | None = Field(default=None, description="Enable Prometheus metrics.")
+    debug_mode: bool = Field(default=False, description="Enable debug mode.")
+    disable_eager_activity_execution: bool = Field(default=True, description="Disable eager activity execution.")
+
+
+class TemporalConfigSchema(BaseConfig):
+    """Temporal connection and worker configuration."""
+
+    host: str = Field(default="127.0.0.1:7233", description="Temporal server host.")
+    namespace: str = Field(default="default", description="Temporal namespace.")
+    default_factory: str = Field(
+        default="tempokat.worker:WorkerFactory",
+        description="Default worker factory class path.",
+    )
+    interceptors: list[str] = Field(default_factory=list, description="Global interceptor import paths.")
+    converter: str | None = Field(default=None, description="Global data converter import path.")
+    pre_init: list[str] = Field(default_factory=list, description="Global pre-initialization function paths.")
+    max_concurrent_activities: int = Field(default=100, description="Default max concurrent activities.")
+    max_concurrent_workflow_tasks: int = Field(default=100, description="Default max concurrent workflow tasks.")
+    metric_bind_address: str = Field(default="0.0.0.0:9000", description="Default Prometheus metrics bind address.")
+    enable_metrics: bool = Field(default=False, description="Enable Prometheus metrics by default.")
+    workers: list[WorkerConfigSchema] = Field(default_factory=list, description="Worker configurations.")
+
+    @model_validator(mode="after")
+    def inherit_worker_settings(self) -> "TemporalConfigSchema":
+        """Apply top-level settings to workers that don't have them set."""
+        for worker in self.workers:
+            if worker.host is None:
+                worker.host = self.host
+            if worker.namespace is None:
+                worker.namespace = self.namespace
+            if worker.factory is None:
+                worker.factory = self.default_factory
+            if worker.converter is None:
+                worker.converter = self.converter
+            if worker.interceptors is None:
+                worker.interceptors = self.interceptors
+            if worker.pre_init is None:
+                worker.pre_init = self.pre_init
+            if worker.max_concurrent_activities is None:
+                worker.max_concurrent_activities = self.max_concurrent_activities
+            if worker.max_concurrent_workflow_tasks is None:
+                worker.max_concurrent_workflow_tasks = self.max_concurrent_workflow_tasks
+            if worker.metric_bind_address is None:
+                worker.metric_bind_address = self.metric_bind_address
+            if worker.enable_metrics is None:
+                worker.enable_metrics = self.enable_metrics
+        return self
+
+
+class TempokatConfigSchema(BaseConfig):
+    """Main tempokat config schema."""
+
+    temporalio: TemporalConfigSchema = Field(
+        default_factory=TemporalConfigSchema,
+        description="Temporal configuration.",
+    )
+    schedules: dict[str, TemporalScheduleSchema] = Field(
+        default_factory=dict,
+        description="Schedule definitions.",
+    )
+
+
+class TempokatSchema(CoreKatConfigSchema):
+    """Main tempokat config schema."""
+
+    model_config = SettingsConfigDict(
+        env_prefix=f"{ENVPREFIX}_",
+        env_nested_delimiter="__",
+        case_sensitive=False,
+        extra="allow",
+    )
+    tempokat: TempokatConfigSchema = Field(
+        default_factory=TempokatConfigSchema,
+        description="Temporal configuration.",
+    )
+
+
+class Config(CoreKatConfig[TempokatSchema]):
+    """tempokat typed configuration manager."""
+
+    __config_class__ = TempokatSchema
+
+    @property
+    def tempokat(self) -> TempokatConfigSchema:
+        """Access tempokat config."""
+        return self.schema.tempokat
+
+
+def config(path: str | None = None) -> Config:
+    """
+    Convenience function to load default CoreKat configuration.
+    For custom schemas, use Config.load() directly.
+
+    Example:
+        cfg = config("myconfig.yaml")
+        print(cfg.schema.name)
+    """
+
+    return Config.load(TempokatSchema, path=path, env_prefix=ENVPREFIX)

tempokat/converters/__init__.py

@@ -0,0 +1,5 @@
+"""Temporal data converters for tempokat."""
+
+from tempokat.converters.pydantic import PydanticPayloadConverter, pydantic_data_converter
+
+__all__ = ["PydanticPayloadConverter", "pydantic_data_converter"]

tempokat/converters/pydantic.py

@@ -0,0 +1,47 @@
+"""Pydantic-aware Temporal payload converter."""
+
+import json
+from typing import Any
+
+from temporalio.api.common.v1 import Payload
+from temporalio.converter import (
+    CompositePayloadConverter,
+    DataConverter,
+    DefaultPayloadConverter,
+    JSONPlainPayloadConverter,
+)
+
+
+class PydanticJSONPayloadConverter(JSONPlainPayloadConverter):
+    """
+    Extends JSONPlainPayloadConverter to serialize Pydantic models via model_dump_json().
+
+    Falls back to standard json.dumps for non-Pydantic values.
+    """
+
+    def to_payload(self, value: Any) -> Payload | None:
+        if hasattr(value, "model_dump_json"):
+            return Payload(
+                metadata={"encoding": self.encoding.encode()},
+                data=value.model_dump_json().encode(),
+            )
+        return Payload(
+            metadata={"encoding": self.encoding.encode()},
+            data=json.dumps(value).encode(),
+        )
+
+
+class PydanticPayloadConverter(CompositePayloadConverter):
+    """Composite payload converter that replaces Temporal's default JSON converter with Pydantic-aware one."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            *(
+                c if not isinstance(c, JSONPlainPayloadConverter) else PydanticJSONPayloadConverter()
+                for c in DefaultPayloadConverter.default_encoding_payload_converters
+            )
+        )
+
+
+pydantic_data_converter = DataConverter(payload_converter_class=PydanticPayloadConverter)
+"""DataConverter using Pydantic JSON serialization."""

tempokat/discovery.py

@@ -0,0 +1,79 @@
+"""Temporal auto-discovery utilities for workflows and activities."""
+
+import importlib
+import inspect
+import logging
+import pkgutil
+from types import ModuleType
+
+logger = logging.getLogger(__name__)
+
+
+def _inspect_module(module: ModuleType, activities: set[str], workflows: set[str]) -> None:
+    """Safely inspects a module to find temporal activities and workflows."""
+    try:
+        members = inspect.getmembers(module)
+    except Exception as e:
+        logger.debug("Failed to inspect module %s: %s", getattr(module, "__name__", "unknown"), e)
+        return
+
+    for name, obj in members:
+        try:
+            # Ensure the object is defined in this exact module to avoid duplicate registrations from imports
+            if getattr(obj, "__module__", None) != module.__name__:
+                continue
+
+            if inspect.isfunction(obj) and hasattr(obj, "__temporal_activity_definition"):
+                activities.add(f"{module.__name__}:{name}")
+            elif inspect.isclass(obj) and hasattr(obj, "__temporal_workflow_definition"):
+                workflows.add(f"{module.__name__}:{name}")
+        except Exception:
+            pass
+
+
+def discover_temporal_components(
+    packages: list[str],
+    recursive: bool = True,
+    discover_activities: bool = True,
+    discover_workflows: bool = True,
+) -> tuple[list[str], list[str]]:
+    """
+    Scans a list of packages for Temporal activities and workflows.
+
+    Args:
+        packages: A list of package names to scan.
+        recursive: Whether to recursively scan all submodules inside the packages.
+        discover_activities: Whether to inspect and return discovered activities.
+        discover_workflows: Whether to inspect and return discovered workflows.
+
+    Returns:
+        A tuple containing two lists: sorted activity import paths and sorted workflow import paths.
+    """
+    activities: set[str] = set()
+    workflows: set[str] = set()
+
+    for package_name in packages:
+        try:
+            package = importlib.import_module(package_name)
+        except ImportError as e:
+            logger.warning("Could not import package '%s' for Temporal auto-discovery: %s", package_name, e)
+            continue
+
+        _inspect_module(package, activities, workflows)
+
+        if recursive:
+            prefix = package.__name__ + "."
+            package_path = getattr(package, "__path__", [])
+
+            for module_info in pkgutil.walk_packages(package_path, prefix):
+                try:
+                    module = importlib.import_module(module_info.name)
+                    _inspect_module(module, activities, workflows)
+                except Exception as e:
+                    logger.debug("Could not inspect submodule '%s': %s", module_info.name, e)
+                    continue
+
+    result_activities = sorted(list(activities)) if discover_activities else []
+    result_workflows = sorted(list(workflows)) if discover_workflows else []
+
+    return result_activities, result_workflows