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

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

@@ -70,3 +70,4 @@ htmlcov/
 .env
 mise.local.toml
 prefactor.json
+.worktrees/

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

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: prefactor-core
-Version: 0.2.3
+Version: 0.2.5
 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.1
+Requires-Dist: prefactor-http>=0.1.3
 Requires-Dist: pydantic>=2.0.0
 Description-Content-Type: text/markdown
 
@@ -81,6 +81,10 @@ async def main():
 asyncio.run(main())
 ```
 
+`create_agent_instance()` supports two auth modes:
+- Account-scoped token: pass `agent_id` and usually `environment_id`.
+- Deployment-scoped token: omit `agent_id` and `environment_id`; the API derives both from the token.
+
 ## API Reference
 
 ### `PrefactorCoreClient`
@@ -98,9 +102,9 @@ await client.close()
 
 ```python
 handle = await client.create_agent_instance(
-    agent_id="my-agent",
     agent_version={"name": "My Agent", "external_identifier": "v1.0.0"},
     agent_schema_version=None,        # Optional: auto-generated if schema_registry is configured
+    agent_id="my-agent",              # Optional for deployment-scoped tokens
     external_schema_version_id=None,  # Optional: reference an existing schema version
 ) -> AgentInstanceHandle
 ```
@@ -240,8 +244,8 @@ config = PrefactorCoreConfig(
 async with PrefactorCoreClient(config) as client:
     # agent_schema_version is generated automatically from the registry
     instance = await client.create_agent_instance(
-        agent_id="my-agent",
         agent_version={"name": "My Agent", "external_identifier": "v1.0.0"},
+        agent_id="my-agent",  # Optional for deployment-scoped tokens
     )
 ```
 

{prefactor_core-0.2.3 → prefactor_core-0.2.5}/README.md

@@ -70,6 +70,10 @@ async def main():
 asyncio.run(main())
 ```
 
+`create_agent_instance()` supports two auth modes:
+- Account-scoped token: pass `agent_id` and usually `environment_id`.
+- Deployment-scoped token: omit `agent_id` and `environment_id`; the API derives both from the token.
+
 ## API Reference
 
 ### `PrefactorCoreClient`
@@ -87,9 +91,9 @@ await client.close()
 
 ```python
 handle = await client.create_agent_instance(
-    agent_id="my-agent",
     agent_version={"name": "My Agent", "external_identifier": "v1.0.0"},
     agent_schema_version=None,        # Optional: auto-generated if schema_registry is configured
+    agent_id="my-agent",              # Optional for deployment-scoped tokens
     external_schema_version_id=None,  # Optional: reference an existing schema version
 ) -> AgentInstanceHandle
 ```
@@ -229,8 +233,8 @@ config = PrefactorCoreConfig(
 async with PrefactorCoreClient(config) as client:
     # agent_schema_version is generated automatically from the registry
     instance = await client.create_agent_instance(
-        agent_id="my-agent",
         agent_version={"name": "My Agent", "external_identifier": "v1.0.0"},
+        agent_id="my-agent",  # Optional for deployment-scoped tokens
     )
 ```
 

{prefactor_core-0.2.3 → prefactor_core-0.2.5}/examples/agent_e2e.py

@@ -24,8 +24,11 @@ Run via mise (env vars set automatically):
 Or manually:
     PREFACTOR_API_URL=https://api.prefactor.ai \\
     PREFACTOR_API_TOKEN=your-token \\
-    PREFACTOR_AGENT_ID=your-agent-id \\
     python packages/core/examples/agent_e2e.py
