projectdavid 1.29.9__py3-none-any.whl → 1.38.1__py3-none-any.whl

projectdavid/clients/runs.py

@@ -1,13 +1,13 @@
+#!!Python
 import json
 import threading
 import time
-from enum import Enum
 from typing import Any, Callable, Dict, List, Optional
 
 import httpx
 import requests
 from projectdavid_common import UtilsInterface, ValidationInterface
-from projectdavid_common.validation import StatusEnum
+from projectdavid_common.validation import StatusEnum, TruncationStrategy
 from pydantic import ValidationError
 from sseclient import SSEClient
 
@@ -43,62 +43,73 @@ class RunsClient(BaseAPIClient):
         thread_id: str,
         instructions: str = "",
         meta_data: Optional[Dict[str, Any]] = None,
+        *,
+        # new optional knobs; keep backwards compatible
+        model: Optional[str] = None,
+        response_format: str = "text",
+        tool_choice: Optional[str] = None,  # allow None in signature, fix below
+        temperature: float = 1.0,
+        top_p: float = 1.0,
+        # ↓ NEW: optional; only sent if provided
+        truncation_strategy: Optional[ent_validator.TruncationStrategy] = None,
     ) -> ent_validator.Run:
         """
-        Create a run. The server expects user_id to be injected explicitly,
-        which is passed in from the authenticated API key.
-
-        Returns a fully‑populated Run model (read schema).
+        Create a run. The server injects user_id from the API key.
+        We normalize all timestamp fields to epoch ints (or None).
         """
-        if meta_data is None:
-            meta_data = {}
+        # ── Coerce client-friendly Nones into schema-acceptable values ─────────
+        meta_data = meta_data or {}  # schema expects Dict
+        tool_choice = tool_choice or "none"  # schema expects str
+        model = model or "gpt-4"  # defer to schema default or override at callsite
+
+        now = int(time.time())
 
-        # Construct the RunCreate payload, including user_id
         run_payload = ent_validator.RunCreate(
             id=UtilsInterface.IdentifierService.generate_run_id(),
-            user_id=None,
+            user_id=None,  # server fills this
             assistant_id=assistant_id,
             thread_id=thread_id,
             instructions=instructions,
             meta_data=meta_data,
             cancelled_at=None,
             completed_at=None,
-            created_at=int(time.time()),
-            expires_at=int(time.time()) + 3600,
+            created_at=now,
+            expires_at=now + 3600,
             failed_at=None,
             incomplete_details=None,
             last_error=None,
             max_completion_tokens=1000,
             max_prompt_tokens=500,
-            model="llama3.1",
+            model=model,
             object="run",
             parallel_tool_calls=False,
             required_action=None,
-            response_format="text",
+            response_format=response_format,
             started_at=None,
-            status=StatusEnum.queued,
-            tool_choice="none",
+            status=ent_validator.RunStatus.pending,
+            tool_choice=tool_choice,
             tools=[],
-            truncation_strategy={},
             usage=None,
-            temperature=0.7,
-            top_p=0.9,
+            temperature=temperature,
+            top_p=top_p,
             tool_resources={},
+            # Directly pass the truncation_strategy. It will be None if not provided.
+            truncation_strategy=truncation_strategy,
         )
 
         logging_utility.info(
-            "Creating run for assistant_id=%s, thread_id=%s",
-            assistant_id,
-            thread_id,
+            "Creating run for assistant_id=%s, thread_id=%s", assistant_id, thread_id
         )
-
         logging_utility.debug("Run payload: %s", run_payload.model_dump())
 
         try:
-            resp = self.client.post("/v1/runs", json=run_payload.model_dump())
-            resp.raise_for_status()
+            # Build dict from the Pydantic model. `exclude_none=True` will
+            # automatically omit `truncation_strategy` if it is None, allowing
+            # the server-side database default to apply.
+            payload_dict = run_payload.model_dump(exclude_none=True)
 
-            # Validate response with the *read* schema
+            resp = self.client.post("/v1/runs", json=payload_dict)
+            resp.raise_for_status()
             run_out = ent_validator.Run(**resp.json())
             logging_utility.info("Run created successfully: %s", run_out.id)
             return run_out
