langroid 0.1.251__py3-none-any.whl → 0.1.253__py3-none-any.whl

langroid/__init__.py

@@ -43,20 +43,6 @@ from .agent.chat_agent import (
 
 from .agent.task import Task, TaskConfig
 
-try:
-    from .agent.callbacks.chainlit import (
-        ChainlitAgentCallbacks,
-        ChainlitTaskCallbacks,
-        ChainlitCallbackConfig,
-    )
-
-    chainlit_available = True
-    ChainlitAgentCallbacks
-    ChainlitTaskCallbacks
-    ChainlitCallbackConfig
-except ImportError:
-    chainlit_available = False
-
 
 from .mytypes import (
     DocMetaData,
@@ -65,6 +51,7 @@ from .mytypes import (
 )
 
 from .exceptions import InfiniteLoopException
+from .exceptions import LangroidImportError
 
 __all__ = [
     "mytypes",
@@ -94,8 +81,20 @@ __all__ = [
     "llm_response_batch",
     "agent_response_batch",
     "InfiniteLoopException",
+    "LangroidImportError",
 ]
-if chainlit_available:
+
+
+try:
+    from .agent.callbacks.chainlit import (
+        ChainlitAgentCallbacks,
+        ChainlitTaskCallbacks,
+        ChainlitCallbackConfig,
+    )
+
+    ChainlitAgentCallbacks
+    ChainlitTaskCallbacks
+    ChainlitCallbackConfig
     __all__.extend(
         [
             "ChainlitAgentCallbacks",
@@ -103,3 +102,5 @@ if chainlit_available:
             "ChainlitCallbackConfig",
         ]
     )
+except ImportError:
+    pass

langroid/agent/__init__.py

@@ -18,6 +18,7 @@ from . import tool_message
 from . import tools
 from . import special
 
+
 __all__ = [
     "Agent",
     "AgentConfig",

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

langroid/agent/callbacks/chainlit.py

@@ -9,19 +9,12 @@ from typing import Any, Callable, Dict, List, Literal, Optional, no_type_check
 
 from pydantic import BaseSettings
 
+from langroid.exceptions import LangroidImportError
+
 try:
     import chainlit as cl
 except ImportError:
-    raise ImportError(
-        """
-        You are attempting to use `chainlit`, which is not installed 
-        by default with `langroid`.
-        Please install langroid with the `chainlit` extra using:
-        `pip install langroid[chainlit]` or 
-        `poetry install -E chainlit`
-        depending on your scenario
-        """
-    )
+    raise LangroidImportError("chainlit", "chainlit")
 
 from chainlit import run_sync
 from chainlit.config import config
@@ -83,9 +76,9 @@ async def setup_llm() -> None:
 
 
 @no_type_check
-async def update_llm(settings: Dict[str, Any]) -> None:
+async def update_llm(new_settings: Dict[str, Any]) -> None:
     """Update LLMConfig and LLM from settings, and save in session state."""
-    cl.user_session.set("llm_settings", settings)
+    cl.user_session.set("llm_settings", new_settings)
     await inform_llm_settings()
     await setup_llm()
 

langroid/agent/special/__init__.py

@@ -25,6 +25,7 @@ from . import lance_doc_chat_agent
 from . import lance_rag
 from . import table_chat_agent
 
+
 __all__ = [
     "RelevanceExtractorAgent",
     "RelevanceExtractorAgentConfig",
@@ -34,7 +35,6 @@ __all__ = [
     "RecordDoc",
     "RetrieverAgentConfig",
     "RetrieverAgent",
-    "LanceDocChatAgent",
     "dataframe_summary",
     "TableChatAgent",
     "TableChatAgentConfig",
@@ -43,8 +43,9 @@ __all__ = [
     "relevance_extractor_agent",
     "doc_chat_agent",
     "retriever_agent",
+    "table_chat_agent",
+    "LanceDocChatAgent",
     "lance_tools",
     "lance_doc_chat_agent",
     "lance_rag",
-    "table_chat_agent",
 ]

langroid/agent/special/doc_chat_agent.py

@@ -31,7 +31,10 @@ from langroid.agent.special.relevance_extractor_agent import (
 )
 from langroid.agent.task import Task
 from langroid.agent.tools.retrieval_tool import RetrievalTool
-from langroid.embedding_models.models import OpenAIEmbeddingsConfig
+from langroid.embedding_models.models import (
+    OpenAIEmbeddingsConfig,
+    SentenceTransformerEmbeddingsConfig,
+)
 from langroid.language_models.base import StreamingIfAllowed
 from langroid.language_models.openai_gpt import OpenAIChatModel, OpenAIGPTConfig
 from langroid.mytypes import DocMetaData, Document, Entity
@@ -51,9 +54,13 @@ from langroid.prompts.prompts_config import PromptsConfig
 from langroid.prompts.templates import SUMMARY_ANSWER_PROMPT_GPT4
 from langroid.utils.constants import NO_ANSWER
 from langroid.utils.output import show_if_debug, status
+from langroid.utils.output.citations import (
+    extract_markdown_references,
+    format_footnote_text,
+)
 from langroid.utils.pydantic_utils import dataframe_to_documents, extract_fields
 from langroid.vector_store.base import VectorStore, VectorStoreConfig
-from langroid.vector_store.lancedb import LanceDBConfig
+from langroid.vector_store.qdrantdb import QdrantDBConfig
 
 
 @cache
@@ -82,47 +89,36 @@ except ImportError:
     pass
 
 
-def extract_markdown_references(md_string: str) -> list[int]:
-    """
-    Extracts markdown references (e.g., [^1], [^2]) from a string and returns
-    them as a sorted list of integers.
-
-    Args:
-        md_string (str): The markdown string containing references.
-
-    Returns:
-        list[int]: A sorted list of unique integers from the markdown references.
-    """
-    import re
-
-    # Regex to find all occurrences of [^<number>]
-    matches = re.findall(r"\[\^(\d+)\]", md_string)
-    # Convert matches to integers, remove duplicates with set, and sort
-    return sorted(set(int(match) for match in matches))
+hf_embed_config = SentenceTransformerEmbeddingsConfig(
+    model_type="sentence-transformer",
+    model_name="BAAI/bge-large-en-v1.5",
+)
 
+oai_embed_config = OpenAIEmbeddingsConfig(
+    model_type="openai",
+    model_name="text-embedding-ada-002",
+    dims=1536,
+)
 
-def format_footnote_text(content: str, width: int = 80) -> str:
-    """
-    Formats the content part of a footnote (i.e. not the first line that
-    appears right after the reference [^4])
-    It wraps the text so that no line is longer than the specified width and indents
-    lines as necessary for markdown footnotes.
+vecdb_config: VectorStoreConfig = QdrantDBConfig(
+    collection_name="doc-chat-qdrantdb",
+    replace_collection=True,
+    storage_path=".qdrantdb/data/",
+    embedding=hf_embed_config if has_sentence_transformers else oai_embed_config,
+)
 
-    Args:
-        content (str): The text of the footnote to be formatted.
-        width (int): Maximum width of the text lines.
+try:
+    from langroid.vector_store.lancedb import LanceDBConfig
 
-    Returns:
-        str: Properly formatted markdown footnote text.
-    """
-    import textwrap
+    vecdb_config = LanceDBConfig(
+        collection_name="doc-chat-lancedb",
+        replace_collection=True,
+        storage_path=".lancedb/data/",
+        embedding=(hf_embed_config if has_sentence_transformers else oai_embed_config),
+    )
 
-    # Wrap the text to the specified width
-    wrapped_lines = textwrap.wrap(content, width)
-    if len(wrapped_lines) == 0:
-        return ""
-    indent = "    "  # Indentation for markdown footnotes
-    return indent + ("\n" + indent).join(wrapped_lines)
+except ImportError:
+    pass
 
 
 class DocChatAgentConfig(ChatAgentConfig):
@@ -199,26 +195,10 @@ class DocChatAgentConfig(ChatAgentConfig):
             library="pdfplumber",
         ),
     )
-    from langroid.embedding_models.models import SentenceTransformerEmbeddingsConfig
-
-    hf_embed_config = SentenceTransformerEmbeddingsConfig(
-        model_type="sentence-transformer",
-        model_name="BAAI/bge-large-en-v1.5",
-    )
-
-    oai_embed_config = OpenAIEmbeddingsConfig(
-        model_type="openai",
-        model_name="text-embedding-ada-002",
-        dims=1536,
-    )
 
     # Allow vecdb to be None in case we want to explicitly set it later
-    vecdb: Optional[VectorStoreConfig] = LanceDBConfig(
-        collection_name="doc-chat-lancedb",
-        replace_collection=True,
-        storage_path=".lancedb/data/",
-        embedding=hf_embed_config if has_sentence_transformers else oai_embed_config,
-    )
+    vecdb: Optional[VectorStoreConfig] = vecdb_config
+
     llm: OpenAIGPTConfig = OpenAIGPTConfig(
         type="openai",
         chat_model=OpenAIChatModel.GPT4,

langroid/agent/special/neo4j/csv_kg_chat.py

@@ -1,4 +1,4 @@
-from typing import List, Optional
+from typing import List, Optional, Tuple
 
 import pandas as pd
 import typer
@@ -105,7 +105,7 @@ class PandasToKGTool(ToolMessage):
     args: list[str]
 
     @classmethod
-    def examples(cls) -> List["ToolMessage"]:
+    def examples(cls) -> List["ToolMessage" | Tuple[str, "ToolMessage"]]:
         return [
             cls(
                 cypherQuery="""MERGE (employee:Employee {name: $employeeName, 

langroid/agent/special/sql/__init__.py

@@ -1,7 +1,6 @@
+from . import sql_chat_agent, utils
 from .sql_chat_agent import SQLChatAgentConfig, SQLChatAgent
 
-from . import sql_chat_agent
-from . import utils
 
 __all__ = [
     "SQLChatAgentConfig",

langroid/agent/special/sql/sql_chat_agent.py

@@ -12,10 +12,16 @@ from typing import Any, Dict, List, Optional, Sequence, Union
 
 from rich import print
 from rich.console import Console
-from sqlalchemy import MetaData, Row, create_engine, inspect, text
-from sqlalchemy.engine import Engine
-from sqlalchemy.exc import SQLAlchemyError
-from sqlalchemy.orm import Session, sessionmaker
+
+from langroid.exceptions import LangroidImportError
+
+try:
+    from sqlalchemy import MetaData, Row, create_engine, inspect, text
+    from sqlalchemy.engine import Engine
+    from sqlalchemy.exc import SQLAlchemyError
+    from sqlalchemy.orm import Session, sessionmaker
+except ImportError as e:
+    raise LangroidImportError(extra="sql", error=str(e))
 
 from langroid.agent.chat_agent import ChatAgent, ChatAgentConfig
 from langroid.agent.chat_document import ChatDocMetaData, ChatDocument

langroid/agent/special/sql/utils/__init__.py

@@ -1,3 +1,7 @@
+from . import tools
+from . import description_extractors
+from . import populate_metadata
+from . import system_message
 from .tools import (
     RunQueryTool,
     GetTableNamesTool,
@@ -5,11 +9,6 @@ from .tools import (
     GetColumnDescriptionsTool,
 )
 
-from . import description_extractors
-from . import populate_metadata
-from . import system_message
-from . import tools
-
 __all__ = [
     "RunQueryTool",
     "GetTableNamesTool",

langroid/agent/special/sql/utils/description_extractors.py

@@ -1,7 +1,12 @@
 from typing import Any, Dict, List, Optional
 
-from sqlalchemy import inspect, text
-from sqlalchemy.engine import Engine
+from langroid.exceptions import LangroidImportError
+
+try:
+    from sqlalchemy import inspect, text
+    from sqlalchemy.engine import Engine
+except ImportError as e:
+    raise LangroidImportError(extra="sql", error=str(e))
 
 
 def extract_postgresql_descriptions(

langroid/agent/special/sql/utils/populate_metadata.py

@@ -1,6 +1,11 @@
 from typing import Dict, List, Union
 
-from sqlalchemy import MetaData
+from langroid.exceptions import LangroidImportError
+
+try:
+    from sqlalchemy import MetaData
+except ImportError as e:
+    raise LangroidImportError(extra="sql", error=str(e))
 
 
 def populate_metadata_with_schema_tools(

langroid/agent/special/table_chat_agent.py

@@ -12,7 +12,7 @@ the expression and returns the result as a string.
 import io
 import logging
 import sys
-from typing import List, Optional, no_type_check
+from typing import List, Optional, Tuple, no_type_check
 
 import numpy as np
 import pandas as pd
@@ -138,7 +138,7 @@ class PandasEvalTool(ToolMessage):
     expression: str
 
     @classmethod
-    def examples(cls) -> List["ToolMessage"]:
+    def examples(cls) -> List["ToolMessage" | Tuple[str, "ToolMessage"]]:
         return [
             cls(expression="df.head()"),
             cls(expression="df[(df['gender'] == 'Male')]['income'].mean()"),

langroid/agent/task.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import asyncio
 import copy
 import logging
 from collections import Counter, deque
@@ -59,13 +60,18 @@ def noop_fn(*args: List[Any], **kwargs: Dict[str, Any]) -> None:
 
 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 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."""
+    we have config classes for `Agent`, `ChatAgent`, `LanguageModel`, etc.
 
-    inf_loop_cycle_len: int = 10  # max exact-loop cycle length: 0 => no inf loop test
-    inf_loop_dominance_factor: float = 1.5  # dominance factor for exact-loop detection
-    # wait this * cycle_len msgs before checking for loop
+    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
 
 
@@ -517,7 +523,12 @@ class Task:
                 and i % self.config.inf_loop_cycle_len == 0
                 and self._maybe_infinite_loop()
             ):
-                raise InfiniteLoopException("Possible infinite loop detected!")
+                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:
@@ -587,6 +598,7 @@ 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:
@@ -606,7 +618,12 @@ class Task:
                 and i % self.config.inf_loop_cycle_len == 0
                 and self._maybe_infinite_loop()
             ):
-                raise InfiniteLoopException("Possible infinite loop detected!")
+                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:
@@ -1122,7 +1139,7 @@ class Task:
             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 in the plot, from m to m+1.
+            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,

langroid/agent/tool_message.py

@@ -10,7 +10,7 @@ import json
 import textwrap
 from abc import ABC
 from random import choice
-from typing import Any, Dict, List, Type
+from typing import Any, Dict, List, Tuple, Type
 
 from docstring_parser import parse
 from pydantic import BaseModel
@@ -65,9 +65,16 @@ class ToolMessage(ABC, BaseModel):
         return ToolMessageWithRecipient
 
     @classmethod
-    def examples(cls) -> List["ToolMessage"]:
+    def examples(cls) -> List["ToolMessage" | Tuple[str, "ToolMessage"]]:
         """
         Examples to use in few-shot demos with JSON formatting instructions.
+        Each example can be either:
+        - just a ToolMessage instance, e.g. MyTool(param1=1, param2="hello"), or
+        - a tuple (description, ToolMessage instance), where the description is
+            a natural language "thought" that leads to the tool usage,
+            e.g. ("I want to find the square of 5",  SquareTool(num=5))
+            In some scenarios, ncluding such a description can significantly
+            enhance reliability of tool use.
         Returns:
         """
         return []
@@ -83,7 +90,11 @@ class ToolMessage(ABC, BaseModel):
         if len(cls.examples()) == 0:
             return ""
         ex = choice(cls.examples())
-        return ex.json_example()
+        if isinstance(ex, tuple):
+            # (description, example_instance)
+            return f"{ex[0]} => {ex[1].json_example()}"
+        else:
+            return ex.json_example()
 
     def to_json(self) -> str:
         return self.json(indent=4, exclude={"result", "purpose"})

langroid/agent/tools/__init__.py

@@ -1,8 +1,7 @@
-from .google_search_tool import GoogleSearchTool
-from .recipient_tool import AddRecipientTool, RecipientTool
-
 from . import google_search_tool
 from . import recipient_tool
+from .google_search_tool import GoogleSearchTool
+from .recipient_tool import AddRecipientTool, RecipientTool
 
 __all__ = [
     "GoogleSearchTool",

langroid/agent/tools/duckduckgo_search_tool.py

@@ -5,7 +5,7 @@ access to agent state), it can be enabled for any agent, without having to defin
 special method inside the agent: `agent.enable_message(DuckduckgoSearchTool)`
 """
 
-from typing import List
+from typing import List, Tuple
 
 from langroid.agent.tool_message import ToolMessage
 from langroid.parsing.web_search import duckduckgo_search
@@ -41,7 +41,7 @@ class DuckduckgoSearchTool(ToolMessage):
         """
 
     @classmethod
-    def examples(cls) -> List["ToolMessage"]:
+    def examples(cls) -> List["ToolMessage" | Tuple[str, "ToolMessage"]]:
         return [
             cls(
                 query="When was the Llama2 Large Language Model (LLM) released?",

langroid/agent/tools/google_search_tool.py

@@ -9,7 +9,7 @@ environment variables in your `.env` file, as explained in the
 [README](https://github.com/langroid/langroid#gear-installation-and-setup).
 """
 
-from typing import List
+from typing import List, Tuple
 
 from langroid.agent.tool_message import ToolMessage
 from langroid.parsing.web_search import google_search
@@ -30,7 +30,7 @@ class GoogleSearchTool(ToolMessage):
         return "\n\n".join(str(result) for result in search_results)
 
     @classmethod
-    def examples(cls) -> List["ToolMessage"]:
+    def examples(cls) -> List["ToolMessage" | Tuple[str, "ToolMessage"]]:
         return [
             cls(
                 query="When was the Llama2 Large Language Model (LLM) released?",

langroid/agent/tools/metaphor_search_tool.py

@@ -21,7 +21,7 @@ For more information, please refer to the official docs:
 https://metaphor.systems/
 """
 
-from typing import List
+from typing import List, Tuple
 
 from langroid.agent.tool_message import ToolMessage
 from langroid.parsing.web_search import metaphor_search
@@ -58,7 +58,7 @@ class MetaphorSearchTool(ToolMessage):
         """
 
     @classmethod
-    def examples(cls) -> List["ToolMessage"]:
+    def examples(cls) -> List["ToolMessage" | Tuple[str, "ToolMessage"]]:
         return [
             cls(
                 query="When was the Llama2 Large Language Model (LLM) released?",

langroid/agent/tools/retrieval_tool.py

@@ -1,4 +1,4 @@
-from typing import List
+from typing import List, Tuple
 
 from langroid.agent.tool_message import ToolMessage
 
@@ -16,7 +16,7 @@ class RetrievalTool(ToolMessage):
     num_results: int
 
     @classmethod
-    def examples(cls) -> List["ToolMessage"]:
+    def examples(cls) -> List["ToolMessage" | Tuple[str, "ToolMessage"]]:
         return [
             cls(
                 query="What are the eligibility criteria for the scholarship?",

langroid/agent/tools/run_python_code.py

@@ -1,6 +1,6 @@
 import io
 import sys
-from typing import List
+from typing import List, Tuple
 
 from langroid.agent.tool_message import ToolMessage
 
@@ -19,7 +19,7 @@ class RunPythonCodeTool(ToolMessage):
     code: str
 
     @classmethod
-    def examples(cls) -> List["ToolMessage"]:
+    def examples(cls) -> List["ToolMessage" | Tuple[str, "ToolMessage"]]:
         return [
             cls(code="import numpy as np\nnp.square(9)"),
         ]

langroid/agent/tools/segment_extract_tool.py

@@ -10,7 +10,7 @@ This will usually be much cheaper and faster than actually writing out the extra
 text. The handler of this tool/function will then extract the text and send it back.
 """
 
-from typing import List
+from typing import List, Tuple
 
 from langroid.agent.tool_message import ToolMessage
 
@@ -25,7 +25,7 @@ class SegmentExtractTool(ToolMessage):
     segment_list: str
 
     @classmethod
-    def examples(cls) -> List["ToolMessage"]:
+    def examples(cls) -> List["ToolMessage" | Tuple[str, "ToolMessage"]]:
         return [cls(segment_list="1,3,5-7")]
 
     @classmethod

langroid/cachedb/base.py

@@ -1,18 +1,26 @@
 from abc import ABC, abstractmethod
 from typing import Any, Dict, List
 
+from pydantic import BaseSettings
+
+
+class CacheDBConfig(BaseSettings):
+    """Configuration model for CacheDB."""
+
+    pass
+
 
 class CacheDB(ABC):
     """Abstract base class for a cache database."""
 
     @abstractmethod
-    def store(self, key: str, value: Dict[str, Any]) -> None:
+    def store(self, key: str, value: Any) -> None:
         """
         Abstract method to store a value associated with a key.
 
         Args:
             key (str): The key under which to store the value.
-            value (dict): The value to store.
+            value (Any): The value to store.
         """
         pass