+
+Set `PREFACTOR_AGENT_ID` only when using an account-scoped token. With a
+deployment-scoped token, leave it unset and the API derives the agent and
+environment from the token.
 """
 
 import asyncio
@@ -182,7 +185,7 @@ async def simulate_retrieval(query: str) -> list[str]:
 
 
 async def main() -> None:
-    agent_id = os.environ["PREFACTOR_AGENT_ID"]
+    agent_id = os.environ.get("PREFACTOR_AGENT_ID")
 
     config = PrefactorCoreConfig(
         http_config=HttpClientConfig(
@@ -194,10 +197,21 @@ async def main() -> None:
 
     async with PrefactorCoreClient(config) as client:
         # Register the agent instance — schema version derived from registry.
-        instance = await client.create_agent_instance(
-            agent_id=agent_id,
-            agent_version={"name": "Example Agent", "external_identifier": "v8.0.0"},
-        )
+        if agent_id is None:
+            instance = await client.create_agent_instance(
+                agent_version={
+                    "name": "Example Agent",
+                    "external_identifier": "v8.0.0",
+                }
+            )
+        else:
+            instance = await client.create_agent_instance(
+                agent_id=agent_id,
+                agent_version={
+                    "name": "Example Agent",
+                    "external_identifier": "v8.0.0",
+                },
+            )
 
         await instance.start()
 

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

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

{prefactor_core-0.2.3 → prefactor_core-0.2.5}/src/prefactor_core/_version.py

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

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

@@ -274,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"),
                 )
@@ -313,11 +314,12 @@ class PrefactorCoreClient:
 
     async def create_agent_instance(
         self,
-        agent_id: str,
         agent_version: dict[str, Any],
         agent_schema_version: dict[str, Any] | None = None,
+        agent_id: str | None = None,
         instance_id: str | None = None,
         external_schema_version_id: str | None = None,
+        environment_id: str | None = None,
     ) -> "AgentInstanceHandle":
         """Create a new agent instance.
 
@@ -328,13 +330,14 @@ class PrefactorCoreClient:
         the registry's schemas will be used automatically.
 
         Args:
-            agent_id: ID of the agent to create an instance for.
+            agent_id: Agent ID. Omit when using a deployment-scoped token.
             agent_version: Version information (name, etc.).
             agent_schema_version: Schema version. Uses registry if not provided
                 and registry is configured.
             instance_id: Optional custom ID for the instance.
             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.
 
         Returns:
             AgentInstanceHandle for the created instance.
@@ -355,7 +358,10 @@ class PrefactorCoreClient:
             # Use registry to generate schema version
             ext_id = external_schema_version_id
             if ext_id is None:
-                ext_id = f"auto-{agent_id}-{time.time()}"
+                if agent_id is None:
+                    ext_id = f"auto-deployment-{time.time()}"
+                else:
+                    ext_id = f"auto-{agent_id}-{time.time()}"
             final_schema_version = self._config.schema_registry.to_agent_schema_version(
                 ext_id
             )
@@ -372,6 +378,7 @@ class PrefactorCoreClient:
             agent_version=agent_version,
             agent_schema_version=final_schema_version,
             instance_id=instance_id,
