algen-agent-runtime 0.1.0a1__py3-none-any.whl

algen_agent_runtime/__init__.py

@@ -0,0 +1,50 @@
+"""Composable, provider-neutral agent runtime."""
+
+from algen_agent_runtime.artifacts import (
+    ArtifactLifecycleService,
+    ArtifactScanner,
+    ArtifactScanResult,
+)
+from algen_agent_runtime.cache import CacheContext, CachePolicy, CacheScope, CacheService
+from algen_agent_runtime.retrieval.contracts import (
+    RetrievalQuery,
+    RetrievedDocument,
+    SourceDocument,
+)
+from algen_agent_runtime.retrieval.memory import HashingEmbedder, InMemoryRetriever
+from algen_agent_runtime.runtime.client import AlgenAgentRuntimeClient
+from algen_agent_runtime.runtime.runtime import AgentRuntime
+from algen_agent_runtime.types.contracts import (
+    AgentDefinition,
+    Artifact,
+    ArtifactDescriptor,
+    ArtifactStatus,
+    Citation,
+    RunRequest,
+    RunResult,
+)
+
+__all__ = [
+    "AgentDefinition",
+    "AgentRuntime",
+    "AlgenAgentRuntimeClient",
+    "Artifact",
+    "ArtifactDescriptor",
+    "ArtifactLifecycleService",
+    "ArtifactScanResult",
+    "ArtifactScanner",
+    "ArtifactStatus",
+    "CacheContext",
+    "CachePolicy",
+    "CacheScope",
+    "CacheService",
+    "Citation",
+    "HashingEmbedder",
+    "InMemoryRetriever",
+    "RetrievalQuery",
+    "RetrievedDocument",
+    "RunRequest",
+    "RunResult",
+    "SourceDocument",
+]
+__version__ = "0.1.0a1"

algen_agent_runtime/analytics/__init__.py

@@ -0,0 +1,15 @@
+from algen_agent_runtime.analytics.contracts import *  # noqa: F403
+from algen_agent_runtime.analytics.engine import AnalyticalGraphEngine, AnalyticalNodeRegistry
+from algen_agent_runtime.analytics.handlers import builtin_handlers
+from algen_agent_runtime.analytics.stores import (
+    InMemoryAnalyticalGraphStore,
+    PostgresAnalyticalGraphStore,
+)
+
+__all__ = [
+    "AnalyticalGraphEngine",
+    "AnalyticalNodeRegistry",
+    "InMemoryAnalyticalGraphStore",
+    "PostgresAnalyticalGraphStore",
+    "builtin_handlers",
+]

