prefactor-core 0.2.7__tar.gz → 0.4.0__tar.gz

{prefactor_core-0.2.7 → prefactor_core-0.4.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: prefactor-core
-Version: 0.2.7
+Version: 0.4.0
 Summary: Core Prefactor SDK with async queue-based operations
 Author-email: Prefactor Pty Ltd <josh@prefactor.tech>
 License: MIT
 Requires-Python: <4.0.0,>=3.11.0
-Requires-Dist: prefactor-http>=0.1.5
+Requires-Dist: prefactor-http>=0.3.0
 Requires-Dist: pydantic>=2.0.0
 Description-Content-Type: text/markdown
 

{prefactor_core-0.2.7 → prefactor_core-0.4.0}/pyproject.toml

@@ -9,7 +9,7 @@ authors = [
 ]
 requires-python = ">=3.11.0, <4.0.0"
 dependencies = [
-    "prefactor-http>=0.1.5",
+    "prefactor-http>=0.3.0",
     "pydantic>=2.0.0",
 ]
 

{prefactor_core-0.2.7 → prefactor_core-0.4.0}/src/prefactor_core/_version.py

@@ -3,5 +3,5 @@
 from __future__ import annotations
 
 PACKAGE_NAME = "prefactor-core"
-__version__ = "0.2.7"
+__version__ = "0.4.0"
 PACKAGE_VERSION = __version__

{prefactor_core-0.2.7 → prefactor_core-0.4.0}/src/prefactor_core/client.py

@@ -11,6 +11,7 @@ import asyncio
 import logging
 import time
 from contextlib import asynccontextmanager
+from datetime import datetime
 from typing import TYPE_CHECKING, Any
 
 from prefactor_http.client import PrefactorHttpClient
@@ -19,6 +20,7 @@ from prefactor_http.exceptions import (
     is_permanent_http_error,
     is_transient_http_error,
 )
+from prefactor_http.models.types import InstancePurpose
 
 from ._version import PACKAGE_NAME as CORE_PACKAGE_NAME
 from ._version import PACKAGE_VERSION as CORE_PACKAGE_VERSION
@@ -331,6 +333,11 @@ class PrefactorCoreClient:
                         return
                     raise
 
+            elif operation.type == OperationType.UPDATE_AGENT_INSTANCE:
+                await self._http.agent_instances.update(
+                    agent_instance_id=operation.payload["instance_id"],
+                    quality_payload=operation.payload.get("quality_payload"),
+                )
             elif operation.type == OperationType.CREATE_SPAN:
                 await self._http.agent_spans.create(
                     agent_instance_id=operation.payload["instance_id"],
@@ -339,6 +346,7 @@ class PrefactorCoreClient:
                     id=operation.payload.get("span_id"),
                     parent_span_id=operation.payload.get("parent_span_id"),
                     payload=operation.payload.get("payload"),
+                    started_at=operation.payload.get("started_at"),
                     control_signal_callback=self._on_control_signal,
                 )
 
@@ -401,6 +409,7 @@ class PrefactorCoreClient:
         instance_id: str | None = None,
         external_schema_version_id: str | None = None,
         environment_id: str | None = None,
+        purpose: InstancePurpose | None = None,
     ) -> "AgentInstanceHandle":
         """Create a new agent instance.
 
@@ -419,6 +428,8 @@ class PrefactorCoreClient:
             external_schema_version_id: Optional external identifier for the
                 schema version. Defaults to "auto-generated" when using registry.
             environment_id: Optional environment ID used to scope the agent instance.
+            purpose: Why this instance ran — ``"live"``, ``"smoke_test"``,
+                or ``"eval"``. Omitted (None) lets the API default to ``"live"``.
 
         Returns:
             AgentInstanceHandle for the created instance.
@@ -460,6 +471,7 @@ class PrefactorCoreClient:
             agent_schema_version=final_schema_version,
             instance_id=instance_id,
             environment_id=environment_id,
+            purpose=purpose,
         )
 
         self._set_current_instance(instance_id)
@@ -475,6 +487,7 @@ class PrefactorCoreClient:
         schema_name: str,
         parent_span_id: str | None = None,
         payload: dict[str, Any] | None = None,
+        started_at: datetime | None = None,
     ) -> str:
         """Create a span and return its ID without finishing it.
 
