roark-analytics 5.2.0__tar.gz → 5.3.0__tar.gz

roark_analytics-5.3.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "5.3.0"
+}

{roark_analytics-5.2.0 → roark_analytics-5.3.0}/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [5.3.0](https://github.com/roarkhq/sdk-roark-analytics-python/compare/v5.2.0...v5.3.0) (2026-09-23)
+
+
+### Features
+
+* **api:** api update ([#584](https://github.com/roarkhq/sdk-roark-analytics-python/issues/584)) ([cee63db](https://github.com/roarkhq/sdk-roark-analytics-python/commit/cee63db9b32260aca49bb546d679c827d92f3f08))
+
+
+### Chores
+
+* fold next into main ([b9e8037](https://github.com/roarkhq/sdk-roark-analytics-python/commit/b9e8037016700697f50dd87c97ce06f16f866a1e))
+
 ## [5.2.0](https://github.com/roarkhq/sdk-roark-analytics-python/compare/v5.1.0...v5.2.0) (2026-09-23)
 
 

{roark_analytics-5.2.0 → roark_analytics-5.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: roark_analytics
-Version: 5.2.0
+Version: 5.3.0
 Summary: The official Python library for the roark API
 Project-URL: Homepage, https://github.com/roarkhq/sdk-roark-analytics-python
 Project-URL: Repository, https://github.com/roarkhq/sdk-roark-analytics-python

{roark_analytics-5.2.0 → roark_analytics-5.3.0}/api.md

@@ -121,11 +121,12 @@ Methods:
 Types:
 
 ```python
-from roark_analytics.types import SimulationRunResponse
+from roark_analytics.types import SimulationMockToolResponse, SimulationRunResponse
 ```
 
 Methods:
 
+- <code title="post /v1/simulation/tool-mock">client.simulation.<a href="./src/roark_analytics/resources/simulation.py">mock_tool</a>(\*\*<a href="src/roark_analytics/types/simulation_mock_tool_params.py">params</a>) -> <a href="./src/roark_analytics/types/simulation_mock_tool_response.py">SimulationMockToolResponse</a></code>
 - <code title="post /v1/simulation/run">client.simulation.<a href="./src/roark_analytics/resources/simulation.py">run</a>(\*\*<a href="src/roark_analytics/types/simulation_run_params.py">params</a>) -> <a href="./src/roark_analytics/types/simulation_run_response.py">SimulationRunResponse</a></code>
 
 # SimulationJob

{roark_analytics-5.2.0 → roark_analytics-5.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "roark_analytics"
-version = "5.2.0"
+version = "5.3.0"
 description = "The official Python library for the roark API"
 dynamic = ["readme"]
 license = "Apache-2.0"

{roark_analytics-5.2.0 → roark_analytics-5.3.0}/src/roark_analytics/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "roark_analytics"
-__version__ = "5.2.0"  # x-release-please-version
+__version__ = "5.3.0"  # x-release-please-version

{roark_analytics-5.2.0 → roark_analytics-5.3.0}/src/roark_analytics/resources/simulation.py

@@ -7,7 +7,7 @@ from typing_extensions import Literal
 
 import httpx
 
-from ..types import simulation_run_params
+from ..types import simulation_run_params, simulation_mock_tool_params
 from .._types import Body, Omit, Query, Headers, NotGiven, SequenceNotStr, omit, not_given
 from .._utils import required_args, maybe_transform, async_maybe_transform
 from .._compat import cached_property
@@ -20,6 +20,7 @@ from .._response import (
 )
 from .._base_client import make_request_options
 from ..types.simulation_run_response import SimulationRunResponse
+from ..types.simulation_mock_tool_response import SimulationMockToolResponse
 
 __all__ = ["SimulationResource", "AsyncSimulationResource"]
 
@@ -44,6 +45,78 @@ class SimulationResource(SyncAPIResource):
         """
         return SimulationResourceWithStreamingResponse(self)
 
+    def mock_tool(
+        self,
+        *,
+        simulation_job_id: str,
+        tool_name: str,
+        arguments: Dict[str, object] | Omit = omit,
+        session_id: str | Omit = omit,
+        tool_description: str | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> SimulationMockToolResponse:
+        """The server half of the tool guard for code-first agents.
+
+        When a guarded tool
+        fires during a Roark test call, send the invocation here instead of executing
+        it: Roark answers with a simulated backend response that is valid JSON, shaped
+        by the tool contract you pass, consistent with the test scenario, and consistent
+        with earlier mocked responses in the same call. Real callers are never affected:
+        the guard only diverts when the agent-config resolve response identified the
+        session as a Roark simulation, and this endpoint independently re-validates the
+        simulation before answering. Failure contract for your wrapper: `404` means the
+        simulation id is unknown to this project (treat the session as real). `409`
+        means the simulation has already ended (stale session state: do NOT execute the
+        real tool; return your static fallback). `5xx` means generation failed (return
+        your static fallback). Identical retries (same tool, same arguments) within a
+        few minutes return the stored response, so double-fired handlers stay
+        consistent.
+
+        Args:
+          simulation_job_id: The simulation this session belongs to, from the agent-config resolve response
+              (`simulationJobId`). Roark re-validates it against the live simulation before
+              answering.
+
+          tool_name: The tool the agent invoked.
+
+          arguments: The arguments the agent called the tool with, verbatim.
+
+          session_id: Your session or room identifier, echoed back in logs for correlation.
+
+          tool_description: The tool's contract: its description and, ideally, its parameter and return
+              shape. The more contract you pass, the more faithful the simulated response.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return self._post(
+            "/v1/simulation/tool-mock",
+            body=maybe_transform(
+                {
+                    "simulation_job_id": simulation_job_id,
+                    "tool_name": tool_name,
+                    "arguments": arguments,
+                    "session_id": session_id,
+                    "tool_description": tool_description,
+                },
+                simulation_mock_tool_params.SimulationMockToolParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=SimulationMockToolResponse,
+        )
+
     @overload
     def run(
         self,
@@ -377,6 +450,78 @@ class AsyncSimulationResource(AsyncAPIResource):
         """
         return AsyncSimulationResourceWithStreamingResponse(self)
 
+    async def mock_tool(
+        self,
+        *,
+        simulation_job_id: str,
+        tool_name: str,
+        arguments: Dict[str, object] | Omit = omit,
+        session_id: str | Omit = omit,
+        tool_description: str | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> SimulationMockToolResponse:
+        """The server half of the tool guard for code-first agents.
+
+        When a guarded tool
+        fires during a Roark test call, send the invocation here instead of executing
+        it: Roark answers with a simulated backend response that is valid JSON, shaped
+        by the tool contract you pass, consistent with the test scenario, and consistent
+        with earlier mocked responses in the same call. Real callers are never affected:
+        the guard only diverts when the agent-config resolve response identified the
+        session as a Roark simulation, and this endpoint independently re-validates the
+        simulation before answering. Failure contract for your wrapper: `404` means the
+        simulation id is unknown to this project (treat the session as real). `409`
+        means the simulation has already ended (stale session state: do NOT execute the
+        real tool; return your static fallback). `5xx` means generation failed (return
+        your static fallback). Identical retries (same tool, same arguments) within a
+        few minutes return the stored response, so double-fired handlers stay
+        consistent.
+
+        Args:
+          simulation_job_id: The simulation this session belongs to, from the agent-config resolve response
+              (`simulationJobId`). Roark re-validates it against the live simulation before
+              answering.
+
+          tool_name: The tool the agent invoked.
+
+          arguments: The arguments the agent called the tool with, verbatim.
+
+          session_id: Your session or room identifier, echoed back in logs for correlation.
+
+          tool_description: The tool's contract: its description and, ideally, its parameter and return
+              shape. The more contract you pass, the more faithful the simulated response.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return await self._post(
+            "/v1/simulation/tool-mock",
+            body=await async_maybe_transform(
+                {
+                    "simulation_job_id": simulation_job_id,
+                    "tool_name": tool_name,
+                    "arguments": arguments,
+                    "session_id": session_id,
+                    "tool_description": tool_description,
+                },
+                simulation_mock_tool_params.SimulationMockToolParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=SimulationMockToolResponse,
+        )
+
     @overload
     async def run(
         self,
@@ -694,6 +839,9 @@ class SimulationResourceWithRawResponse:
     def __init__(self, simulation: SimulationResource) -> None:
         self._simulation = simulation
 
+        self.mock_tool = to_raw_response_wrapper(
+            simulation.mock_tool,
+        )
         self.run = to_raw_response_wrapper(
             simulation.run,
         )
@@ -703,6 +851,9 @@ class AsyncSimulationResourceWithRawResponse:
     def __init__(self, simulation: AsyncSimulationResource) -> None:
         self._simulation = simulation
 
+        self.mock_tool = async_to_raw_response_wrapper(
+            simulation.mock_tool,
+        )
         self.run = async_to_raw_response_wrapper(
             simulation.run,
         )
@@ -712,6 +863,9 @@ class SimulationResourceWithStreamingResponse:
     def __init__(self, simulation: SimulationResource) -> None:
         self._simulation = simulation
 
+        self.mock_tool = to_streamed_response_wrapper(
+            simulation.mock_tool,
+        )
         self.run = to_streamed_response_wrapper(
             simulation.run,
         )
@@ -721,6 +875,9 @@ class AsyncSimulationResourceWithStreamingResponse:
     def __init__(self, simulation: AsyncSimulationResource) -> None:
         self._simulation = simulation
 
+        self.mock_tool = async_to_streamed_response_wrapper(
+            simulation.mock_tool,
+        )
         self.run = async_to_streamed_response_wrapper(
             simulation.run,
         )

{roark_analytics-5.2.0 → roark_analytics-5.3.0}/src/roark_analytics/types/__init__.py

@@ -55,6 +55,7 @@ from .customer_flow_update_params import CustomerFlowUpdateParams as CustomerFlo
 from .metric_policy_create_params import MetricPolicyCreateParams as MetricPolicyCreateParams
 from .metric_policy_list_response import MetricPolicyListResponse as MetricPolicyListResponse
 from .metric_policy_update_params import MetricPolicyUpdateParams as MetricPolicyUpdateParams
+from .simulation_mock_tool_params import SimulationMockToolParams as SimulationMockToolParams
 from .agent_config_update_response import AgentConfigUpdateResponse as AgentConfigUpdateResponse
 from .agent_endpoint_create_params import AgentEndpointCreateParams as AgentEndpointCreateParams
 from .agent_endpoint_list_response import AgentEndpointListResponse as AgentEndpointListResponse
@@ -79,6 +80,7 @@ from .managed_agent_config_revision import ManagedAgentConfigRevision as Managed
 from .metric_policy_create_response import MetricPolicyCreateResponse as MetricPolicyCreateResponse
 from .metric_policy_delete_response import MetricPolicyDeleteResponse as MetricPolicyDeleteResponse
 from .metric_policy_update_response import MetricPolicyUpdateResponse as MetricPolicyUpdateResponse
+from .simulation_mock_tool_response import SimulationMockToolResponse as SimulationMockToolResponse
 from .agent_endpoint_create_response import AgentEndpointCreateResponse as AgentEndpointCreateResponse
 from .agent_endpoint_update_response import AgentEndpointUpdateResponse as AgentEndpointUpdateResponse
 from .benchmark_list_suites_response import BenchmarkListSuitesResponse as BenchmarkListSuitesResponse

roark_analytics-5.3.0/src/roark_analytics/types/simulation_mock_tool_params.py

@@ -0,0 +1,34 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing import Dict
+from typing_extensions import Required, Annotated, TypedDict
+
+from .._utils import PropertyInfo
+
+__all__ = ["SimulationMockToolParams"]
+
+
+class SimulationMockToolParams(TypedDict, total=False):
+    simulation_job_id: Required[Annotated[str, PropertyInfo(alias="simulationJobId")]]
+    """
+    The simulation this session belongs to, from the agent-config resolve response
+    (`simulationJobId`). Roark re-validates it against the live simulation before
+    answering.
+    """
+
+    tool_name: Required[Annotated[str, PropertyInfo(alias="toolName")]]
+    """The tool the agent invoked."""
+
+    arguments: Dict[str, object]
+    """The arguments the agent called the tool with, verbatim."""
+
+    session_id: Annotated[str, PropertyInfo(alias="sessionId")]
+    """Your session or room identifier, echoed back in logs for correlation."""
+
+    tool_description: Annotated[str, PropertyInfo(alias="toolDescription")]
+    """
+    The tool's contract: its description and, ideally, its parameter and return
+    shape. The more contract you pass, the more faithful the simulated response.
+    """

roark_analytics-5.3.0/src/roark_analytics/types/simulation_mock_tool_response.py

@@ -0,0 +1,41 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Optional
+
+from pydantic import Field as FieldInfo
+
+from .._models import BaseModel
+
+__all__ = ["SimulationMockToolResponse", "Data"]
+
+
+class Data(BaseModel):
+    """
+    A simulated backend response for a guarded tool during a Roark test call. The
+    real tool was not, and must not be, executed.
+    """
+
+    reused: bool
+    """
+    True when this exact invocation (same tool, same arguments) was answered moments
+    ago and the stored response was returned, e.g. on a retry.
+    """
+
+    simulation_job_id: str = FieldInfo(alias="simulationJobId")
+
+    tool_name: str = FieldInfo(alias="toolName")
+
+    result: Optional[object] = None
+    """
+    The simulated tool response: valid JSON, shaped by the tool contract, consistent
+    with the test scenario and with earlier mocked responses in the same call.
+    Return this from your tool instead of executing it.
+    """
+
+
+class SimulationMockToolResponse(BaseModel):
+    data: Data
+    """
+    A simulated backend response for a guarded tool during a Roark test call. The
+    real tool was not, and must not be, executed.
+    """

{roark_analytics-5.2.0 → roark_analytics-5.3.0}/tests/api_resources/test_simulation.py

@@ -9,7 +9,10 @@ import pytest
 
 from tests.utils import assert_matches_type
 from roark_analytics import Roark, AsyncRoark
-from roark_analytics.types import SimulationRunResponse
+from roark_analytics.types import (
+    SimulationRunResponse,
+    SimulationMockToolResponse,
+)
 
 base_url = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010")
 
@@ -17,6 +20,51 @@ base_url = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010")
 class TestSimulation:
     parametrize = pytest.mark.parametrize("client", [False, True], indirect=True, ids=["loose", "strict"])
 
+    @parametrize
+    def test_method_mock_tool(self, client: Roark) -> None:
+        simulation = client.simulation.mock_tool(
+            simulation_job_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
+            tool_name="book_appointment",
+        )
+        assert_matches_type(SimulationMockToolResponse, simulation, path=["response"])
+
+    @parametrize
+    def test_method_mock_tool_with_all_params(self, client: Roark) -> None:
+        simulation = client.simulation.mock_tool(
+            simulation_job_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
+            tool_name="book_appointment",
+            arguments={"date": "2026-10-01", "time": "15:00"},
+            session_id="sessionId",
+            tool_description="Books an appointment. Args: date (YYYY-MM-DD), time (HH:MM). Returns {confirmationId, status}.",
+        )
+        assert_matches_type(SimulationMockToolResponse, simulation, path=["response"])
+
+    @parametrize
+    def test_raw_response_mock_tool(self, client: Roark) -> None:
+        response = client.simulation.with_raw_response.mock_tool(
+            simulation_job_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
+            tool_name="book_appointment",
+        )
+
+        assert response.is_closed is True
+        assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+        simulation = response.parse()
+        assert_matches_type(SimulationMockToolResponse, simulation, path=["response"])
+
+    @parametrize
+    def test_streaming_response_mock_tool(self, client: Roark) -> None:
+        with client.simulation.with_streaming_response.mock_tool(
+            simulation_job_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
+            tool_name="book_appointment",
+        ) as response:
+            assert not response.is_closed
+            assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+
+            simulation = response.parse()
+            assert_matches_type(SimulationMockToolResponse, simulation, path=["response"])
+
+        assert cast(Any, response.is_closed) is True
+
     @parametrize
     def test_method_run_overload_1(self, client: Roark) -> None:
         simulation = client.simulation.run(
@@ -228,6 +276,51 @@ class TestAsyncSimulation:
         "async_client", [False, True, {"http_client": "aiohttp"}], indirect=True, ids=["loose", "strict", "aiohttp"]
     )
 
+    @parametrize
+    async def test_method_mock_tool(self, async_client: AsyncRoark) -> None:
+        simulation = await async_client.simulation.mock_tool(
+            simulation_job_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
+            tool_name="book_appointment",
+        )
+        assert_matches_type(SimulationMockToolResponse, simulation, path=["response"])
+
+    @parametrize
+    async def test_method_mock_tool_with_all_params(self, async_client: AsyncRoark) -> None:
+        simulation = await async_client.simulation.mock_tool(
+            simulation_job_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
+            tool_name="book_appointment",
+            arguments={"date": "2026-10-01", "time": "15:00"},
+            session_id="sessionId",
+            tool_description="Books an appointment. Args: date (YYYY-MM-DD), time (HH:MM). Returns {confirmationId, status}.",
+        )
+        assert_matches_type(SimulationMockToolResponse, simulation, path=["response"])
+
+    @parametrize
+    async def test_raw_response_mock_tool(self, async_client: AsyncRoark) -> None:
+        response = await async_client.simulation.with_raw_response.mock_tool(
+            simulation_job_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
+            tool_name="book_appointment",
+        )
+
+        assert response.is_closed is True
+        assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+        simulation = await response.parse()
+        assert_matches_type(SimulationMockToolResponse, simulation, path=["response"])
+
+    @parametrize
+    async def test_streaming_response_mock_tool(self, async_client: AsyncRoark) -> None:
+        async with async_client.simulation.with_streaming_response.mock_tool(
+            simulation_job_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
+            tool_name="book_appointment",
+        ) as response:
+            assert not response.is_closed
+            assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+
+            simulation = await response.parse()
+            assert_matches_type(SimulationMockToolResponse, simulation, path=["response"])
+
+        assert cast(Any, response.is_closed) is True
+
     @parametrize
     async def test_method_run_overload_1(self, async_client: AsyncRoark) -> None:
         simulation = await async_client.simulation.run(

roark_analytics-5.2.0/.release-please-manifest.json

@@ -1,3 +0,0 @@
-{
-  ".": "5.2.0"
-}