Merge pull request #71 from nasa-jpl/hotfix/tiktoken-rust-dep

- Fix critical tiktoken dependency issue that prevented ROSA from running in Docker containers due to missing Rust compiler
- Improve keyboard interrupt (Ctrl+C) handling to allow users to gracefully cancel long-running operations without crashing the agent
- Enhance the turtle agent demo with new high-level drawing tools for creating complex shapes like rectangles, circles, polylines, and arcs
- Improve documentation and parameter descriptions for turtle control tools to reduce agent confusion and improve drawing accuracy
- Fix X11 forwarding configuration in demo script to support multiple operating systems and environments

Author: RobRoyce

Dockerfile

@@ -11,10 +11,19 @@ RUN apt-get update && apt-get install -y \
     locales \
     xvfb \
     python3.9 \
-    python3-pip
+    python3-pip \
+    curl \
+    build-essential
 
+# Install Rust (required for building tiktoken)
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+ENV PATH="/root/.cargo/bin:${PATH}"
+
+# Cleanup disabled for development builds
 # RUN apt-get clean && rm -rf /var/lib/apt/lists/*
-RUN python3 -m pip install -U python-dotenv catkin_tools
+# Upgrade pip first, then install packages
+RUN python3.9 -m pip install --upgrade pip
+RUN python3.9 -m pip install --break-system-packages python-dotenv catkin_tools
 RUN rosdep update && \
     echo "source /opt/ros/noetic/setup.bash" >> /root/.bashrc && \
     echo "alias start='catkin build && source devel/setup.bash && roslaunch turtle_agent agent.launch'" >> /root/.bashrc && \
@@ -25,9 +34,9 @@ WORKDIR /app/
 
 # Modify the RUN command to use ARG
 RUN /bin/bash -c 'if [ "$DEVELOPMENT" = "true" ]; then \
-    python3.9 -m pip install --user -e .; \
+    python3.9 -m pip install --break-system-packages --ignore-installed --user -e .; \
     else \
-    python3.9 -m pip install -U jpl-rosa>=1.0.7; \
+    python3.9 -m pip install --break-system-packages --ignore-installed -U jpl-rosa>=1.0.8; \
     fi'
 
 CMD ["/bin/bash", "-c", "source /opt/ros/noetic/setup.bash && \
@@ -39,5 +48,5 @@ CMD ["/bin/bash", "-c", "source /opt/ros/noetic/setup.bash && \
     xvfb-run -a -s \"-screen 0 1920x1080x24\" rosrun turtlesim turtlesim_node & \
     fi && \
     sleep 5 && \
-    echo \"Run \\`start\\` to build and launch the ROSA-TurtleSim demo.\" && \
+    echo \"Run \\`start streaming:=true\\` to build and launch the ROSA-TurtleSim demo.\" && \
     /bin/bash"]

demo.sh

@@ -26,19 +26,35 @@ HEADLESS=${HEADLESS:-false}
 DEVELOPMENT=${DEVELOPMENT:-false}
 
 # Enable X11 forwarding based on OS
+echo "Enabling X11 forwarding..."
 case "$(uname)" in
-    Linux*|Darwin*)
-        echo "Enabling X11 forwarding..."
-        # If running under WSL, use :0 for DISPLAY
-        if grep -q "WSL" /proc/version; then
-            export DISPLAY=:0
-        else
-            export DISPLAY=host.docker.internal:0
+    Linux*)
+        export DISPLAY=${DISPLAY:-:0}
+        xhost +local:docker &>/dev/null || echo "Warning: xhost command failed"
+        # Verify X11 is working
+        if ! xset q &>/dev/null; then
+            echo "Error: X11 forwarding is not working. Please check your X11 server."
+            exit 1
+        fi
+        ;;
+    Darwin*)
+        # Keep XQuartz's DISPLAY or default to :0
+        export DISPLAY=${DISPLAY:-:0}
+        xhost +local:docker &>/dev/null || true
+        
+        # Check if XQuartz is running and properly configured
+        if ! pgrep -xq "Xquartz" && ! pgrep -xq "X11"; then
+            echo "Error: XQuartz is not running. Please start XQuartz and try again."
+            exit 1
+        fi
+        
+        # Warn if network connections are disabled
+        if ! defaults read org.xquartz.X11 nolisten_tcp 2>/dev/null | grep -q 0; then
+            echo "Warning: XQuartz may not allow network connections."
+            echo "Enable in: XQuartz Preferences > Security > 'Allow connections from network clients'"
         fi
-        xhost +
         ;;
     MINGW*|CYGWIN*|MSYS*)
-        echo "Enabling X11 forwarding for Windows..."
         export DISPLAY=host.docker.internal:0
         ;;
     *)
@@ -47,29 +63,45 @@ case "$(uname)" in
         ;;
 esac
 
-# Check if X11 forwarding is working
-if ! xset q &>/dev/null; then
-    echo "Error: X11 forwarding is not working. Please check your X11 server and try again."
-    exit 1
-fi
-
 # Build and run the Docker container
 CONTAINER_NAME="rosa-turtlesim-demo"
+
+# Detect platform for Apple Silicon
+PLATFORM_ARG=""
+if [ "$(uname -m)" = "arm64" ]; then
+    PLATFORM_ARG="--platform linux/amd64"
+fi
+
 echo "Building the $CONTAINER_NAME Docker image..."
-docker build --build-arg DEVELOPMENT=$DEVELOPMENT -t $CONTAINER_NAME -f Dockerfile . || { echo "Error: Docker build failed"; exit 1; }
+docker build $PLATFORM_ARG --build-arg DEVELOPMENT=$DEVELOPMENT -t $CONTAINER_NAME -f Dockerfile . || {
+    echo "Error: Docker build failed"
+    exit 1
+}
 
 echo "Running the Docker container..."
-docker run -it --rm --name $CONTAINER_NAME \
-    -e DISPLAY=$DISPLAY \
-    -e HEADLESS=$HEADLESS \
-    -e DEVELOPMENT=$DEVELOPMENT \
-    -v /tmp/.X11-unix:/tmp/.X11-unix \
-    -v "$PWD/src":/app/src \
-    -v "$PWD/tests":/app/tests \
-    --network host \
-    $CONTAINER_NAME
+if [ "$(uname)" = "Darwin" ]; then
+    # macOS: Use host.docker.internal for X11
+    docker run -it --rm --init --name $CONTAINER_NAME \
+        -e DISPLAY=host.docker.internal:0 \
+        -e HEADLESS=$HEADLESS \
+        -e DEVELOPMENT=$DEVELOPMENT \
+        -v "$PWD/src":/app/src \
+        -v "$PWD/tests":/app/tests \
+        $CONTAINER_NAME
+else
+    # Linux/WSL: Use unix socket
+    docker run -it --rm --init --name $CONTAINER_NAME \
+        -e DISPLAY=$DISPLAY \
+        -e HEADLESS=$HEADLESS \
+        -e DEVELOPMENT=$DEVELOPMENT \
+        -v /tmp/.X11-unix:/tmp/.X11-unix \
+        -v "$PWD/src":/app/src \
+        -v "$PWD/tests":/app/tests \
+        --network host \
+        $CONTAINER_NAME
+fi
 
 # Disable X11 forwarding
-xhost -
+xhost -local:docker &>/dev/null || true
 
 exit 0

src/rosa/prompts.py

@@ -69,6 +69,36 @@ def __str__(self):
         "interact with the robotic system you are integrated with. Your responses should be grounded in real-time "
         "information whenever possible using the tools available to you.",
     ),