@@ -486,6 +499,7 @@ class PrefactorCoreClient:
             schema_name: Name of the schema for this span.
             parent_span_id: Optional explicit parent span ID.
             payload: Optional initial payload (params/inputs) stored on creation.
+            started_at: Optional ISO 8601 start time (defaults to current time).
 
         Returns:
             The span ID.
@@ -502,23 +516,49 @@ class PrefactorCoreClient:
             schema_name=schema_name,
             parent_span_id=parent_span_id,
             payload=payload,
+            started_at=started_at,
         )
 
     async def finish_span(
         self,
         span_id: str,
         result_payload: dict[str, Any] | None = None,
+        timestamp: datetime | None = None,
     ) -> None:
         """Finish a previously created span.
 
         Args:
             span_id: The ID of the span to finish.
             result_payload: Optional result data to store on the span.
+            timestamp: Optional ISO 8601 finish time (defaults to current time).
         """
         self._ensure_initialized()
         assert self._span_manager is not None
 
-        await self._span_manager.finish(span_id, result_payload=result_payload)
+        await self._span_manager.finish(
+            span_id,
+            result_payload=result_payload,
+            timestamp=timestamp,
+        )
+
+    async def update_agent_instance(
+        self,
+        instance_id: str,
+        quality_payload: dict[str, Any] | None = None,
+    ) -> None:
+        """Update an agent instance (e.g., set quality payload).
+
+        Args:
+            instance_id: The ID of the instance to update.
+            quality_payload: Quality evaluation payload (None to clear).
+        """
+        self._ensure_initialized()
+        assert self._instance_manager is not None
+
+        await self._instance_manager.update(
+            instance_id,
+            quality_payload=quality_payload,
+        )
 
     @asynccontextmanager
     async def span(

{prefactor_core-0.2.7 → prefactor_core-0.4.0}/src/prefactor_core/managers/agent_instance.py

@@ -14,7 +14,7 @@ from ..utils import generate_idempotency_key
 
 if TYPE_CHECKING:
     from prefactor_http.client import PrefactorHttpClient
-    from prefactor_http.models.types import FinishStatus
+    from prefactor_http.models.types import FinishStatus, InstancePurpose
 
     from ..client import PrefactorCoreClient
 
@@ -64,6 +64,7 @@ class AgentInstanceManager:
         agent_id: str | None = None,
         instance_id: str | None = None,
         environment_id: str | None = None,
+        purpose: "InstancePurpose | None" = None,
     ) -> str:
         """Register a new agent instance.
 
@@ -79,6 +80,8 @@ class AgentInstanceManager:
                 the API generates one.
             environment_id: Optional environment ID. Required when using an
                 account-scoped token; omit when using a deployment-scoped token.
+            purpose: Why this instance ran — ``"live"``, ``"smoke_test"``,
+                or ``"eval"``. Omitted (None) lets the API default to ``"live"``.
 
         Returns:
             The instance ID (API-generated).
@@ -90,32 +93,49 @@ class AgentInstanceManager:
             environment_id=environment_id,
             id=instance_id,
             idempotency_key=generate_idempotency_key(),
+            purpose=purpose,
         )
         return result.id
 
-    async def start(self, instance_id: str) -> None:
+    async def start(
+        self,
+        instance_id: str,
+        timestamp: datetime | None = None,
+    ) -> None:
         """Mark an instance as started.
 
         Queues a start operation for the instance.
 
         Args:
             instance_id: The ID of the instance to start.
