hud-python 0.4.1__py3-none-any.whl → 0.4.3__py3-none-any.whl

hud/types.py

@@ -1,136 +1,136 @@
-from __future__ import annotations
-
-import uuid
-from typing import Any, Literal
-
-from mcp.types import CallToolRequestParams, CallToolResult
-from pydantic import BaseModel, ConfigDict, Field
-
-
-class MCPToolCall(CallToolRequestParams):
-    """A tool call."""
-
-    id: str = Field(default_factory=lambda: str(uuid.uuid4()))  # Unique identifier for reference
-
-    def __str__(self) -> str:
-        response = f"Tool: {self.name}"
-        if self.arguments:
-            response += f"\nArguments: {self.arguments}"
-        return response
-
-
-class MCPToolResult(CallToolResult):
-    """A tool result."""
-
-    def __str__(self) -> str:
-        response = f"Content: {self.content}"
-        if self.structuredContent:
-            response += f"\nStructured Content: {self.structuredContent}"
-        if self.isError:
-            response += f"\nError: {self.isError}"
-        return response
-
-
-class AgentResponse(BaseModel):
-    """A model response in the conversation."""
-
-    # --- FUNCTIONAL ---
-    tool_calls: list[MCPToolCall] = Field(default_factory=list)
-    done: bool = Field(default=False)
-
-    # --- TELEMETRY [app.hud.so] ---
-    # Responses
-    content: str | None = Field(default=None)
-    reasoning: str | None = Field(default=None)
-    info: dict[str, Any] = Field(default_factory=dict)
-    isError: bool = Field(default=False)
-    raw: Any | None = Field(default=None)  # Include raw response for access to Choice objects
-
-    # Timestamps
-    start_timestamp: str | None = None
-    end_timestamp: str | None = None
-
-    def __str__(self) -> str:
-        response = ""
-        if self.reasoning:
-            response += f"Reasoning: {self.reasoning}\n"
-        if self.content:
-            response += f"Content: {self.content}\n"
-        if self.tool_calls:
-            response += f"""Tool Calls: {
-                ", ".join([f"{tc.name}: {tc.arguments}" for tc in self.tool_calls])
-            }"""
-        if self.raw:
-            response += f"Raw: {self.raw}"
-        return response
-
-
-class TraceStep(BaseModel):
-    """Canonical data for a single span (shared with telemetry)."""
-
-    # HUD identifiers
-    task_run_id: str | None = Field(default=None)
-    job_id: str | None = Field(default=None)
-
-    # Span category - can be any string, but "mcp" and "agent" are privileged on the platform
-    category: Literal["mcp", "agent"] | str = Field(default="mcp")  # noqa: PYI051
-
-    # Generic I/O fields - works for any category
-    request: Any | None = None
-    result: Any | None = None
-
-    # Generic span info
-    type: str = Field(default="CLIENT")
-
-    # Timestamps (optional, for local tracking)
-    start_timestamp: str | None = None
-    end_timestamp: str | None = None
-
-    model_config = ConfigDict(populate_by_name=True, extra="allow")
-
-
-class Trace(BaseModel):
-    """Unified result from agent execution (task or prompt).
-
-    Fields:
-    - done: Whether the run is complete
-    - reward: The reward for the run
-    - info: Additional metadata for the run
-    - content: The final content/response from the agent
-    - isError: Whether the execution resulted in an error
-    - trace: The steps taken in the run (empty if not tracing)
-    """
-
-    done: bool = Field(default=True)
-    reward: float = Field(default=0.0)
-    info: dict[str, Any] = Field(default_factory=dict)
-    content: str | None = Field(default=None)
-    isError: bool = Field(default=False)
-    trace: list[TraceStep] = Field(default_factory=list)
-
-    def append(self, step: TraceStep) -> None:
-        self.trace.append(step)
-
-    def populate_from_context(self) -> None:
-        """Populate trace steps from the current trace context if available.
-
-        This checks if we're executing within a hud.trace() context and
-        automatically populates the trace field with collected steps.
-        """
-        from hud.otel.context import get_current_task_run_id
-        from hud.telemetry.replay import get_trace
-
-        task_run_id = get_current_task_run_id()
-        if task_run_id:
-            collected_trace = get_trace(task_run_id)
-            if collected_trace:
-                self.trace = collected_trace.trace
-
-
-__all__ = [
-    "AgentResponse",
-    "MCPToolCall",
-    "MCPToolResult",
-    "Trace",
-    "TraceStep",
-]
+from __future__ import annotations
+
+import uuid
+from typing import Any, Literal
+
+from mcp.types import CallToolRequestParams, CallToolResult
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class MCPToolCall(CallToolRequestParams):
+    """A tool call."""
+
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))  # Unique identifier for reference
+
+    def __str__(self) -> str:
+        response = f"Tool: {self.name}"
+        if self.arguments:
+            response += f"\nArguments: {self.arguments}"
+        return response
+
+
+class MCPToolResult(CallToolResult):
+    """A tool result."""
+
+    def __str__(self) -> str:
+        response = f"Content: {self.content}"
+        if self.structuredContent:
+            response += f"\nStructured Content: {self.structuredContent}"
+        if self.isError:
+            response += f"\nError: {self.isError}"
+        return response
+
+
+class AgentResponse(BaseModel):
+    """A model response in the conversation."""
+
+    # --- FUNCTIONAL ---
+    tool_calls: list[MCPToolCall] = Field(default_factory=list)
+    done: bool = Field(default=False)
+
+    # --- TELEMETRY [app.hud.so] ---
+    # Responses
+    content: str | None = Field(default=None)
+    reasoning: str | None = Field(default=None)
+    info: dict[str, Any] = Field(default_factory=dict)
+    isError: bool = Field(default=False)
+    raw: Any | None = Field(default=None)  # Include raw response for access to Choice objects
+
+    # Timestamps
+    start_timestamp: str | None = None
+    end_timestamp: str | None = None
+
+    def __str__(self) -> str:
+        response = ""
+        if self.reasoning:
+            response += f"Reasoning: {self.reasoning}\n"
+        if self.content:
+            response += f"Content: {self.content}\n"
+        if self.tool_calls:
+            response += f"""Tool Calls: {
+                ", ".join([f"{tc.name}: {tc.arguments}" for tc in self.tool_calls])
+            }"""
+        if self.raw:
+            response += f"Raw: {self.raw}"
+        return response
+
+
+class TraceStep(BaseModel):
+    """Canonical data for a single span (shared with telemetry)."""
+
+    # HUD identifiers
+    task_run_id: str | None = Field(default=None)
+    job_id: str | None = Field(default=None)
+
+    # Span category - can be any string, but "mcp" and "agent" are privileged on the platform
+    category: Literal["mcp", "agent"] | str = Field(default="mcp")  # noqa: PYI051
+
+    # Generic I/O fields - works for any category
+    request: Any | None = None
+    result: Any | None = None
+
+    # Generic span info
+    type: str = Field(default="CLIENT")
+
+    # Timestamps (optional, for local tracking)
+    start_timestamp: str | None = None
+    end_timestamp: str | None = None
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class Trace(BaseModel):
+    """Unified result from agent execution (task or prompt).
+
+    Fields:
+    - done: Whether the run is complete
+    - reward: The reward for the run
+    - info: Additional metadata for the run
+    - content: The final content/response from the agent
+    - isError: Whether the execution resulted in an error
+    - trace: The steps taken in the run (empty if not tracing)
+    """
+
+    done: bool = Field(default=True)
+    reward: float = Field(default=0.0)
+    info: dict[str, Any] = Field(default_factory=dict)
+    content: str | None = Field(default=None)
+    isError: bool = Field(default=False)
+    trace: list[TraceStep] = Field(default_factory=list)
+
+    def append(self, step: TraceStep) -> None:
+        self.trace.append(step)
+
+    def populate_from_context(self) -> None:
+        """Populate trace steps from the current trace context if available.
+
+        This checks if we're executing within a hud.trace() context and
+        automatically populates the trace field with collected steps.
+        """
+        from hud.otel.context import get_current_task_run_id
+        from hud.telemetry.replay import get_trace
+
+        task_run_id = get_current_task_run_id()
+        if task_run_id:
+            collected_trace = get_trace(task_run_id)
+            if collected_trace:
+                self.trace = collected_trace.trace
+
+
+__all__ = [
+    "AgentResponse",
+    "MCPToolCall",
+    "MCPToolResult",
+    "Trace",
+    "TraceStep",
+]

hud/utils/__init__.py

@@ -1,10 +1,10 @@
-from __future__ import annotations
-
-from .design import HUDDesign, design
-from .telemetry import stream
-
-__all__ = [
-    "HUDDesign",
-    "design",
-    "stream",
-]
+from __future__ import annotations
+
+from .design import HUDDesign, design
+from .telemetry import stream
+
+__all__ = [
+    "HUDDesign",
+    "design",
+    "stream",
+]

hud/utils/async_utils.py

@@ -1,65 +1,65 @@
-"""Async utilities for HUD SDK.
-
-This module provides utilities for running async code in various environments,
-including Jupyter notebooks and synchronous contexts.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import logging
-import threading
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from collections.abc import Coroutine
-
-logger = logging.getLogger(__name__)
-
-
-def fire_and_forget(coro: Coroutine[Any, Any, Any], description: str = "task") -> None:
-    """Execute a coroutine in a fire-and-forget manner.
-
-    This function handles running async code in various contexts:
-    - When an event loop is already running (normal async context)
-    - When no event loop exists (sync context, some Jupyter setups)
-    - Gracefully handles interpreter shutdown
-
-    Args:
-        coro: The coroutine to execute
-        description: Description of the task for logging (e.g., "update job status")
-
-    Example:
-        fire_and_forget(
-            some_async_function(),
-            description="update status"
-        )
-    """
-    try:
-        # Try to get current event loop
-        loop = asyncio.get_running_loop()
-        # Schedule the coroutine
-        task = loop.create_task(coro)
-        # Add error handler to prevent unhandled exceptions
-        task.add_done_callback(lambda t: t.exception() if not t.cancelled() else None)
-    except RuntimeError:
-        # No running event loop (e.g., Jupyter without %autoawait, sync context)
-        try:
-            # Try to run in a thread as a fallback
-            def run_in_thread() -> None:
-                loop = asyncio.new_event_loop()
-                asyncio.set_event_loop(loop)
-                try:
-                    loop.run_until_complete(coro)
-                except Exception as e:
-                    # Suppress warnings about interpreter shutdown
-                    if "interpreter shutdown" not in str(e):
-                        logger.debug("Error in threaded %s: %s", description, e)
-
-            thread = threading.Thread(target=run_in_thread, daemon=True)
-            thread.start()
-        except Exception as e:
-            # If that fails too, just log and continue
-            # Special case: suppress "cannot schedule new futures after interpreter shutdown"
-            if "interpreter shutdown" not in str(e):
-                logger.debug("Could not %s - no event loop available: %s", description, e)
+"""Async utilities for HUD SDK.
+
+This module provides utilities for running async code in various environments,
+including Jupyter notebooks and synchronous contexts.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Coroutine
+
+logger = logging.getLogger(__name__)
+
+
+def fire_and_forget(coro: Coroutine[Any, Any, Any], description: str = "task") -> None:
+    """Execute a coroutine in a fire-and-forget manner.
+
+    This function handles running async code in various contexts:
+    - When an event loop is already running (normal async context)
+    - When no event loop exists (sync context, some Jupyter setups)
+    - Gracefully handles interpreter shutdown
+
+    Args:
+        coro: The coroutine to execute
+        description: Description of the task for logging (e.g., "update job status")
+
+    Example:
+        fire_and_forget(
+            some_async_function(),
+            description="update status"
+        )
+    """
+    try:
+        # Try to get current event loop
+        loop = asyncio.get_running_loop()
+        # Schedule the coroutine
+        task = loop.create_task(coro)
+        # Add error handler to prevent unhandled exceptions
+        task.add_done_callback(lambda t: t.exception() if not t.cancelled() else None)
+    except RuntimeError:
+        # No running event loop (e.g., Jupyter without %autoawait, sync context)
+        try:
+            # Try to run in a thread as a fallback
+            def run_in_thread() -> None:
+                loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(loop)
+                try:
+                    loop.run_until_complete(coro)
+                except Exception as e:
+                    # Suppress warnings about interpreter shutdown
+                    if "interpreter shutdown" not in str(e):
+                        logger.debug("Error in threaded %s: %s", description, e)
+
+            thread = threading.Thread(target=run_in_thread, daemon=True)
+            thread.start()
+        except Exception as e:
+            # If that fails too, just log and continue
+            # Special case: suppress "cannot schedule new futures after interpreter shutdown"
+            if "interpreter shutdown" not in str(e):
+                logger.debug("Could not %s - no event loop available: %s", description, e)