langroid 0.1.250__py3-none-any.whl → 0.1.252__py3-none-any.whl

langroid/__init__.py

@@ -41,7 +41,7 @@ from .agent.chat_agent import (
     ChatAgentConfig,
 )
 
-from .agent.task import Task
+from .agent.task import Task, TaskConfig
 
 try:
     from .agent.callbacks.chainlit import (
@@ -64,8 +64,11 @@ from .mytypes import (
     Entity,
 )
 
+from .exceptions import InfiniteLoopException
+
 __all__ = [
     "mytypes",
+    "exceptions",
     "utils",
     "parsing",
     "prompts",
@@ -82,6 +85,7 @@ __all__ = [
     "ChatDocument",
     "ChatDocMetaData",
     "Task",
+    "TaskConfig",
     "DocMetaData",
     "Document",
     "Entity",
@@ -89,6 +93,7 @@ __all__ = [
     "run_batch_tasks",
     "llm_response_batch",
     "agent_response_batch",
+    "InfiniteLoopException",
 ]
 if chainlit_available:
     __all__.extend(

langroid/agent/base.py

@@ -2,6 +2,7 @@ import asyncio
 import inspect
 import json
 import logging
+import re
 from abc import ABC
 from contextlib import ExitStack
 from types import SimpleNamespace
@@ -19,7 +20,7 @@ from typing import (
     no_type_check,
 )
 
-from pydantic import BaseSettings, ValidationError
+from pydantic import BaseSettings, ValidationError, validator
 from rich import print
 from rich.console import Console
 from rich.markup import escape
@@ -64,6 +65,15 @@ class AgentConfig(BaseSettings):
     prompts: Optional[PromptsConfig] = PromptsConfig()
     show_stats: bool = True  # show token usage/cost stats?
 
+    @validator("name")
+    def check_name_alphanum(cls, v: str) -> str:
+        if not re.match(r"^[a-zA-Z0-9_-]+$", v):
+            raise ValueError(
+                "The name must only contain alphanumeric characters, "
+                "underscores, or hyphens, with no spaces"
+            )
+        return v
+
 
 def noop_fn(*args: List[Any], **kwargs: Dict[str, Any]) -> None:
     pass
@@ -87,6 +97,7 @@ class Agent(ABC):
         self.llm_tools_map: Dict[str, Type[ToolMessage]] = {}
         self.llm_tools_handled: Set[str] = set()
         self.llm_tools_usable: Set[str] = set()
+        self.interactive: bool | None = None
         self.total_llm_token_cost = 0.0
         self.total_llm_token_usage = 0
         self.token_stats_str = ""
@@ -223,8 +234,8 @@ class Agent(ABC):
         ):
             setattr(self, tool, lambda obj: obj.response(self))
 
-        if hasattr(message_class, "handle_message_fallback") and inspect.isfunction(
-            message_class.handle_message_fallback
+        if hasattr(message_class, "handle_message_fallback") and (
+            inspect.isfunction(message_class.handle_message_fallback)
         ):
             setattr(
                 self,
@@ -279,9 +290,9 @@ class Agent(ABC):
         ]
         return "\n\n".join(sample_convo)
 
-    def agent_response_template(self) -> ChatDocument:
+    def create_agent_response(self, content: str | None = None) -> ChatDocument:
         """Template for agent_response."""
-        return self._response_template(Entity.AGENT)
+        return self._response_template(Entity.AGENT, content)
 
     async def agent_response_async(
         self,
@@ -342,19 +353,19 @@ class Agent(ABC):
             ),
         )
 
-    def _response_template(self, e: Entity) -> ChatDocument:
+    def _response_template(self, e: Entity, content: str | None = None) -> ChatDocument:
         """Template for response from entity `e`."""
         return ChatDocument(
-            content="",
+            content=content or "",
             tool_messages=[],
             metadata=ChatDocMetaData(
                 source=e, sender=e, sender_name=self.config.name, tool_ids=[]
             ),
         )
 
-    def user_response_template(self) -> ChatDocument:
+    def create_user_response(self, content: str | None = None) -> ChatDocument:
         """Template for user_response."""
-        return self._response_template(Entity.USER)
+        return self._response_template(Entity.USER, content)
 
     async def user_response_async(
         self,
@@ -377,11 +388,21 @@ class Agent(ABC):
             (str) User response, packaged as a ChatDocument
 
         """
-        if self.default_human_response is not None:
+
+        # When msg explicitly addressed to user, this means an actual human response
+        # is being sought.
+        need_human_response = (
+            isinstance(msg, ChatDocument) and msg.metadata.recipient == Entity.USER
+        )
+
+        interactive = (
+            self.interactive if self.interactive is not None else settings.interactive
+        )
+        if self.default_human_response is not None and not need_human_response:
             # useful for automated testing
             user_msg = self.default_human_response
-        elif not settings.interactive:
-            user_msg = ""
+        elif not interactive and not need_human_response:
+            return None
         else:
             if self.callbacks.get_user_response is not None:
                 # ask user with empty prompt: no need for prompt
@@ -440,9 +461,9 @@ class Agent(ABC):
 
         return True
 
-    def llm_response_template(self) -> ChatDocument:
+    def create_llm_response(self, content: str | None = None) -> ChatDocument:
         """Template for llm_response."""
-        return self._response_template(Entity.LLM)
+        return self._response_template(Entity.LLM, content)
 
     @no_type_check
     async def llm_response_async(
@@ -736,6 +757,24 @@ class Agent(ABC):
 
     def _get_one_tool_message(self, json_str: str) -> Optional[ToolMessage]:
         json_data = json.loads(json_str)
+        # check if the json_data contains a "properties" field
+        # which further contains the actual tool-call
+        # (some weak LLMs do this). E.g. gpt-4o sometimes generates this:
+        # TOOL: {
+        #     "type": "object",
+        #     "properties": {
+        #         "request": "square",
+        #         "number": 9
+        #     },
+        #     "required": [
+        #         "number",
+        #         "request"
+        #     ]
+        # }
+
+        properties = json_data.get("properties")
+        if properties is not None:
+            json_data = properties
         request = json_data.get("request")
         if (
             request is None

langroid/agent/chat_agent.py

@@ -273,10 +273,11 @@ class ChatAgent(Agent):
                 example = "" if self.config.use_tools else (msg_cls.usage_example())
                 if example != "":
                     example = "EXAMPLE: " + example
+                class_instructions = msg_cls.instructions()
                 guidance = (
                     ""
-                    if msg_cls.instructions() == ""
-                    else ("GUIDANCE: " + msg_cls.instructions())
+                    if class_instructions == ""
+                    else ("GUIDANCE: " + class_instructions)
                 )
                 if guidance == "" and example == "":
                     continue
@@ -783,23 +784,20 @@ class ChatAgent(Agent):
         if self.llm is None:
             return
         if not citation_only and (not self.llm.get_stream() or is_cached):
-            # We expect response to be LLMResponse in this context
-            if not isinstance(response, LLMResponse):
-                raise ValueError(
-                    "Expected response to be LLMResponse, but got "
-                    f"{type(response)} instead."
-                )
             # We would have already displayed the msg "live" ONLY if
             # streaming was enabled, AND we did not find a cached response.
             # If we are here, it means the response has not yet been displayed.
             cached = f"[red]{self.indent}(cached)[/red]" if is_cached else ""
             if not settings.quiet:
+                chat_doc = (
+                    response
+                    if isinstance(response, ChatDocument)
+                    else ChatDocument.from_LLMResponse(response, displayed=True)
+                )
                 print(cached + "[green]" + escape(str(response)))
                 self.callbacks.show_llm_response(
                     content=str(response),
-                    is_tool=self.has_tool_message_attempt(
-                        ChatDocument.from_LLMResponse(response, displayed=True),
-                    ),
+                    is_tool=self.has_tool_message_attempt(chat_doc),
                     cached=is_cached,
                 )
         if isinstance(response, LLMResponse):

langroid/agent/special/lance_rag/critic_agent.py

@@ -70,13 +70,19 @@ class QueryPlanCriticConfig(LanceQueryPlanAgentConfig):
       plan execution FAILED, and your feedback should say INVALID along 
       with the ERROR message, `suggested_fix` that aims to help the assistant 
       fix the problem (or simply equals "address the the error shown in feedback")
+    - Ask yourself, is the ANSWER in the expected form, e.g. 
+        if the question is asking for the name of an ENTITY with max SIZE,
+        then the answer should be the ENTITY name, NOT the SIZE!! 
     - If the ANSWER is in the expected form, then the QUERY PLAN is likely VALID,
       and your feedback should say VALID, with empty `suggested_fix`.
+      ===> HOWEVER!!! Watch out for a spurious correct-looking answer, for EXAMPLE:
+      the query was to find the ENTITY with a maximum SIZE, 
+      but the dataframe calculation is find the SIZE, NOT the ENTITY!!      
     - If the ANSWER is {NO_ANSWER} or of the wrong form, 
       then try to DIAGNOSE the problem IN THE FOLLOWING ORDER:
       - DATAFRAME CALCULATION -- is it doing the right thing?
         Is it finding the Index of a row instead of the value in a column?
-        Or another example: mmaybe it is finding the maximum population
+        Or another example: maybe it is finding the maximum population
            rather than the CITY with the maximum population?
         If you notice a problem with the DATAFRAME CALCULATION, then
         ONLY SUBMIT FEEDBACK ON THE DATAFRAME CALCULATION, and DO NOT

langroid/agent/special/lance_rag/query_planner_agent.py

@@ -195,7 +195,7 @@ class LanceQueryPlanAgent(ChatAgent):
                 plan=self.curr_query_plan,
                 answer=self.result,
             )
-            response_tmpl = self.agent_response_template()
+            response_tmpl = self.create_agent_response()
             # ... add the QueryPlanAnswerTool to the response
             # (Notice how the Agent is directly sending a tool, not the LLM)
             response_tmpl.tool_messages = [query_plan_answer_tool]

langroid/agent/task.py

@@ -1,14 +1,15 @@
 from __future__ import annotations
 
+import asyncio
 import copy
 import logging
-import re
-from collections import Counter
+from collections import Counter, deque
 from types import SimpleNamespace
 from typing import (
     Any,
     Callable,
     Coroutine,
+    Deque,
     Dict,
     List,
     Optional,
@@ -18,6 +19,8 @@ from typing import (
     cast,
 )
 
+import numpy as np
+from pydantic import BaseModel
 from rich import print
 from rich.markup import escape
 
@@ -30,8 +33,10 @@ from langroid.agent.chat_document import (
     StatusCode,
 )
 from langroid.cachedb.redis_cachedb import RedisCache, RedisCacheConfig
+from langroid.exceptions import InfiniteLoopException
 from langroid.mytypes import Entity
 from langroid.parsing.parse_json import extract_top_level_json
+from langroid.parsing.routing import parse_addressed_message
 from langroid.utils.configuration import settings
 from langroid.utils.constants import (
     DONE,
@@ -42,6 +47,7 @@ from langroid.utils.constants import (
     USER_QUIT_STRINGS,
 )
 from langroid.utils.logging import RichFileLogger, setup_file_logger
+from langroid.utils.system import hash
 
 logger = logging.getLogger(__name__)
 
@@ -52,6 +58,23 @@ def noop_fn(*args: List[Any], **kwargs: Dict[str, Any]) -> None:
     pass
 
 
+class TaskConfig(BaseModel):
+    """Configuration for a Task. This is a container for any params that
+    we didn't include in the task `__init__` method.
+    We may eventually move all the task __init__ params to this class, analogous to how
+    we have config classes for `Agent`, `ChatAgent`, `LanguageModel`, etc.
+
+    Attributes:
+        inf_loop_cycle_len: max exact-loop cycle length: 0 => no inf loop test
+        inf_loop_dominance_factor: dominance factor for exact-loop detection
+        inf_loop_wait_factor: wait this * cycle_len msgs before loop-check
+    """
+
+    inf_loop_cycle_len: int = 10
+    inf_loop_dominance_factor: float = 1.5
+    inf_loop_wait_factor: float = 5.0
+
+
 class Task:
     """
     A `Task` wraps an `Agent` object, and sets up the `Agent`'s goals and instructions.
@@ -102,6 +125,7 @@ class Task:
         max_stalled_steps: int = 5,
         done_if_no_response: List[Responder] = [],
         done_if_response: List[Responder] = [],
+        config: TaskConfig = TaskConfig(),
     ):
         """
         A task to be performed by an agent.
@@ -157,6 +181,11 @@ class Task:
             show_subtask_response=noop_fn,
             set_parent_agent=noop_fn,
         )
+        self.config = config
+        # counts of distinct pending messages in history,
+        # to help detect (exact) infinite loops
+        self.message_counter: Counter[str] = Counter()
+        self.history_count: Deque[int] = deque(maxlen=self.config.inf_loop_cycle_len)
         # copy the agent's config, so that we don't modify the original agent's config,
         # which may be shared by other agents.
         try:
@@ -201,10 +230,11 @@ class Task:
             agent.config.name = name
         self.name = name or agent.config.name
         self.value: str = self.name
-        self.default_human_response = default_human_response
+
         if default_human_response is not None and default_human_response == "":
             interactive = False
         self.interactive = interactive
+        self.agent.interactive = interactive
         self.message_history_idx = -1
         if interactive:
             only_user_quits_root = True
@@ -213,6 +243,7 @@ class Task:
             only_user_quits_root = False
         if default_human_response is not None:
             self.agent.default_human_response = default_human_response
+        self.default_human_response = default_human_response
         if self.interactive:
             self.agent.default_human_response = None
         self.only_user_quits_root = only_user_quits_root
@@ -289,6 +320,7 @@ class Task:
             max_stalled_steps=self.max_stalled_steps,
             done_if_no_response=[Entity(s) for s in self.done_if_no_response],
             done_if_response=[Entity(s) for s in self.done_if_response],
+            config=self.config,
         )
 
     def __repr__(self) -> str:
@@ -448,6 +480,8 @@ class Task:
         self.max_tokens = max_tokens
         self.session_id = session_id
         self._set_alive()
+        self.message_counter.clear()
+        self.history_count.clear()
 
         assert (
             msg is None or isinstance(msg, str) or isinstance(msg, ChatDocument)
@@ -476,9 +510,25 @@ class Task:
                     print("[magenta]Bye, hope this was useful!")
                 break
             i += 1
-            if turns > 0 and i >= turns:
+            max_turns = (
+                min(turns, settings.max_turns)
+                if turns > 0 and settings.max_turns > 0
+                else max(turns, settings.max_turns)
+            )
+            if max_turns > 0 and i >= max_turns:
                 status = StatusCode.MAX_TURNS
                 break
+            if (
+                self.config.inf_loop_cycle_len > 0
+                and i % self.config.inf_loop_cycle_len == 0
+                and self._maybe_infinite_loop()
+            ):
+                raise InfiniteLoopException(
+                    """Possible infinite loop detected!
+                    You can adjust infinite loop detection by changing the params
+                    in the TaskConfig passed to the Task constructor: 
+                    e.g. set inf_loop_cycle_len=0 to disable loop detection."""
+                )
 
         final_result = self.result()
         if final_result is not None:
@@ -528,6 +578,8 @@ class Task:
         self.max_tokens = max_tokens
         self.session_id = session_id
         self._set_alive()
+        self.message_counter.clear()
+        self.history_count.clear()
 
         if (
             isinstance(msg, ChatDocument)
@@ -546,15 +598,32 @@ class Task:
         i = 0
         while True:
             await self.step_async()
+            await asyncio.sleep(0.01)  # temp yield to avoid blocking
             done, status = self.done()
             if done:
                 if self._level == 0 and not settings.quiet:
                     print("[magenta]Bye, hope this was useful!")
                 break
             i += 1
-            if turns > 0 and i >= turns:
+            max_turns = (
+                min(turns, settings.max_turns)
+                if turns > 0 and settings.max_turns > 0
+                else max(turns, settings.max_turns)
+            )
+            if max_turns > 0 and i >= max_turns:
                 status = StatusCode.MAX_TURNS
                 break
+            if (
+                self.config.inf_loop_cycle_len > 0
+                and i % self.config.inf_loop_cycle_len == 0
+                and self._maybe_infinite_loop()
+            ):
+                raise InfiniteLoopException(
+                    """Possible infinite loop detected!
+                    You can adjust infinite loop detection by changing the params
+                    in the TaskConfig passed to the Task constructor: 
+                    e.g. set inf_loop_cycle_len=0 to disable loop detection."""
+                )
 
         final_result = self.result()
         if final_result is not None:
@@ -824,6 +893,12 @@ class Task:
             # reset stuck counter since we made progress
             self.n_stalled_steps = 0
 
+        # update counters for infinite loop detection
+        if self.pending_message is not None:
+            hashed_msg = hash(str(self.pending_message))
+            self.message_counter.update([hashed_msg])
+            self.history_count.append(self.message_counter[hashed_msg])
+
     def _process_invalid_step_result(self, parent: ChatDocument | None) -> None:
         """
         Since step had no valid result from any responder, decide whether to update the
@@ -856,42 +931,6 @@ class Task:
             msg_str = escape(str(self.pending_message))
             print(f"[grey37][{sender_str}]{msg_str}[/grey37]")
 
-    def _parse_routing(self, msg: ChatDocument | str) -> Tuple[bool | None, str | None]:
-        """
-        Parse routing instruction if any, of the form:
-        PASS:<recipient>  (pass current pending msg to recipient)
-        SEND:<recipient> <content> (send content to recipient)
-        Args:
-            msg (ChatDocument|str|None): message to parse
-        Returns:
-            Tuple[bool,str|None]:
-                bool: true=PASS, false=SEND, or None if neither
-                str: recipient, or None
-        """
-        # handle routing instruction in result if any,
-        # of the form PASS=<recipient>
-        content = msg.content if isinstance(msg, ChatDocument) else msg
-        content = content.strip()
-        if PASS in content and PASS_TO not in content:
-            return True, None
-        if PASS_TO in content and content.split(":")[1] != "":
-            return True, content.split(":")[1]
-        if SEND_TO in content and (send_parts := re.split(r"[,: ]", content))[1] != "":
-            # assume syntax is SEND_TO:<recipient> <content>
-            # or SEND_TO:<recipient>,<content> or SEND_TO:<recipient>:<content>
-            recipient = send_parts[1].strip()
-            # get content to send, clean out routing instruction, and
-            # start from 1 char after SEND_TO:<recipient>,
-            # because we expect there is either a blank or some other separator
-            # after the recipient
-            content_to_send = content.replace(f"{SEND_TO}{recipient}", "").strip()[1:]
-            # if no content then treat same as PASS_TO
-            if content_to_send == "":
-                return True, recipient
-            else:
-                return False, recipient
-        return None, None
-
     def response(
         self,
         e: Responder,
@@ -929,7 +968,8 @@ class Task:
         # process result in case there is a routing instruction
         if result is None:
             return None
-        is_pass, recipient = self._parse_routing(result)
+        # if result content starts with @name, set recipient to name
+        is_pass, recipient, content = parse_routing(result)
         if is_pass is None:  # no routing, i.e. neither PASS nor SEND
             return result
         if is_pass:
@@ -949,9 +989,7 @@ class Task:
         elif recipient is not None:
             # we are sending non-empty content to non-null recipient
             # clean up result.content, set metadata.recipient and return
-            result.content = result.content.replace(
-                f"{SEND_TO}:{recipient}", ""
-            ).strip()
+            result.content = content or ""
             result.metadata.recipient = recipient
             return result
         else:
@@ -1080,38 +1118,76 @@ class Task:
             or (not self._is_empty_message(result) and response_says_done)
         )
 
-    def _maybe_infinite_loop(self, history: int = 10) -> bool:
+    def _maybe_infinite_loop(self) -> bool:
         """
-        TODO Not currently used, until we figure out best way.
-        Check if {NO_ANSWER}, empty answer, or a specific non-LLM msg occurs too
-        often in history of pending messages -- this can be an indicator of a possible
-        multi-step infinite loop that we should exit.
-        (A single-step infinite loop is where individual steps don't show progress
-        and are easy to detect via n_stalled_steps, but a multi-step infinite loop
-        could show "progress" at each step, but can still be an infinite loop, e.g.
-        if the steps are just alternating between two messages).
+        Detect possible infinite loop based on message frequencies.
+        NOTE: This only (attempts to) detect "exact" loops, i.e. a cycle
+        of messages that repeats exactly, e.g.
+        a r b i t r a t e r a t e r a t e r a t e ...
+
+        [It does not detect "approximate" loops, where the LLM is generating a
+        sequence of messages that are similar, but not exactly the same.]
+
+        Intuition: when you look at a sufficiently long sequence with an m-message
+        loop, then the frequencies of these m messages will "dominate" those
+        of all other messages.
+
+        1. First find m "dominant" messages, i.e. when arranged in decreasing
+            frequency order, find the m such that
+                freq[m] > F * freq[m+1] and
+                freq[m] > W + freq[m+1]
+            where F = config.inf_loop_dominance_factor (default 1.5) and
+            W = config.inf_loop_wait_factor (default 5).
+            So if you plot these frequencies in decreasing order,
+            you will see a big drop in the plot, from m to m+1.
+            We call the freqs until m the "dominant" freqs.
+        2. Say we found m such dominant frequencies.
+           If these are the same as the freqs of the last m messages,
+           then we are likely in a loop.
         """
-        p = self.pending_message
-        n_no_answers = 0
-        n_empty_answers = 0
-        counter: Counter[str] = Counter()
-        # count number of NO_ANSWER and empty answers in last up to 10 messages
-        # in ancestors of self.pending_message
-        for _ in range(history):
-            if p is None:
-                break
-            n_no_answers += p.content.strip() == NO_ANSWER
-            n_empty_answers += p.content.strip() == "" and p.function_call is None
-            if p.metadata.sender != Entity.LLM and PASS not in p.content:
-                counter.update([p.metadata.sender + ":" + p.content])
-            p = p.metadata.parent
-
-        # freq of most common message in history
-        high_freq = (counter.most_common(1) or [("", 0)])[0][1]
-        # We deem this a potential infinite loop if:
-        # - a specific non-LLM msg occurs too often, or
-        # - a NO_ANSWER or empty answer occurs too often
-        return max(high_freq, n_no_answers) > self.max_stalled_steps
+        max_cycle_len = self.config.inf_loop_cycle_len
+        if max_cycle_len <= 0:
+            # no loop detection
+            return False
+        wait_factor = self.config.inf_loop_wait_factor
+        if sum(self.message_counter.values()) < wait_factor * max_cycle_len:
+            # we haven't seen enough messages to detect a loop
+            return False
+
+        most_common_msg_counts: List[Tuple[str, int]] = (
+            self.message_counter.most_common(max_cycle_len + 1)
+        )
+        # get the most dominant msgs, i.e. these are at least 1.5x more freq
+        # than the rest
+        F = self.config.inf_loop_dominance_factor
+        # counts array in non-increasing order
+        counts = np.array([c for _, c in most_common_msg_counts])
+        # find first index where counts[i] > F * counts[i+1]
+        ratios = counts[:-1] / counts[1:]
+        diffs = counts[:-1] - counts[1:]
+        indices = np.where((ratios > F) & (diffs > wait_factor))[0]
+        m = indices[0] if indices.size > 0 else -1
+        if m < 0:
+            # no dominance found, but...
+            if len(most_common_msg_counts) <= max_cycle_len:
+                # ...The most-common messages are at most max_cycle_len,
+                # even though we looked for the most common (max_cycle_len + 1) msgs.
+                # This means there are only at most max_cycle_len distinct messages,
+                # which also indicates a possible loop.
+                m = len(most_common_msg_counts) - 1
+            else:
+                # ... we have enough messages, but no dominance found,
+                # so there COULD be loops longer than max_cycle_len,
+                # OR there is no loop at all; we can't tell, so we return False.
+                return False
+
+        dominant_msg_counts = most_common_msg_counts[: m + 1]
+        # if the dominant m message counts are the same as the
+        # counts of the last m messages, then we are likely in a loop
+        dominant_counts = sorted([c for _, c in dominant_msg_counts])
+        recent_counts = sorted(list(self.history_count)[-(m + 1) :])
+
+        return dominant_counts == recent_counts
 
     def done(
         self, result: ChatDocument | None = None, r: Responder | None = None
@@ -1289,7 +1365,9 @@ class Task:
         return (
             self.pending_message is not None
             and (recipient := self.pending_message.metadata.recipient) != ""
-            and recipient not in (e.name, self.name)
+            and recipient != e  # case insensitive
+            and recipient != e.name
+            and recipient != self.name  # case sensitive
         )
 
     def _can_respond(self, e: Responder) -> bool:
@@ -1316,3 +1394,53 @@ class Task:
 
         """
         self.color_log = enable
+
+
+def parse_routing(
+    msg: ChatDocument | str,
+) -> Tuple[bool | None, str | None, str | None]:
+    """
+    Parse routing instruction if any, of the form:
+    PASS:<recipient>  (pass current pending msg to recipient)
+    SEND:<recipient> <content> (send content to recipient)
+    @<recipient> <content> (send content to recipient)
+    Args:
+        msg (ChatDocument|str|None): message to parse
+    Returns:
+        Tuple[bool|None, str|None, str|None]:
+            bool: true=PASS, false=SEND, or None if neither
+            str: recipient, or None
+            str: content to send, or None
+    """
+    # handle routing instruction in result if any,
+    # of the form PASS=<recipient>
+    content = msg.content if isinstance(msg, ChatDocument) else msg
+    content = content.strip()
+    if PASS in content and PASS_TO not in content:
+        return True, None, None
+    if PASS_TO in content and content.split(":")[1] != "":
+        return True, content.split(":")[1], None
+    if (
+        SEND_TO in content
+        and (addressee_content := parse_addressed_message(content, SEND_TO))[0]
+        is not None
+    ):
+        (addressee, content_to_send) = addressee_content
+        # if no content then treat same as PASS_TO
+        if content_to_send == "":
+            return True, addressee, None
+        else:
+            return False, addressee, content_to_send
+    AT = "@"
+    if (
+        AT in content
+        and (addressee_content := parse_addressed_message(content, AT))[0] is not None
+    ):
+        (addressee, content_to_send) = addressee_content
+        # if no content then treat same as PASS_TO
+        if content_to_send == "":
+            return True, addressee, None
+        else:
+            return False, addressee, content_to_send
+
+    return None, None, None

langroid/agent/tool_message.py

@@ -52,7 +52,10 @@ class ToolMessage(ABC, BaseModel):
 
     @classmethod
     def instructions(cls) -> str:
-        return ""
+        return """
+        IMPORTANT: When using this or any other tool/function, you MUST include a 
+        `request` field and set it equal to the FUNCTION/TOOL NAME you intend to use.
+        """
 
     @classmethod
     def require_recipient(cls) -> Type["ToolMessage"]:

langroid/agent/tools/recipient_tool.py

@@ -97,9 +97,13 @@ class RecipientTool(ToolMessage):
     content: str
 
     @classmethod
-    def create(cls, recipients: List[str]) -> Type["RecipientTool"]:
+    def create(cls, recipients: List[str], default: str = "") -> Type["RecipientTool"]:
+        """Create a restricted version of RecipientTool that
+        only allows certain recipients, and possibly sets a default recipient."""
+
         class RecipientToolRestricted(cls):  # type: ignore
             allowed_recipients = recipients
+            default_recipient = default
 
         return RecipientToolRestricted
 
@@ -133,16 +137,18 @@ class RecipientTool(ToolMessage):
 
     def response(self, agent: ChatAgent) -> str | ChatDocument:
         """
-        When LLM has correctly used this tool, set the agent's `recipient_tool_used`
-        field to True, and construct a ChatDocument with an explicit recipient,
+        When LLM has correctly used this tool,
+        construct a ChatDocument with an explicit recipient,
         and make it look like it is from the LLM.
 
         Returns:
             (ChatDocument): with content set to self.content and
-                metadata.recipient set to self.recipient.
+                metadata.recipient set to self.intended_recipient.
         """
-
-        if self.intended_recipient == "":
+        default_recipient = self.__class__.default_value("default_recipient")
+        if self.intended_recipient == "" and default_recipient not in ["", None]:
+            self.intended_recipient = default_recipient
+        elif self.intended_recipient == "":
             # save the content as a class-variable, so that
             # we can construct the ChatDocument once the LLM specifies a recipient.
             # This avoids having to re-generate the entire message, saving time + cost.
@@ -198,9 +204,11 @@ class RecipientTool(ToolMessage):
         # since the recipient will differ from the task name.
         # So if this method is called, we can be sure that the recipient has not
         # been specified.
-        if isinstance(msg, str):
-            return None
-        if msg.metadata.sender != Entity.LLM:
+        if (
+            isinstance(msg, str)
+            or msg.metadata.sender != Entity.LLM
+            or msg.metadata.recipient != ""  # there IS an explicit recipient
+        ):
             return None
         content = msg if isinstance(msg, str) else msg.content
         # save the content as a class-variable, so that

langroid/exceptions.py

@@ -0,0 +1,3 @@
+class InfiniteLoopException(Exception):
+    def __init__(self, message: str = "Infinite loop detected", *args: object) -> None:
+        super().__init__(message, *args)

langroid/mytypes.py

@@ -22,6 +22,18 @@ class Entity(str, Enum):
     USER = "User"
     SYSTEM = "System"
 
+    def __eq__(self, other: object) -> bool:
+        """Allow case-insensitive comparison with strings."""
+        if isinstance(other, str):
+            return self.value.lower() == other.lower()
+        return super().__eq__(other)
+
+    def __hash__(self) -> int:
+        """Override this to ensure hashability of the enum,
+        so it can be used sets and dictionary keys.
+        """
+        return hash(self.value.lower())
+
 
 class DocMetaData(BaseModel):
     """Metadata for a document."""

langroid/parsing/routing.py

@@ -0,0 +1,27 @@
+import re
+from typing import Optional, Tuple
+
+
+def parse_addressed_message(
+    content: str, addressing: str = "@"
+) -> Tuple[Optional[str], str]:
+    # escape special characters in addressing prefix for regex use
+    addressing_escaped = re.escape(addressing)
+    pattern = rf"{addressing_escaped}(\w+)[,:\s]?"
+    # Regular expression to find a username prefixed by addressing character or string
+    match = re.findall(pattern, content)
+
+    addressee = None
+    if match:
+        # select the last match as the addressee
+        addressee = match[-1]
+
+        # Remove the last occurrence of the addressing prefix followed by the
+        # username and optional punctuation or whitespace
+        # To remove only the last occurrence, we'll construct a new pattern that
+        # specifically matches the last addressee
+        last_occurrence_pattern = rf"{addressing_escaped}{addressee}[,:\\s]?"
+        # Replace the last occurrence found in the content
+        content = re.sub(last_occurrence_pattern, "", content, count=1).strip()
+
+    return addressee, content

langroid/utils/configuration.py

@@ -11,6 +11,7 @@ class Settings(BaseSettings):
     # NOTE all of these can be overridden in your .env file with upper-case names,
     # for example CACHE_TYPE=momento
     debug: bool = False  # show debug messages?
+    max_turns: int = -1  # maximum number of turns in a task (to avoid inf loop)
     progress: bool = False  # show progress spinners/bars?
     stream: bool = True  # stream output?
     cache: bool = True  # use cache?

langroid/utils/system.py

@@ -6,6 +6,7 @@ import logging
 import shutil
 import socket
 import traceback
+import uuid
 from typing import Any
 
 logger = logging.getLogger(__name__)
@@ -153,3 +154,22 @@ def update_hash(hash: str | None = None, s: str = "") -> str:
 
     # Return the updated hash in hexadecimal format and the original string
     return hash_obj.hexdigest()
+
+
+def hash(s: str) -> str:
+    """
+    Generate a SHA256 hash of a string.
+
+    Args:
+        s (str): The string to hash.
+
+    Returns:
+        str: The SHA256 hash of the string.
+    """
+    return update_hash(s=s)
+
+
+def generate_unique_id() -> str:
+    """Generate a unique ID using UUID4."""
+    unique_id = str(uuid.uuid4())
+    return unique_id

{langroid-0.1.250.dist-info → langroid-0.1.252.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: langroid
-Version: 0.1.250
+Version: 0.1.252
 Summary: Harness LLMs with Multi-Agent Programming
 License: MIT
 Author: Prasad Chalasani

{langroid-0.1.250.dist-info → langroid-0.1.252.dist-info}/RECORD

@@ -1,10 +1,10 @@
-langroid/__init__.py,sha256=zsYpGiAUsvyzZzjm964NUamsJImrXSJPVGz9a2jE_uY,1679
+langroid/__init__.py,sha256=GXjDRv1rVNCxEB0BkfPIT4xgldKkB20b7kGPuGxNdiI,1803
 langroid/agent/__init__.py,sha256=_D8dxnfdr92ch1CIrUkKjrB5HVvsQdn62b1Fb2kBxV8,785
-langroid/agent/base.py,sha256=5HQ9fAFTQL771rhx7UkVkL90bjxSVA1DjtvxV8_1RJA,35652
+langroid/agent/base.py,sha256=6EznAMa4zeRdouo3U3_UzOI_cblvdpNH4v5CAM-fgbA,37171
 langroid/agent/batch.py,sha256=feRA_yRG768ElOQjrKEefcRv6Aefd_yY7qktuYUQDwc,10040
 langroid/agent/callbacks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 langroid/agent/callbacks/chainlit.py,sha256=LboE3zlLLzClKxpBkzHX4XU6fW4lNZW97zwwN97uuaU,21067
-langroid/agent/chat_agent.py,sha256=YwlRMWoK_7vEl9pxgMeUjQAgsukrnZjDGJR0WVomSuQ,39592
+langroid/agent/chat_agent.py,sha256=_xsBfGBkwcHd8IRErsW7tKNz7qn0h2oKSg_BFleOPCs,39475
 langroid/agent/chat_document.py,sha256=uwCq53SHRyxQw6qyhjzPYuJG48VHBgOf2122Ew3fk6c,9316
 langroid/agent/helpers.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 langroid/agent/junk,sha256=LxfuuW7Cijsg0szAzT81OjWWv1PMNI-6w_-DspVIO2s,339
@@ -13,9 +13,9 @@ langroid/agent/special/__init__.py,sha256=NG0JkB5y4K0bgnd9Q9UIvFExun3uTfVOWEVLVy
 langroid/agent/special/doc_chat_agent.py,sha256=MTUrUyCZ7_wksTo11AwSTHMOKZf1WX-cAJowi_sfT2o,55320
 langroid/agent/special/lance_doc_chat_agent.py,sha256=USp0U3eTaJzwF_3bdqE7CedSLbaqAi2tm-VzygcyLaA,10175
 langroid/agent/special/lance_rag/__init__.py,sha256=QTbs0IVE2ZgDg8JJy1zN97rUUg4uEPH7SLGctFNumk4,174
-langroid/agent/special/lance_rag/critic_agent.py,sha256=OsOcpcU_AmU2MagpZ5X5yxFeXyteKN9QJMzJGqIITig,6871
+langroid/agent/special/lance_rag/critic_agent.py,sha256=ufTdpHSeHgCzN85Q0sfWOrpBpsCjGVZdAg5yOH1ogU8,7296
 langroid/agent/special/lance_rag/lance_rag_task.py,sha256=l_HQgrYY-CX2FwIsS961aEF3bYog3GDYo98fj0C0mSk,2889
-langroid/agent/special/lance_rag/query_planner_agent.py,sha256=U_2V8l3M44R3mX-El3wG1k-u2lTToU-HGfKvRkEWoEA,9816
+langroid/agent/special/lance_rag/query_planner_agent.py,sha256=wSkrtY3Qz98KAqpVf0xMf4LRgKbHLASWVNUrbqwUAB0,9814
 langroid/agent/special/lance_tools.py,sha256=btMwKdcT8RdwAjmzbtN1xxm3s1H7ipO9GSpUamryYx8,1456
 langroid/agent/special/neo4j/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 langroid/agent/special/neo4j/csv_kg_chat.py,sha256=koL3sKtHm3aRkLTiARs54ngrcU3lOR1WaLLc_i8rWOU,6374
@@ -32,15 +32,15 @@ langroid/agent/special/sql/utils/populate_metadata.py,sha256=x2OMKfmIBnJESBG3qKt
 langroid/agent/special/sql/utils/system_message.py,sha256=qKLHkvQWRQodTtPLPxr1GSLUYUFASZU8x-ybV67cB68,1885
 langroid/agent/special/sql/utils/tools.py,sha256=6uB2424SLtmapui9ggcEr0ZTiB6_dL1-JRGgN8RK9Js,1332
 langroid/agent/special/table_chat_agent.py,sha256=xz4nWndTYTykET_oaveHcZUQ8IEpmA5yB8QGTXfOifw,9624
-langroid/agent/task.py,sha256=b_d46txohISETxXJoWpmIX0hinvt1wjHbK08LZRBEz8,54020
-langroid/agent/tool_message.py,sha256=2kPsQUwi3ZzINTUNj10huKnZLjLp5SXmefacTHx8QDc,8304
+langroid/agent/task.py,sha256=J4GIvbPMlL9uXKr7J-bSPHGvFK5tI2R0INgbnbFRmqk,59265
+langroid/agent/tool_message.py,sha256=aNSYLiRCszPZXJpKt7bGXWjBRzJVJIZoTjQXy7RHMQs,8486
 langroid/agent/tools/__init__.py,sha256=q-maq3k2BXhPAU99G0H6-j_ozoRvx15I1RFpPVicQIU,304
 langroid/agent/tools/duckduckgo_search_tool.py,sha256=mLGhlgs6pwbYZIwrOs9shfh1dMBVT4DtkR29pYL3cCQ,1900
 langroid/agent/tools/extract_tool.py,sha256=u5lL9rKBzaLBOrRyLnTAZ97pQ1uxyLP39XsWMnpaZpw,3789
 langroid/agent/tools/generator_tool.py,sha256=y0fB0ZObjA0b3L0uSTtrqRCKHDUR95arBftqiUeKD2o,663
 langroid/agent/tools/google_search_tool.py,sha256=cQxcNtb8XCNpOo_yCeYRwG_y-OATjPgkbr01kea9qWE,1421
 langroid/agent/tools/metaphor_search_tool.py,sha256=NKHss-AkI942_XhfMgUctAwHjIHpqp5NfYIebKV4UcE,2454
-langroid/agent/tools/recipient_tool.py,sha256=61vdKv06qgVdtnE3gxjzV8RvUEy8JhbC9eWa0J0BPdw,9171
+langroid/agent/tools/recipient_tool.py,sha256=NrLxIeQT-kbMv7AeYX0uqvGeMK4Q3fIDvG15OVzlgk8,9624
 langroid/agent/tools/retrieval_tool.py,sha256=6uvRNg-kG_ItPa3sF9NWkthQ5frHn8bkB1Z3GSd3Oas,836
 langroid/agent/tools/run_python_code.py,sha256=V3mHdHQYn0M0PAtyoHxjNvk6KvWWcQ4ugo0TOKc8HyI,1752
 langroid/agent/tools/segment_extract_tool.py,sha256=W39poS7Av2EuJ34tGKhLhzgj3zEyZnBplpSt2goRAp4,1285
@@ -59,6 +59,7 @@ langroid/embedding_models/protoc/embeddings_pb2.py,sha256=4Q57PhOunv-uZNJrxYrWBX
 langroid/embedding_models/protoc/embeddings_pb2.pyi,sha256=UkNy7BrNsmQm0vLb3NtGXy8jVtz-kPWwwFsX-QbQBhQ,1475
 langroid/embedding_models/protoc/embeddings_pb2_grpc.py,sha256=9dYQqkW3JPyBpSEjeGXTNpSqAkC-6FPtBHyteVob2Y8,2452
 langroid/embedding_models/remote_embeds.py,sha256=6_kjXByVbqhY9cGwl9R83ZcYC2km-nGieNNAo1McHaY,5151
+langroid/exceptions.py,sha256=aQwRVRb04flh1GVbLo3PmoIf3sP9RC7Q5gJH9aVSEkI,169
 langroid/language_models/__init__.py,sha256=5L9ndEEC8iLJHjDJmYFTnv6-2-3xsxWUMHcugR8IeDs,821
 langroid/language_models/azure_openai.py,sha256=ncRCbKooqLVOY-PWQUIo9C3yTuKEFbAwyngXT_M4P7k,5989
 langroid/language_models/base.py,sha256=2JhacnbQ-DJzLbOaJqyZPnl867xyiz_W-ODiAlEcp98,21131
@@ -70,7 +71,7 @@ langroid/language_models/prompt_formatter/base.py,sha256=eDS1sgRNZVnoajwV_ZIha6c
 langroid/language_models/prompt_formatter/hf_formatter.py,sha256=TFL6ppmeQWnzr6CKQzRZFYY810zE1mr8DZnhw6i85ok,5217
 langroid/language_models/prompt_formatter/llama2_formatter.py,sha256=YdcO88qyBeuMENVIVvVqSYuEpvYSTndUe_jd6hVTko4,2899
 langroid/language_models/utils.py,sha256=j8xEEm__-2b9eql1oTiWQk5dHW59UwmrRKs5kMHaGGo,4803
-langroid/mytypes.py,sha256=opL488mtHKob1uJeK_h1-kNjU5GZwkgCfXhBQCsONWU,2614
+langroid/mytypes.py,sha256=qD3o2v1pccICz-xeei4cwkvJviVC2llJ3eIYgBP9RDE,3045
 langroid/parsing/__init__.py,sha256=2O5HOW8nDE3v-JInc5z2wIbFGejf4h5ZTdPqxsFtaWE,870
 langroid/parsing/agent_chats.py,sha256=sbZRV9ujdM5QXvvuHVjIi2ysYSYlap-uqfMMUKulrW0,1068
 langroid/parsing/code-parsing.md,sha256=--cyyNiSZSDlIwcjAV4-shKrSiRe2ytF3AdSoS_hD2g,3294
@@ -82,6 +83,7 @@ langroid/parsing/para_sentence_split.py,sha256=AJBzZojP3zpB-_IMiiHismhqcvkrVBQ3Z
 langroid/parsing/parse_json.py,sha256=tgB_oatcrgt6L9ZplC-xBBXjLzL1gjSQf1L2_W5kwFA,4230
 langroid/parsing/parser.py,sha256=2TT6YMgEe79Kz9bPIqI-1RIEK77V2H2gbpbX5DhNNrY,10743
 langroid/parsing/repo_loader.py,sha256=My5UIe-h1xr0I-6Icu0ZVwRHmGRRRW8SrJYMc9J1M9Q,29361
+langroid/parsing/routing.py,sha256=_NFPe7wLjd5B6s47w3M8-5vldL8e2Sz51Gb5bwF5ooY,1072
 langroid/parsing/search.py,sha256=plQtjarB9afGfJLB0CyPXPq3mM4m7kRsfd0_4brziEI,8846
 langroid/parsing/spider.py,sha256=w_mHR1B4KOmxsBLoVI8kMkMTEbwTzeK3ath9fOMJrTk,3043
 langroid/parsing/table_loader.py,sha256=qNM4obT_0Y4tjrxNBCNUYjKQ9oETCZ7FbolKBTcz-GM,3410
@@ -99,7 +101,7 @@ langroid/prompts/transforms.py,sha256=GsQo1klGxUy0fACh6j0lTblk6XEl2erRnhRWlN2M4-
 langroid/utils/__init__.py,sha256=ARx5To4Hsv1K5QAzK4uUqdEoB_iq5HK797vae1AcMBI,300
 langroid/utils/algorithms/__init__.py,sha256=WylYoZymA0fnzpB4vrsH_0n7WsoLhmuZq8qxsOCjUpM,41
 langroid/utils/algorithms/graph.py,sha256=JbdpPnUOhw4-D6O7ou101JLA3xPCD0Lr3qaPoFCaRfo,2866
-langroid/utils/configuration.py,sha256=TiDZrQVeEthMFA4QY_HTgQaDCJwS4I5S-aR_taOdc00,3201
+langroid/utils/configuration.py,sha256=FvkbWf0A5iNdmtORfjlY6ZAHp4Fov_OTL6A8U4C3y-A,3282
 langroid/utils/constants.py,sha256=Y_8p7CyLF5b3xsEV5O3wuutLHQCtegsaxWgr8yNTlIE,563
 langroid/utils/docker.py,sha256=kJQOLTgM0x9j9pgIIqp0dZNZCTvoUDhp6i8tYBq1Jr0,1105
 langroid/utils/globals.py,sha256=VkTHhlqSz86oOPq65sjul0XU8I52UNaFC5vwybMQ74w,1343
@@ -111,7 +113,7 @@ langroid/utils/output/printing.py,sha256=5EsYB1O4qKhocW19aebOUzK82RD9U5nygbY21yo
 langroid/utils/output/status.py,sha256=rzbE7mDJcgNNvdtylCseQcPGCGghtJvVq3lB-OPJ49E,1049
 langroid/utils/pandas_utils.py,sha256=UctS986Jtl_MvU5rA7-GfrjEHXP7MNu8ePhepv0bTn0,755
 langroid/utils/pydantic_utils.py,sha256=yb-ghaQYL7EIYeiZ0tailvZvAuJZNF7UBXkd3z35OYc,21728
-langroid/utils/system.py,sha256=tWoEbzHzJ6ywdsoa9EwsQrZfGk2t7q87_zKNwau2C8s,4546
+langroid/utils/system.py,sha256=RfAcQODu4tjl-pAO8zZ65yKB9-6WsvzSz2dEPkJdSdw,4909
 langroid/utils/web/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 langroid/utils/web/login.py,sha256=1iz9eUAHa87vpKIkzwkmFa00avwFWivDSAr7QUhK7U0,2528
 langroid/vector_store/__init__.py,sha256=D82ioqPWxKTTbN0qiPNB-I1GjovhLw1MgDuYhcB3hCs,831
@@ -122,7 +124,7 @@ langroid/vector_store/meilisearch.py,sha256=d2huA9P-NoYRuAQ9ZeXJmMKr7ry8u90RUSR2
 langroid/vector_store/momento.py,sha256=9cui31TTrILid2KIzUpBkN2Ey3g_CZWOQVdaFsA4Ors,10045
 langroid/vector_store/qdrant_cloud.py,sha256=3im4Mip0QXLkR6wiqVsjV1QvhSElfxdFSuDKddBDQ-4,188
 langroid/vector_store/qdrantdb.py,sha256=sk5Qb2ZNbooi0rorsMuqIMokF7WADw6PJ0D6goM2XBw,16802
-langroid-0.1.250.dist-info/LICENSE,sha256=EgVbvA6VSYgUlvC3RvPKehSg7MFaxWDsFuzLOsPPfJg,1065
-langroid-0.1.250.dist-info/METADATA,sha256=FOv0qbbaZxR3TJWncDj2NvvslRp7RXOI0Xahb4yBT3I,49559
-langroid-0.1.250.dist-info/WHEEL,sha256=FMvqSimYX_P7y0a7UY-_Mc83r5zkBZsCYPm7Lr0Bsq4,88
-langroid-0.1.250.dist-info/RECORD,,
+langroid-0.1.252.dist-info/LICENSE,sha256=EgVbvA6VSYgUlvC3RvPKehSg7MFaxWDsFuzLOsPPfJg,1065
+langroid-0.1.252.dist-info/METADATA,sha256=zRgxQH1C04RM1tofjy6tNtYSE1YalSYHvqVz7oVjYU8,49559
+langroid-0.1.252.dist-info/WHEEL,sha256=FMvqSimYX_P7y0a7UY-_Mc83r5zkBZsCYPm7Lr0Bsq4,88
+langroid-0.1.252.dist-info/RECORD,,