+            timestamp: Optional ISO 8601 start time (defaults to current time).
         """
-        await self.start_with_idempotency_key(instance_id, generate_idempotency_key())
+        await self.start_with_idempotency_key(
+            instance_id,
+            generate_idempotency_key(),
+            timestamp=timestamp,
+        )
 
     async def start_with_idempotency_key(
         self,
         instance_id: str,
         idempotency_key: str,
+        timestamp: datetime | None = None,
     ) -> None:
-        """Queue a start operation using a stable idempotency key."""
+        """Queue a start operation using a stable idempotency key.
+
+        Args:
+            instance_id: The ID of the instance to start.
+            idempotency_key: Stable key for idempotent retries.
+            timestamp: Optional ISO 8601 start time (defaults to current time).
+        """
         operation = Operation(
             type=OperationType.START_AGENT_INSTANCE,
             payload={
                 "instance_id": instance_id,
                 "idempotency_key": idempotency_key,
             },
-            timestamp=datetime.now(timezone.utc),
+            timestamp=timestamp or datetime.now(timezone.utc),
         )
 
         await self._enqueue(operation)
@@ -124,6 +144,7 @@ class AgentInstanceManager:
         self,
         instance_id: str,
         status: "FinishStatus" = "complete",
+        timestamp: datetime | None = None,
     ) -> None:
         """Mark an instance as finished.
 
@@ -132,11 +153,13 @@ class AgentInstanceManager:
         Args:
             instance_id: The ID of the instance to finish.
             status: Terminal status for the instance. Defaults to ``"complete"``.
+            timestamp: Optional ISO 8601 finish time (defaults to current time).
         """
         await self.finish_with_idempotency_key(
             instance_id,
             generate_idempotency_key(),
             status=status,
+            timestamp=timestamp,
         )
 
     async def finish_with_idempotency_key(
@@ -144,8 +167,16 @@ class AgentInstanceManager:
         instance_id: str,
         idempotency_key: str,
         status: "FinishStatus" = "complete",
+        timestamp: datetime | None = None,
     ) -> None:
-        """Queue a finish operation using a stable idempotency key."""
+        """Queue a finish operation using a stable idempotency key.
+
+        Args:
+            instance_id: The ID of the instance to finish.
+            idempotency_key: Stable key for idempotent retries.
+            status: Terminal status for the instance. Defaults to ``"complete"``.
+            timestamp: Optional ISO 8601 finish time (defaults to current time).
+        """
         operation = Operation(
             type=OperationType.FINISH_AGENT_INSTANCE,
             payload={
@@ -153,6 +184,30 @@ class AgentInstanceManager:
                 "idempotency_key": idempotency_key,
                 "status": status,
             },
+            timestamp=timestamp or datetime.now(timezone.utc),
+        )
+
+        await self._enqueue(operation)
+
+    async def update(
+        self,
+        instance_id: str,
+        quality_payload: dict[str, Any] | None = None,
+    ) -> None:
+        """Update an agent instance (e.g., set quality payload).
+
+        Queues an update operation for the instance.
+
+        Args:
+            instance_id: The ID of the instance to update.
+            quality_payload: Quality evaluation payload (None to clear).
+        """
+        operation = Operation(
+            type=OperationType.UPDATE_AGENT_INSTANCE,
+            payload={
+                "instance_id": instance_id,
+                "quality_payload": quality_payload,
+            },
             timestamp=datetime.now(timezone.utc),
         )
 
@@ -203,19 +258,27 @@ class AgentInstanceHandle:
         """
         return self._instance_id
 
-    async def start(self) -> None:
+    async def start(self, timestamp: datetime | None = None) -> None:
         """Mark the instance as started.
 
         This queues a start operation for the instance.
+
+        Args:
+            timestamp: Optional ISO 8601 start time (defaults to current time).
         """
         manager = self._client.instance_manager
         assert manager is not None
         await manager.start_with_idempotency_key(
             self._instance_id,
             self._start_idempotency_key,
+            timestamp=timestamp,
         )
 
