prefactor-core 0.2.2__tar.gz → 0.2.4__tar.gz

{prefactor_core-0.2.2 → prefactor_core-0.2.4}/.gitignore

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

{prefactor_core-0.2.2 → prefactor_core-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefactor-core
-Version: 0.2.2
+Version: 0.2.4
 Summary: Core Prefactor SDK with async queue-based operations
 Author-email: Prefactor Pty Ltd <josh@prefactor.tech>
 License: MIT

{prefactor_core-0.2.2 → prefactor_core-0.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "prefactor-core"
-version = "0.2.2"
+dynamic = ["version"]
 description = "Core Prefactor SDK with async queue-based operations"
 readme = "README.md"
 license = { text = "MIT" }
@@ -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.2 → prefactor_core-0.2.4}/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
@@ -22,8 +26,6 @@ from .schema_registry import SchemaRegistry
 from .span_context import SpanContext
 from .utils import generate_idempotency_key, validate_idempotency_key
 
-__version__ = "0.2.1"
-
 __all__ = [
     # Client
     "PrefactorCoreClient",
@@ -40,6 +42,7 @@ __all__ = [
     "OperationError",
     "InstanceNotFoundError",
     "SpanNotFoundError",
+    "PrefactorTelemetryFailureError",
     # Models
     "AgentInstance",
     "Span",
@@ -58,4 +61,5 @@ __all__ = [
     # Utils
     "generate_idempotency_key",
     "validate_idempotency_key",
+    "__version__",
 ]

prefactor_core-0.2.4/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.4"
+PACKAGE_VERSION = __version__

{prefactor_core-0.2.2 → prefactor_core-0.2.4}/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:
@@ -194,6 +274,7 @@ class PrefactorCoreClient:
             elif operation.type == OperationType.FINISH_AGENT_INSTANCE:
                 await self._http.agent_instances.finish(
                     agent_instance_id=operation.payload["instance_id"],
+                    status=operation.payload.get("status", "complete"),
                     timestamp=operation.timestamp,
                     idempotency_key=operation.payload.get("idempotency_key"),
                 )
@@ -217,6 +298,8 @@ class PrefactorCoreClient:
                 )
 
         except Exception as e:
+            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}",
@@ -262,6 +345,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
@@ -318,6 +402,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:
@@ -380,6 +465,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.2 → prefactor_core-0.2.4}/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.2 → prefactor_core-0.2.4}/src/prefactor_core/managers/agent_instance.py

@@ -14,6 +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 ..client import PrefactorCoreClient
 
@@ -96,30 +97,57 @@ 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,
-                "idempotency_key": generate_idempotency_key(),
+                "idempotency_key": idempotency_key,
             },
             timestamp=datetime.now(timezone.utc),
         )
 
         await self._enqueue(operation)
 
-    async def finish(self, instance_id: str) -> None:
+    async def finish(
+        self,
+        instance_id: str,
+        status: "FinishStatus" = "complete",
+    ) -> None:
         """Mark an instance as finished.
 
         Queues a finish operation for the instance.
 
         Args:
             instance_id: The ID of the instance to finish.
+            status: Terminal status for the instance. Defaults to ``"complete"``.
         """
+        await self.finish_with_idempotency_key(
+            instance_id,
+            generate_idempotency_key(),
+            status=status,
+        )
+
+    async def finish_with_idempotency_key(
+        self,
+        instance_id: str,
+        idempotency_key: str,
+        status: "FinishStatus" = "complete",
+    ) -> None:
+        """Queue a finish operation using a stable idempotency key."""
         operation = Operation(
             type=OperationType.FINISH_AGENT_INSTANCE,
             payload={
                 "instance_id": instance_id,
-                "idempotency_key": generate_idempotency_key(),
+                "idempotency_key": idempotency_key,
+                "status": status,
             },
             timestamp=datetime.now(timezone.utc),
         )
@@ -159,8 +187,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:
@@ -176,26 +204,29 @@ class AgentInstanceHandle:
 
         This queues a start operation for the instance.
         """
-        if self._started:
-            return
-
         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:
+    async def finish(self, status: "FinishStatus" = "complete") -> None:
         """Mark the instance as finished.
 
         This queues a finish operation for the instance.
-        """
-        if self._finished:
-            return
 
+        Args:
+            status: Terminal status for the instance — one of ``"complete"``,
+                ``"failed"``, or ``"cancelled"``. Defaults to ``"complete"``.
+        """
         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,
