julee.util.temporal
===================

.. py:module:: julee.util.temporal

.. autoapi-nested-parse::

   Temporal utilities package.

   This package provides utility functions and classes for working with
   Temporal workflows and activities.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/julee/util/temporal/activities/index
   /autoapi/julee/util/temporal/decorators/index


Functions
---------

.. autoapisummary::

   julee.util.temporal.collect_activities_from_instances
   julee.util.temporal.discover_protocol_methods
   julee.util.temporal.temporal_activity_registration
   julee.util.temporal.temporal_workflow_proxy


Package Contents
----------------

.. py:function:: collect_activities_from_instances(*instances)

   Automatically collect all activity methods from decorated instances.

   Uses protocol method discovery to find and collect all methods that have
   been wrapped as Temporal activities by the @temporal_activity_registration
   decorator. This ensures we don't miss any activities and eliminates
   boilerplate registration code.

   :param \*instances: Repository and service instances decorated with
                       @temporal_activity_registration

   :returns: List of activity methods ready for Worker registration

   .. admonition:: Example

      # Instead of manually listing all activities:
      activities = [
          repo.generate_id,
          repo.save,
          repo.get,
          # ... many more lines
      ]
      
      # Use automatic discovery:
      activities = collect_activities_from_instances(
          temporal_assembly_repo,
          temporal_document_repo,
          temporal_knowledge_service,
      )


.. py:function:: discover_protocol_methods(cls_hierarchy)

   Discover protocol methods that should be wrapped as activities.

   This function finds async methods defined in protocol interfaces within
   a class hierarchy. It's used to automatically collect methods that should
   be registered as Temporal activities.

   :param cls_hierarchy: The class MRO (method resolution order)

   :returns: Dict mapping method names to method objects from the concrete class


.. py:function:: temporal_activity_registration(activity_prefix)

   Class decorator that wraps async protocol methods as Temporal activities.

   This decorator inspects the class and wraps all async methods (coroutine
   functions) that don't start with underscore as Temporal activities. The
   activity names are generated using the provided prefix and the method
   name.

   :param activity_prefix: Prefix for activity names (e.g., "sample.payment_repo.minio"). Method names will be appended to create full activity names like "sample.payment_repo.minio.process_payment"

   :returns: The decorated class with all async methods wrapped as Temporal activities

   .. admonition:: Example

      @temporal_activity_registration("sample.payment_repo.minio")
      class TemporalMinioPaymentRepository(MinioPaymentRepository):
          pass
      
      # This automatically creates activities for all protocol methods:
      # - process_payment -> "sample.payment_repo.minio.process_payment"
      # - get_payment -> "sample.payment_repo.minio.get_payment"
      # - refund_payment -> "sample.payment_repo.minio.refund_payment"


.. py:function:: temporal_workflow_proxy(activity_base, default_timeout_seconds = 30, retry_methods = None)

   Class decorator that automatically creates workflow proxy methods that
   delegate to Temporal activities.

   This decorator inspects the protocol/interface being implemented and
   generates methods that call workflow.execute_activity with the appropriate
   activity names, timeouts, and retry policies.

   :param activity_base: Base activity name (e.g., "julee.document_repo.minio")
   :param default_timeout_seconds: Default timeout for activities in seconds
   :param retry_methods: List of method names that should use retry policies

   :returns: The decorated class with all protocol methods implemented as workflow
             activity calls

   .. admonition:: Example

      @temporal_workflow_proxy(
          "julee.document_repo.minio",
          default_timeout_seconds=30,
          retry_methods=["save", "generate_id"]
      )
      class WorkflowDocumentRepositoryProxy(DocumentRepository):
          pass
      
      # This automatically creates workflow methods for all methods:
      # - get() -> calls "julee.document_repo.minio.get" activity
      # - save() -> calls "julee.document_repo.minio.save" with retry
      # - generate_id() -> calls "julee.document_repo.minio.generate_id" with retry