narada 0.2.7__tar.gz → 0.2.9__tar.gz

{narada-0.2.7 → narada-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: narada
-Version: 0.2.7
+Version: 0.2.9
 Summary: Python client SDK for Narada
 Project-URL: Homepage, https://github.com/NaradaAI/narada-python-sdk/narada
 Project-URL: Repository, https://github.com/NaradaAI/narada-python-sdk
@@ -9,7 +9,7 @@ Author-email: Narada <support@narada.ai>
 License-Expression: Apache-2.0
 Requires-Python: >=3.12
 Requires-Dist: aiohttp>=3.12.13
-Requires-Dist: narada-core==0.1.4
+Requires-Dist: narada-core==0.1.6
 Requires-Dist: packaging==24.2
 Requires-Dist: playwright>=1.53.0
 Requires-Dist: rich>=14.0.0

{narada-0.2.7 → narada-0.2.9}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "narada"
-version = "0.2.7"
+version = "0.2.9"
 description = "Python client SDK for Narada"
 license = "Apache-2.0"
 readme = "README.md"
 authors = [{ name = "Narada", email = "support@narada.ai" }]
 requires-python = ">=3.12"
 dependencies = [
-    "narada-core==0.1.4",
+    "narada-core==0.1.6",
     "aiohttp>=3.12.13",
     "playwright>=1.53.0",
     "rich>=14.0.0",

{narada-0.2.7 → narada-0.2.9}/src/narada/agent.py

@@ -81,8 +81,6 @@ class Agent(Generic[_StructuredOutput]):
         self.environment = environment
         self.kind = kind
 
-    # `reasoning` is only valid with the Core Agent; these two overloads make
-    # that constraint type-checkable when callers construct a core-agent instance.
     @overload
     async def run(
         self,
@@ -160,6 +158,12 @@ class Agent(Generic[_StructuredOutput]):
         timeout: int = 1000,
     ) -> AgentResponse:
         """Invokes an agent in the bound Narada environment."""
+        if reasoning is not None and not isinstance(self.kind, AgentKind):
+            raise ValueError(
+                "`reasoning` is only supported for built-in `AgentKind` values; "
+                "named Agent Studio agents own reasoning per workflow step"
+            )
+
         remote_dispatch_response = await self._dispatch_request(
             prompt=prompt,
             clear_chat=clear_chat,
@@ -246,70 +250,29 @@ class Agent(Generic[_StructuredOutput]):
         timeout: int = 1000,
     ) -> Response:
         dispatch_agent = self.kind if agent is None else agent
-        # Branch on `reasoning` so each call site binds a single, typed overload
-        # of `_dispatch_request`. The validation also lives in `_dispatch_request`
-        # itself (defense in depth + reachable when callers go straight to the
-        # low-level API), so the redundancy here is intentional.
-        if reasoning is None:
-            remote_dispatch_response = await self.environment._dispatch_request(
-                prompt=prompt,
-                agent=dispatch_agent,
-                clear_chat=clear_chat,
-                generate_gif=generate_gif,
-                output_schema=output_schema,
-                previous_request_id=previous_request_id,
-                chat_history=chat_history,
-                additional_context=additional_context,
-                attachment=attachment,
-                time_zone=time_zone,
-                user_resource_credentials=user_resource_credentials,
-                mcp_servers=mcp_servers,
-                secret_variables=secret_variables,
-                input_variables=input_variables,
-                callback_url=callback_url,
-                callback_secret=callback_secret,
-                callback_headers=callback_headers,
-                on_input_required=on_input_required,
-                critic_context=critic_context,
-                timeout=timeout,
-            )
-        else:
-            if dispatch_agent is not AgentKind.CORE_AGENT:
-                raise ValueError(
-                    "`reasoning` is only supported with `kind=AgentKind.CORE_AGENT` "
-                    f"(got kind={dispatch_agent!r})"
-                )
-            # The CORE_AGENT-specific overloads of `_dispatch_request` split on
-            # a narrower `output_schema` discriminator (None vs `type[T]`),
-            # which the impl's `type[BaseModel] | None` union doesn't cleanly
-            # narrow into without further branching. The public `run()`
-            # overloads above already give callers correct return-type
-            # narrowing, so the internal forward call bypasses overload
-            # disambiguation on this single dimension.
-            remote_dispatch_response = await self.environment._dispatch_request(  # pyright: ignore[reportCallIssue]
-                prompt=prompt,
-                agent=dispatch_agent,
-                reasoning=reasoning,
-                clear_chat=clear_chat,
-                generate_gif=generate_gif,
-                output_schema=output_schema,  # pyright: ignore[reportArgumentType]
-                previous_request_id=previous_request_id,
-                chat_history=chat_history,
-                additional_context=additional_context,
-                attachment=attachment,
-                time_zone=time_zone,
-                user_resource_credentials=user_resource_credentials,
-                mcp_servers=mcp_servers,
-                secret_variables=secret_variables,
-                input_variables=input_variables,
-                callback_url=callback_url,
-                callback_secret=callback_secret,
-                callback_headers=callback_headers,
-                on_input_required=on_input_required,
-                critic_context=critic_context,
-                timeout=timeout,
-            )
-        return remote_dispatch_response
+        return await self.environment._dispatch_request(
+            prompt=prompt,
+            agent=dispatch_agent,
+            reasoning=reasoning,
+            clear_chat=clear_chat,
+            generate_gif=generate_gif,
+            output_schema=output_schema,
+            previous_request_id=previous_request_id,
+            chat_history=chat_history,
+            additional_context=additional_context,
+            attachment=attachment,
+            time_zone=time_zone,
+            user_resource_credentials=user_resource_credentials,
+            mcp_servers=mcp_servers,
+            secret_variables=secret_variables,
+            input_variables=input_variables,
+            callback_url=callback_url,
+            callback_secret=callback_secret,
+            callback_headers=callback_headers,
+            on_input_required=on_input_required,
+            critic_context=critic_context,
+            timeout=timeout,
+        )
 
     def _browser_environment(self) -> BaseBrowserEnvironment:
         if not isinstance(self.environment, BaseBrowserEnvironment):

{narada-0.2.7 → narada-0.2.9}/src/narada/environment.py

@@ -840,67 +840,13 @@ class Environment(ABC):
             "mimeType": mime_type,
         }
 
-    # `reasoning` is only valid with the Core Agent; these two overloads make
-    # that constraint type-checkable. Generic-agent calls fall through to the
-    # general overloads below, which do not accept a `reasoning` argument.
-    @overload
-    async def _dispatch_request(
-        self,
-        *,
-        prompt: str,
-        agent: Literal[AgentKind.CORE_AGENT],
-        reasoning: ReasoningEffort | None = None,
-        clear_chat: bool | None = None,
-        generate_gif: bool | None = None,
-        output_schema: None = None,
-        previous_request_id: str | None = None,
-        chat_history: list[RemoteDispatchChatHistoryItem] | None = None,
-        additional_context: dict[str, str] | None = None,
-        attachment: File | IO[Any] | None = None,
-        time_zone: str = "America/Los_Angeles",
-        user_resource_credentials: UserResourceCredentials | None = None,
-        mcp_servers: list[McpServer] | None = None,
-        secret_variables: dict[str, str] | None = None,
-        input_variables: Mapping[str, Any] | None = None,
-        callback_url: str | None = None,
-        callback_secret: str | None = None,
-        callback_headers: Mapping[str, Any] | None = None,
-        on_input_required: InputRequiredCallback | None = None,
-        timeout: int = 1000,
-    ) -> Response[None]: ...
-
-    @overload
-    async def _dispatch_request(
-        self,
-        *,
-        prompt: str,
-        agent: Literal[AgentKind.CORE_AGENT],
-        reasoning: ReasoningEffort | None = None,
-        clear_chat: bool | None = None,
-        generate_gif: bool | None = None,
-        output_schema: type[_StructuredOutput],
-        previous_request_id: str | None = None,
-        chat_history: list[RemoteDispatchChatHistoryItem] | None = None,
-        additional_context: dict[str, str] | None = None,
-        attachment: File | IO[Any] | None = None,
-        time_zone: str = "America/Los_Angeles",
-        user_resource_credentials: UserResourceCredentials | None = None,
-        mcp_servers: list[McpServer] | None = None,
-        secret_variables: dict[str, str] | None = None,
-        input_variables: Mapping[str, Any] | None = None,
-        callback_url: str | None = None,
-        callback_secret: str | None = None,
-        callback_headers: Mapping[str, Any] | None = None,
-        on_input_required: InputRequiredCallback | None = None,
-        timeout: int = 1000,
-    ) -> Response[_StructuredOutput]: ...
-
     @overload
     async def _dispatch_request(
         self,
         *,
         prompt: str,
         agent: AgentKind | str = AgentKind.OPERATOR,
+        reasoning: ReasoningEffort | None = None,
         clear_chat: bool | None = None,
         generate_gif: bool | None = None,
         output_schema: None = None,
@@ -927,6 +873,7 @@ class Environment(ABC):
         *,
         prompt: str,
         agent: AgentKind | str = AgentKind.OPERATOR,
+        reasoning: ReasoningEffort | None = None,
         clear_chat: bool | None = None,
         generate_gif: bool | None = None,
         output_schema: type[_StructuredOutput],
@@ -978,14 +925,6 @@ class Environment(ABC):
         """
         await self._ensure_initialized()
 
-        # The overloads enforce this at type-check time when callers use
-        # ``AgentKind.CORE_AGENT``; the runtime check covers string-form agents
-        # (``agent="..."``) and callers without a type checker.
-        if reasoning is not None and agent is not AgentKind.CORE_AGENT:
-            raise ValueError(
-                "`reasoning` is only supported with `agent=AgentKind.CORE_AGENT` "
-                f"(got agent={agent!r})"
-            )
         deadline = time.monotonic() + timeout
 
         agent_prefix = (

narada-0.2.9/tests/test_action_trace.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import pytest
+from narada_core.tracing.model import OperatorActionTraceItem, parse_action_trace
+from pydantic import ValidationError
+
+
+def test_parse_operator_action_trace_exposes_timestamps() -> None:
+    trace = parse_action_trace(
+        [
+            {
+                "url": "https://example.com",
+                "action": "Clicked Submit",
+                "startTs": "2026-07-20T17:00:00.000Z",
+                "endTs": "2026-07-20T17:00:01.500Z",
+                "durationMs": 1_500,
+            }
+        ]
+    )
+
+    item = trace[0]
+    assert isinstance(item, OperatorActionTraceItem)
+    assert item.start_ts == "2026-07-20T17:00:00.000Z"
+    assert item.end_ts == "2026-07-20T17:00:01.500Z"
+    assert item.duration_ms == 1_500
+
+
+@pytest.mark.parametrize(
+    "timestamps",
+    [
+        {"startTs": "2026-07-20T17:00:00.000Z", "durationMs": 1_000},
+        {"endTs": "2026-07-20T17:00:01.000Z", "durationMs": 1_000},
+        {
+            "startTs": "2026-07-20T17:00:02.000Z",
+            "endTs": "2026-07-20T17:00:01.000Z",
+            "durationMs": 0,
+        },
+        {
+            "startTs": "not-a-timestamp",
+            "endTs": "2026-07-20T17:00:01.000Z",
+            "durationMs": 1_000,
+        },
+        {
+            "startTs": "2026-07-20T17:00:00",
+            "endTs": "2026-07-20T17:00:01",
+            "durationMs": 1_000,
+        },
+        {"startTs": 1_000, "endTs": 2_000, "durationMs": 1_000},
+        {
+            "startTs": "2026-07-20T17:00:00.000Z",
+            "endTs": "2026-07-20T17:00:01.000Z",
+        },
+        {
+            "startTs": "2026-07-20T17:00:00.000Z",
+            "endTs": "2026-07-20T17:00:01.000Z",
+            "durationMs": 999,
+        },
+    ],
+)
+def test_operator_action_trace_rejects_invalid_timing(
+    timestamps: dict[str, str | int],
+) -> None:
+    with pytest.raises(ValidationError):
+        OperatorActionTraceItem(
+            url="https://example.com",
+            action="Clicked Submit",
+            **timestamps,
+        )
+
+
+def test_operator_action_trace_accepts_explicit_utc_offset() -> None:
+    item = OperatorActionTraceItem(
+        url="https://example.com",
+        action="Clicked Submit",
+        startTs="2026-07-20T17:00:00.000+00:00",
+        endTs="2026-07-20T17:00:01.000+00:00",
+        durationMs=1_000,
+    )
+
+    assert item.start_ts.endswith("+00:00")

{narada-0.2.7 → narada-0.2.9}/tests/test_agent.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from typing import Any
 
 import pytest
-from narada import Agent, Environment
+from narada import Agent, AgentKind, Environment, ReasoningEffort
 
 
 class _FakeResponse:
@@ -100,6 +100,46 @@ async def test_agent_run_reruns_but_environment_initialization_is_cached(
         "/Operator first",
         "/Operator second",
     ]
+    assert all("reasoningMode" not in body for body in fake_session.dispatched_bodies)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("kind", "reasoning", "expected_prompt"),
+    [
+        (AgentKind.PRODUCTIVITY, ReasoningEffort.NONE, "analyze"),
+        (AgentKind.OPERATOR, ReasoningEffort.LOW, "/Operator analyze"),
+        (AgentKind.CORE_AGENT, ReasoningEffort.MEDIUM, "/coreAgent analyze"),
+    ],
+)
+async def test_agent_run_forwards_reasoning_for_every_agent_kind(
+    monkeypatch: pytest.MonkeyPatch,
+    kind: AgentKind | str,
+    reasoning: ReasoningEffort,
+    expected_prompt: str,
+) -> None:
+    import narada.environment as environment_module
+
+    fake_session = _RemoteDispatchFakeClientSession()
+    monkeypatch.setattr(
+        environment_module.aiohttp, "ClientSession", lambda: fake_session
+    )
+
+    await Agent(environment=_CountingEnvironment(), kind=kind).run(
+        "analyze",
+        reasoning=reasoning,
+    )
+
+    assert fake_session.dispatched_bodies[0]["prompt"] == expected_prompt
+    assert fake_session.dispatched_bodies[0]["reasoningMode"] == reasoning.value
+
+
+@pytest.mark.asyncio
+async def test_agent_run_rejects_top_level_reasoning_for_named_agent() -> None:
+    agent = Agent(environment=_CountingEnvironment(), kind="/owner/custom-agent")
+
+    with pytest.raises(ValueError, match="named Agent Studio agents"):
+        await agent.run("analyze", reasoning=ReasoningEffort.HIGH)
 
 
 @pytest.mark.asyncio