@@ -190,36 +201,6 @@ class RunsClient(BaseAPIClient):
             )
             raise
 
-    def list_runs(self, limit: int = 20, order: str = "asc") -> List[ent_validator.Run]:
-        """
-        List runs with the given limit and order.
-
-        Args:
-            limit (int): Maximum number of runs to retrieve.
-            order (str): 'asc' or 'desc' for ordering.
-
-        Returns:
-            List[Run]: A list of runs.
-        """
-        logging_utility.info("Listing runs with limit: %d, order: %s", limit, order)
-        params = {"limit": limit, "order": order}
-        try:
-            response = self.client.get("/v1/runs", params=params)
-            response.raise_for_status()
-            runs = response.json()
-            validated_runs = [ent_validator.Run(**run) for run in runs]
-            logging_utility.info("Retrieved %d runs", len(validated_runs))
-            return validated_runs
-        except ValidationError as e:
-            logging_utility.error("Validation error: %s", e.json())
-            raise ValueError(f"Validation error: {e}")
-        except httpx.HTTPStatusError as e:
-            logging_utility.error("HTTP error occurred while listing runs: %s", str(e))
-            raise
-        except Exception as e:
-            logging_utility.error("An error occurred while listing runs: %s", str(e))
-            raise
-
     def delete_run(self, run_id: str) -> Dict[str, Any]:
         """
         Delete a run by its ID.
@@ -366,36 +347,17 @@ class RunsClient(BaseAPIClient):
     def poll_and_execute_action(
         self,
         run_id: str,
-        thread_id: str,  # Needed for submit_tool_output
-        assistant_id: str,  # Needed for submit_tool_output
-        # *** Accept the consumer's handler function ***
+        thread_id: str,
+        assistant_id: str,
         tool_executor: Callable[[str, Dict[str, Any]], str],
-        # *** Accept SDK sub-clients or main client ***
-        actions_client: Any,  # Instance of ActionsClient
-        messages_client: Any,  # Instance of MessagesClient
+        actions_client: Any,
+        messages_client: Any,
         timeout: float = 60.0,
         interval: float = 1.0,
     ) -> bool:
         """
