millwork-solver 0.1.0__tar.gz → 0.1.2__tar.gz

millwork_solver-0.1.2/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: millwork-solver
+Version: 0.1.2
+Summary: Sync and async Python clients for the Millwork Solver API
+Author: Millwork
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/millworkdev/solver-python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx==0.28.1
+Dynamic: license-file
+
+# Millwork Solver for Python
+
+`millwork-solver` is an early preview client for the Millwork Solver API. Import
+`millwork_solver` to use the synchronous `Solver` client or the asynchronous
+`AsyncSolver` client on CPython 3.11 through 3.14.
+
+The [generated REST lifecycle reference](https://docs.getmillwork.dev/api-reference/output-checks)
+owns output-check operation IDs and fields. The
+[verifier-dock contract](https://docs.getmillwork.dev/contracts/verifier-dock/v1.json)
+owns the endpoint request and response. Follow
+[Recipe 0](https://docs.getmillwork.dev/cookbook/output-checks/build-the-dock)
+for local tests, deployment, and a receipt.
+
+Pass `api_key` and `base_url` directly, or use `SOLVERAPI_API_KEY` and
+`SOLVERAPI_BASE_URL`. Retry settings use `SOLVERAPI_MAX_RETRIES` (default `2`)
+and `SOLVERAPI_RETRY_BACKOFF_MS` (default `500`).
+
+Both clients provide the same typed operation surface, explicit timeout and
+close behavior, and receipt-aware responses. Echo reaches a terminal status and
+returns a receipt; it does not return result content.
+
+Use the API base URL with its `/v1` suffix:
+
+```bash
+export SOLVERAPI_BASE_URL="https://api.getmillwork.dev/v1"
+export SOLVERAPI_API_KEY="<organization API key>"
+```
+
+Call an operation by its OpenAPI `operation_id`. This complete test run uses
+`postExecutions`; the request must include both `task` and `policy`:
+
+```python
+import uuid
+
+from millwork_solver import Solver
+
+with Solver() as client:
+    run = client.request(
+        "postExecutions",
+        body={
+            "mode": "echo",
+            "task": {"objective": "Check the Millwork API lifecycle."},
+            "policy": {
+                "data_classes": ["public"],
+                "budget": {"max_cost_usd": 1, "max_runtime_s": 30},
+            },
+        },
+        idempotency_key=str(uuid.uuid4()),
+    )
+    receipt = client.request(
+        "getReceiptsByExecutionId",
+        path_parameters={"executionId": run["execution_id"]},
+    )
+    print(run["status"], receipt["mode"])
+```
+
+Common operation IDs include `getAccount`, `getArms`, `getModelCatalog`,
+`getVerifiers`, `postExecutions`, `getExecutionsByExecutionId`,
+`getExecutionsByExecutionIdResult`, and `getReceiptsByExecutionId`. The package
+ships the complete operation contract in `millwork_solver/_contract.json`.
+
+## Verifier lifecycle
+
+The installed client can register and test a public output check. Set
+`VERIFIER_URL` to an endpoint implementing the
+[output-check contract](https://docs.getmillwork.dev/cookbook/output-checks/build-the-dock#the-endpoint-contract):
+
+```python
+import os
+import uuid
+from millwork_solver import Solver
+
+with Solver() as client:
+    registered = client.request("postVerifiers", body={
+        "display_name": "My output check", "version": "1.0.0", "kind": "endpoint",
+        "endpoint": {"url": os.environ["VERIFIER_URL"], "auth_ref": ""},
+        "input_data_classes": ["public"],
+        "scoring": {"correctness": "boolean_anchors", "quality": "scalar_0_1"},
+    }, idempotency_key=str(uuid.uuid4()))
+    verifier_id = registered["verifier_id"]
+    print(verifier_id, client.request("postVerifiersByVerifierIdTest",
+          path_parameters={"verifierId": verifier_id}, idempotency_key=str(uuid.uuid4())))
+```
+
+The published `millwork-solver==0.1.1` wheel includes the public verifier
+operation IDs and `verifier_connection`. Install that pinned release to run
+the protected-connection methods below. The earlier `0.1.0` wheel does not
+include these methods.
+
+For a protected endpoint, register that endpoint with the same secretless
+`postVerifiers` body, then use **its** `verifier_id` for the private handoff.
+The REST registration has no `access` field; the protected connection is
+established by `verifier_connection`. Give `continue_url` only to the intended
+person through your host's private browser handoff. The callback below belongs
+to that host and must not log or expose the URL. The endpoint key is never an
+argument to these methods.
+
+```python
+import uuid
+from urllib.parse import urlsplit
+
+def start_protected(client, verifier_id, trusted_app_origin, open_private_url):
+    intent = client.verifier_connection.create_intent(
+        verifier_id, {"kind": "preset_days", "days": 90},
+        idempotency_key=str(uuid.uuid4()))
+    expected = urlsplit(trusted_app_origin)
+    actual = urlsplit(intent["continue_url"])
+    if (actual.scheme, actual.netloc) != (expected.scheme, expected.netloc):
+        raise ValueError("Unexpected private-entry origin")
+    open_private_url(intent["continue_url"])
+    return intent["intent_id"]
+
+def continue_protected(client, verifier_id, operation_key):
+    return client.verifier_connection.continue_connection(
+        verifier_id, operation_key=operation_key,
+        idempotency_key=str(uuid.uuid4()))
+```
+
+`enter_key` means private entry is still needed. `resume` means retain the same
+operation key and use a fresh request idempotency key. `start_again` means the
+endpoint test failed; correct the endpoint or key and create a new intent.
+`inspect` means another connection change intervened. `refused` means the server
+rejected the change with a non-retryable client error; read `outcome.error["status"]`
+and `outcome.error["title"]`, inspect that operation, and correct the cause before
+another action. A `401` or `403` raises a `ProblemError` instead of returning a
+lifecycle outcome. Only a read-backed `done`
+confirms completion. The async `AsyncSolver.verifier_connection` has the same
+methods, awaited. Replacement and restoration use a new intent and the same
+private-entry path. Disconnect requires explicit caller confirmation:
+`client.verifier_connection.disconnect(verifier_id, operation_key=...,
+idempotency_key=..., confirmed=True)`. Millwork stopping use of a key does not
+revoke it at your endpoint. A governed run requires separate authorization and
+uses this `verifier_id`.

millwork_solver-0.1.2/README.md

@@ -0,0 +1,133 @@
+# Millwork Solver for Python
+
+`millwork-solver` is an early preview client for the Millwork Solver API. Import
+`millwork_solver` to use the synchronous `Solver` client or the asynchronous
+`AsyncSolver` client on CPython 3.11 through 3.14.
+
+The [generated REST lifecycle reference](https://docs.getmillwork.dev/api-reference/output-checks)
+owns output-check operation IDs and fields. The
+[verifier-dock contract](https://docs.getmillwork.dev/contracts/verifier-dock/v1.json)
+owns the endpoint request and response. Follow
+[Recipe 0](https://docs.getmillwork.dev/cookbook/output-checks/build-the-dock)
+for local tests, deployment, and a receipt.
+
+Pass `api_key` and `base_url` directly, or use `SOLVERAPI_API_KEY` and
+`SOLVERAPI_BASE_URL`. Retry settings use `SOLVERAPI_MAX_RETRIES` (default `2`)
+and `SOLVERAPI_RETRY_BACKOFF_MS` (default `500`).
+
+Both clients provide the same typed operation surface, explicit timeout and
+close behavior, and receipt-aware responses. Echo reaches a terminal status and
+returns a receipt; it does not return result content.
+
+Use the API base URL with its `/v1` suffix:
+
+```bash
+export SOLVERAPI_BASE_URL="https://api.getmillwork.dev/v1"
+export SOLVERAPI_API_KEY="<organization API key>"
+```
+
+Call an operation by its OpenAPI `operation_id`. This complete test run uses
+`postExecutions`; the request must include both `task` and `policy`:
+
+```python
+import uuid
+
+from millwork_solver import Solver
+
+with Solver() as client:
+    run = client.request(
+        "postExecutions",
+        body={
+            "mode": "echo",
+            "task": {"objective": "Check the Millwork API lifecycle."},
+            "policy": {
+                "data_classes": ["public"],
+                "budget": {"max_cost_usd": 1, "max_runtime_s": 30},
+            },
+        },
+        idempotency_key=str(uuid.uuid4()),
+    )
+    receipt = client.request(
+        "getReceiptsByExecutionId",
+        path_parameters={"executionId": run["execution_id"]},
+    )
+    print(run["status"], receipt["mode"])
+```
+
+Common operation IDs include `getAccount`, `getArms`, `getModelCatalog`,
+`getVerifiers`, `postExecutions`, `getExecutionsByExecutionId`,
+`getExecutionsByExecutionIdResult`, and `getReceiptsByExecutionId`. The package
+ships the complete operation contract in `millwork_solver/_contract.json`.
+
+## Verifier lifecycle
+
+The installed client can register and test a public output check. Set
+`VERIFIER_URL` to an endpoint implementing the
+[output-check contract](https://docs.getmillwork.dev/cookbook/output-checks/build-the-dock#the-endpoint-contract):
+
+```python
+import os
+import uuid
+from millwork_solver import Solver
+
+with Solver() as client:
+    registered = client.request("postVerifiers", body={
+        "display_name": "My output check", "version": "1.0.0", "kind": "endpoint",
+        "endpoint": {"url": os.environ["VERIFIER_URL"], "auth_ref": ""},
+        "input_data_classes": ["public"],
+        "scoring": {"correctness": "boolean_anchors", "quality": "scalar_0_1"},
+    }, idempotency_key=str(uuid.uuid4()))
+    verifier_id = registered["verifier_id"]
+    print(verifier_id, client.request("postVerifiersByVerifierIdTest",
+          path_parameters={"verifierId": verifier_id}, idempotency_key=str(uuid.uuid4())))
+```
+
+The published `millwork-solver==0.1.1` wheel includes the public verifier
+operation IDs and `verifier_connection`. Install that pinned release to run
+the protected-connection methods below. The earlier `0.1.0` wheel does not
+include these methods.
+
+For a protected endpoint, register that endpoint with the same secretless
+`postVerifiers` body, then use **its** `verifier_id` for the private handoff.
+The REST registration has no `access` field; the protected connection is
+established by `verifier_connection`. Give `continue_url` only to the intended
+person through your host's private browser handoff. The callback below belongs
+to that host and must not log or expose the URL. The endpoint key is never an
+argument to these methods.
+
+```python
+import uuid
+from urllib.parse import urlsplit
+
+def start_protected(client, verifier_id, trusted_app_origin, open_private_url):
+    intent = client.verifier_connection.create_intent(
+        verifier_id, {"kind": "preset_days", "days": 90},
+        idempotency_key=str(uuid.uuid4()))
+    expected = urlsplit(trusted_app_origin)
+    actual = urlsplit(intent["continue_url"])
+    if (actual.scheme, actual.netloc) != (expected.scheme, expected.netloc):
+        raise ValueError("Unexpected private-entry origin")
+    open_private_url(intent["continue_url"])
+    return intent["intent_id"]
+
+def continue_protected(client, verifier_id, operation_key):
+    return client.verifier_connection.continue_connection(
+        verifier_id, operation_key=operation_key,
+        idempotency_key=str(uuid.uuid4()))
+```
+
+`enter_key` means private entry is still needed. `resume` means retain the same
+operation key and use a fresh request idempotency key. `start_again` means the
+endpoint test failed; correct the endpoint or key and create a new intent.
+`inspect` means another connection change intervened. `refused` means the server
+rejected the change with a non-retryable client error; read `outcome.error["status"]`
+and `outcome.error["title"]`, inspect that operation, and correct the cause before
+another action. A `401` or `403` raises a `ProblemError` instead of returning a
+lifecycle outcome. Only a read-backed `done`
+confirms completion. The async `AsyncSolver.verifier_connection` has the same
+methods, awaited. Replacement and restoration use a new intent and the same
+private-entry path. Disconnect requires explicit caller confirmation:
+`client.verifier_connection.disconnect(verifier_id, operation_key=...,
+idempotency_key=..., confirmed=True)`. Millwork stopping use of a key does not
+revoke it at your endpoint. A governed run requires separate authorization and
+uses this `verifier_id`.

{millwork_solver-0.1.0 → millwork_solver-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "millwork-solver"
-version = "0.1.0"
+version = "0.1.2"
 description = "Sync and async Python clients for the Millwork Solver API"
 readme = "README.md"
 requires-python = ">=3.11,<3.15"

{millwork_solver-0.1.0 → millwork_solver-0.1.2}/src/millwork_solver/__init__.py

@@ -10,6 +10,7 @@ from .errors import (
     ProtocolError,
 )
 from .types import Page
+from .verifier_connection import AsyncVerifierConnection, ConnectionIntent, LifecycleOutcome, StopChoice, VerifierConnection
 
 __all__ = (
     "AsyncSolver",
@@ -21,4 +22,9 @@ __all__ = (
     "ProblemError",
     "ProtocolError",
     "Solver",
+    "VerifierConnection",
+    "AsyncVerifierConnection",
+    "ConnectionIntent",
+    "LifecycleOutcome",
+    "StopChoice",
 )

{millwork_solver-0.1.0 → millwork_solver-0.1.2}/src/millwork_solver/_contract.json

@@ -2,8 +2,8 @@
   "schema_version": 1,
   "generated_from": {
     "python_operation_view": "contracts/developer-experience/python-operation-view.json",
-    "operation_manifest_version": "1.0.0",
-    "openapi_sha256": "ad959a037922a16bda51221ed989d00ea0ae6b70eb86b5f2aef07eccee91d3c6",
+    "operation_manifest_version": "2.2.0",
+    "openapi_sha256": "0a7d6b2e24ac80602e3ae0991ff6d964fc3727304a49144c6a5d73eb89d75d97",
     "retry_fixture": "contracts/developer-experience/fixtures/retry-error-idempotency.json"
   },
   "operations": [
@@ -122,6 +122,16 @@
       "method": "GET",
       "path": "/v1/receipts/{executionId}"
     },
+    {
+      "operation_id": "getReviewComposerAgents",
+      "method": "GET",
+      "path": "/v1/review-composer/agents"
+    },
+    {
+      "operation_id": "getReviewComposerAgentsByArmIdConnection",
+      "method": "GET",
+      "path": "/v1/review-composer/agents/{armId}/connection"
+    },
     {
       "operation_id": "getSourceConnections",
       "method": "GET",
@@ -137,6 +147,26 @@
       "method": "GET",
       "path": "/v1/source-credential-handoffs/{handoffIntentId}"
     },
+    {
+      "operation_id": "getTenantModelSelection",
+      "method": "GET",
+      "path": "/v1/tenant-model-selection"
+    },
+    {
+      "operation_id": "getTenantTemplateApplications",
+      "method": "GET",
+      "path": "/v1/tenant-template-applications"
+    },
+    {
+      "operation_id": "getTenantTemplateApplicationsByApplicationId",
+      "method": "GET",
+      "path": "/v1/tenant-template-applications/{applicationId}"
+    },
+    {
+      "operation_id": "getTenantTemplates",
+      "method": "GET",
+      "path": "/v1/tenant-templates"
+    },
     {
       "operation_id": "getUsage",
       "method": "GET",
@@ -152,6 +182,11 @@
       "method": "GET",
       "path": "/v1/verifiers/{verifierId}"
     },
+    {
+      "operation_id": "getVerifiersByVerifierIdConnection",
+      "method": "GET",
+      "path": "/v1/verifiers/{verifierId}/connection"
+    },
     {
       "operation_id": "getWebhooks",
       "method": "GET",
@@ -212,6 +247,11 @@
       "method": "POST",
       "path": "/v1/executions/{executionId}/cancel"
     },
+    {
+      "operation_id": "postModelCatalogQuote",
+      "method": "POST",
+      "path": "/v1/model-catalog/quote"
+    },
     {
       "operation_id": "postProposalsByProposalIdApprove",
       "method": "POST",
@@ -222,6 +262,26 @@
       "method": "POST",
       "path": "/v1/proposals/{proposalId}/reject"
     },
+    {
+      "operation_id": "postReviewComposerAgents",
+      "method": "POST",
+      "path": "/v1/review-composer/agents"
+    },
+    {
+      "operation_id": "postReviewComposerAgentsByArmIdConnectionIntents",
+      "method": "POST",
+      "path": "/v1/review-composer/agents/{armId}/connection/intents"
+    },
+    {
+      "operation_id": "postReviewComposerAgentsByArmIdConnectionRevoke",
+      "method": "POST",
+      "path": "/v1/review-composer/agents/{armId}/connection/revoke"
+    },
+    {
+      "operation_id": "postReviewComposerAgentsByArmIdConnectionTest",
+      "method": "POST",
+      "path": "/v1/review-composer/agents/{armId}/connection/test"
+    },
     {
       "operation_id": "postSourceConnections",
       "method": "POST",
@@ -247,11 +307,31 @@
       "method": "POST",
       "path": "/v1/source-credential-handoffs"
     },
+    {
+      "operation_id": "postTenantModelSelection",
+      "method": "POST",
+      "path": "/v1/tenant-model-selection"
+    },
     {
       "operation_id": "postTenants",
       "method": "POST",
       "path": "/v1/tenants"
     },
+    {
+      "operation_id": "postTenantTemplateApplications",
+      "method": "POST",
+      "path": "/v1/tenant-template-applications"
+    },
+    {
+      "operation_id": "postTenantTemplateApplicationsByApplicationIdResume",
+      "method": "POST",
+      "path": "/v1/tenant-template-applications/{applicationId}/resume"
+    },
+    {
+      "operation_id": "postTenantTemplatePlans",
+      "method": "POST",
+      "path": "/v1/tenant-template-plans"
+    },
     {
       "operation_id": "postVerifiers",
       "method": "POST",

{millwork_solver-0.1.0 → millwork_solver-0.1.2}/src/millwork_solver/_core/catalog.py

@@ -89,9 +89,9 @@ class _OperationCatalog:
         sources = view.get("sources")
         expected_counts = view.get("expected_counts")
         if not isinstance(sources, dict) or expected_counts != {
-            "operations": 70,
-            "included": 54,
-            "excluded": 16,
+            "operations": 89,
+            "included": 70,
+            "excluded": 19,
         }:
             raise _OperationBoundaryError("PY1 pointer/count contract drifted")
 
@@ -130,10 +130,10 @@ class _OperationCatalog:
             for operation_id, classification in classification_by_id.items()
             if classification.get("disposition") == "exclude"
         }
-        if len(wire_operations) != 70 or len(f1_included) != 54 or len(f1_excluded) != 16:
-            raise _OperationBoundaryError("F1 54/16 operation partition drifted")
+        if len(wire_operations) != 89 or len(f1_included) != 70 or len(f1_excluded) != 19:
+            raise _OperationBoundaryError("F1 70/19 operation partition drifted")
         if included_set != f1_included or len(included_ids) != len(included_set):
-            raise _OperationBoundaryError("PY1 pointer does not resolve exactly to F1's 54 includes")
+            raise _OperationBoundaryError("PY1 pointer does not resolve exactly to F1's 70 includes")
         if set(classification_by_id) != set(wire_operations):
             raise _OperationBoundaryError("F1 classifications do not cover OpenAPI exactly")
 
@@ -162,8 +162,8 @@ class _OperationCatalog:
         if snapshot.get("schema_version") != 1:
             raise _OperationBoundaryError("installed Python wire snapshot version drifted")
         operations = snapshot.get("operations")
-        if not isinstance(operations, list) or len(operations) != 54:
-            raise _OperationBoundaryError("installed Python wire snapshot must contain 54 operations")
+        if not isinstance(operations, list) or len(operations) != 70:
+            raise _OperationBoundaryError("installed Python wire snapshot must contain 70 operations")
 
         allowed: dict[str, _Operation] = {}
         for item in operations:

{millwork_solver-0.1.0 → millwork_solver-0.1.2}/src/millwork_solver/_core/clients.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from collections.abc import AsyncIterator, Iterator, Mapping
 from typing import Any, Awaitable, Callable
+from urllib.parse import quote
 
 from ..types import Page
 from .catalog import _OperationCatalog
@@ -38,6 +39,27 @@ def _is_terminal_event(event: Mapping[str, Any]) -> bool:
     )
 
 
+_CONNECTION_ACTIONS = {
+    "intent": ("POST", "connection-intents"),
+    "inspect": ("GET", "connection"),
+    "promote": ("POST", "connection/test"),
+    "revoke": ("POST", "connection/revoke"),
+}
+
+
+def _connection_request(action: str, verifier_id: str, *, query: Mapping[str, object] | None,
+                        body: object | None, idempotency_key: str | None,
+                        policy: _TransportPolicy):
+    if action not in _CONNECTION_ACTIONS or not verifier_id:
+        raise ValueError("unknown verifier connection action or empty verifier ID")
+    method, suffix = _CONNECTION_ACTIONS[action]
+    return _prepare_request(
+        operation_id=f"verifierConnection.{action}", method=method,
+        path=f"/v1/verifiers/{quote(verifier_id, safe='')}/{suffix}",
+        query=query, body=body, idempotency_key=idempotency_key, policy=policy,
+    )
+
+
 class _SyncClient:
     def __init__(
         self,
@@ -59,6 +81,12 @@ class _SyncClient:
         if self._closed:
             raise _ClientClosedError("client is closed")
 
+    def _verifier_connection(self, action: str, verifier_id: str, *, query: Mapping[str, object] | None = None,
+                             body: object | None = None, idempotency_key: str | None = None) -> Any:
+        self._ensure_open()
+        return self._transport.execute(_connection_request(action, verifier_id, query=query, body=body,
+                                                            idempotency_key=idempotency_key, policy=self._policy))
+
     def _resolve_fixture_request(self, method: str, path: str) -> tuple[str, Mapping[str, str]]:
         return self._catalog.match_fixture_request(method, path)
 
@@ -172,6 +200,12 @@ class _AsyncClient:
         if self._closed:
             raise _ClientClosedError("client is closed")
 
+    async def _verifier_connection(self, action: str, verifier_id: str, *, query: Mapping[str, object] | None = None,
+                                   body: object | None = None, idempotency_key: str | None = None) -> Any:
+        self._ensure_open()
+        return await self._transport.execute(_connection_request(action, verifier_id, query=query, body=body,
+                                                                  idempotency_key=idempotency_key, policy=self._policy))
+
     def _resolve_fixture_request(self, method: str, path: str) -> tuple[str, Mapping[str, str]]:
         return self._catalog.match_fixture_request(method, path)
 

{millwork_solver-0.1.0 → millwork_solver-0.1.2}/src/millwork_solver/client.py

@@ -13,6 +13,7 @@ import httpx
 from ._core.boundary import _create_async_client, _create_sync_client
 from ._core.clients import _AsyncClient, _SyncClient
 from .types import Page
+from .verifier_connection import AsyncVerifierConnection, VerifierConnection
 
 
 def _required_setting(explicit: str | None, environment_name: str) -> str:
@@ -68,7 +69,7 @@ def _snapshot_resource():
 
 
 class Solver:
-    """Synchronous client for the signed 54-operation Python boundary."""
+    """Synchronous client for the signed operation catalog and protected verifier lifecycle."""
 
     def __init__(
         self,
@@ -101,6 +102,7 @@ class Solver:
         except BaseException:
             self._snapshot_context.__exit__(None, None, None)
             raise
+        self.verifier_connection = VerifierConnection(self._client)
         self._closed = False
 
     def request(
@@ -193,6 +195,7 @@ class AsyncSolver:
         except BaseException:
             self._snapshot_context.__exit__(None, None, None)
             raise
+        self.verifier_connection = AsyncVerifierConnection(self._client)
         self._closed = False
 
     async def request(

millwork_solver-0.1.2/src/millwork_solver/verifier_connection.py

@@ -0,0 +1,279 @@
+"""Secretless verifier connection handoff and read-backed lifecycle."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Literal, TypedDict
+
+from ._core.clients import _AsyncClient, _SyncClient
+from .errors import NetworkError, ProblemError
+
+
+class NoExpiration(TypedDict):
+    kind: Literal["no_expiration"]
+
+
+class PresetDays(TypedDict):
+    kind: Literal["preset_days"]
+    days: Literal[30, 90, 180, 365]
+
+
+class CalendarDate(TypedDict):
+    kind: Literal["calendar_date"]
+    date: str
+    time_zone: str
+
+
+StopChoice = NoExpiration | PresetDays | CalendarDate
+
+
+class ConnectionIntent(TypedDict):
+    continue_url: str
+    intake_origin: str
+    intent_id: str
+    origin: str
+    expires_at: str
+
+
+def _checked_stop_choice(choice: StopChoice) -> StopChoice:
+    if not isinstance(choice, dict):
+        raise TypeError("invalid verifier stop choice")
+    kind = choice.get("kind")
+    if kind == "no_expiration" and set(choice) == {"kind"}:
+        return {"kind": kind}
+    if kind == "preset_days" and set(choice) == {"kind", "days"} and type(choice["days"]) is int and choice["days"] in {30, 90, 180, 365}:
+        return {"kind": kind, "days": choice["days"]}
+    if kind == "calendar_date" and set(choice) == {"kind", "date", "time_zone"}:
+        date, time_zone = choice["date"], choice["time_zone"]
+        if isinstance(date, str) and len(date) == 10 and isinstance(time_zone, str) and time_zone:
+            return {"kind": kind, "date": date, "time_zone": time_zone}
+    raise ValueError("invalid verifier stop choice")
+
+
+@dataclass(frozen=True)
+class LifecycleOutcome:
+    state: Literal["action_required", "pending", "unknown", "test_failed", "changed", "nothing_pending", "refused", "done"]
+    next_action: Literal["enter_key", "resume", "start_again", "inspect"] | None
+    connection: Mapping[str, Any] | None
+    error: Mapping[str, Any] | None = None
+
+
+def _refusal(error: Exception, connection: Mapping[str, Any] | None) -> LifecycleOutcome | None:
+    if isinstance(error, ProblemError):
+        if error.status in {401, 403}:
+            raise error
+        if error.status < 500 and error.status not in {408, 429}:
+            return LifecycleOutcome("refused", "inspect", connection,
+                                    {"status": error.status, "title": error.title})
+        return None
+    if isinstance(error, NetworkError):
+        return None
+    raise error
+
+
+def _operation(view: Mapping[str, Any]) -> Mapping[str, Any]:
+    value = view.get("last_operation")
+    return value if isinstance(value, dict) and value.get("status") != "unknown" else {}
+
+
+def _staged_handle(view: Mapping[str, Any]) -> str | None:
+    operation = _operation(view)
+    state = operation.get("resulting_state")
+    handle = state.get("handle") if isinstance(state, dict) and operation.get("kind") == "stage" else None
+    return handle if isinstance(handle, str) else None
+
+
+def _promotion_result(view: Mapping[str, Any], handle: str) -> LifecycleOutcome:
+    if view.get("status") == "active" and view.get("handle") == handle:
+        return LifecycleOutcome("done", None, view)
+    last_test = view.get("last_test")
+    if isinstance(last_test, dict) and last_test.get("outcome") == "failed" and last_test.get("handle") == handle:
+        return LifecycleOutcome("test_failed", "start_again", view)
+    pending = view.get("pending_key")
+    if isinstance(pending, dict) and pending.get("handle") == handle:
+        return LifecycleOutcome("pending", "resume", view)
+    return LifecycleOutcome("changed", "inspect", view)
+
+
+def _disconnect_result(view: Mapping[str, Any] | None) -> LifecycleOutcome:
+    if view is None:
+        return LifecycleOutcome("unknown", "resume", None)
+    operation = _operation(view)
+    if view.get("status") == "revoked" or (operation.get("kind") == "revoke" and operation.get("phase") == "committed"):
+        return LifecycleOutcome("done", None, view)
+    return LifecycleOutcome("unknown", "resume", view)
+
+
+def _require_mapping(value: Any) -> Mapping[str, Any]:
+    if not isinstance(value, dict):
+        raise TypeError("verifier connection response must be an object")
+    return value
+
+
+class VerifierConnection:
+    """Synchronous protected lifecycle. The key is entered at continue_url, never here."""
+
+    def __init__(self, client: _SyncClient) -> None:
+        self._client = client
+
+    def create_intent(self, verifier_id: str, stop_choice: StopChoice, *, idempotency_key: str) -> ConnectionIntent:
+        return _require_mapping(self._client._verifier_connection("intent", verifier_id,
+                                body={"stop_choice": _checked_stop_choice(stop_choice)}, idempotency_key=idempotency_key))  # type: ignore[return-value]
+
+    def inspect(self, verifier_id: str, *, operation_key: str | None = None) -> Mapping[str, Any]:
+        query = {"operation_key": operation_key} if operation_key else None
+        return _require_mapping(self._client._verifier_connection("inspect", verifier_id, query=query))
+
+    def test_and_promote(self, verifier_id: str, *, handle: str, captured_generation: int,
+                         operation_key: str, idempotency_key: str) -> Mapping[str, Any]:
+        return _require_mapping(self._client._verifier_connection("promote", verifier_id,
+                                body={"handle": handle, "captured_generation": captured_generation,
+                                      "operation_key": operation_key}, idempotency_key=idempotency_key))
+
+    def revoke(self, verifier_id: str, *, operation_key: str, idempotency_key: str) -> Mapping[str, Any]:
+        return _require_mapping(self._client._verifier_connection("revoke", verifier_id,
+                                body={"operation_key": operation_key}, idempotency_key=idempotency_key))
+
+    def _safe_inspect(self, verifier_id: str, operation_key: str) -> Mapping[str, Any] | LifecycleOutcome | None:
+        try:
+            return self.inspect(verifier_id, operation_key=operation_key)
+        except (ProblemError, NetworkError) as error:
+            return _refusal(error, None)
+
+    def continue_connection(self, verifier_id: str, *, operation_key: str, idempotency_key: str) -> LifecycleOutcome:
+        before = self._safe_inspect(verifier_id, operation_key)
+        if isinstance(before, LifecycleOutcome):
+            return before
+        if before is None:
+            return LifecycleOutcome("unknown", "resume", None)
+        operation = _operation(before)
+        if operation.get("kind") == "promote" and operation.get("phase") == "committed":
+            return LifecycleOutcome("done", None, before)
+        handle = _staged_handle(before)
+        if handle is None:
+            return LifecycleOutcome("action_required", "enter_key", before)
+        pending = before.get("pending_key")
+        if isinstance(pending, dict) and pending.get("handle") != handle:
+            return LifecycleOutcome("changed", "inspect", before)
+        if not isinstance(pending, dict):
+            return _promotion_result(before, handle)
+        write_refusal = None
+        try:
+            self.test_and_promote(verifier_id, handle=handle,
+                                  captured_generation=pending["captured_generation"],
+                                  operation_key=operation_key, idempotency_key=idempotency_key)
+        except (ProblemError, NetworkError) as error:
+            write_refusal = _refusal(error, before)
+        after = self._safe_inspect(verifier_id, operation_key)
+        if isinstance(after, LifecycleOutcome):
+            return after
+        if after is None:
+            return write_refusal or LifecycleOutcome("unknown", "resume", None)
+        result = _promotion_result(after, handle)
+        if write_refusal and result.state not in {"test_failed", "done"}:
+            return LifecycleOutcome("refused", "inspect", after, write_refusal.error)
+        return result
+
+    def disconnect(self, verifier_id: str, *, operation_key: str, idempotency_key: str,
+                   confirmed: bool) -> LifecycleOutcome:
+        if not confirmed:
+            raise ValueError("verifier disconnect requires explicit confirmation")
+        write_refusal = None
+        try:
+            self.revoke(verifier_id, operation_key=operation_key, idempotency_key=idempotency_key)
+        except (ProblemError, NetworkError) as error:
+            write_refusal = _refusal(error, None)
+        after = self._safe_inspect(verifier_id, operation_key)
+        if isinstance(after, LifecycleOutcome):
+            return after
+        if after is None and write_refusal:
+            return write_refusal
+        result = _disconnect_result(after)
+        if write_refusal and result.state != "done":
+            return LifecycleOutcome("refused", "inspect", after, write_refusal.error)
+        return result
+
+
+class AsyncVerifierConnection:
+    """Async equivalent of the secretless protected lifecycle."""
+
+    def __init__(self, client: _AsyncClient) -> None:
+        self._client = client
+
+    async def create_intent(self, verifier_id: str, stop_choice: StopChoice, *, idempotency_key: str) -> ConnectionIntent:
+        return _require_mapping(await self._client._verifier_connection("intent", verifier_id,
+                                body={"stop_choice": _checked_stop_choice(stop_choice)}, idempotency_key=idempotency_key))  # type: ignore[return-value]
+
+    async def inspect(self, verifier_id: str, *, operation_key: str | None = None) -> Mapping[str, Any]:
+        query = {"operation_key": operation_key} if operation_key else None
+        return _require_mapping(await self._client._verifier_connection("inspect", verifier_id, query=query))
+
+    async def test_and_promote(self, verifier_id: str, *, handle: str, captured_generation: int,
+                               operation_key: str, idempotency_key: str) -> Mapping[str, Any]:
+        return _require_mapping(await self._client._verifier_connection("promote", verifier_id,
+                                body={"handle": handle, "captured_generation": captured_generation,
+                                      "operation_key": operation_key}, idempotency_key=idempotency_key))
+
+    async def revoke(self, verifier_id: str, *, operation_key: str, idempotency_key: str) -> Mapping[str, Any]:
+        return _require_mapping(await self._client._verifier_connection("revoke", verifier_id,
+                                body={"operation_key": operation_key}, idempotency_key=idempotency_key))
+
+    async def _safe_inspect(self, verifier_id: str, operation_key: str) -> Mapping[str, Any] | LifecycleOutcome | None:
+        try:
+            return await self.inspect(verifier_id, operation_key=operation_key)
+        except (ProblemError, NetworkError) as error:
+            return _refusal(error, None)
+
+    async def continue_connection(self, verifier_id: str, *, operation_key: str, idempotency_key: str) -> LifecycleOutcome:
+        before = await self._safe_inspect(verifier_id, operation_key)
+        if isinstance(before, LifecycleOutcome):
+            return before
+        if before is None:
+            return LifecycleOutcome("unknown", "resume", None)
+        operation = _operation(before)
+        if operation.get("kind") == "promote" and operation.get("phase") == "committed":
+            return LifecycleOutcome("done", None, before)
+        handle = _staged_handle(before)
+        if handle is None:
+            return LifecycleOutcome("action_required", "enter_key", before)
+        pending = before.get("pending_key")
+        if isinstance(pending, dict) and pending.get("handle") != handle:
+            return LifecycleOutcome("changed", "inspect", before)
+        if not isinstance(pending, dict):
+            return _promotion_result(before, handle)
+        write_refusal = None
+        try:
+            await self.test_and_promote(verifier_id, handle=handle,
+                                        captured_generation=pending["captured_generation"],
+                                        operation_key=operation_key, idempotency_key=idempotency_key)
+        except (ProblemError, NetworkError) as error:
+            write_refusal = _refusal(error, before)
+        after = await self._safe_inspect(verifier_id, operation_key)
+        if isinstance(after, LifecycleOutcome):
+            return after
+        if after is None:
+            return write_refusal or LifecycleOutcome("unknown", "resume", None)
+        result = _promotion_result(after, handle)
+        if write_refusal and result.state not in {"test_failed", "done"}:
+            return LifecycleOutcome("refused", "inspect", after, write_refusal.error)
+        return result
+
+    async def disconnect(self, verifier_id: str, *, operation_key: str, idempotency_key: str,
+                         confirmed: bool) -> LifecycleOutcome:
+        if not confirmed:
+            raise ValueError("verifier disconnect requires explicit confirmation")
+        write_refusal = None
+        try:
+            await self.revoke(verifier_id, operation_key=operation_key, idempotency_key=idempotency_key)
+        except (ProblemError, NetworkError) as error:
+            write_refusal = _refusal(error, None)
+        after = await self._safe_inspect(verifier_id, operation_key)
+        if isinstance(after, LifecycleOutcome):
+            return after
+        if after is None and write_refusal:
+            return write_refusal
+        result = _disconnect_result(after)
+        if write_refusal and result.state != "done":
+            return LifecycleOutcome("refused", "inspect", after, write_refusal.error)
+        return result

millwork_solver-0.1.2/src/millwork_solver.egg-info/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: millwork-solver
+Version: 0.1.2
+Summary: Sync and async Python clients for the Millwork Solver API
+Author: Millwork
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/millworkdev/solver-python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx==0.28.1
+Dynamic: license-file
+
+# Millwork Solver for Python
+
+`millwork-solver` is an early preview client for the Millwork Solver API. Import
+`millwork_solver` to use the synchronous `Solver` client or the asynchronous
+`AsyncSolver` client on CPython 3.11 through 3.14.
+
+The [generated REST lifecycle reference](https://docs.getmillwork.dev/api-reference/output-checks)
+owns output-check operation IDs and fields. The
+[verifier-dock contract](https://docs.getmillwork.dev/contracts/verifier-dock/v1.json)
+owns the endpoint request and response. Follow
+[Recipe 0](https://docs.getmillwork.dev/cookbook/output-checks/build-the-dock)
+for local tests, deployment, and a receipt.
+
+Pass `api_key` and `base_url` directly, or use `SOLVERAPI_API_KEY` and
+`SOLVERAPI_BASE_URL`. Retry settings use `SOLVERAPI_MAX_RETRIES` (default `2`)
+and `SOLVERAPI_RETRY_BACKOFF_MS` (default `500`).
+
+Both clients provide the same typed operation surface, explicit timeout and
+close behavior, and receipt-aware responses. Echo reaches a terminal status and
+returns a receipt; it does not return result content.
+
+Use the API base URL with its `/v1` suffix:
+
+```bash
+export SOLVERAPI_BASE_URL="https://api.getmillwork.dev/v1"
+export SOLVERAPI_API_KEY="<organization API key>"
+```
+
+Call an operation by its OpenAPI `operation_id`. This complete test run uses
+`postExecutions`; the request must include both `task` and `policy`:
+
+```python
+import uuid
+
+from millwork_solver import Solver
+
+with Solver() as client:
+    run = client.request(
+        "postExecutions",
+        body={
+            "mode": "echo",
+            "task": {"objective": "Check the Millwork API lifecycle."},
+            "policy": {
+                "data_classes": ["public"],
+                "budget": {"max_cost_usd": 1, "max_runtime_s": 30},
+            },
+        },
+        idempotency_key=str(uuid.uuid4()),
+    )
+    receipt = client.request(
+        "getReceiptsByExecutionId",
+        path_parameters={"executionId": run["execution_id"]},
+    )
+    print(run["status"], receipt["mode"])
+```
+
+Common operation IDs include `getAccount`, `getArms`, `getModelCatalog`,
+`getVerifiers`, `postExecutions`, `getExecutionsByExecutionId`,
+`getExecutionsByExecutionIdResult`, and `getReceiptsByExecutionId`. The package
+ships the complete operation contract in `millwork_solver/_contract.json`.
+
+## Verifier lifecycle
+
+The installed client can register and test a public output check. Set
+`VERIFIER_URL` to an endpoint implementing the
+[output-check contract](https://docs.getmillwork.dev/cookbook/output-checks/build-the-dock#the-endpoint-contract):
+
+```python
+import os
+import uuid
+from millwork_solver import Solver
+
+with Solver() as client:
+    registered = client.request("postVerifiers", body={
+        "display_name": "My output check", "version": "1.0.0", "kind": "endpoint",
+        "endpoint": {"url": os.environ["VERIFIER_URL"], "auth_ref": ""},
+        "input_data_classes": ["public"],
+        "scoring": {"correctness": "boolean_anchors", "quality": "scalar_0_1"},
+    }, idempotency_key=str(uuid.uuid4()))
+    verifier_id = registered["verifier_id"]
+    print(verifier_id, client.request("postVerifiersByVerifierIdTest",
+          path_parameters={"verifierId": verifier_id}, idempotency_key=str(uuid.uuid4())))
+```
+
+The published `millwork-solver==0.1.1` wheel includes the public verifier
+operation IDs and `verifier_connection`. Install that pinned release to run
+the protected-connection methods below. The earlier `0.1.0` wheel does not
+include these methods.
+
+For a protected endpoint, register that endpoint with the same secretless
+`postVerifiers` body, then use **its** `verifier_id` for the private handoff.
+The REST registration has no `access` field; the protected connection is
+established by `verifier_connection`. Give `continue_url` only to the intended
+person through your host's private browser handoff. The callback below belongs
+to that host and must not log or expose the URL. The endpoint key is never an
+argument to these methods.
+
+```python
+import uuid
+from urllib.parse import urlsplit
+
+def start_protected(client, verifier_id, trusted_app_origin, open_private_url):
+    intent = client.verifier_connection.create_intent(
+        verifier_id, {"kind": "preset_days", "days": 90},
+        idempotency_key=str(uuid.uuid4()))
+    expected = urlsplit(trusted_app_origin)
+    actual = urlsplit(intent["continue_url"])
+    if (actual.scheme, actual.netloc) != (expected.scheme, expected.netloc):
+        raise ValueError("Unexpected private-entry origin")
+    open_private_url(intent["continue_url"])
+    return intent["intent_id"]
+
+def continue_protected(client, verifier_id, operation_key):
+    return client.verifier_connection.continue_connection(
+        verifier_id, operation_key=operation_key,
+        idempotency_key=str(uuid.uuid4()))
+```
+
+`enter_key` means private entry is still needed. `resume` means retain the same
+operation key and use a fresh request idempotency key. `start_again` means the
+endpoint test failed; correct the endpoint or key and create a new intent.
+`inspect` means another connection change intervened. `refused` means the server
+rejected the change with a non-retryable client error; read `outcome.error["status"]`
+and `outcome.error["title"]`, inspect that operation, and correct the cause before
+another action. A `401` or `403` raises a `ProblemError` instead of returning a
+lifecycle outcome. Only a read-backed `done`
+confirms completion. The async `AsyncSolver.verifier_connection` has the same
+methods, awaited. Replacement and restoration use a new intent and the same
+private-entry path. Disconnect requires explicit caller confirmation:
+`client.verifier_connection.disconnect(verifier_id, operation_key=...,
+idempotency_key=..., confirmed=True)`. Millwork stopping use of a key does not
+revoke it at your endpoint. A governed run requires separate authorization and
+uses this `verifier_id`.

{millwork_solver-0.1.0 → millwork_solver-0.1.2}/src/millwork_solver.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ src/millwork_solver/client.py
 src/millwork_solver/errors.py
 src/millwork_solver/py.typed
 src/millwork_solver/types.py
+src/millwork_solver/verifier_connection.py
 src/millwork_solver.egg-info/PKG-INFO
 src/millwork_solver.egg-info/SOURCES.txt
 src/millwork_solver.egg-info/dependency_links.txt

millwork_solver-0.1.0/PKG-INFO

@@ -1,32 +0,0 @@
-Metadata-Version: 2.4
-Name: millwork-solver
-Version: 0.1.0
-Summary: Sync and async Python clients for the Millwork Solver API
-Author: Millwork
-License-Expression: Apache-2.0
-Project-URL: Repository, https://github.com/millworkdev/solver-python
-Classifier: Development Status :: 3 - Alpha
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Requires-Python: <3.15,>=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: httpx==0.28.1
-Dynamic: license-file
-
-# Millwork Solver for Python
-
-`millwork-solver` is an early preview client for the Millwork Solver API. Import
-`millwork_solver` to use the synchronous `Solver` client or the asynchronous
-`AsyncSolver` client on CPython 3.11 through 3.14.
-
-Pass `api_key` and `base_url` directly, or use `SOLVERAPI_API_KEY` and
-`SOLVERAPI_BASE_URL`. Retry settings use `SOLVERAPI_MAX_RETRIES` (default `2`)
-and `SOLVERAPI_RETRY_BACKOFF_MS` (default `500`).
-
-Both clients provide the same typed operation surface, explicit timeout and
-close behavior, and receipt-aware responses. Echo reaches a terminal status and
-returns a receipt; it does not return result content.

millwork_solver-0.1.0/README.md

@@ -1,13 +0,0 @@
-# Millwork Solver for Python
-
-`millwork-solver` is an early preview client for the Millwork Solver API. Import
-`millwork_solver` to use the synchronous `Solver` client or the asynchronous
-`AsyncSolver` client on CPython 3.11 through 3.14.
-
-Pass `api_key` and `base_url` directly, or use `SOLVERAPI_API_KEY` and
-`SOLVERAPI_BASE_URL`. Retry settings use `SOLVERAPI_MAX_RETRIES` (default `2`)
-and `SOLVERAPI_RETRY_BACKOFF_MS` (default `500`).
-
-Both clients provide the same typed operation surface, explicit timeout and
-close behavior, and receipt-aware responses. Echo reaches a terminal status and
-returns a receipt; it does not return result content.

millwork_solver-0.1.0/src/millwork_solver.egg-info/PKG-INFO

@@ -1,32 +0,0 @@
-Metadata-Version: 2.4
-Name: millwork-solver
-Version: 0.1.0
-Summary: Sync and async Python clients for the Millwork Solver API
-Author: Millwork
-License-Expression: Apache-2.0
-Project-URL: Repository, https://github.com/millworkdev/solver-python
-Classifier: Development Status :: 3 - Alpha
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Requires-Python: <3.15,>=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: httpx==0.28.1
-Dynamic: license-file
-
-# Millwork Solver for Python
-
-`millwork-solver` is an early preview client for the Millwork Solver API. Import
-`millwork_solver` to use the synchronous `Solver` client or the asynchronous
-`AsyncSolver` client on CPython 3.11 through 3.14.
-
-Pass `api_key` and `base_url` directly, or use `SOLVERAPI_API_KEY` and
-`SOLVERAPI_BASE_URL`. Retry settings use `SOLVERAPI_MAX_RETRIES` (default `2`)
-and `SOLVERAPI_RETRY_BACKOFF_MS` (default `500`).
-
-Both clients provide the same typed operation surface, explicit timeout and
-close behavior, and receipt-aware responses. Echo reaches a terminal status and
-returns a receipt; it does not return result content.