+            environment_id=environment_id,
         )
 
         return AgentInstanceHandle(

{prefactor_core-0.2.3 → prefactor_core-0.2.5}/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
 
@@ -58,10 +59,11 @@ class AgentInstanceManager:
 
     async def register(
         self,
-        agent_id: str,
         agent_version: dict[str, Any],
         agent_schema_version: dict[str, Any],
+        agent_id: str | None = None,
         instance_id: str | None = None,
+        environment_id: str | None = None,
     ) -> str:
         """Register a new agent instance.
 
@@ -69,12 +71,14 @@ class AgentInstanceManager:
         the API-generated ID.
 
         Args:
-            agent_id: ID of the agent to create an instance for.
+            agent_id: Agent ID. Omit when using a deployment-scoped token.
             agent_version: Version information (name, external_identifier, etc.).
             agent_schema_version: Schema version information.
             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.
+            environment_id: Optional environment ID. Required when using an
+                account-scoped token; omit when using a deployment-scoped token.
 
         Returns:
             The instance ID (API-generated).
@@ -83,6 +87,7 @@ class AgentInstanceManager:
             agent_id=agent_id,
             agent_version=agent_version,
             agent_schema_version=agent_schema_version,
+            environment_id=environment_id,
             id=instance_id,
             idempotency_key=generate_idempotency_key(),
         )
@@ -115,20 +120,30 @@ class AgentInstanceManager:
 
         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())
+        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(
@@ -136,6 +151,7 @@ class AgentInstanceManager:
             payload={
                 "instance_id": instance_id,
                 "idempotency_key": idempotency_key,
+                "status": status,
             },
             timestamp=datetime.now(timezone.utc),
         )
@@ -199,16 +215,21 @@ class AgentInstanceHandle:
             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.
+
+        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_with_idempotency_key(
             self._instance_id,
             self._finish_idempotency_key,
+            status=status,
         )
 
     async def create_span(

prefactor_core-0.2.5/tests/test_agent_instance_finish_status.py

@@ -0,0 +1,104 @@
+"""Tests for AgentInstanceHandle.finish() accepting an optional status.
+
+See GitHub issue prefactordev/python-sdk#13.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+from prefactor_core import PrefactorCoreClient
+from prefactor_core.config import PrefactorCoreConfig, QueueConfig
+from prefactor_http.config import HttpClientConfig
+
+
+class _StubAgentInstances:
+    def __init__(self) -> None:
+        self.finish_calls: list[dict] = []
+
+    async def register(self, **kwargs):
+        return SimpleNamespace(id=kwargs.get("id") or "inst-1")
+
+    async def start(self, **kwargs):
+        return SimpleNamespace(id=kwargs["agent_instance_id"])
+
+    async def finish(self, **kwargs):
+        self.finish_calls.append(kwargs)
+        return SimpleNamespace(id=kwargs["agent_instance_id"])
+
+
+class _StubAgentSpans:
+    async def create(self, **kwargs):
+        return SimpleNamespace(id="span-1")
+
+    async def finish(self, **kwargs):
+        return SimpleNamespace(id=kwargs["agent_span_id"])
+
+
+class _StubHttpClient:
+    def __init__(
+        self,
+        *_args,
+        agent_instances: _StubAgentInstances | None = None,
+        **_kwargs,
+    ) -> None:
+        self.agent_instances = agent_instances or _StubAgentInstances()
+        self.agent_spans = _StubAgentSpans()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        return None
+
+
+def _make_client_config() -> PrefactorCoreConfig:
+    return PrefactorCoreConfig(
+        http_config=HttpClientConfig(
+            api_url="https://api.test.com",
+            api_token="test-token",
+            max_retries=0,
+            initial_retry_delay=0.01,
+            max_retry_delay=0.02,
+        ),
+        queue_config=QueueConfig(num_workers=1, max_retries=0),
+    )
+
+
+@pytest.mark.asyncio
+async def test_finish_without_status_defaults_to_complete():
+    """Default call to finish() should forward status='complete' to HTTP."""
+    stub_http = _StubHttpClient()
+
+    with patch("prefactor_core.client.PrefactorHttpClient", return_value=stub_http):
+        async with PrefactorCoreClient(_make_client_config()) as client:
+            instance = await client.create_agent_instance(
+                agent_id="agent-1",
+                agent_version={"name": "v1"},
+                agent_schema_version={"span_schemas": {}},
+            )
+            await instance.finish()
+
+    assert len(stub_http.agent_instances.finish_calls) == 1
+    assert stub_http.agent_instances.finish_calls[0].get("status") == "complete"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("status", ["failed", "cancelled", "complete"])
+async def test_finish_forwards_explicit_status(status):
+    """Explicit status on handle.finish() should reach the HTTP layer."""
+    stub_http = _StubHttpClient()
+
+    with patch("prefactor_core.client.PrefactorHttpClient", return_value=stub_http):
+        async with PrefactorCoreClient(_make_client_config()) as client:
+            instance = await client.create_agent_instance(
+                agent_id="agent-1",
+                agent_version={"name": "v1"},
+                agent_schema_version={"span_schemas": {}},
+            )
+            await instance.finish(status=status)
+
+    assert len(stub_http.agent_instances.finish_calls) == 1
+    assert stub_http.agent_instances.finish_calls[0]["status"] == status

prefactor_core-0.2.5/tests/test_agent_instance_register.py

@@ -0,0 +1,123 @@
+"""Tests for environment_id threading through the core register flow."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+from prefactor_core import PrefactorCoreClient
+from prefactor_core.config import PrefactorCoreConfig, QueueConfig
+from prefactor_http.config import HttpClientConfig
+
+
+def _make_config() -> PrefactorCoreConfig:
+    return PrefactorCoreConfig(
+        http_config=HttpClientConfig(
+            api_url="https://api.test.com",
+            api_token="test-token",
+            max_retries=0,
+        ),
+        queue_config=QueueConfig(num_workers=1, max_retries=0),
+    )
+
+
+class _StubAgentInstances:
+    def __init__(self) -> None:
+        self.register_calls: list[dict] = []
+
+    async def register(self, **kwargs):
+        self.register_calls.append(kwargs)
+        return SimpleNamespace(id="inst-1")
+
+    async def start(self, **kwargs):
+        return SimpleNamespace(id=kwargs["agent_instance_id"])
+
+    async def finish(self, **kwargs):
+        return SimpleNamespace(id=kwargs["agent_instance_id"])
+
+
+class _StubAgentSpans:
+    async def create(self, **kwargs):
+        return SimpleNamespace(id="span-1")
+
+    async def finish(self, **kwargs):
+        return SimpleNamespace(id=kwargs["agent_span_id"])
+
+
+class _StubHttpClient:
+    def __init__(self, *args, **kwargs) -> None:
+        self.agent_instances = _StubAgentInstances()
+        self.agent_spans = _StubAgentSpans()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        return None
+
+
+@pytest.mark.asyncio
+async def test_create_agent_instance_passes_environment_id_to_register():
+    """environment_id passed to create_agent_instance() reaches the HTTP layer."""
+    stub_http = _StubHttpClient()
+    with patch("prefactor_core.client.PrefactorHttpClient", return_value=stub_http):
+        async with PrefactorCoreClient(_make_config()) as client:
+            await client.create_agent_instance(
+                agent_id="agent-1",
+                agent_version={"name": "v1"},
+                agent_schema_version={"span_schemas": {}},
+                environment_id="env-1",
+            )
+    assert stub_http.agent_instances.register_calls[0]["environment_id"] == "env-1"
+
+
+@pytest.mark.asyncio
+async def test_create_agent_instance_without_environment_id_omits_field():
+    """Omitting environment_id does not send it to the HTTP register call."""
+    stub_http = _StubHttpClient()
+    with patch("prefactor_core.client.PrefactorHttpClient", return_value=stub_http):
+        async with PrefactorCoreClient(_make_config()) as client:
+            await client.create_agent_instance(
+                agent_id="agent-1",
+                agent_version={"name": "v1"},
+                agent_schema_version={"span_schemas": {}},
+            )
+    call = stub_http.agent_instances.register_calls[0]
+    assert "environment_id" not in call or call["environment_id"] is None
+
+
+@pytest.mark.asyncio
+async def test_create_agent_instance_without_agent_id_omits_field():
+    """Omitting agent_id does not send it to the HTTP register call."""
+    stub_http = _StubHttpClient()
+    with patch("prefactor_core.client.PrefactorHttpClient", return_value=stub_http):
+        async with PrefactorCoreClient(_make_config()) as client:
+            await client.create_agent_instance(
+                agent_version={"name": "v1"},
+                agent_schema_version={"span_schemas": {}},
+            )
+    call = stub_http.agent_instances.register_calls[0]
+    assert "agent_id" not in call or call["agent_id"] is None
+
+
+@pytest.mark.asyncio
+async def test_create_agent_instance_without_agent_id_uses_deployment_schema_fallback():
+    """Registry fallback should not require agent_id to generate an external ID."""
+    stub_http = _StubHttpClient()
+    config = _make_config()
+    config.schema_registry = SimpleNamespace(
+        to_agent_schema_version=lambda external_id: {"external_identifier": external_id}
+    )
+
+    with patch("prefactor_core.client.PrefactorHttpClient", return_value=stub_http):
+        async with PrefactorCoreClient(config) as client:
+            await client.create_agent_instance(
+                agent_version={"name": "v1"},
+                agent_schema_version=None,
+            )
+
+    call = stub_http.agent_instances.register_calls[0]
+    assert call["agent_schema_version"]["external_identifier"].startswith(
+        "auto-deployment-"
+    )

{prefactor_core-0.2.3 → prefactor_core-0.2.5}/tests/test_sdk_header.py

@@ -47,7 +47,7 @@ class TestPrefactorCoreSdkHeader:
         """Core prepends the adapter entry ahead of the core entry."""
         client = PrefactorCoreClient(
             create_config(),
-            sdk_header_entry="prefactor-langchain@0.2.4",
+            sdk_header_entry="prefactor-langchain@0.2.5",
         )
 
         with (
@@ -63,7 +63,7 @@ class TestPrefactorCoreSdkHeader:
             await client.initialize()
             assert client._http is not None
             assert client._http._sdk_header == (
-                f"prefactor-langchain@0.2.4 {CORE_SDK_HEADER_ENTRY}"
+                f"prefactor-langchain@0.2.5 {CORE_SDK_HEADER_ENTRY}"
             )
             await client.close()