-    async def finish(self, status: "FinishStatus" = "complete") -> None:
+    async def finish(
+        self,
+        status: "FinishStatus" = "complete",
+        timestamp: datetime | None = None,
+    ) -> None:
         """Mark the instance as finished.
 
         Resets the termination monitor (fence + new event) before enqueueing
@@ -225,6 +288,7 @@ class AgentInstanceHandle:
         Args:
             status: Terminal status for the instance — one of ``"complete"``,
                 ``"failed"``, or ``"cancelled"``. Defaults to ``"complete"``.
+            timestamp: Optional ISO 8601 finish time (defaults to current time).
         """
         monitor = getattr(self._client, "_termination_monitor", None)
         if monitor is not None:
@@ -236,6 +300,25 @@ class AgentInstanceHandle:
             self._instance_id,
             self._finish_idempotency_key,
             status=status,
+            timestamp=timestamp,
+        )
+
+    async def update(
+        self,
+        quality_payload: dict[str, Any] | None = None,
+    ) -> None:
+        """Update the instance (e.g., set quality payload).
+
+        This queues an update operation for the instance.
+
+        Args:
+            quality_payload: Quality evaluation payload (None to clear).
+        """
+        manager = self._client.instance_manager
+        assert manager is not None
+        await manager.update(
+            self._instance_id,
+            quality_payload=quality_payload,
         )
 
     async def create_span(
@@ -243,6 +326,7 @@ class AgentInstanceHandle:
         schema_name: str,
         parent_span_id: str | None = None,
         payload: dict[str, Any] | None = None,
+        started_at: datetime | None = None,
     ) -> str:
         """Create a span within this instance and return its ID.
 
@@ -252,6 +336,7 @@ class AgentInstanceHandle:
             schema_name: Name of the schema for this span.
             parent_span_id: Optional explicit parent span ID.
             payload: Optional initial payload (params/inputs) stored on creation.
+            started_at: Optional ISO 8601 start time (defaults to current time).
 
         Returns:
             The span ID.
@@ -262,20 +347,27 @@ class AgentInstanceHandle:
             schema_name=schema_name,
             parent_span_id=parent_span_id,
             payload=payload,
+            started_at=started_at,
         )
 
     async def finish_span(
         self,
         span_id: str,
         result_payload: dict[str, Any] | None = None,
+        timestamp: datetime | None = None,
     ) -> None:
         """Finish a previously created span.
 
         Args:
             span_id: The ID of the span to finish.
             result_payload: Optional result data to store on the span.
+            timestamp: Optional ISO 8601 finish time (defaults to current time).
         """
-        await self._client.finish_span(span_id, result_payload=result_payload)
+        await self._client.finish_span(
+            span_id,
+            result_payload=result_payload,
+            timestamp=timestamp,
+        )
 
     @asynccontextmanager
     async def span(

{prefactor_core-0.2.7 → prefactor_core-0.4.0}/src/prefactor_core/managers/span.py

@@ -109,6 +109,7 @@ class SpanManager:
         self,
         temp_id: str,
         payload: dict[str, Any] | None = None,
+        started_at: datetime | None = None,
     ) -> str:
         """Post the span to the API as ``active`` and return the API-generated ID.
 
@@ -121,6 +122,7 @@ class SpanManager:
         Args:
             temp_id: The temporary ID returned by ``prepare()``.
             payload: Optional params/inputs to send with the span.
+            started_at: Optional ISO 8601 start time (defaults to current time).
 
         Returns:
             The API-generated span ID.
@@ -139,6 +141,7 @@ class SpanManager:
             status="active",
             payload=payload or {},
             parent_span_id=span.parent_span_id,
+            started_at=started_at,
             idempotency_key=generate_idempotency_key(),
         )
 
@@ -148,6 +151,7 @@ class SpanManager:
         span.id = api_id
         span.payload = payload or {}
         span.status = "active"
+        span.started_at = started_at or datetime.now(timezone.utc)
         del self._spans[temp_id]
         self._spans[api_id] = span
 
