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

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

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: prefactor-core
-Version: 0.2.1
+Version: 0.2.2
 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.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "prefactor-core"
-version = "0.2.1"
+version = "0.2.2"
 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",
 ]
 

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

@@ -20,6 +20,7 @@ from .operations import Operation, OperationType
 from .queue import InMemoryQueue, Queue, QueueClosedError, TaskExecutor
 from .schema_registry import SchemaRegistry
 from .span_context import SpanContext
+from .utils import generate_idempotency_key, validate_idempotency_key
 
 __version__ = "0.2.1"
 
@@ -54,4 +55,7 @@ __all__ = [
     "AgentInstanceHandle",
     # Schema Registry
     "SchemaRegistry",
+    # Utils
+    "generate_idempotency_key",
+    "validate_idempotency_key",
 ]

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

@@ -188,12 +188,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 +213,22 @@ 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
+            # 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,
@@ -344,7 +352,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 +373,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.
 

{prefactor_core-0.2.1 → prefactor_core-0.2.2}/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
 
@@ -94,7 +98,10 @@ class AgentInstanceManager:
         """
         operation = Operation(
             type=OperationType.START_AGENT_INSTANCE,
-            payload={"instance_id": instance_id},
+            payload={
+                "instance_id": instance_id,
+                "idempotency_key": generate_idempotency_key(),
+            },
             timestamp=datetime.now(timezone.utc),
         )
 
@@ -110,7 +117,10 @@ class AgentInstanceManager:
         """
         operation = Operation(
             type=OperationType.FINISH_AGENT_INSTANCE,
-            payload={"instance_id": instance_id},
+            payload={
+                "instance_id": instance_id,
+                "idempotency_key": generate_idempotency_key(),
+            },
             timestamp=datetime.now(timezone.utc),
         )
 
@@ -169,7 +179,7 @@ class AgentInstanceHandle:
         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
@@ -182,7 +192,7 @@ class AgentInstanceHandle:
         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

{prefactor_core-0.2.1 → prefactor_core-0.2.2}/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
@@ -185,12 +186,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"
@@ -261,10 +264,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": generate_idempotency_key(),
+        }
         if result_payload is not None:
             op_payload["result_payload"] = result_payload
 

{prefactor_core-0.2.1 → prefactor_core-0.2.2}/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.2/src/prefactor_core/utils.py

@@ -0,0 +1,41 @@
+"""Utility functions for prefactor-core."""
+
+from __future__ import annotations
+
+import uuid
+
+
+def generate_idempotency_key() -> str:
+    """Generate a new UUID-based idempotency key.
+
+    The returned key is a UUID4 string (36 characters), always within the
+    64-character API limit.
+
+    Returns:
+        A unique idempotency key string.
+    """
+    return str(uuid.uuid4())
+
+
+def validate_idempotency_key(key: str) -> str:
+    """Validate that an idempotency key is a non-empty string of at most 64 characters.
+
+    Args:
+        key: The idempotency key to validate.
+
+    Returns:
+        The key unchanged if valid.
+
+    Raises:
+        ValueError: If the key is empty or exceeds 64 characters.
+    """
+    if not key:
+        raise ValueError("Idempotency key must not be empty")
+    if len(key) > 64:
+        raise ValueError(
+            f"Idempotency key must be at most 64 characters, got {len(key)}"
+        )
+    return key
+
+
+__all__ = ["generate_idempotency_key", "validate_idempotency_key"]

prefactor_core-0.2.2/tests/test_span_manager.py

@@ -0,0 +1,85 @@
+"""Tests for SpanManager idempotency key auto-generation."""
+
+from __future__ import annotations
+
+import uuid
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from prefactor_core.managers.span import SpanManager
+
+
+def _make_span_result(span_id: str = "api-span-id") -> MagicMock:
+    result = MagicMock()
+    result.id = span_id
+    return result
+
+
+@pytest.fixture
+def http_client():
+    """Return a mock HTTP client with stubbed agent_spans create/finish methods."""
+    client = MagicMock()
+    client.agent_spans = MagicMock()
+    client.agent_spans.create = AsyncMock(return_value=_make_span_result())
+    client.agent_spans.finish = AsyncMock(return_value=_make_span_result())
+    return client
+
+
+@pytest.fixture
+def enqueue():
+    """Return an async mock for the enqueue callback."""
+    return AsyncMock()
+
+
+@pytest.fixture
+def manager(http_client, enqueue):
+    """Return a SpanManager wired to the mock http_client and enqueue fixtures."""
+    return SpanManager(http_client, enqueue)
+
+
+class TestSpanManagerIdempotencyKeys:
+    """Tests that SpanManager generates and propagates idempotency keys correctly."""
+
+    async def test_start_passes_idempotency_key(self, manager, http_client):
+        """start() should pass a valid UUID idempotency key to agent_spans.create."""
+        temp_id = manager.prepare(instance_id="inst-1", schema_name="agent:llm")
+        await manager.start(temp_id)
+
+        call_kwargs = http_client.agent_spans.create.call_args.kwargs
+        key = call_kwargs.get("idempotency_key")
+        assert key is not None
+        assert len(key) <= 64
+        uuid.UUID(key)  # must be valid UUID
+
+    async def test_cancel_unstarted_passes_distinct_keys(self, manager, http_client):
+        """cancel_unstarted() should use distinct keys for create and finish calls."""
+        temp_id = manager.prepare(instance_id="inst-1", schema_name="agent:llm")
+        await manager.cancel_unstarted(temp_id)
+
+        create_key = http_client.agent_spans.create.call_args.kwargs.get(
+            "idempotency_key"
+        )
+        finish_key = http_client.agent_spans.finish.call_args.kwargs.get(
+            "idempotency_key"
+        )
+
+        assert create_key is not None
+        assert finish_key is not None
+        assert create_key != finish_key
+
+    async def test_finish_includes_idempotency_key_in_operation(
+        self, manager, http_client, enqueue
+    ):
+        """finish() should enqueue an operation with a valid UUID idempotency key."""
+        # Start a span first to get a real API id
+        temp_id = manager.prepare(instance_id="inst-1", schema_name="agent:llm")
+        api_id = await manager.start(temp_id)
+
+        await manager.finish(api_id)
+
+        enqueue.assert_called_once()
+        operation = enqueue.call_args.args[0]
+        key = operation.payload.get("idempotency_key")
+        assert key is not None
+        assert len(key) <= 64
+        uuid.UUID(key)

prefactor_core-0.2.2/tests/test_utils.py

@@ -0,0 +1,46 @@
+"""Tests for prefactor_core utility functions."""
+
+from __future__ import annotations
+
+import uuid
+
+import pytest
+from prefactor_core.utils import generate_idempotency_key, validate_idempotency_key
+
+
+class TestGenerateIdempotencyKey:
+    def test_returns_valid_uuid(self):
+        key = generate_idempotency_key()
+        parsed = uuid.UUID(key)
+        assert parsed.version == 4
+
+    def test_max_length(self):
+        key = generate_idempotency_key()
+        assert len(key) <= 64
+
+    def test_unique_per_call(self):
+        keys = {generate_idempotency_key() for _ in range(10)}
+        assert len(keys) == 10
+
+
+class TestValidateIdempotencyKey:
+    def test_accepts_valid_key(self):
+        key = "a" * 64
+        assert validate_idempotency_key(key) == key
+
+    def test_accepts_short_key(self):
+        key = "abc"
+        assert validate_idempotency_key(key) == key
+
+    def test_rejects_empty_key(self):
+        with pytest.raises(ValueError, match="must not be empty"):
+            validate_idempotency_key("")
+
+    def test_rejects_oversized_key(self):
+        key = "a" * 65
+        with pytest.raises(ValueError, match="64 characters"):
+            validate_idempotency_key(key)
+
+    def test_accepts_uuid_key(self):
+        key = str(uuid.uuid4())
+        assert validate_idempotency_key(key) == key