-        Polls for a required action, executes it using the provided executor,
-        submits the result, and updates run status. This is a BLOCKING call.
-
-        Args:
-            run_id (str): The ID of the run to monitor and handle.
-            thread_id (str): The ID of the thread the run belongs to.
-            assistant_id (str): The ID of the assistant for the run.
-            tool_executor (Callable): A function provided by the consumer that takes
-                                      (tool_name: str, arguments: dict) and returns
-                                      a string result.
-            actions_client (Any): An initialized instance of the ActionsClient.
-            messages_client (Any): An initialized instance of the MessagesClient.
-            timeout (float): Maximum time to wait for an action in seconds.
-            interval (float): Time between polling attempts in seconds.
-
-        Returns:
-            bool: True if an action was successfully found, executed, and submitted.
-                  False if timeout occurred, the run reached a terminal state first,
-                  or an error prevented successful handling.
+        Polls for a required action, executes it, and explicitly updates
+        the Action state to 'completed' or 'failed'.
         """
         if timeout <= 0 or interval <= 0:
             raise ValueError("Timeout and interval must be positive numbers.")
@@ -404,183 +366,123 @@ class RunsClient(BaseAPIClient):
 
         start_time = time.time()
         action_handled_successfully = False
-        logging_utility.info(
-            f"[SDK Helper] Waiting for action on run {run_id} (timeout: {timeout}s)..."
-        )
+        logging_utility.info(f"[SDK Helper] Monitoring run {run_id} for actions...")
 
-        # Define terminal states using the exact string values from your StatusEnum
-        terminal_states = {
+        terminal_run_states = {
             StatusEnum.completed.value,
             StatusEnum.failed.value,
             StatusEnum.cancelled.value,
             StatusEnum.expired.value,
         }
-        transient_states = {
-            StatusEnum.queued.value,
-            StatusEnum.in_progress.value,
-            StatusEnum.processing.value,
-            StatusEnum.cancelling.value,
-            StatusEnum.pending.value,
-            StatusEnum.retrying.value,
-        }
-        target_state = StatusEnum.pending_action.value
+
+        target_run_state = StatusEnum.pending_action.value
 
         while (time.time() - start_time) < timeout:
             action_to_handle = None
-            current_status_str = None
 
-            # --- Check Run Status First ---
             try:
-                current_run = self.retrieve_run(run_id)  # Use self.retrieve_run
-                if isinstance(current_run.status, Enum):
-                    current_status_str = current_run.status.value
-                else:
-                    current_status_str = str(current_run.status)
-
-                logging_utility.debug(
-                    f"[SDK Helper] Polling run {run_id}: Status='{current_status_str}'"
+                # 1. Check Run Status
+                current_run = self.retrieve_run(run_id)
+                status_str = (
+                    current_run.status.value
+                    if hasattr(current_run.status, "value")
+                    else str(current_run.status)
                 )
 
-                if current_status_str == target_state:
-                    # Action required, now get action details
+                if status_str in terminal_run_states:
                     logging_utility.info(
-                        f"[SDK Helper] Run {run_id} requires action. Fetching details..."
+                        f"[SDK Helper] Run {run_id} terminated externally ({status_str})."
                     )
-                    try:
-                        # Use the passed-in actions_client
-                        pending_actions = actions_client.get_pending_actions(
-                            run_id=run_id
-                        )
-                        if pending_actions:
-                            action_to_handle = pending_actions[0]
-                        else:
-                            logging_utility.warning(
-                                f"[SDK Helper] Run {run_id} is '{target_state}' but no pending actions found via API."
-                            )
-                            # Maybe the status changed again quickly? Loop will re-check status.
-                    except Exception as e:
-                        logging_utility.error(
-                            f"[SDK Helper] Error fetching pending actions for run {run_id}: {e}",
-                            exc_info=True,
+                    return False
+
+                if status_str == target_run_state:
+                    # 2. Get the specific Action details
+                    pending_actions = actions_client.get_pending_actions(run_id=run_id)
+                    if pending_actions:
+                        action_to_handle = pending_actions[0]
+                    else:
+                        logging_utility.warning(
+                            f"[SDK Helper] Run is {target_run_state} but no actions found."
                         )
-                        # Consider stopping if we can't get action details
-                        return False  # Stop if error getting action details
-                elif current_status_str in terminal_states:
-                    logging_utility.info(
-                        f"[SDK Helper] Run {run_id} reached terminal state '{current_status_str}'. Stopping wait."
-                    )
-                    return False  # Stop if run finished/failed
-                elif current_status_str not in transient_states:
-                    logging_utility.warning(
-                        f"[SDK Helper] Run {run_id} in unexpected state '{current_status_str}'. Stopping wait."
-                    )
-                    return False  # Stop on unexpected states
 
-            except httpx.HTTPStatusError as e:
-                if e.response.status_code == 404:
-                    raise  # Re-raise 404 immediately
-                logging_utility.error(
-                    f"[SDK Helper] HTTP error {e.response.status_code} retrieving run {run_id} status: {e.response.text}. Stopping wait."
-                )
-                return False  # Stop on other HTTP errors
             except Exception as e:
-                logging_utility.error(
-                    f"[SDK Helper] Error retrieving run {run_id} status: {e}",
-                    exc_info=True,
-                )
-                return False  # Stop on other errors retrieving status
+                logging_utility.error(f"[SDK Helper] Error polling run status: {e}")
+                return False
 
-            # --- Process Action if Found ---
+            # 3. Process the Action if found
             if action_to_handle:
                 action_id = action_to_handle.get("action_id")
                 tool_name = action_to_handle.get("tool_name")
                 arguments = action_to_handle.get("function_arguments")
 
-                if not action_id or not tool_name:
-                    logging_utility.error(
-                        f"[SDK Helper] Invalid action data found for run {run_id}: {action_to_handle}"
-                    )
-                    # Continue loop to re-fetch status/actions? Or fail? Let's fail for now.
-                    return False
-
                 logging_utility.info(
-                    f"[SDK Helper] Processing action {action_id} (Tool: '{tool_name}') for run {run_id}..."
+                    f"[SDK Helper] Executing Tool: '{tool_name}' (ID: {action_id})"
                 )
+
                 try:
-                    # --- Call Consumer's Executor ---
-                    logging_utility.debug(
-                        f"[SDK Helper] Calling provided tool_executor for '{tool_name}'..."
+                    # --- Step A: Mark Action as Processing ---
+                    # This signals the UI and prevents other workers from picking it up
+                    actions_client.update_action(
+                        action_id, status=StatusEnum.processing.value
                     )
-                    tool_result_content = tool_executor(tool_name, arguments)
-                    if not isinstance(tool_result_content, str):
-                        logging_utility.warning(
-                            f"[SDK Helper] tool_executor for '{tool_name}' did not return a string. Attempting json.dumps."
-                        )
-                        try:
-                            tool_result_content = json.dumps(tool_result_content)
-                        except Exception:
-                            logging_utility.error(
-                                f"[SDK Helper] Failed to convert tool_executor result to JSON string."
-                            )
-                            raise TypeError(
-                                "Tool executor must return a string or JSON-serializable object."
-                            )
-                    logging_utility.info(
-                        f"[SDK Helper] tool_executor for '{tool_name}' completed."
-                    )
-                    # --- End Consumer's Executor ---
 
-                    # --- Submit Tool Output ---
-                    logging_utility.debug(
-                        f"[SDK Helper] Submitting output for action {action_id}..."
-                    )
-                    # Use the passed-in messages_client
+                    # --- Step B: Execute the Tool ---
+                    result_content = tool_executor(tool_name, arguments)
+
+                    if not isinstance(result_content, str):
+                        result_content = json.dumps(result_content)
+
+                    # --- Step C: Submit Success ---
+                    # Our backend 'submit_tool_output' now marks the action 'completed' automatically
                     messages_client.submit_tool_output(
                         thread_id=thread_id,
                         tool_id=action_id,
-                        content=tool_result_content,
+                        content=result_content,
                         role="tool",
                         assistant_id=assistant_id,
                     )
                     logging_utility.info(
-                        f"[SDK Helper] Output submitted successfully for action {action_id}."
+                        f"[SDK Helper] Action {action_id} completed successfully."
                     )
-                    # --- End Submit ---
-
-                    # --- Optional: Update Run Status ---
-                    # Backend might do this automatically, but updating here ensures client knows
-                    # try:
-                    #      self.update_run_status(run_id=run_id, new_status=StatusEnum.processing.value)
-                    #      logging_utility.info(f"[SDK Helper] Run {run_id} status updated to '{StatusEnum.processing.value}'.")
-                    # except Exception as e:
-                    #      logging_utility.warning(f"[SDK Helper] Failed to update run status after submitting output for {action_id}: {e}")
-                    # --- End Optional Status Update ---
-
                     action_handled_successfully = True
-                    break  # Exit the while loop successfully
+                    break
 
-                except Exception as e:
+                except Exception as tool_exc:
+                    # --- Step D: Submit Failure ---
+                    # IMPORTANT: We must submit the error so the backend stops polling
+                    # and the AI can potentially see what went wrong.
                     logging_utility.error(
-                        f"[SDK Helper] Error during execution or submission for action {action_id} (Run {run_id}): {e}",
-                        exc_info=True,
+                        f"[SDK Helper] Tool execution failed: {tool_exc}"
                     )
-                    # Should we update action/run to failed? Depends on API design.
-                    # For now, just break the loop and return False.
+
+                    error_payload = json.dumps(
+                        {"error": "ToolExecutionError", "message": str(tool_exc)}
+                    )
+
+                    try:
+                        # Passing is_error=True (if supported) or just the payload
+                        # The backend 'submit_tool_output' will mark the action 'failed'
+                        messages_client.submit_tool_output(
+                            thread_id=thread_id,
+                            tool_id=action_id,
+                            content=error_payload,
+                            role="tool",
+                            assistant_id=assistant_id,
+                        )
+                    except Exception as submit_exc:
+                        logging_utility.error(
+                            f"[SDK Helper] Critical: Failed to report tool error: {submit_exc}"
+                        )
+
                     action_handled_successfully = False
                     break
 
-            # If no action to handle yet and not in terminal/error state, sleep.
-            if not action_to_handle:
-                time.sleep(interval)
-        # --- End While Loop ---
+            time.sleep(interval)
 
+        # 4. Handle Timeout
         if not action_handled_successfully and (time.time() - start_time) >= timeout:
             logging_utility.warning(
-                f"[SDK Helper] Timeout reached waiting for action on run {run_id}."
-            )
-        elif not action_handled_successfully:
-            logging_utility.info(
-                f"[SDK Helper] Exited wait loop for run {run_id} without handling action (likely due to error or terminal state reached)."
+                f"[SDK Helper] Timeout waiting for action on run {run_id}."
             )
 
         return action_handled_successfully
@@ -637,3 +539,46 @@ class RunsClient(BaseAPIClient):
         t = threading.Thread(target=_listen_and_handle, daemon=True)
         t.start()
         t.join()
+
+    # ------------------------------------------------------------
+    # List all runs by thread_id
+    # ------------------------------------------------------------
+    def list_runs(
+        self, thread_id: str, limit: int = 20, order: str = "asc"
+    ) -> ent_validator.RunListResponse:
+        params = {"limit": limit, "order": order if order in ("asc", "desc") else "asc"}
+        resp = self.client.get(f"/v1/threads/{thread_id}/runs", params=params)
+        resp.raise_for_status()
+        payload = resp.json()
+        if isinstance(payload, dict) and "data" in payload:
+            return ent_validator.RunListResponse(**payload)
+        runs = [ent_validator.Run(**item) for item in payload]
+        return ent_validator.RunListResponse(
+            object="list",
+            data=runs,
+            first_id=runs[0].id if runs else None,
+            last_id=runs[-1].id if runs else None,
+            has_more=False,
+        )
+
+    # ------------------------------------------------------------
+    # List all runs by user
+    # ------------------------------------------------------------
+    def list_all_runs(
+        self, limit: int = 20, order: str = "asc"
+    ) -> ent_validator.RunListResponse:
+        params = {"limit": limit, "order": order if order in ("asc", "desc") else "asc"}
+        resp = self.client.get("/v1/runs", params=params)
+        resp.raise_for_status()
+        payload = resp.json()
+        if isinstance(payload, dict) and "data" in payload:
+            return ent_validator.RunListResponse(**payload)
+        # legacy fallback: wrap raw list
+        runs = [ent_validator.Run(**item) for item in payload]
+        return ent_validator.RunListResponse(
+            object="list",
+            data=runs,
+            first_id=runs[0].id if runs else None,
+            last_id=runs[-1].id if runs else None,
+            has_more=False,
+        )

projectdavid/clients/synchronous_inference_wrapper.py

@@ -1,16 +1,24 @@
+# src/projectdavid/clients/synchronous_inference_wrapper.py
 import asyncio
 from contextlib import suppress
 from typing import Generator, Optional
 
 from projectdavid_common import UtilsInterface
 
-logging_utility = UtilsInterface.LoggingUtility()
+# StreamRefiner removed as categorization is now handled at the provider level
+LOG = UtilsInterface.LoggingUtility()
 
 
 class SynchronousInferenceStream:
+    # ------------------------------------------------------------ #
+    #   GLOBAL EVENT LOOP  (single hidden thread for sync wrapper)
+    # ------------------------------------------------------------ #
     _GLOBAL_LOOP = asyncio.new_event_loop()
     asyncio.set_event_loop(_GLOBAL_LOOP)
 
+    # ------------------------------------------------------------ #
+    #   Init / setup
+    # ------------------------------------------------------------ #
     def __init__(self, inference) -> None:
         self.inference_client = inference
         self.user_id: Optional[str] = None
@@ -29,6 +37,7 @@ class SynchronousInferenceStream:
         run_id: str,
         api_key: str,
     ) -> None:
+        """Populate IDs once, so callers only provide provider/model."""
         self.user_id = user_id
         self.thread_id = thread_id
         self.assistant_id = assistant_id
@@ -36,31 +45,31 @@ class SynchronousInferenceStream:
         self.run_id = run_id
         self.api_key = api_key
 
+    # ------------------------------------------------------------ #
+    #   Core sync-to-async streaming wrapper
+    # ------------------------------------------------------------ #
     def stream_chunks(
         self,
         provider: str,
         model: str,
-        *,  # Following parameters are keyword-only.
+        *,
         api_key: Optional[str] = None,
         timeout_per_chunk: float = 280.0,
+        suppress_fc: bool = True,  # Note: Now primarily a hint for the consumer
     ) -> Generator[dict, None, None]:
         """
-        Streams inference response chunks synchronously by wrapping an async generator.
+        Sync generator that mirrors async `inference_client.stream_inference_response`.
 
-        Args:
-            provider (str): The provider name.
-            model (str): The model name.
-            api_key (Optional[str]): API key for authentication. If not provided, falls back to the value from setup().
-            timeout_per_chunk (float): Timeout per chunk in seconds.
-
-        Yields:
-            dict: A chunk of the inference response.
+        Refined Logic:
+        We no longer use string-based Refiners. Chunks are now typed at the source
+        (e.g., 'content', 'call_arguments', 'reasoning', 'hot_code').
+        The consumer handles visibility based on these types.
         """
-        # Prefer direct input over self.api_key
+
         resolved_api_key = api_key or self.api_key
 
-        async def _stream_chunks_async() -> Generator[dict, None, None]:
-            async for chunk in self.inference_client.stream_inference_response(
+        async def _stream_chunks_async():
+            async for chk in self.inference_client.stream_inference_response(
                 provider=provider,
                 model=model,
                 api_key=resolved_api_key,
@@ -69,30 +78,49 @@ class SynchronousInferenceStream:
                 run_id=self.run_id,
                 assistant_id=self.assistant_id,
             ):
-                yield chunk
+                yield chk
 
-        gen = _stream_chunks_async().__aiter__()
+        agen = _stream_chunks_async().__aiter__()
+
+        LOG.debug("[SyncStream] Starting typed stream (Unified Orchestration Mode)")
 
         while True:
             try:
                 chunk = self._GLOBAL_LOOP.run_until_complete(
-                    asyncio.wait_for(gen.__anext__(), timeout=timeout_per_chunk)
+                    asyncio.wait_for(agen.__anext__(), timeout=timeout_per_chunk)
                 )
+
+                # Always attach run_id for front-end helpers
+                chunk["run_id"] = self.run_id
+
+                # In the new typed architecture, we yield everything.
+                # If the provider is doing its job, 'call_arguments' are already
+                # separated from 'content'.
+
+                # Logic check: If for some reason we still want the SDK to enforce
+                # suppression of tool-call arguments, we can do it via the type key.
+                if suppress_fc and chunk.get("type") == "call_arguments":
+                    continue
+
                 yield chunk
+
             except StopAsyncIteration:
-                logging_utility.info("Stream completed normally.")
+                LOG.info("[SyncStream] Stream completed normally.")
                 break
+
             except asyncio.TimeoutError:
-                logging_utility.error(
-                    "[TimeoutError] Timeout occurred, stopping stream."
-                )
+                LOG.error("[SyncStream] Timeout waiting for next chunk.")
                 break
-            except Exception as e:
-                logging_utility.error(
-                    "Unexpected error during streaming completions: %s", e
+
+            except Exception as exc:
+                LOG.error(
+                    "[SyncStream] Unexpected streaming error: %s", exc, exc_info=True
                 )
                 break
 
+    # ------------------------------------------------------------ #
+    #   House-keeping
+    # ------------------------------------------------------------ #
     @classmethod
     def shutdown_loop(cls) -> None:
         if cls._GLOBAL_LOOP and not cls._GLOBAL_LOOP.is_closed():