@@ -165,7 +169,11 @@ class SpanManager:
 
         return api_id
 
-    async def cancel_unstarted(self, temp_id: str) -> None:
+    async def cancel_unstarted(
+        self,
+        temp_id: str,
+        timestamp: datetime | None = None,
+    ) -> None:
         """Cancel a span that was never started.
 
         When ``cancel()`` is called before ``start()``, the span has not yet
@@ -175,6 +183,7 @@ class SpanManager:
 
         Args:
             temp_id: The temporary ID returned by ``prepare()``.
+            timestamp: Optional ISO 8601 finish time (defaults to current time).
 
         Raises:
             KeyError: If temp_id is not a known pending span.
@@ -197,11 +206,13 @@ class SpanManager:
         await self._http.agent_spans.finish(
             agent_span_id=api_id,
             status="cancelled",
+            timestamp=timestamp,
             idempotency_key=generate_idempotency_key(),
         )
 
+        effective_timestamp = timestamp or datetime.now(timezone.utc)
         span.status = "cancelled"
-        span.finished_at = datetime.now(timezone.utc)
+        span.finished_at = effective_timestamp
 
         stack = SpanContextStack.get_stack()
         if temp_id in stack:
@@ -218,6 +229,7 @@ class SpanManager:
         parent_span_id: str | None = None,
         payload: dict[str, Any] | None = None,
         span_id: str | None = None,
+        started_at: datetime | None = None,
     ) -> str:
         """Create a span in one step (prepare + start).
 
@@ -230,6 +242,7 @@ class SpanManager:
             parent_span_id: Optional parent span ID (auto-detected if None).
             payload: Optional initial payload data.
             span_id: Ignored (API generates IDs).
+            started_at: Optional ISO 8601 start time (defaults to current time).
 
         Returns:
             The API-generated span ID.
@@ -239,7 +252,7 @@ class SpanManager:
             schema_name=schema_name,
             parent_span_id=parent_span_id,
         )
