Temporal Configuration

Marqov uses Temporal for durable workflow execution. Workflows defined with @task/@workflow decorators are dispatched to Temporal for parallel execution, retry handling, and observability.

Local Development

Use the provided Docker Compose file at docker/docker-compose.yml:

cd docker
docker-compose up -d

This starts four services:

Local environment variables:

TEMPORAL_ADDRESS=localhost:7233
TEMPORAL_NAMESPACE=default
NEXT_PUBLIC_TEMPORAL_UI_URL=http://localhost:8088

The Temporal UI is available at http://localhost:8088 and provides workflow visualization, history inspection, and debugging tools.

Stopping Services

cd docker
docker-compose down        # Stop containers, keep volumes
docker-compose down -v     # Stop containers and delete volumes (resets state)

Temporal Cloud (Production)

For production, use Temporal Cloud instead of self-hosted Temporal.

Required environment variables:

Temporal Cloud uses TLS by default. The worker SDK auto-negotiates the connection when TEMPORAL_API_KEY is set.

Namespace Configuration

Temporal organizes workflows into namespaces. Marqov uses:

Creating a Namespace (Local)

The temporalio/auto-setup Docker image creates the default namespace automatically. To create additional namespaces:

docker exec -it marqov-temporal-admin tctl namespace register --namespace my-namespace

Task Queues

Marqov uses the marqov-workflows task queue for all workflow execution. This is the default in WorkflowDispatch.run() and create_worker().

Worker Configuration

The Marqov worker registers the JobWorkflow workflow class and execute_task activity with Temporal. Start a worker:

from temporalio.client import Client
from marqov.workflows import create_worker
 
client = await Client.connect("localhost:7233")
worker = await create_worker(client, task_queue="marqov-workflows")
await worker.run()

In production, the platform worker (platform/src/platform_worker.py) handles worker lifecycle automatically.

Dynamic Configuration

The Docker Compose setup mounts docker/temporal-config/ into the Temporal container at /etc/temporal/config/dynamicconfig/. Place a development.yaml file there to override Temporal server defaults.

Workflow Execution Model

1. A @workflow function is called, building a TransportGraph of @task nodes.
2. WorkflowDispatch.run(client) serializes the graph as JSON and starts a Temporal workflow.
3. The JobWorkflow executes tasks level-by-level, running independent tasks in parallel.
4. Each task is executed as a Temporal activity (execute_task), which deserializes the function via cloudpickle and runs it.
5. Results are collected and returned as JSON.

Sandbox restriction: Temporal’s workflow sandbox prevents importing marqov directly in workflow modules. Tasks handle all marqov-dependent logic. The workflow module receives pre-serialized, pure-JSON inputs only.