+    (
+        "system",
+        "CRITICAL - TOOL USAGE REQUIREMENT: When a user asks you to perform an action involving ROS nodes, topics, "
+        "or services, you MUST IMMEDIATELY use your tools to check what is available before responding. "
+        "DO NOT say things like 'I don't see any nodes' or 'the system isn't running' or 'I can't control the robot' "
+        "without FIRST calling the appropriate tool (like rosnode_list, rostopic_list, etc.) to verify the actual "
+        "current state. Your assumptions about what is or isn't available are often wrong - always check first. "
+        "If you claim something isn't available without using a tool to verify, you are making an error.",
+    ),
+    (
+        "system",
+        "CRITICAL - SEQUENTIAL TOOL EXECUTION: You MUST call tools ONE AT A TIME and wait for each to complete before calling the next. "
+        "NEVER call multiple tools in parallel in a single response. This is especially critical for drawing/movement commands. "
+        "When you need to execute multiple operations (like drawing multiple shapes), you must: "
+        "1. Call the FIRST tool and stop "
+        "2. Wait for the result "
+        "3. Then call the NEXT tool and stop "
+        "4. Repeat until all operations complete "
+        "Even if operations seem independent, you MUST execute them sequentially. Do not batch tool calls together.",
+    ),
+    (
+        "system",
+        "WORKFLOW FOR ACTION REQUESTS: When a user asks you to perform a robotic action (move, draw, control, etc.), "
+        "follow this workflow: "
+        "1. FIRST: Call rosnode_list() and rostopic_list() WITHOUT any parameters to see what's available. "
+        "   Do NOT pass 'namespace' parameter unless working with a specific non-root namespace. "
+        "2. SECOND: If relevant nodes/topics exist, proceed with the action immediately. "
+        "3. THIRD: Only if the tools show nothing is available should you explain that to the user. "
+        "Do NOT skip step 1. Do NOT describe what you 'would do if the system were running' - check if it IS running first.",
+    ),
     (
         "system",
         "When asked to provide names of topics or nodes, first retrieve a list of available names using the "
@@ -92,8 +122,10 @@ def __str__(self):
     ),
     (
         "system",
-        "You must use your math tools to perform calculations. Failing to do this may result in a catastrophic "
-        "failure of the system. You must never perform calculations manually or assume you know the correct answer. ",
+        "You must use your math tools to perform calculations, especially for angles, distances, coordinates, and "
+        "geometric computations. Failing to do this may result in incorrect commands or system failures. You must "
+        "never perform calculations manually in your reasoning - always use the provided calculation tools to ensure "
+        "accuracy. This is critical for robotics operations where precision matters.",
     ),
     (
         "system",

src/rosa/rosa.py

@@ -47,6 +47,9 @@ class ROSA:
         accumulate_chat_history (bool): Whether to accumulate chat history. Defaults to True.
         show_token_usage (bool): Whether to show token usage. Does not work when streaming is enabled. Defaults to False.
         streaming (bool): Whether to stream the output of the agent. Defaults to True.
+        max_iterations (int): Maximum number of iterations for the agent executor. Defaults to 100.
+        return_intermediate_steps (bool): Whether to return intermediate steps in the agent's execution. 
+            Setting to True increases memory usage but provides detailed execution traces. Defaults to False.
 
     Attributes:
         chat_history (list): A list of messages representing the chat history.
@@ -75,6 +78,8 @@ def __init__(
         accumulate_chat_history: bool = True,
         show_token_usage: bool = False,
         streaming: bool = True,
+        max_iterations: int = 100,
+        return_intermediate_steps: bool = False,
     ):
         self.__chat_history = []
         self.__ros_version = ros_version
@@ -84,6 +89,8 @@ def __init__(
         self.__blacklist = blacklist if blacklist else []
         self.__accumulate_chat_history = accumulate_chat_history
         self.__streaming = streaming
+        self.__max_iterations = max_iterations
+        self.__return_intermediate_steps = return_intermediate_steps
         self.__tools = self._get_tools(
             ros_version, packages=tool_packages, tools=tools, blacklist=self.__blacklist
         )
@@ -129,6 +136,9 @@ def invoke(self, query: str) -> str:
                     {"input": query, "chat_history": self.__chat_history}
                 )
                 self._print_usage(cb)
+        except KeyboardInterrupt:
+            # Re-raise KeyboardInterrupt so it can be handled upstream
+            raise
         except Exception as e:
             return f"An error occurred: {str(e)}"
 
@@ -215,6 +225,9 @@ async def astream(self, query: str) -> AsyncIterable[Dict[str, Any]]:
 
             if final_output:
                 self._record_chat_history(query, final_output)
+        except KeyboardInterrupt:
+            # Re-raise KeyboardInterrupt so it can be handled upstream
+            yield {"type": "error", "content": "Operation interrupted by user"}
         except Exception as e:
             yield {"type": "error", "content": f"An error occurred: {e}"}
 
@@ -225,6 +238,9 @@ def _get_executor(self, verbose: bool) -> AgentExecutor:
             tools=self.__tools.get_tools(),
             stream_runnable=self.__streaming,
             verbose=verbose,
+            max_iterations=self.__max_iterations,
+            handle_parsing_errors=True,
+            return_intermediate_steps=self.__return_intermediate_steps,
         )
         return executor
 

src/rosa/tools/calculation.py

@@ -238,7 +238,13 @@ def acos(x_values: List[float]) -> List[dict]:
 
 @tool
 def atan(x_values: List[float]) -> List[dict]:
-    """Performs arctangent on the input values x.
+    """
+    Calculate arctangent (inverse tangent) of input values. Returns angle in radians.
+    Use this to find an angle from a slope (rise/run).
+    
+    For finding angle from point A to point B, use atan2 instead (it's better).
+    
+    Example: atan(1) = π/4 ≈ 0.785 radians = 45 degrees
 
     :arg x_values: A list of values x (e.g. [x1, x2, ...])
     """
@@ -317,24 +323,111 @@ def count_lines(text: str) -> int:
 @tool
 def degrees_to_radians(degrees: List[float]):
     """
-    Convert degrees to radians.
+    Convert degrees to radians. Use this for angle conversions.
 
     :param degrees: A list of one or more degrees to convert to radians.
     """
     rads = {}
     for degree in degrees:
-        rads[degree] = f"{degree * (3.14159 / 180)} radians."
+        rads[degree] = degree * (math.pi / 180)
     return rads
 
 
 @tool
 def radians_to_degrees(radians: List[float]):
     """
-    Convert radians to degrees.
+    Convert radians to degrees. Use this for angle conversions.
 
     :param radians: A list of one or more radians to convert to degrees.
     """
     degs = {}
     for radian in radians:
-        degs[radian] = f"{radian * (180 / 3.14159)} degrees."
+        degs[radian] = radian * (180 / math.pi)
     return degs
+
+
+@tool
+def sqrt(x_values: List[float]) -> List[dict]:
+    """
+    Calculate the square root of input values. Essential for distance calculations.
+
+    :arg x_values: A list of values x (e.g. [x1, x2, ...])
+    """
+    results = []
+    for x in x_values:
+        if x < 0:
+            result = {f"sqrt({x})": "undefined (negative number)"}
+        else:
+            result = {f"sqrt({x})": math.sqrt(x)}
+        results.append(result)
+    return results
+
+
+@tool
+def atan2(pairs: List[tuple]) -> List[dict]:
+    """
+    Calculate the angle (in radians) from the positive x-axis to the point (x, y).
+    This is the MOST IMPORTANT tool for calculating angles between two points.
+    
+    To find the angle from point (x1, y1) to point (x2, y2):
+    Use atan2(y2-y1, x2-x1)
+    
+    Example: angle from (1, 1) to (3, 4) = atan2(4-1, 3-1) = atan2(3, 2) ≈ 0.98 radians
+
+    :arg pairs: A list of tuples containing (y, x) values in that order, e.g., [(y1, x1), (y2, x2), ...]
+    """
+    results = []
+    for y, x in pairs:
+        result = {f"atan2({y}, {x})": math.atan2(y, x)}
+        results.append(result)
+    return results
+
+
+@tool
+def distance_between_points(point_pairs: List[tuple]) -> List[dict]:
+    """
+    Calculate the straight-line distance between two points using the Pythagorean theorem.
+    Formula: sqrt((x2-x1)^2 + (y2-y1)^2)
+    
+    This is essential for determining how far the turtle needs to move.
+
+    :arg point_pairs: A list of tuples, each containing ((x1, y1), (x2, y2))
+    Example: [((0, 0), (3, 4))] calculates distance from (0,0) to (3,4) = 5.0
+    """
+    results = []
+    for (x1, y1), (x2, y2) in point_pairs:
+        dx = x2 - x1
+        dy = y2 - y1
+        dist = math.sqrt(dx**2 + dy**2)
+        result = {f"distance from ({x1},{y1}) to ({x2},{y2})": dist}
+        results.append(result)
+    return results
+
+
+@tool
+def calculate_line_angle_and_distance(point_pairs: List[tuple]) -> List[dict]:
+    """
+    Calculate BOTH the angle (in radians) and distance needed to draw a line from point A to point B.
+    This is a high-level helper that combines atan2 and distance calculations.
+    
+    Use this when planning to draw a line between two specific coordinates.
+    The angle returned is relative to the positive x-axis (right = 0, up = π/2).
+
+    :arg point_pairs: A list of tuples, each containing ((x1, y1), (x2, y2))
+    Example: [((2, 3), (5, 7))] returns angle and distance from (2,3) to (5,7)
+    """
+    results = []
+    for (x1, y1), (x2, y2) in point_pairs:
+        dx = x2 - x1
+        dy = y2 - y1
+        angle = math.atan2(dy, dx)
+        distance = math.sqrt(dx**2 + dy**2)
+        result = {
+            f"line from ({x1},{y1}) to ({x2},{y2})": {
+                "angle_radians": angle,
+                "angle_degrees": angle * (180 / math.pi),
+                "distance": distance,
+            }
+        }
+        results.append(result)
+    return results