-        return await self.start(temp_id, payload=payload)
+        return await self.start(temp_id, payload=payload, started_at=started_at)
 
     async def finish(
         self,
@@ -247,6 +260,7 @@ class SpanManager:
         result_payload: dict[str, Any] | None = None,
         status: "FinishStatus" = "complete",
         idempotency_key: str | None = None,
+        timestamp: datetime | None = None,
     ) -> None:
         """Mark a span as finished.
 
@@ -261,6 +275,7 @@ class SpanManager:
                 to cancel a span that was never started.
             idempotency_key: Optional key to make repeated finish requests
                 duplicate-safe. When omitted, a new key is generated.
+            timestamp: Optional ISO 8601 finish time (defaults to current time).
 
         Raises:
             KeyError: If the span ID is not known.
@@ -268,8 +283,9 @@ class SpanManager:
         if span_id not in self._spans:
             raise KeyError(f"Unknown span: {span_id}")
 
+        effective_timestamp = timestamp or datetime.now(timezone.utc)
         self._spans[span_id].status = status
-        self._spans[span_id].finished_at = datetime.now(timezone.utc)
+        self._spans[span_id].finished_at = effective_timestamp
 
         stack = SpanContextStack.get_stack()
         if span_id in stack:
@@ -288,7 +304,7 @@ class SpanManager:
         operation = Operation(
             type=OperationType.FINISH_SPAN,
             payload=op_payload,
-            timestamp=datetime.now(timezone.utc),
+            timestamp=effective_timestamp,
         )
 
         await self._enqueue(operation)

{prefactor_core-0.2.7 → prefactor_core-0.4.0}/src/prefactor_core/models.py

@@ -28,10 +28,12 @@ class AgentInstance:
     id: str
     agent_id: str
     status: str = "pending"
+    purpose: str | None = None
     created_at: datetime = field(default_factory=datetime.now)
     started_at: datetime | None = None
     finished_at: datetime | None = None
     metadata: dict[str, Any] = field(default_factory=dict)
+    quality_payload: dict[str, Any] | None = None
 
 
 @dataclass

{prefactor_core-0.2.7 → prefactor_core-0.4.0}/src/prefactor_core/operations.py

@@ -19,6 +19,7 @@ class OperationType(Enum):
     REGISTER_AGENT_INSTANCE = auto()
     START_AGENT_INSTANCE = auto()
     FINISH_AGENT_INSTANCE = auto()
+    UPDATE_AGENT_INSTANCE = auto()
     CREATE_SPAN = auto()
     FINISH_SPAN = auto()
 

{prefactor_core-0.2.7 → prefactor_core-0.4.0}/src/prefactor_core/schema_registry.py

@@ -67,6 +67,8 @@ class SchemaRegistry:
         self._span_result_schemas: dict[str, dict[str, Any]] = {}
         # span_type_schemas: name → full structured entry
         self._span_type_schemas: dict[str, dict[str, Any]] = {}
+        # quality_schema: optional quality schema for instance evaluations
+        self._quality_schema: dict[str, Any] | None = None
 
     def register(
         self,
@@ -188,6 +190,46 @@ class SchemaRegistry:
 
         self._span_type_schemas[name] = entry
 
+    def register_quality_schema(
+        self,
+        schema: dict[str, Any],
+        title: str | None = None,
+        description: str | None = None,
+        template: str | None = None,
+        data_risk: dict[str, Any] | None = None,
+    ) -> None:
+        """Register a quality schema for instance evaluations.
+
+        The quality schema defines the shape of quality payloads that can be
+        set on agent instances. It uses the same ``title``, ``description``,
+        ``template``, and ``data_risk`` fields as span type schemas.
+
+        Args:
+            schema: JSON Schema dict defining the quality payload structure.
+            title: Optional human-readable title (defaults to "quality" on API).
+            description: Optional description of the quality evaluation.
+            template: Optional display template using ``{{field}}`` interpolation.
+            data_risk: Optional data risk classification dict (same structure
+                as span type data_risk).
+
+        Raises:
+            ValueError: If a quality schema is already registered.
+        """
+        if self._quality_schema is not None:
+            raise ValueError("Quality schema is already registered")
+
+        entry: dict[str, Any] = {"schema": schema}
+        if title is not None:
+            entry["title"] = title
+        if description is not None:
+            entry["description"] = description
+        if template is not None:
+            entry["template"] = template
+        if data_risk is not None:
+            entry["data_risk"] = data_risk
+
+        self._quality_schema = entry
+
     def get(self, schema_name: str) -> dict[str, Any] | None:
         """Get a params schema by name.
 
@@ -244,6 +286,9 @@ class SchemaRegistry:
         if self._span_type_schemas:
             result["span_type_schemas"] = list(self._span_type_schemas.values())
 
+        if self._quality_schema is not None:
+            result["quality_schema"] = dict(self._quality_schema)
+
         return result
 
     def merge(self, other: "SchemaRegistry") -> None:
@@ -270,6 +315,10 @@ class SchemaRegistry:
             if name in self._span_type_schemas:
                 conflicts.append(f"span_type_schemas/{name}")
 
+        if other._quality_schema is not None:
+            if self._quality_schema is not None:
+                conflicts.append("quality_schema")
+
         if conflicts:
             msg = f"Cannot merge registries - conflicting schemas: {conflicts}"
             raise ValueError(msg)
@@ -283,5 +332,8 @@ class SchemaRegistry:
         for name, entry in other._span_type_schemas.items():
             self._span_type_schemas[name] = entry.copy()
 
+        if other._quality_schema is not None:
+            self._quality_schema = other._quality_schema.copy()
+
 
 __all__ = ["SchemaRegistry"]

{prefactor_core-0.2.7 → prefactor_core-0.4.0}/src/prefactor_core/span_context.py