+            status=status,
+        )
 
     async def create_span(
         self,
@@ -215,6 +246,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.2 → prefactor_core-0.2.4}/src/prefactor_core/managers/span.py

@@ -151,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]
@@ -242,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.
 
@@ -254,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.
@@ -273,7 +280,7 @@ class SpanManager:
         op_payload: dict[str, Any] = {
             "span_id": span_id,
             "status": status,
-            "idempotency_key": generate_idempotency_key(),
+            "idempotency_key": idempotency_key or generate_idempotency_key(),
         }
         if result_payload is not None:
             op_payload["result_payload"] = result_payload

{prefactor_core-0.2.2 → prefactor_core-0.2.4}/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}"

{prefactor_core-0.2.2 → prefactor_core-0.2.4}/src/prefactor_core/queue/memory.py

@@ -6,7 +6,7 @@ for durability requirements.
 """
 
 from asyncio import Queue as AsyncQueue
-from typing import TypeVar
+from typing import TypeVar, cast
 
 from .base import Queue, QueueClosedError
 
@@ -34,7 +34,7 @@ class InMemoryQueue(Queue[T]):
 
     def __init__(self) -> None:
         """Initialize an empty in-memory queue."""
-        self._queue: AsyncQueue[T] = AsyncQueue()
+        self._queue: AsyncQueue[T | object] = AsyncQueue()
         self._closed = False
 
     async def put(self, item: T) -> None:
@@ -66,7 +66,7 @@ class InMemoryQueue(Queue[T]):
         # Re-raise as closed so the worker exits cleanly.
         if item is self._SENTINEL:
             raise QueueClosedError("Queue is closed and empty")
-        return item
+        return cast(T, item)
 
     def size(self) -> int:
         """Return the current number of items in the queue.
@@ -89,7 +89,7 @@ class InMemoryQueue(Queue[T]):
         self._closed = True
         # Wake any workers blocked in asyncio.Queue.get() so they can exit.
         for _ in range(num_waiters):
-            await self._queue.put(self._SENTINEL)  # type: ignore[arg-type]
+            await self._queue.put(self._SENTINEL)
 
     @property
     def closed(self) -> bool:

{prefactor_core-0.2.2 → prefactor_core-0.2.4}/src/prefactor_core/schema_registry.py

@@ -4,6 +4,8 @@ This module provides a SchemaRegistry that allows registration of span schemas
 from multiple packages before agent instances are created.
 """
 
+from __future__ import annotations
+
 from typing import Any
 
 
@@ -131,12 +133,13 @@ class SchemaRegistry:
         title: str | None = None,
         description: str | None = None,
         template: str | None = None,
+        data_risk: dict[str, Any] | None = None,
     ) -> None:
         """Register a full structured span type schema.
 
         Adds to ``span_type_schemas``. This is the richest form and supports
         all API fields: params schema, result schema, human-readable title,
-        description, and a display template.
+        description, template, and data risk classification.
 
         Args:
             name: Span type name (e.g., "agent:llm")
@@ -145,6 +148,25 @@ class SchemaRegistry:
             title: Optional human-readable title (defaults to name on the API)
             description: Optional description of the span type
             template: Optional display template using ``{{field}}`` interpolation
+            data_risk: Optional data risk classification dict. See DataRisk model
+                in prefactor_http.models.agent_instance for structure. Must include:
+                - action_profile (object): Permitted actions with keys:
+                  create_data, read_data, update_data, destroy_data,
+                  financial_transactions, external_communication (values:
+                  "unknown" | "allowed" | "disallowed")
+                - params_data_categories (object): Input data categories with keys
+                  like personal_identifiers, contact_information,
+                  financial_information, etc. (values: "unknown" | "included"
+                  | "excluded")
+                - result_data_categories (object): Output data categories,
+                  same structure as params_data_categories
+                All three top-level keys are required; fields within each default
+                to "unknown" when omitted.
+                Example: {
+                    "action_profile": {"read_data": "allowed"},
+                    "params_data_categories": {"personal_identifiers": "included"},
+                    "result_data_categories": {},
+                }
 
         Raises:
             ValueError: If name is already registered as a span type schema.
@@ -161,6 +183,8 @@ class SchemaRegistry:
             entry["description"] = description
         if template is not None:
             entry["template"] = template
+        if data_risk is not None:
+            entry["data_risk"] = data_risk
 
         self._span_type_schemas[name] = entry