algen_agent_runtime/analytics/contracts.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any, Protocol
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from algen_agent_runtime.types.contracts import utc_now
+
+
+class AnalyticalNodeKind(StrEnum):
+    SEMANTIC_QUERY = "semantic_query"
+    JOIN_RESULTS = "join_results"
+    COMPARE_PERIODS = "compare_periods"
+    CALCULATE = "calculate"
+    MODEL_CALL = "model_call"
+    RANK = "rank"
+    VERIFY = "verify"
+    COMPOSE = "compose"
+
+
+class NodeStatus(StrEnum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+    CANCELLED = "cancelled"
+
+
+class GraphStatus(StrEnum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class NodeRetryPolicy(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    maximum_attempts: int = Field(default=1, ge=1, le=10)
+    initial_backoff_seconds: float = Field(default=0.1, ge=0, le=60)
+    maximum_backoff_seconds: float = Field(default=5, ge=0, le=300)
+
+
+class NodeCachePolicy(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    enabled: bool = False
+    policy_name: str = "analytical_nodes"
+
+
+class NodeBudget(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    timeout_seconds: float = Field(default=30, gt=0, le=3600)
+    maximum_rows: int = Field(default=10_000, ge=1, le=1_000_000)
+    maximum_bytes: int = Field(default=10_000_000, ge=1)
+    maximum_cost_usd: float | None = Field(default=None, ge=0)
+
+
+class ResultReference(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    node_id: str
+    path: str | None = None
+
+
+class AnalyticalNode(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    id: str = Field(pattern=r"^[a-zA-Z][a-zA-Z0-9_.-]*$")
+    kind: AnalyticalNodeKind
+    dependencies: tuple[str, ...] = ()
+    inputs: dict[str, ResultReference] = Field(default_factory=dict)
+    configuration: dict[str, Any] = Field(default_factory=dict)
+    input_schema: dict[str, Any] = Field(default_factory=lambda: {"type": "object"})
+    output_schema: dict[str, Any] = Field(default_factory=dict)
+    retry: NodeRetryPolicy = Field(default_factory=NodeRetryPolicy)
+    cache: NodeCachePolicy = Field(default_factory=NodeCachePolicy)
+    budget: NodeBudget = Field(default_factory=NodeBudget)
+    concurrency_key: str | None = None
+
+    @model_validator(mode="after")
+    def validate_references(self) -> AnalyticalNode:
+        referenced = {value.node_id for value in self.inputs.values()}
+        if not referenced.issubset(set(self.dependencies)):
+            raise ValueError("every input result reference must be declared as a dependency")
+        if self.id in self.dependencies:
+            raise ValueError("a node cannot depend on itself")
+        return self
+
+
+class AnalyticalGraph(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    name: str
+    version: str
+    nodes: tuple[AnalyticalNode, ...] = Field(min_length=1)
+    maximum_concurrency: int = Field(default=4, ge=1, le=128)
+    maximum_nodes: int = Field(default=100, ge=1, le=1000)
+    timeout_seconds: float = Field(default=300, gt=0, le=86_400)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def validate_dag(self) -> AnalyticalGraph:
+        if len(self.nodes) > self.maximum_nodes:
+            raise ValueError("graph exceeds maximum_nodes")
+        ids = [node.id for node in self.nodes]
+        if len(ids) != len(set(ids)):
+            raise ValueError("graph node identifiers must be unique")
+        known = set(ids)
+        for node in self.nodes:
+            missing = set(node.dependencies) - known
+            if missing:
+                raise ValueError(f"node {node.id!r} has unknown dependencies {sorted(missing)}")
+        visiting: set[str] = set()
+        visited: set[str] = set()
+        dependencies = {node.id: node.dependencies for node in self.nodes}
+
+        def visit(node_id: str) -> None:
+            if node_id in visiting:
+                raise ValueError("analytical graph contains a dependency cycle")
+            if node_id in visited:
+                return
+            visiting.add(node_id)
+            for dependency in dependencies[node_id]:
+                visit(dependency)
+            visiting.remove(node_id)
+            visited.add(node_id)
+
+        for node_id in ids:
+            visit(node_id)
+        return self
+
+
+class ResultProvenance(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    source_ids: tuple[str, ...] = ()
+    source_columns: tuple[str, ...] = ()
+    upstream_result_ids: tuple[str, ...] = ()
+    semantic_layer_digest: str | None = None
+    metric_versions: dict[str, str] = Field(default_factory=dict)
+    method_version: str | None = None
+    model_version: str | None = None
+    query_fingerprint: str | None = None
+    freshness_observed_at: datetime | None = None
+    lineage: dict[str, Any] = Field(default_factory=dict)
+
+
+class AnalyticalResult(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    node_id: str
+    value: Any
+    schema_: dict[str, Any] = Field(default_factory=dict, alias="schema")
+    row_count: int | None = Field(default=None, ge=0)
+    byte_count: int = Field(default=0, ge=0)
+    cost_usd: float = Field(default=0, ge=0)
+    provenance: ResultProvenance = Field(default_factory=ResultProvenance)
+    warnings: tuple[str, ...] = ()
+    created_at: datetime = Field(default_factory=utc_now)
+
+
+class NodeExecution(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    node_id: str
+    status: NodeStatus = NodeStatus.PENDING
+    attempts: int = 0
+    result_id: str | None = None
+    error: str | None = None
+    started_at: datetime | None = None
+    completed_at: datetime | None = None
+
+
+class AnalyticalGraphState(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    id: str
+    tenant_id: str
+    user_id: str
+    graph: AnalyticalGraph
+    status: GraphStatus = GraphStatus.PENDING
+    nodes: dict[str, NodeExecution] = Field(default_factory=dict)
+    results: dict[str, AnalyticalResult] = Field(default_factory=dict)
+    version: int = 0
+    created_at: datetime = Field(default_factory=utc_now)
+    updated_at: datetime = Field(default_factory=utc_now)
+
+
+class GraphExecutionContext(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    tenant_id: str
+    user_id: str
+    session_id: str | None = None
+    run_id: str | None = None
+    authorization_fingerprint: str | None = None
+    attributes: dict[str, Any] = Field(default_factory=dict)
+
+
+class AnalyticalNodeHandler(Protocol):
+    async def __call__(
+        self,
+        node: AnalyticalNode,
+        inputs: dict[str, Any],
+        context: GraphExecutionContext,
+    ) -> AnalyticalResult: ...
+
+
+class AnalyticalGraphStore(Protocol):
+    async def create(self, state: AnalyticalGraphState) -> None: ...
+    async def get(self, graph_id: str, tenant_id: str) -> AnalyticalGraphState | None: ...
+    async def save(self, state: AnalyticalGraphState, expected_version: int) -> None: ...

algen_agent_runtime/analytics/engine.py

@@ -0,0 +1,397 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from collections import defaultdict
+from collections.abc import Mapping
+from time import monotonic
+from typing import Any
+
+import jsonschema
+from opentelemetry import metrics, trace
+
+from algen_agent_runtime.analytics.contracts import (
+    AnalyticalGraph,
+    AnalyticalGraphState,
+    AnalyticalGraphStore,
+    AnalyticalNode,
+    AnalyticalNodeHandler,
+    AnalyticalNodeKind,
+    AnalyticalResult,
+    GraphExecutionContext,
+    GraphStatus,
+    NodeExecution,
+    NodeStatus,
+    ResultProvenance,
+)
+from algen_agent_runtime.cache import CacheContext, CacheService
+from algen_agent_runtime.exceptions.errors import BudgetExceededError, ConfigurationError
+from algen_agent_runtime.types.contracts import utc_now
+
+
+class AnalyticalNodeRegistry:
+    def __init__(self) -> None:
+        self._handlers: dict[AnalyticalNodeKind, AnalyticalNodeHandler] = {}
+
+    def register(self, kind: AnalyticalNodeKind, handler: AnalyticalNodeHandler) -> None:
+        if kind in self._handlers:
+            raise ConfigurationError(f"handler for analytical node {kind.value!r} is registered")
+        self._handlers[kind] = handler
+
+    def get(self, kind: AnalyticalNodeKind) -> AnalyticalNodeHandler:
+        try:
+            return self._handlers[kind]
+        except KeyError as exc:
+            raise ConfigurationError(f"no handler for analytical node {kind.value!r}") from exc
+
+    def kinds(self) -> tuple[AnalyticalNodeKind, ...]:
+        return tuple(sorted(self._handlers, key=str))
+
+
+class AnalyticalGraphEngine:
+    """Checkpointed DAG executor that keeps each node result independently addressable."""
+
+    def __init__(
+        self,
+        registry: AnalyticalNodeRegistry,
+        store: AnalyticalGraphStore,
+        *,
+        cache: CacheService | None = None,
+        maximum_concurrency: int = 8,
+        maximum_node_timeout_seconds: float = 30,
+        maximum_graph_timeout_seconds: float = 300,
+    ) -> None:
+        self._registry = registry
+        self._store = store
+        self._cache = cache
+        self._maximum_concurrency = maximum_concurrency
+        self._maximum_node_timeout_seconds = maximum_node_timeout_seconds
+        self._maximum_graph_timeout_seconds = maximum_graph_timeout_seconds
+        self._tracer = trace.get_tracer("algen_agent_runtime.analytics")
+        meter = metrics.get_meter("algen_agent_runtime.analytics")
+        self._node_duration = meter.create_histogram(
+            "algen_agent_runtime.analytics.node.duration", unit="ms"
+        )
+        self._node_runs = meter.create_counter("algen_agent_runtime.analytics.node.executions")
+        self._locks: defaultdict[str, asyncio.Lock] = defaultdict(asyncio.Lock)
+        self._checkpoint_locks: defaultdict[str, asyncio.Lock] = defaultdict(asyncio.Lock)
+        self._concurrency_locks: defaultdict[str, asyncio.Lock] = defaultdict(asyncio.Lock)
+
+    def register_handler(
+        self,
+        kind: AnalyticalNodeKind,
+        handler: AnalyticalNodeHandler,
+    ) -> None:
+        """Register an application-owned node handler on the composed graph engine."""
+        self._registry.register(kind, handler)
+
+    def handler_kinds(self) -> tuple[AnalyticalNodeKind, ...]:
+        """Return node kinds available in this composed engine."""
+        return self._registry.kinds()
+
+    async def run(
+        self, graph: AnalyticalGraph, context: GraphExecutionContext
+    ) -> AnalyticalGraphState:
+        state = AnalyticalGraphState(
+            id=graph.id,
+            tenant_id=context.tenant_id,
+            user_id=context.user_id,
+            graph=graph,
+            nodes={node.id: NodeExecution(node_id=node.id) for node in graph.nodes},
+        )
+        await self._store.create(state)
+        return await self._drive(state, context)
+
+    async def resume(self, graph_id: str, context: GraphExecutionContext) -> AnalyticalGraphState:
+        state = await self._store.get(graph_id, context.tenant_id)
+        if state is None:
+            raise ConfigurationError(f"analytical graph {graph_id!r} was not found")
+        if state.user_id != context.user_id:
+            raise ConfigurationError("analytical graph belongs to another user")
+        for execution in state.nodes.values():
+            if execution.status == NodeStatus.RUNNING:
+                execution.status = NodeStatus.PENDING
+                execution.error = "recovered after an interrupted worker lease"
+        if state.status == GraphStatus.RUNNING:
+            state.status = GraphStatus.PENDING
+        return await self._drive(state, context)
+
+    async def _drive(
+        self, state: AnalyticalGraphState, context: GraphExecutionContext
+    ) -> AnalyticalGraphState:
+        async with self._locks[state.id]:
+            with self._tracer.start_as_current_span(
+                "analytical_graph.run",
+                attributes={
+                    "analytics.graph.id": state.id,
+                    "analytics.graph.name": state.graph.name,
+                    "analytics.graph.version": state.graph.version,
+                    "tenant.id": context.tenant_id,
+                },
+            ):
+                state.status = GraphStatus.RUNNING
+                await self._checkpoint(state)
+                try:
+                    async with asyncio.timeout(
+                        min(state.graph.timeout_seconds, self._maximum_graph_timeout_seconds)
+                    ):
+                        await self._schedule(state, context)
+                except TimeoutError:
+                    state.status = GraphStatus.FAILED
+                    for execution in state.nodes.values():
+                        if execution.status in {NodeStatus.PENDING, NodeStatus.RUNNING}:
+                            execution.status = NodeStatus.CANCELLED
+                            execution.error = "graph timeout exhausted"
+                    await self._checkpoint(state)
+                    raise BudgetExceededError("analytical graph timeout exhausted") from None
+                except asyncio.CancelledError:
+                    state.status = GraphStatus.CANCELLED
+                    await self._checkpoint(state)
+                    raise
+                except Exception:
+                    state.status = GraphStatus.FAILED
+                    await self._checkpoint(state)
+                    raise
+                state.status = GraphStatus.COMPLETED
+                await self._checkpoint(state)
+                return state
+
+    async def _schedule(self, state: AnalyticalGraphState, context: GraphExecutionContext) -> None:
+        nodes = {node.id: node for node in state.graph.nodes}
+        semaphore = asyncio.Semaphore(
+            min(state.graph.maximum_concurrency, self._maximum_concurrency)
+        )
+        while True:
+            incomplete = {
+                node_id
+                for node_id, execution in state.nodes.items()
+                if execution.status != NodeStatus.COMPLETED
+            }
+            if not incomplete:
+                return
+            failed = [
+                node_id
+                for node_id in incomplete
+                if state.nodes[node_id].status in {NodeStatus.FAILED, NodeStatus.CANCELLED}
+            ]
+            if failed:
+                raise RuntimeError(f"analytical graph failed at nodes {sorted(failed)}")
+            ready = [
+                nodes[node_id]
+                for node_id in incomplete
+                if state.nodes[node_id].status == NodeStatus.PENDING
+                and all(
+                    state.nodes[item].status == NodeStatus.COMPLETED
+                    for item in nodes[node_id].dependencies
+                )
+            ]
+            if not ready:
+                raise RuntimeError("analytical graph has no runnable nodes")
+
+            async def execute(node: AnalyticalNode) -> None:
+                async with semaphore:
+                    if node.concurrency_key:
+                        async with self._concurrency_locks[node.concurrency_key]:
+                            await self._execute_node(state, node, context)
+                    else:
+                        await self._execute_node(state, node, context)
+
+            outcomes = await asyncio.gather(
+                *(execute(node) for node in ready), return_exceptions=True
+            )
+            errors = [item for item in outcomes if isinstance(item, BaseException)]
+            if errors:
+                raise errors[0]
+
+    async def _execute_node(
+        self,
+        state: AnalyticalGraphState,
+        node: AnalyticalNode,
+        context: GraphExecutionContext,
+    ) -> None:
+        execution = state.nodes[node.id]
+        execution.status = NodeStatus.RUNNING
+        execution.started_at = utc_now()
+        await self._checkpoint(state)
+        inputs = self._resolve_inputs(state, node)
+        jsonschema.validate(inputs, node.input_schema)
+        handler = self._registry.get(node.kind)
+        started = monotonic()
+        attributes = {
+            "analytics.graph.id": state.id,
+            "analytics.node.id": node.id,
+            "analytics.node.kind": node.kind.value,
+        }
+        with self._tracer.start_as_current_span(
+            f"analytical_node.{node.kind.value}", attributes=attributes
+        ) as span:
+            try:
+                cached = await self._cached_result(state, node, context, inputs)
+                if cached is not None:
+                    result = cached
+                    span.set_attribute("cache.hit", True)
+                else:
+                    result = await self._invoke(handler, node, inputs, context, execution)
+                    await self._validate_result(node, result)
+                    await self._store_result_cache(state, node, context, inputs, result)
+                    span.set_attribute("cache.hit", False)
+                if result.node_id != node.id:
+                    result = result.model_copy(update={"node_id": node.id})
+                self._enforce_result_budget(node, result)
+                state.results[node.id] = result
+                execution.result_id = result.id
+                execution.status = NodeStatus.COMPLETED
+                execution.completed_at = utc_now()
+                self._node_runs.add(1, {**attributes, "outcome": "completed"})
+            except BaseException as exc:
+                execution.status = NodeStatus.FAILED
+                execution.error = f"{type(exc).__name__}: {exc}"
+                execution.completed_at = utc_now()
+                span.record_exception(exc)
+                self._node_runs.add(1, {**attributes, "outcome": "failed"})
+                raise
+            finally:
+                self._node_duration.record((monotonic() - started) * 1000, attributes)
+                await self._checkpoint(state)
+
+    async def _invoke(
+        self,
+        handler: AnalyticalNodeHandler,
+        node: AnalyticalNode,
+        inputs: dict[str, Any],
+        context: GraphExecutionContext,
+        execution: NodeExecution,
+    ) -> AnalyticalResult:
+        last_error: BaseException | None = None
+        for attempt in range(1, node.retry.maximum_attempts + 1):
+            execution.attempts = attempt
+            try:
+                async with asyncio.timeout(
+                    min(node.budget.timeout_seconds, self._maximum_node_timeout_seconds)
+                ):
+                    return await handler(node, inputs, context)
+            except asyncio.CancelledError:
+                raise
+            except BaseException as exc:
+                last_error = exc
+                if attempt < node.retry.maximum_attempts:
+                    delay = min(
+                        node.retry.maximum_backoff_seconds,
+                        node.retry.initial_backoff_seconds * (2 ** (attempt - 1)),
+                    )
+                    await asyncio.sleep(delay)
+        assert last_error is not None
+        raise last_error
+
+    @staticmethod
+    def _resolve_inputs(state: AnalyticalGraphState, node: AnalyticalNode) -> dict[str, Any]:
+        resolved: dict[str, Any] = {}
+        for name, reference in node.inputs.items():
+            result = state.results[reference.node_id]
+            value = result.value
+            if reference.path:
+                for part in reference.path.split("."):
+                    if isinstance(value, Mapping):
+                        value = value[part]
+                    elif isinstance(value, list):
+                        value = value[int(part)]
+                    else:
+                        raise ConfigurationError(
+                            f"result path {reference.path!r} cannot traverse {type(value).__name__}"
+                        )
+            resolved[name] = value
+        return resolved
+
+    @staticmethod
+    async def _validate_result(node: AnalyticalNode, result: AnalyticalResult) -> None:
+        if node.output_schema:
+            jsonschema.validate(result.value, node.output_schema)
+
+    @staticmethod
+    def _enforce_result_budget(node: AnalyticalNode, result: AnalyticalResult) -> None:
+        encoded = json.dumps(result.value, default=str).encode()
+        if len(encoded) > node.budget.maximum_bytes:
+            raise BudgetExceededError(f"node {node.id!r} exceeded result byte budget")
+        if result.row_count is not None and result.row_count > node.budget.maximum_rows:
+            raise BudgetExceededError(f"node {node.id!r} exceeded result row budget")
+        if (
+            node.budget.maximum_cost_usd is not None
+            and result.cost_usd > node.budget.maximum_cost_usd
+        ):
+            raise BudgetExceededError(f"node {node.id!r} exceeded result cost budget")
+
+    async def _cached_result(
+        self,
+        state: AnalyticalGraphState,
+        node: AnalyticalNode,
+        context: GraphExecutionContext,
+        inputs: dict[str, Any],
+    ) -> AnalyticalResult | None:
+        if self._cache is None or not node.cache.enabled:
+            return None
+        value = await self._cache.get_json(
+            node.cache.policy_name,
+            f"analytical-node.{state.graph.name}.{node.kind.value}",
+            self._cache_material(state, node, inputs),
+            self._cache_context(context),
+        )
+        return AnalyticalResult.model_validate(value) if value is not None else None
+
+    async def _store_result_cache(
+        self,
+        state: AnalyticalGraphState,
+        node: AnalyticalNode,
+        context: GraphExecutionContext,
+        inputs: dict[str, Any],
+        result: AnalyticalResult,
+    ) -> None:
+        if self._cache is None or not node.cache.enabled:
+            return
+        await self._cache.set_json(
+            node.cache.policy_name,
+            f"analytical-node.{state.graph.name}.{node.kind.value}",
+            self._cache_material(state, node, inputs),
+            result.model_dump(mode="json", by_alias=True),
+            self._cache_context(context),
+            tags=(f"graph:{state.graph.name}",),
+        )
+
+    @staticmethod
+    def _cache_material(
+        state: AnalyticalGraphState, node: AnalyticalNode, inputs: dict[str, Any]
+    ) -> dict[str, Any]:
+        return {
+            "graph_version": state.graph.version,
+            "node": node.model_dump(mode="json"),
+            "inputs": inputs,
+        }
+
+    @staticmethod
+    def _cache_context(context: GraphExecutionContext) -> CacheContext:
+        return CacheContext(
+            tenant_id=context.tenant_id,
+            user_id=context.user_id,
+            session_id=context.session_id,
+            run_id=context.run_id,
+            authorization_fingerprint=context.authorization_fingerprint,
+        )
+
+    async def _checkpoint(self, state: AnalyticalGraphState) -> None:
+        async with self._checkpoint_locks[state.id]:
+            state.updated_at = utc_now()
+            await self._store.save(state, state.version)
+
+
+async def passthrough_handler(
+    node: AnalyticalNode, inputs: dict[str, Any], context: GraphExecutionContext
+) -> AnalyticalResult:
+    del context
+    value = inputs if inputs else node.configuration.get("value")
+    return AnalyticalResult(
+        node_id=node.id,
+        value=value,
+        row_count=len(value) if isinstance(value, list) else None,
+        provenance=ResultProvenance(
+            upstream_result_ids=tuple(reference.node_id for reference in node.inputs.values())
+        ),
+    )