prefactor-core 0.2.1__tar.gz → 0.2.3__tar.gz

{prefactor_core-0.2.1 → prefactor_core-0.2.3}/.gitignore

@@ -69,3 +69,4 @@ htmlcov/
 # Env
 .env
 mise.local.toml
+prefactor.json

{prefactor_core-0.2.1 → prefactor_core-0.2.3}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: prefactor-core
-Version: 0.2.1
+Version: 0.2.3
 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.0
+Requires-Dist: prefactor-http>=0.1.1
 Requires-Dist: pydantic>=2.0.0
 Description-Content-Type: text/markdown
 

{prefactor_core-0.2.1 → prefactor_core-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "prefactor-core"
-version = "0.2.1"
+dynamic = ["version"]
 description = "Core Prefactor SDK with async queue-based operations"
 readme = "README.md"
 license = { text = "MIT" }
@@ -9,7 +9,7 @@ authors = [
 ]
 requires-python = ">=3.11.0, <4.0.0"
 dependencies = [
-    "prefactor-http>=0.1.0",
+    "prefactor-http>=0.1.1",
     "pydantic>=2.0.0",
 ]
 
@@ -17,6 +17,9 @@ dependencies = [
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.version]
+path = "src/prefactor_core/_version.py"
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/prefactor_core"]
 

{prefactor_core-0.2.1 → prefactor_core-0.2.3}/src/prefactor_core/__init__.py

@@ -3,6 +3,9 @@
 This module exports the main classes and functions for the prefactor-core SDK.
 """
 
+from __future__ import annotations
+
+from ._version import __version__
 from .client import PrefactorCoreClient
 from .config import PrefactorCoreConfig, QueueConfig
 from .context_stack import SpanContextStack
@@ -12,6 +15,7 @@ from .exceptions import (
     InstanceNotFoundError,
     OperationError,
     PrefactorCoreError,
+    PrefactorTelemetryFailureError,
     SpanNotFoundError,
 )
 from .managers.agent_instance import AgentInstanceHandle
@@ -20,8 +24,7 @@ from .operations import Operation, OperationType
 from .queue import InMemoryQueue, Queue, QueueClosedError, TaskExecutor
 from .schema_registry import SchemaRegistry
 from .span_context import SpanContext
-
-__version__ = "0.2.1"
+from .utils import generate_idempotency_key, validate_idempotency_key
 
 __all__ = [
     # Client
@@ -39,6 +42,7 @@ __all__ = [
     "OperationError",
     "InstanceNotFoundError",
     "SpanNotFoundError",
+    "PrefactorTelemetryFailureError",
     # Models
     "AgentInstance",
     "Span",
@@ -54,4 +58,8 @@ __all__ = [
     "AgentInstanceHandle",
     # Schema Registry
     "SchemaRegistry",
+    # Utils
+    "generate_idempotency_key",
+    "validate_idempotency_key",
+    "__version__",
 ]

prefactor_core-0.2.3/src/prefactor_core/_version.py

@@ -0,0 +1,7 @@
+"""Package version for prefactor-core."""
+
+from __future__ import annotations
+
+PACKAGE_NAME = "prefactor-core"
+__version__ = "0.2.3"
+PACKAGE_VERSION = __version__

{prefactor_core-0.2.1 → prefactor_core-0.2.3}/src/prefactor_core/client.py

@@ -13,12 +13,16 @@ from contextlib import asynccontextmanager
 from typing import TYPE_CHECKING, Any
 
 from prefactor_http.client import PrefactorHttpClient
+from prefactor_http.exceptions import is_permanent_http_error, is_transient_http_error
 
+from ._version import PACKAGE_NAME as CORE_PACKAGE_NAME
+from ._version import PACKAGE_VERSION as CORE_PACKAGE_VERSION
 from .config import PrefactorCoreConfig
 from .context_stack import SpanContextStack
 from .exceptions import (
     ClientAlreadyInitializedError,
     ClientNotInitializedError,
+    PrefactorTelemetryFailureError,
 )
 from .managers.agent_instance import AgentInstanceManager
 from .managers.span import SpanManager
@@ -31,6 +35,7 @@ if TYPE_CHECKING:
     from .managers.agent_instance import AgentInstanceHandle
 
 logger = logging.getLogger(__name__)
+CORE_SDK_HEADER_ENTRY = f"{CORE_PACKAGE_NAME}@{CORE_PACKAGE_VERSION}"
 
 
 class PrefactorCoreClient:
@@ -61,6 +66,7 @@ class PrefactorCoreClient:
         self,
         config: PrefactorCoreConfig,
         queue: Queue[Operation] | None = None,
+        sdk_header_entry: str | None = None,
     ) -> None:
         """Initialize the client.
 
@@ -68,14 +74,30 @@ class PrefactorCoreClient:
             config: Configuration for the client.
             queue: Optional custom queue implementation. If not provided,
                 an InMemoryQueue is used.
+            sdk_header_entry: Optional upstream SDK header entry to prepend.
         """
         self._config = config
         self._queue = queue or InMemoryQueue()
+        self._sdk_header_entry = sdk_header_entry.strip() if sdk_header_entry else None
         self._http: PrefactorHttpClient | None = None
         self._executor: TaskExecutor | None = None
         self._instance_manager: AgentInstanceManager | None = None
         self._span_manager: SpanManager | None = None
         self._initialized = False
+        self._telemetry_failure: PrefactorTelemetryFailureError | None = None
+        self._telemetry_failure_observed = False
+
+    def _build_http_sdk_header(self) -> str:
+        """Build the effective SDK header for HTTP requests."""
+        if self._sdk_header_entry:
+            return f"{self._sdk_header_entry} {CORE_SDK_HEADER_ENTRY}"
+        return CORE_SDK_HEADER_ENTRY
+
+    def _set_sdk_header_entry(self, sdk_header_entry: str | None) -> None:
+        """Set the upstream SDK header entry for this client lifetime."""
+        self._sdk_header_entry = sdk_header_entry.strip() if sdk_header_entry else None
+        if self._http is not None:
+            self._http._sdk_header = self._build_http_sdk_header()
 
     async def __aenter__(self) -> "PrefactorCoreClient":
         """Enter async context manager."""
@@ -84,7 +106,11 @@ class PrefactorCoreClient:
 
     async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
         """Exit async context manager."""
-        await self.close()
+        try:
+            await self.close()
+        except PrefactorTelemetryFailureError:
+            if exc_type is None:
+                raise
 
     async def initialize(self) -> None:
         """Initialize the client and start processing.
@@ -101,13 +127,17 @@ class PrefactorCoreClient:
             raise ClientAlreadyInitializedError("Client is already initialized")
 
         # Initialize HTTP client
-        self._http = PrefactorHttpClient(self._config.http_config)
+        self._http = PrefactorHttpClient(
+            self._config.http_config,
+            sdk_header=self._build_http_sdk_header(),
+        )
         await self._http.__aenter__()
 
         # Initialize executor
         self._executor = TaskExecutor(
             queue=self._queue,
             handler=self._process_operation,
+            is_retryable=self._is_retryable_operation_error,
             num_workers=self._config.queue_config.num_workers,
             max_retries=self._config.queue_config.max_retries,
         )
@@ -144,6 +174,10 @@ class PrefactorCoreClient:
 
         self._initialized = False
 
+        if self._telemetry_failure is not None and not self._telemetry_failure_observed:
+            self._telemetry_failure_observed = True
+            raise self._telemetry_failure
+
     def _ensure_initialized(self) -> None:
         """Ensure the client is initialized.
 
@@ -156,12 +190,55 @@ class PrefactorCoreClient:
                 "use as context manager."
             )
 
+    def _record_telemetry_failure(
+        self, cause: Exception, operation_type: OperationType | str
+    ) -> None:
+        """Latch the first permanent telemetry failure."""
+        if self._telemetry_failure is not None:
+            return
+        if isinstance(operation_type, OperationType):
+            operation_name = operation_type.name
+        else:
+            operation_name = str(operation_type)
+        self._telemetry_failure = PrefactorTelemetryFailureError(
+            f"Telemetry permanently failed during {operation_name}",
+            cause=cause,
+            operation_type=operation_name,
+            dropped_operations=0,
+        )
+
+    def _increment_dropped_operations(self) -> None:
+        """Increment the dropped operation counter on the latched failure."""
+        if self._telemetry_failure is None:
+            return
+        self._telemetry_failure.dropped_operations += 1
+
+    def _raise_if_telemetry_failed(self) -> None:
+        """Raise the latched telemetry failure for caller-visible operations."""
+        if self._telemetry_failure is None:
+            return
+        self._telemetry_failure_observed = True
+        raise self._telemetry_failure
+
+    def _is_retryable_operation_error(self, error: Exception) -> bool:
+        """Return True when the worker should retry the operation."""
+        if isinstance(error, PrefactorTelemetryFailureError):
+            return False
+        if is_permanent_http_error(error):
+            return False
+        if is_transient_http_error(error):
+            return True
+        return True
+
     async def _enqueue(self, operation: Operation) -> None:
         """Add an operation to the queue.
 
         Args:
             operation: The operation to queue.
         """
+        if self._telemetry_failure is not None:
+            self._increment_dropped_operations()
+            self._raise_if_telemetry_failed()
         await self._queue.put(operation)
 
     async def _process_operation(self, operation: Operation) -> None:
@@ -174,6 +251,9 @@ class PrefactorCoreClient:
         """
         if not self._http:
             return
+        if self._telemetry_failure is not None:
+            self._increment_dropped_operations()
+            return
 
         try:
             if operation.type == OperationType.REGISTER_AGENT_INSTANCE:
@@ -188,12 +268,14 @@ class PrefactorCoreClient:
                 await self._http.agent_instances.start(
                     agent_instance_id=operation.payload["instance_id"],
                     timestamp=operation.timestamp,
+                    idempotency_key=operation.payload.get("idempotency_key"),
                 )
 
             elif operation.type == OperationType.FINISH_AGENT_INSTANCE:
                 await self._http.agent_instances.finish(
                     agent_instance_id=operation.payload["instance_id"],
                     timestamp=operation.timestamp,
+                    idempotency_key=operation.payload.get("idempotency_key"),
                 )
             elif operation.type == OperationType.CREATE_SPAN:
                 await self._http.agent_spans.create(
@@ -211,16 +293,24 @@ class PrefactorCoreClient:
                     status=operation.payload.get("status", "complete"),
                     result_payload=operation.payload.get("result_payload"),
                     timestamp=operation.timestamp,
+                    idempotency_key=operation.payload.get("idempotency_key"),
                 )
 
         except Exception as e:
-            # Log error but don't re-raise - we don't want to crash the worker
+            if is_permanent_http_error(e):
+                self._record_telemetry_failure(e, operation.type)
+            # Log error and re-raise so TaskExecutor retries can run
             logger.error(
                 f"Failed to process operation {operation.type}: {e}",
                 exc_info=True,
             )
             raise
 
+    @property
+    def instance_manager(self) -> AgentInstanceManager | None:
+        """Public accessor for the agent instance manager."""
+        return self._instance_manager
+
     async def create_agent_instance(
         self,
         agent_id: str,
@@ -254,6 +344,7 @@ class PrefactorCoreClient:
             ValueError: If no schema version provided and registry not configured.
         """
         self._ensure_initialized()
+        self._raise_if_telemetry_failed()
         assert self._instance_manager is not None
 
         # Determine the agent_schema_version to use
@@ -310,6 +401,7 @@ class PrefactorCoreClient:
             The span ID.
         """
         self._ensure_initialized()
+        self._raise_if_telemetry_failed()
         assert self._span_manager is not None
 
         if parent_span_id is None:
@@ -344,7 +436,6 @@ class PrefactorCoreClient:
         instance_id: str,
         schema_name: str,
         parent_span_id: str | None = None,
-        span_id: str | None = None,
         payload: dict[str, Any] | None = None,
     ):
         """Context manager for creating and finishing a span.
@@ -366,7 +457,6 @@ class PrefactorCoreClient:
             instance_id: ID of the agent instance this span belongs to.
             schema_name: Name of the schema for this span.
             parent_span_id: Optional explicit parent span ID.
-            span_id: Ignored (API generates IDs).
             payload: Optional initial payload sent via auto-start on exit
                 if ``start()`` is never called explicitly.
 
@@ -374,6 +464,7 @@ class PrefactorCoreClient:
             SpanContext for the created span.
         """
         self._ensure_initialized()
+        self._raise_if_telemetry_failed()
         assert self._span_manager is not None
 
         # Import here to avoid circular import

{prefactor_core-0.2.1 → prefactor_core-0.2.3}/src/prefactor_core/exceptions.py

@@ -1,5 +1,7 @@
 """Custom exceptions for prefactor-core."""
 
+from __future__ import annotations
+
 
 class PrefactorCoreError(Exception):
     """Base exception for all prefactor-core errors."""
@@ -39,6 +41,23 @@ class SpanNotFoundError(PrefactorCoreError):
     pass
 
 
+class PrefactorTelemetryFailureError(PrefactorCoreError):
+    """Raised when telemetry enters a permanent failure state."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        cause: Exception,
+        operation_type: str | None = None,
+        dropped_operations: int = 0,
+    ) -> None:
+        super().__init__(message)
+        self.cause = cause
+        self.operation_type = operation_type
+        self.dropped_operations = dropped_operations
+
+
 __all__ = [
     "PrefactorCoreError",
     "ClientNotInitializedError",
@@ -46,4 +65,5 @@ __all__ = [
     "OperationError",
     "InstanceNotFoundError",
     "SpanNotFoundError",
+    "PrefactorTelemetryFailureError",
 ]

{prefactor_core-0.2.1 → prefactor_core-0.2.3}/src/prefactor_core/managers/agent_instance.py

@@ -10,6 +10,7 @@ from datetime import datetime, timezone
 from typing import TYPE_CHECKING, Any, Awaitable, Callable
 
 from ..operations import Operation, OperationType
+from ..utils import generate_idempotency_key
 
 if TYPE_CHECKING:
     from prefactor_http.client import PrefactorHttpClient
@@ -71,7 +72,9 @@ class AgentInstanceManager:
             agent_id: ID of the agent to create an instance for.
             agent_version: Version information (name, external_identifier, etc.).
             agent_schema_version: Schema version information.
-            instance_id: Ignored (API generates IDs with correct partition).
+            instance_id: Optional ID to forward to the API as ``id``.  When
+                provided, the API uses it as the instance ID; when omitted,
+                the API generates one.
 
         Returns:
             The instance ID (API-generated).
@@ -81,6 +84,7 @@ class AgentInstanceManager:
             agent_version=agent_version,
             agent_schema_version=agent_schema_version,
             id=instance_id,
+            idempotency_key=generate_idempotency_key(),
         )
         return result.id
 
@@ -92,9 +96,20 @@ class AgentInstanceManager:
         Args:
             instance_id: The ID of the instance to start.
         """
+        await self.start_with_idempotency_key(instance_id, generate_idempotency_key())
+
+    async def start_with_idempotency_key(
+        self,
+        instance_id: str,
+        idempotency_key: str,
+    ) -> None:
+        """Queue a start operation using a stable idempotency key."""
         operation = Operation(
             type=OperationType.START_AGENT_INSTANCE,
-            payload={"instance_id": instance_id},
+            payload={
+                "instance_id": instance_id,
+                "idempotency_key": idempotency_key,
+            },
             timestamp=datetime.now(timezone.utc),
         )
 
@@ -108,9 +123,20 @@ class AgentInstanceManager:
         Args:
             instance_id: The ID of the instance to finish.
         """
+        await self.finish_with_idempotency_key(instance_id, generate_idempotency_key())
+
+    async def finish_with_idempotency_key(
+        self,
+        instance_id: str,
+        idempotency_key: str,
+    ) -> None:
+        """Queue a finish operation using a stable idempotency key."""
         operation = Operation(
             type=OperationType.FINISH_AGENT_INSTANCE,
-            payload={"instance_id": instance_id},
+            payload={
+                "instance_id": instance_id,
+                "idempotency_key": idempotency_key,
+            },
             timestamp=datetime.now(timezone.utc),
         )
 
@@ -149,8 +175,8 @@ class AgentInstanceHandle:
         """
         self._instance_id = instance_id
         self._client = client
-        self._started = False
-        self._finished = False
+        self._start_idempotency_key = generate_idempotency_key()
+        self._finish_idempotency_key = generate_idempotency_key()
 
     @property
     def id(self) -> str:
@@ -166,26 +192,24 @@ class AgentInstanceHandle:
 
         This queues a start operation for the instance.
         """
-        if self._started:
-            return
-
-        manager = self._client._instance_manager
+        manager = self._client.instance_manager
         assert manager is not None
-        await manager.start(self._instance_id)
-        self._started = True
+        await manager.start_with_idempotency_key(
+            self._instance_id,
+            self._start_idempotency_key,
+        )
 
     async def finish(self) -> None:
         """Mark the instance as finished.
 
         This queues a finish operation for the instance.
         """
-        if self._finished:
-            return
-
-        manager = self._client._instance_manager
+        manager = self._client.instance_manager
         assert manager is not None
-        await manager.finish(self._instance_id)
-        self._finished = True
+        await manager.finish_with_idempotency_key(
+            self._instance_id,
+            self._finish_idempotency_key,
+        )
 
     async def create_span(
         self,
@@ -205,6 +229,7 @@ class AgentInstanceHandle:
         Returns:
             The span ID.
         """
+        self._client._raise_if_telemetry_failed()
         return await self._client.create_span(
             instance_id=self._instance_id,
             schema_name=schema_name,

{prefactor_core-0.2.1 → prefactor_core-0.2.3}/src/prefactor_core/managers/span.py

@@ -5,13 +5,13 @@ calls into Operation objects that are queued for processing. It also manages
 the span stack for automatic parent detection.
 """
 
-import uuid
 from datetime import datetime, timezone
 from typing import TYPE_CHECKING, Any, Awaitable, Callable
 
 from ..context_stack import SpanContextStack
 from ..models import Span
 from ..operations import Operation, OperationType
+from ..utils import generate_idempotency_key
 
 if TYPE_CHECKING:
     from prefactor_http.client import PrefactorHttpClient
@@ -90,7 +90,7 @@ class SpanManager:
         if parent_span_id is None:
             parent_span_id = SpanContextStack.peek()
 
-        temp_id = str(uuid.uuid4())
+        temp_id = generate_idempotency_key()
 
         span = Span(
             id=temp_id,
@@ -139,6 +139,7 @@ class SpanManager:
             status="active",
             payload=payload or {},
             parent_span_id=span.parent_span_id,
+            idempotency_key=generate_idempotency_key(),
         )
 
         api_id = result.id
@@ -150,6 +151,10 @@ class SpanManager:
         del self._spans[temp_id]
         self._spans[api_id] = span
 
+        for child_span in self._spans.values():
+            if child_span.parent_span_id == temp_id:
+                child_span.parent_span_id = api_id
+
         # Replace temp ID on the context stack
         stack = SpanContextStack.get_stack()
         new_stack = [api_id if s == temp_id else s for s in stack]
@@ -185,12 +190,14 @@ class SpanManager:
             status="pending",
             payload={},
             parent_span_id=span.parent_span_id,
+            idempotency_key=generate_idempotency_key(),
         )
         api_id = result.id
 
         await self._http.agent_spans.finish(
             agent_span_id=api_id,
             status="cancelled",
+            idempotency_key=generate_idempotency_key(),
         )
 
         span.status = "cancelled"
@@ -239,6 +246,7 @@ class SpanManager:
         span_id: str,
         result_payload: dict[str, Any] | None = None,
         status: "FinishStatus" = "complete",
+        idempotency_key: str | None = None,
     ) -> None:
         """Mark a span as finished.
 
@@ -251,6 +259,8 @@ class SpanManager:
                 ``"cancelled"`` (default: ``"complete"``). The span must be
                 ``active`` for this to succeed; use ``cancel_unstarted()``
                 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.
 
         Raises:
             KeyError: If the span ID is not known.
@@ -261,10 +271,17 @@ class SpanManager:
         self._spans[span_id].status = status
         self._spans[span_id].finished_at = datetime.now(timezone.utc)
 
-        if SpanContextStack.peek() == span_id:
-            SpanContextStack.pop()
+        stack = SpanContextStack.get_stack()
+        if span_id in stack:
+            from ..context_stack import _current_span_stack
+
+            _current_span_stack.set([s for s in stack if s != span_id])
 
-        op_payload: dict[str, Any] = {"span_id": span_id, "status": status}
+        op_payload: dict[str, Any] = {
+            "span_id": span_id,
+            "status": status,
+            "idempotency_key": idempotency_key or generate_idempotency_key(),
+        }
         if result_payload is not None:
             op_payload["result_payload"] = result_payload
 

{prefactor_core-0.2.1 → prefactor_core-0.2.3}/src/prefactor_core/operations.py

@@ -38,6 +38,8 @@ class Operation:
         metadata: Optional additional metadata.
 
     Example:
+        from datetime import datetime, timezone
+
         operation = Operation(
             type=OperationType.CREATE_SPAN,
             payload={

{prefactor_core-0.2.1 → prefactor_core-0.2.3}/src/prefactor_core/queue/executor.py

@@ -42,6 +42,8 @@ class TaskExecutor:
         handler: Callable[[Any], Awaitable[None]],
         num_workers: int = 3,
         max_retries: int = 3,
+        *,
+        is_retryable: Callable[[Exception], bool] | None = None,
     ) -> None:
         """Initialize the task executor.
 
@@ -50,9 +52,12 @@ class TaskExecutor:
             handler: Async function to process each item.
             num_workers: Number of concurrent worker tasks.
             max_retries: Maximum retry attempts per item.
+            is_retryable: Optional predicate that decides whether a
+                handler failure should be retried.
         """
         self._queue = queue
         self._handler = handler
+        self._is_retryable = is_retryable or (lambda exc: True)
         self._num_workers = num_workers
         self._max_retries = max_retries
         self._workers: list[Task] = []
@@ -162,13 +167,17 @@ class TaskExecutor:
         """
         last_error: Exception | None = None
 
-        for attempt in range(self._max_retries):
+        total_attempts = self._max_retries + 1
+
+        for attempt in range(total_attempts):
             try:
                 await self._handler(item)
                 return
             except Exception as e:
                 last_error = e
-                if attempt < self._max_retries - 1:
+                if not self._is_retryable(e):
+                    raise
+                if attempt < total_attempts - 1:
                     delay = 2**attempt  # 1s, 2s, 4s
                     logger.warning(
                         f"Attempt {attempt + 1} failed, retrying in {delay}s: {e}"