@@ -6,6 +6,7 @@ and ensures proper cleanup when the span completes.
 
 from __future__ import annotations
 
+from datetime import datetime
 from typing import TYPE_CHECKING, Any
 
 from .utils import generate_idempotency_key
@@ -80,6 +81,7 @@ class SpanContext:
             tuple[FinishStatus, tuple[tuple[str, Any], ...]] | None
         ) = None
         self._finish_idempotency_key: str | None = None
+        self._finish_timestamp: datetime | None = None
 
     @property
     def id(self) -> str:
@@ -93,7 +95,11 @@ class SpanContext:
         """
         return self._span_id
 
-    async def start(self, payload: dict[str, Any] | None = None) -> None:
+    async def start(
+        self,
+        payload: dict[str, Any] | None = None,
+        started_at: datetime | None = None,
+    ) -> None:
         """Post the span to the API as ``active`` with the given params payload.
 
         This triggers ``POST /api/v1/agent_spans``. The span is created as
@@ -105,11 +111,14 @@ class SpanContext:
             payload: Optional params/inputs for the span (e.g. model name,
                 prompt text, tool input). Stored as the span's ``payload``
                 field in the API.
+            started_at: Optional ISO 8601 start time (defaults to current time).
         """
         if self._started:
             return
 
-        api_id = await self._span_manager.start(self._span_id, payload=payload)
+        api_id = await self._span_manager.start(
+            self._span_id, payload=payload, started_at=started_at
+        )
         self._span_id = api_id
         self._started = True
 
@@ -124,37 +133,53 @@ class SpanContext:
         """
         self._result_payload.update(data)
 
-    async def complete(self, result: dict[str, Any] | None = None) -> None:
+    async def complete(
+        self,
+        result: dict[str, Any] | None = None,
+        timestamp: datetime | None = None,
+    ) -> None:
         """Finish the span with ``complete`` status.
 
         Args:
             result: Optional result payload to attach to the span.
+            timestamp: Optional ISO 8601 finish time (defaults to current time).
         """
         if result:
             self.set_result(result)
         self._finish_status = "complete"
+        self._finish_timestamp = timestamp
         await self._finish()
 
-    async def fail(self, result: dict[str, Any] | None = None) -> None:
+    async def fail(
+        self,
+        result: dict[str, Any] | None = None,
+        timestamp: datetime | None = None,
+    ) -> None:
         """Finish the span with ``failed`` status.
 
         Args:
             result: Optional result payload (e.g. error details).
+            timestamp: Optional ISO 8601 finish time (defaults to current time).
         """
         if result:
             self.set_result(result)
         self._finish_status = "failed"
+        self._finish_timestamp = timestamp
         await self._finish()
 
-    async def cancel(self) -> None:
+    async def cancel(self, timestamp: datetime | None = None) -> None:
         """Finish the span with ``cancelled`` status.
 
         Can be called before or after ``start()``. If ``start()`` has not
         been called yet, the span is posted as ``pending`` then immediately
         cancelled — the API only accepts cancellation from the ``pending``
         state, so this is always a valid sequence.
+
+        Args:
+            timestamp: Optional ISO 8601 finish time (defaults to current time).
         """
         self._finish_status = "cancelled"
+        self._finish_timestamp = timestamp
         await self._finish()
 
     async def finish(self) -> None:
@@ -192,7 +217,10 @@ class SpanContext:
 
         try:
             if not self._started and self._finish_status == "cancelled":
-                await self._span_manager.cancel_unstarted(self._span_id)
+                await self._span_manager.cancel_unstarted(
+                    self._span_id,
+                    timestamp=self._finish_timestamp,
+                )
                 self._finished = True
                 return
 
@@ -206,6 +234,7 @@ class SpanContext:
                 result_payload=self._result_payload or None,
                 status=self._finish_status,
                 idempotency_key=self._finish_idempotency_key,
+                timestamp=self._finish_timestamp,
             )
             self._finished = True
         except Exception: