fastworkflow 2.18.3__tar.gz → 2.19.0__tar.gz

{fastworkflow-2.18.3 → fastworkflow-2.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastworkflow
-Version: 2.18.3
+Version: 2.19.0
 Summary: A framework for rapidly building large-scale, deterministic, interactive workflows with a fault-tolerant, conversational UX
 License: Apache-2.0
 Keywords: fastworkflow,ai,workflow,llm,openai

{fastworkflow-2.18.3 → fastworkflow-2.19.0}/fastworkflow/__init__.py

@@ -224,3 +224,13 @@ def get_workflow_id(workflow_id_str: str) -> int:
 
 from .workflow import Workflow as Workflow
 from .chat_session import ChatSession as ChatSession
+from .active_workflow import (
+    get_active_workflow,
+    push_active_workflow,
+    pop_active_workflow,
+    clear_workflow_stack,
+)
+from .workflow_execution_context import (
+    WorkflowExecutionContext,
+    CommandCancelledError,
+)

fastworkflow-2.19.0/fastworkflow/active_workflow.py

@@ -0,0 +1,52 @@
+"""
+Context-scoped active workflow stack (per OS thread / asyncio task).
+
+Replaces the per-ChatSession deque for resolving the current app workflow during
+command execution and child-workflow nesting.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import Optional
+
+import fastworkflow
+from fastworkflow.utils.logging import logger
+
+# Immutable tuple used as a stack; each push/pop replaces the ContextVar value.
+_workflow_stack_var: ContextVar[tuple[fastworkflow.Workflow, ...]] = ContextVar(
+    "active_workflow_stack",
+    default=(),
+)
+
+
+def get_active_workflow() -> Optional[fastworkflow.Workflow]:
+    """Get the currently active workflow (top of stack)."""
+    stack = _workflow_stack_var.get()
+    return stack[-1] if stack else None
+
+
+def push_active_workflow(workflow: fastworkflow.Workflow) -> None:
+    """Push a workflow onto the context-local stack."""
+    stack = _workflow_stack_var.get()
+    new_stack = stack + (workflow,)
+    _workflow_stack_var.set(new_stack)
+    logger.debug(f"Workflow stack: {[w.id for w in new_stack]}")
+
+
+def pop_active_workflow() -> Optional[fastworkflow.Workflow]:
+    """Pop a workflow from the context-local stack."""
+    stack = _workflow_stack_var.get()
+    if not stack:
+        return None
+    workflow = stack[-1]
+    new_stack = stack[:-1]
+    _workflow_stack_var.set(new_stack)
+    logger.debug(f"Workflow stack after pop: {[w.id for w in new_stack]}")
+    return workflow
+
+
+def clear_workflow_stack() -> None:
+    """Clear the entire workflow stack for this context."""
+    _workflow_stack_var.set(())
+    logger.debug("Workflow stack cleared")

fastworkflow-2.19.0/fastworkflow/chat_session.py

@@ -0,0 +1,546 @@
+from enum import Enum
+from queue import Empty, Queue
+from threading import Thread
+from typing import Optional
+import contextlib
+from pathlib import Path
+import os
+import time
+
+import dspy
+from dspy.clients import litellm
+
+import fastworkflow
+from fastworkflow import active_workflow
+from fastworkflow.workflow_execution_context import WorkflowExecutionContext
+from fastworkflow.utils.logging import logger
+from fastworkflow.model_pipeline_training import CommandRouter
+from fastworkflow.utils.startup_progress import StartupProgress
+
+
+class SessionStatus(Enum):
+    STARTING = "STARTING"
+    RUNNING = "RUNNING"
+    STOPPING = "STOPPING"
+    STOPPED = "STOPPED"
+
+class ChatWorker(Thread):
+    def __init__(self, chat_session: "ChatSession"):
+        super().__init__()
+        self.chat_session = chat_session
+        self.daemon = True
+        
+    def run(self):
+        """Process messages for the root workflow"""
+        try:
+            self.chat_session._status = SessionStatus.RUNNING
+            workflow = self.chat_session._current_workflow
+            if workflow:
+                logger.debug(f"Started root workflow {workflow.id}")
+            
+            # Run the workflow loop
+            self.chat_session._run_workflow_loop()
+            
+        finally:
+            self.chat_session._status = SessionStatus.STOPPED
+            # Ensure workflow is popped if thread terminates unexpectedly
+            if self.chat_session.get_active_workflow() is not None:
+                self.chat_session.pop_active_workflow()
+
+class ChatSession:
+    def get_active_workflow(self) -> Optional[fastworkflow.Workflow]:
+        """Get the currently active workflow.
+
+        Returns the top of the context-local stack when set (e.g. during a
+        message turn or explicit push); otherwise falls back to the bound app
+        workflow so callers on other threads see the session's workflow.
+        """
+        workflow = active_workflow.get_active_workflow()
+        if workflow is not None:
+            return workflow
+        return self._core.app_workflow if self._core else None
+
+    def push_active_workflow(self, workflow: fastworkflow.Workflow) -> None:
+        """Push a workflow onto the context-local stack."""
+        active_workflow.push_active_workflow(workflow)
+
+    def pop_active_workflow(self) -> Optional[fastworkflow.Workflow]:
+        """Pop a workflow from the context-local stack."""
+        return active_workflow.pop_active_workflow()
+
+    def clear_workflow_stack(self) -> None:
+        """Clear the entire workflow stack for this context."""
+        active_workflow.clear_workflow_stack()
+
+    def stop_workflow(self) -> None:
+        """
+        Stop the current workflow and clear the workflow stack.
+        This method is called when starting a new root workflow to ensure
+        the previous workflow is properly stopped and resources are cleaned up.
+        """
+        # Set status to stopping to signal the workflow loop to exit
+        self._status = SessionStatus.STOPPING
+        
+        # Wait for the chat worker thread to finish if it exists
+        if self._chat_worker and self._chat_worker.is_alive():
+            self._chat_worker.join(timeout=5.0)  # Wait up to 5 seconds
+            if self._chat_worker.is_alive():
+                logger.warning("Chat worker thread did not terminate within timeout")
+        
+        # Clear the workflow stack
+        self.clear_workflow_stack()
+        
+        # Reset status to stopped
+        self._status = SessionStatus.STOPPED
+        
+        # Clear current workflow reference
+        self._current_workflow = None
+        
+        logger.debug("Workflow stopped and workflow stack cleared")
+
+    def __init__(
+        self,
+        run_as_agent: bool = False,
+        ask_user_timeout: Optional[float] = None,
+    ):
+        """
+        Initialize a chat session.
+        
+        Args:
+            run_as_agent: If True, use agent mode (DSPy-based tool selection).
+                         If False (default), use traditional command execution.
+            ask_user_timeout: Topology B (suspend/resume) safety net only; it has
+                              NO effect here. ChatSession is Topology A (blocking
+                              CLI worker) and always waits for the human on
+                              ask_user. Kept for API compatibility with the core.
+        
+        A chat session can run multiple workflows that share the same message queues.
+        Use start_workflow() to start a specific workflow within this session.
+        """
+        self._core = WorkflowExecutionContext(
+            run_as_agent=run_as_agent,
+            ask_user_timeout=ask_user_timeout,
+        )
+
+        # Create queues for user messages and command outputs (CLI transport)
+        self._user_message_queue = Queue()
+        self._command_output_queue = Queue()
+        self._command_trace_queue = Queue()
+        self._core.set_transport_queues(
+            user_message_queue=self._user_message_queue,
+            command_output_queue=self._command_output_queue,
+            command_trace_queue=self._command_trace_queue,
+        )
+
+        self._status = SessionStatus.STOPPED
+        self._chat_worker = None
+        self._current_workflow = None
+        self._keep_alive = False
+
+        from fastworkflow.command_executor import CommandExecutor
+        self._CommandExecutor = CommandExecutor
+
+        # this intializes the conversation traces file name also
+        # which is necessary when starting a brand new chat session
+        self.clear_conversation_history()
+
+    def start_workflow(self,
+        workflow_folderpath: str, 
+        workflow_id_str: Optional[str] = None, 
+        parent_workflow_id: Optional[int] = None, 
+        workflow_context: dict = None, 
+        startup_command: str = "", 
+        startup_action: Optional[fastworkflow.Action] = None, 
+        keep_alive: bool = False,
+        project_folderpath: Optional[str] = None
+        ) -> Optional[fastworkflow.CommandOutput]:
+        """
+        Create and start a workflow within this chat session.
+        
+        Args:
+            workflow_folderpath: The folder containing the fastworkflow Workflow
+            workflow_id_str: Arbitrary key used to persist the workflow state
+            parent_workflow_id: Persist this workflow under a parent workflow
+            workflow_context: The starting context for the workflow.
+            startup_command: Optional command to execute on startup
+            startup_action: Optional action to execute on startup
+            keep_alive: Whether to keep the chat session alive after workflow completion
+            
+        Returns:
+            CommandOutput for non-keep_alive workflows, None otherwise
+        """
+        if startup_command and startup_action:
+            raise ValueError("Cannot provide both startup_command and startup_action")
+
+        litellm.drop_params = True  # See https://docs.litellm.ai/docs/completion/drop_params
+
+        # Create the workflow
+        workflow = fastworkflow.Workflow.create(
+            workflow_folderpath,
+            workflow_id_str=workflow_id_str,
+            parent_workflow_id=parent_workflow_id,
+            workflow_context=workflow_context,
+            project_folderpath=project_folderpath
+        )
+        
+        self._current_workflow = workflow
+        self._status = SessionStatus.STOPPED
+        self._startup_command = startup_command
+
+        if startup_action and startup_action.workflow_id is None:
+            startup_action.workflow_id = workflow.id
+        self._startup_action = startup_action
+        self._keep_alive = False if parent_workflow_id else keep_alive
+
+        # Check if we need to stop the current workflow
+        # Stop if this is a new root workflow (no parent, keep_alive=True)
+        current_workflow = self.get_active_workflow()
+        if (current_workflow and 
+            parent_workflow_id is None and 
+            self._keep_alive):
+            logger.info(f"Stopping current workflow {current_workflow.id} to start new root workflow {workflow.id}")
+            self.stop_workflow()
+
+        # ------------------------------------------------------------
+        # Eager warm-up of CommandRouter / ModelPipeline
+        # ------------------------------------------------------------
+        # Loading transformer checkpoints and moving them to device is
+        # expensive (~1 s).  We do it here *once* for every model artifact
+        # directory so that the first user message does not pay the cost.
+        try:
+            command_info_root = Path(workflow.folderpath) / "___command_info"
+            if command_info_root.is_dir():
+                subdirs = [d for d in command_info_root.iterdir() if d.is_dir()]
+
+                # Tell the progress bar how many extra steps we are going to
+                # perform (one per directory plus one for the wildcard "*").
+                StartupProgress.add_total(len(subdirs) + 1)
+
+                for subdir in subdirs:
+                    # Instantiating CommandRouter triggers ModelPipeline
+                    # construction and caches it process-wide.
+                    with contextlib.suppress(Exception):
+                        CommandRouter(str(subdir))
+                    StartupProgress.advance(f"Warm-up {subdir.name}")
+
+                # Also warm-up the global-context artefacts, which live in a
+                # pseudo-folder named '*' in some workflows.
+                with contextlib.suppress(Exception):
+                    CommandRouter(str(command_info_root / '*'))
+                StartupProgress.advance("Warm-up global")
+        except Exception as warm_err:  # pragma: no cover – warm-up must never fail
+            logger.debug(f"Model warm-up skipped due to error: {warm_err}")
+
+        self._core.bind_app_workflow(workflow)
+        self._core.keep_alive = self._keep_alive
+
+        # Start the workflow
+        if self._status != SessionStatus.STOPPED:
+            raise RuntimeError("Workflow already started")
+        
+        self._status = SessionStatus.STARTING
+        
+        # Agent + MCP tooling initialize lazily on first agent message (after contextvar push)
+        
+        command_output = None
+        if self._keep_alive:
+            # Root workflow gets a worker thread
+            self._chat_worker = ChatWorker(self)
+            self._chat_worker.start()
+        else:
+            # Child workflows run their loop in the current thread
+            self._status = SessionStatus.RUNNING
+            command_output = self._run_workflow_loop()
+
+        return command_output
+
+    @property
+    def workflow_tool_agent(self):
+        """Get the workflow tool agent for agent mode."""
+        return self._core.workflow_tool_agent
+
+    @property
+    def intent_clarification_agent(self):
+        """Get the intent clarification agent for agent mode."""
+        return self._core.intent_clarification_agent
+
+    @property
+    def cme_workflow(self) -> fastworkflow.Workflow:
+        """Get the command metadata extraction workflow."""
+        return self._core.cme_workflow
+
+    @property
+    def app_workflow(self) -> Optional[fastworkflow.Workflow]:
+        """Get the bound application workflow."""
+        return self._core.app_workflow
+    
+    @property
+    def run_as_agent(self) -> bool:
+        """Check if running in agent mode."""
+        return self._core.run_as_agent
+
+    @property
+    def ask_user_timeout(self) -> Optional[float]:
+        """Seconds to wait on ask_user before cancelling (None = block forever)."""
+        return self._core.ask_user_timeout
+
+    @property
+    def user_message_queue(self) -> Queue:
+        return self._user_message_queue
+
+    @property
+    def command_output_queue(self) -> Queue:
+        return self._command_output_queue
+
+    @property
+    def command_trace_queue(self) -> Queue:
+        return self._command_trace_queue
+
+    @property
+    def workflow_is_complete(self) -> bool:
+        workflow = self._core.app_workflow
+        return workflow.is_complete if workflow else True
+    
+    @workflow_is_complete.setter
+    def workflow_is_complete(self, value: bool) -> None:
+        if workflow := self._core.app_workflow:
+            workflow.is_complete = value
+    
+    @property
+    def conversation_history(self) -> dspy.History:
+        """Return the conversation history."""
+        return self._core.conversation_history
+
+    @property
+    def _conversation_history(self) -> dspy.History:
+        return self._core.conversation_history
+
+    @_conversation_history.setter
+    def _conversation_history(self, value: dspy.History) -> None:
+        self._core._conversation_history = value
+
+    # def clear_conversation_history(self, trace_filename_suffix: Optional[str] = None) -> None:
+    def clear_conversation_history(self) -> None:
+        """
+        Clear the conversation history.
+        This resets the conversation history to an empty state.
+        """
+        self._core.clear_conversation_history()
+        # Filename for conversation traces
+        # if trace_filename_suffix:
+        #     self._conversation_traces_file_name: str = (
+        #         f"conversation_traces_{trace_filename_suffix}"
+        #     )
+        # else:
+        #     self._conversation_traces_file_name: str = (
+        #         f"conversation_traces_{datetime.now().strftime('%m_%d_%Y:%H_%M_%S')}.jsonl"
+        #     )
+
+    def _run_workflow_loop(self) -> Optional[fastworkflow.CommandOutput]:
+        """
+        Run the workflow message processing loop.
+        For child workflows (keep_alive=False):
+        - Returns final CommandOutput when workflow completes
+        - All outputs (success or failure) are sent to queue during processing
+        """
+        last_output = None
+        workflow = self._current_workflow
+
+        try:
+            # Handle startup command/action
+            if self._startup_command:
+                last_output = self._core.process_message(self._startup_command)
+            elif self._startup_action:
+                last_output = self._core.process_action(self._startup_action)
+
+            while (
+                not self.workflow_is_complete or self._keep_alive
+            ) and self._status != SessionStatus.STOPPING:
+                try:
+                    message = self.user_message_queue.get()
+
+                    if isinstance(message, fastworkflow.Action):
+                        last_output = self._core.process_action(message)
+                    else:
+                        last_output = self._core.process_message(message)
+
+                except Empty:
+                    continue
+
+            # Return final output for child workflows, regardless of success/failure
+            if not self._keep_alive:
+                return last_output
+
+        finally:
+            self._status = SessionStatus.STOPPED
+            if self.get_active_workflow() is not None:
+                self.clear_workflow_stack()
+            logger.debug(f"Workflow {workflow.id if workflow else 'unknown'} completed")
+
+        return None
+    
+    # def _is_mcp_tool_call(self, message: str) -> bool:
+    #     """Detect if message is an MCP tool call JSON"""
+    #     try:
+    #         data = json.loads(message)
+    #         return data.get("type") == "mcp_tool_call"
+    #     except (json.JSONDecodeError, AttributeError):
+    #         return False
+    
+    # def _process_mcp_tool_call(self, message: str) -> fastworkflow.CommandOutput:
+    #     # sourcery skip: class-extract-method, extract-method
+    #     """Process an MCP tool call message"""
+    #     workflow = self.get_active_workflow()
+        
+    #     try:
+    #         # Parse JSON message
+    #         data = json.loads(message)
+    #         tool_call_data = data["tool_call"]
+            
+    #         # Create MCPToolCall object
+    #         tool_call = fastworkflow.MCPToolCall(
+    #             name=tool_call_data["name"],
+    #             arguments=tool_call_data["arguments"]
+    #         )
+            
+    #         # Execute via command executor
+    #         mcp_result = self._CommandExecutor.perform_mcp_tool_call(
+    #             workflow, 
+    #             tool_call, 
+    #             command_context=workflow.current_command_context_name
+    #         )
+            
+    #         # Convert MCPToolResult back to CommandOutput for consistency
+    #         command_output = self._convert_mcp_result_to_command_output(mcp_result)
+            
+    #         # Put in output queue if needed
+    #         if (not command_output.success or self._keep_alive) and self.command_output_queue:
+    #             self.command_output_queue.put(command_output)
+
+    #         # Flush on successful or failed tool call – state may have changed.
+    #         if workflow := self.get_active_workflow():
+    #             workflow.flush()
+            
+    #         return command_output
+            
+    #     except Exception as e:
+    #         logger.error(f"Error processing MCP tool call: {e}. Tool call content: {message}")
+    #         return self._process_message(message)  # process as a message
+    
+    # def _convert_mcp_result_to_command_output(self, mcp_result: fastworkflow.MCPToolResult) -> fastworkflow.CommandOutput:
+    #     """Convert MCPToolResult to CommandOutput for compatibility"""
+    #     command_response = fastworkflow.CommandResponse(
+    #         response=mcp_result.content[0].text if mcp_result.content else "No response",
+    #         success=not mcp_result.isError
+    #     )
+        
+    #     command_output = fastworkflow.CommandOutput(command_responses=[command_response])
+    #     command_output._mcp_source = mcp_result  # Mark for special formatting
+    #     return command_output
+    
+    def _process_message(self, message: str) -> fastworkflow.CommandOutput:
+        """Back-compat shim: delegate single-message execution to the core."""
+        return self._core.process_message(message)
+
+    def _process_agent_message(self, message: str) -> fastworkflow.CommandOutput:
+        """Back-compat shim: delegate agent-message execution to the core."""
+        return self._core.process_message(message)
+
+    def _process_action(self, action: fastworkflow.Action) -> fastworkflow.CommandOutput:
+        """Back-compat shim: delegate action execution to the core."""
+        return self._core.process_action(action)
+
+    def profile_invoke_command(self, message: str):
+        """
+        Profile the invoke_command method with detailed focus on performance issues.
+        
+        Args:
+            message: The message to process
+            output_file: Name of the profile output file
+            
+        Returns:
+            The result of the invoke_command call
+        """
+        from datetime import datetime
+        
+        # Generate a unique filename with timestamp
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        output_file = f"invoke_command_{timestamp}.prof"        
+
+        import cProfile
+        import pstats
+        import io
+        import time
+        
+        # Create a Profile object
+        profiler = cProfile.Profile()
+        
+        # Enable profiling
+        profiler.enable()
+        
+        # Execute invoke_command and time it
+        start_time = time.time()
+        if self._core.app_workflow:
+            self.push_active_workflow(self._core.app_workflow)
+        try:
+            result = self._CommandExecutor.invoke_command(self, message)
+        finally:
+            if self._core.app_workflow:
+                self.pop_active_workflow()
+        elapsed = time.time() - start_time
+        
+        # Disable profiling
+        profiler.disable()
+        
+        # Save profile results to file
+        profiler.dump_stats(output_file)
+        print(f"\nProfile data saved to {os.path.abspath(output_file)}")
+        print(f"invoke_command execution took {elapsed:.4f} seconds")
+        
+        # Create summary report
+        report_file = f"{os.path.splitext(output_file)[0]}_report.txt"
+        with open(report_file, "w") as f:
+            # Overall summary by cumulative time
+            s = io.StringIO()
+            ps = pstats.Stats(profiler, stream=s)
+            ps.sort_stats('cumulative').print_stats(30)
+            f.write(f"=== CUMULATIVE TIME SUMMARY (TOP 30) === Execution time: {elapsed:.4f}s\n")
+            f.write(s.getvalue())
+            f.write("\n\n")
+            
+            # Internal time summary
+            s = io.StringIO()
+            ps = pstats.Stats(profiler, stream=s)
+            ps.sort_stats('time').print_stats(30)
+            f.write("=== INTERNAL TIME SUMMARY (TOP 30) ===\n")
+            f.write(s.getvalue())
+            f.write("\n\n")
+            
+            # Most called functions
+            s = io.StringIO()
+            ps = pstats.Stats(profiler, stream=s)
+            ps.sort_stats('calls').print_stats(30)
+            f.write("=== MOST CALLED FUNCTIONS (TOP 30) ===\n")
+            f.write(s.getvalue())
+            
+            # Focus areas for issues 3-7
+            focus_areas = [
+                ('lock_contention', ['lock', 'acquire', 'release'], 'time'),
+                ('model_operations', ['torch', 'nn', 'model'], 'cumulative'),
+                ('command_extraction', ['wildcard.py', 'extract', 'predict'], 'cumulative'),
+                ('file_io', ['_get_sessiondb_folderpath', '_load', '_save'], 'cumulative'),
+                ('frequent_operations', ['startswith', 'isinstance', 'get'], 'calls')
+            ]
+            
+            for name, patterns, sort_by in focus_areas:
+                f.write(f"\n\n=== {name.upper()} ===\n")
+                for pattern in patterns:
+                    s = io.StringIO()
+                    ps = pstats.Stats(profiler, stream=s)
+                    ps.sort_stats(sort_by).print_stats(pattern, 10)
+                    f.write(f"\nPattern: '{pattern}'\n")
+                    f.write(s.getvalue())
+        
+        print(f"Detailed report saved to {os.path.abspath(report_file)}")
+        
+        return result

{fastworkflow-2.18.3 → fastworkflow-2.19.0}/fastworkflow/intent_clarification_agent.py

@@ -7,6 +7,8 @@ import json
 import dspy
 
 import fastworkflow
+from fastworkflow.utils.logging import logger
+from fastworkflow.workflow_execution_context import CommandCancelledError
 from fastworkflow.utils.react import fastWorkflowReAct
 from fastworkflow.command_metadata_api import CommandMetadataAPI
 
@@ -64,13 +66,26 @@ def _ask_user_for_clarification(
     Returns:
         User's response
     """
+    user_queue = chat_session.user_message_queue
+    output_queue = chat_session.command_output_queue
+    if user_queue is None:
+        raise CommandCancelledError(
+            "ask_user requires a user_message_queue (not available in this context)"
+        )
+
+    active = chat_session.get_active_workflow()
+    workflow_name = active.folderpath.split("/")[-1] if active else ""
     command_output = fastworkflow.CommandOutput(
         command_responses=[fastworkflow.CommandResponse(response=clarification_request)],
-        workflow_name=chat_session.get_active_workflow().folderpath.split('/')[-1]
+        workflow_name=workflow_name,
     )
-    chat_session.command_output_queue.put(command_output)
+    if output_queue is not None:
+        output_queue.put(command_output)
 
-    user_response = chat_session.user_message_queue.get()
+    # Topology A (blocking): block indefinitely for the human's answer. The nested
+    # intent-clarification ask_user is last-resort; in Topology B there is no queue
+    # and it aborts via CommandCancelledError above (no timeout involved).
+    user_response = user_queue.get()
 
     # Log to action.jsonl (shared with main agent)
     with open("action.jsonl", "a", encoding="utf-8") as f: