letta-nightly 0.5.5.dev20241122170833__py3-none-any.whl → 0.6.0.dev20241204051808__py3-none-any.whl

letta/config.py

@@ -16,7 +16,7 @@ from letta.constants import (
     LETTA_DIR,
 )
 from letta.log import get_logger
-from letta.schemas.agent import AgentState
+from letta.schemas.agent import PersistedAgentState
 from letta.schemas.embedding_config import EmbeddingConfig
 from letta.schemas.llm_config import LLMConfig
 
@@ -434,7 +434,7 @@ class AgentConfig:
             json.dump(vars(self), f, indent=4)
 
     def to_agent_state(self):
-        return AgentState(
+        return PersistedAgentState(
             name=self.name,
             preset=self.preset,
             persona=self.persona,

letta/constants.py

@@ -36,14 +36,10 @@ DEFAULT_PERSONA = "sam_pov"
 DEFAULT_HUMAN = "basic"
 DEFAULT_PRESET = "memgpt_chat"
 
-# Tools
-BASE_TOOLS = [
-    "send_message",
-    "conversation_search",
-    "conversation_search_date",
-    "archival_memory_insert",
-    "archival_memory_search",
-]
+# Base tools that cannot be edited, as they access agent state directly
+BASE_TOOLS = ["send_message", "conversation_search", "conversation_search_date", "archival_memory_insert", "archival_memory_search"]
+# Base memory tools CAN be edited, and are added by default by the server
+BASE_MEMORY_TOOLS = ["core_memory_append", "core_memory_replace"]
 
 # The name of the tool used to send message to the user
 # May not be relevant in cases where the agent has multiple ways to message to user (send_imessage, send_discord_mesasge, ...)
@@ -133,9 +129,13 @@ MESSAGE_SUMMARY_REQUEST_ACK = "Understood, I will respond with a summary of the
 # These serve as in-context examples of how to use functions / what user messages look like
 MESSAGE_SUMMARY_TRUNC_KEEP_N_LAST = 3
 
+# Maximum length of an error message
+MAX_ERROR_MESSAGE_CHAR_LIMIT = 500
+
 # Default memory limits
-CORE_MEMORY_PERSONA_CHAR_LIMIT = 2000
-CORE_MEMORY_HUMAN_CHAR_LIMIT = 2000
+CORE_MEMORY_PERSONA_CHAR_LIMIT: int = 5000
+CORE_MEMORY_HUMAN_CHAR_LIMIT: int = 5000
+CORE_MEMORY_BLOCK_CHAR_LIMIT: int = 5000
 
 # Function return limits
 FUNCTION_RETURN_CHAR_LIMIT = 6000  # ~300 words
@@ -155,9 +155,5 @@ FUNC_FAILED_HEARTBEAT_MESSAGE = f"{NON_USER_MSG_PREFIX}Function call failed, ret
 
 RETRIEVAL_QUERY_DEFAULT_PAGE_SIZE = 5
 
-# TODO Is this config or constant?
-CORE_MEMORY_PERSONA_CHAR_LIMIT: int = 2000
-CORE_MEMORY_HUMAN_CHAR_LIMIT: int = 2000
-
 MAX_FILENAME_LENGTH = 255
 RESERVED_FILENAMES = {"CON", "PRN", "AUX", "NUL", "COM1", "COM2", "LPT1", "LPT2"}

letta/errors.py

@@ -10,6 +10,18 @@ class LettaError(Exception):
     """Base class for all Letta related errors."""
 
 
+class LettaToolCreateError(LettaError):
+    """Error raised when a tool cannot be created."""
+
+    default_error_message = "Error creating tool."
+
+    def __init__(self, message=None):
+        if message is None:
+            message = self.default_error_message
+        self.message = message
+        super().__init__(self.message)
+
+
 class LLMError(LettaError):
     pass
 

letta/functions/function_sets/base.py

@@ -11,7 +11,7 @@ from letta.constants import MAX_PAUSE_HEARTBEATS
 # If the function fails, throw an exception
 
 
-def send_message(self: Agent, message: str) -> Optional[str]:
+def send_message(self: "Agent", message: str) -> Optional[str]:
     """
     Sends a message to the human user.
 
@@ -172,3 +172,40 @@ def archival_memory_search(self: Agent, query: str, page: Optional[int] = 0) ->
         results_formatted = [f"timestamp: {d['timestamp']}, memory: {d['content']}" for d in results]
         results_str = f"{results_pref} {json_dumps(results_formatted)}"
     return results_str
+
+
+def core_memory_append(agent_state: "AgentState", label: str, content: str) -> Optional[str]:  # type: ignore
+    """
+    Append to the contents of core memory.
+
+    Args:
+        label (str): Section of the memory to be edited (persona or human).
+        content (str): Content to write to the memory. All unicode (including emojis) are supported.
+
+    Returns:
+        Optional[str]: None is always returned as this function does not produce a response.
+    """
+    current_value = str(agent_state.memory.get_block(label).value)
+    new_value = current_value + "\n" + str(content)
+    agent_state.memory.update_block_value(label=label, value=new_value)
+    return None
+
+
+def core_memory_replace(agent_state: "AgentState", label: str, old_content: str, new_content: str) -> Optional[str]:  # type: ignore
+    """
+    Replace the contents of core memory. To delete memories, use an empty string for new_content.
+
+    Args:
+        label (str): Section of the memory to be edited (persona or human).
+        old_content (str): String to replace. Must be an exact match.
+        new_content (str): Content to write to the memory. All unicode (including emojis) are supported.
+
+    Returns:
+        Optional[str]: None is always returned as this function does not produce a response.
+    """
+    current_value = str(agent_state.memory.get_block(label).value)
+    if old_content not in current_value:
+        raise ValueError(f"Old content '{old_content}' not found in memory block '{label}'")
+    new_value = current_value.replace(str(old_content), str(new_content))
+    agent_state.memory.update_block_value(label=label, value=new_value)
+    return None

letta/functions/functions.py

@@ -1,35 +1,61 @@
-import importlib
 import inspect
-import os
 from textwrap import dedent  # remove indentation
 from types import ModuleType
-from typing import Optional, List
+from typing import Dict, List, Optional
 
-from letta.constants import CLI_WARNING_PREFIX
+from letta.errors import LettaToolCreateError
 from letta.functions.schema_generator import generate_schema
 
 
 def derive_openai_json_schema(source_code: str, name: Optional[str] = None) -> dict:
-    # auto-generate openai schema
+    """Derives the OpenAI JSON schema for a given function source code.
+
+    First, attempts to execute the source code in a custom environment with only the necessary imports.
+    Then, it generates the schema from the function's docstring and signature.
+    """
     try:
         # Define a custom environment with necessary imports
         env = {
-            "Optional": Optional,  # Add any other required imports here
-            "List": List
+            "Optional": Optional,
+            "List": List,
+            "Dict": Dict,
+            # To support Pydantic models
+            # "BaseModel": BaseModel,
+            # "Field": Field,
         }
-
         env.update(globals())
+
+        # print("About to execute source code...")
         exec(source_code, env)
+        # print("Source code executed successfully")
 
-        # get available functions
-        functions = [f for f in env if callable(env[f])]
+        functions = [f for f in env if callable(env[f]) and not f.startswith("__")]
+        if not functions:
+            raise LettaToolCreateError("No callable functions found in source code")
 
-        # TODO: not sure if this always works
+        # print(f"Found functions: {functions}")
         func = env[functions[-1]]
-        json_schema = generate_schema(func, name=name)
-        return json_schema
+
+        if not hasattr(func, "__doc__") or not func.__doc__:
+            raise LettaToolCreateError(f"Function {func.__name__} missing docstring")
+
+        # print("About to generate schema...")
+        try:
+            schema = generate_schema(func, name=name)
+            # print("Schema generated successfully")
+            return schema
+        except TypeError as e:
+            raise LettaToolCreateError(f"Type error in schema generation: {str(e)}")
+        except ValueError as e:
+            raise LettaToolCreateError(f"Value error in schema generation: {str(e)}")
+        except Exception as e:
+            raise LettaToolCreateError(f"Unexpected error in schema generation: {str(e)}")
+
     except Exception as e:
-        raise RuntimeError(f"Failed to execute source code: {e}")
+        import traceback
+
+        traceback.print_exc()
+        raise LettaToolCreateError(f"Schema generation failed: {str(e)}") from e
 
 
 def parse_source_code(func) -> str:
@@ -61,46 +87,3 @@ def load_function_set(module: ModuleType) -> dict:
     if len(function_dict) == 0:
         raise ValueError(f"No functions found in module {module}")
     return function_dict
-
-
-def validate_function(module_name, module_full_path):
-    try:
-        file = os.path.basename(module_full_path)
-        spec = importlib.util.spec_from_file_location(module_name, module_full_path)
-        module = importlib.util.module_from_spec(spec)
-        spec.loader.exec_module(module)
-    except ModuleNotFoundError as e:
-        # Handle missing module imports
-        missing_package = str(e).split("'")[1]  # Extract the name of the missing package
-        print(f"{CLI_WARNING_PREFIX}skipped loading python file '{module_full_path}'!")
-        return (
-            False,
-            f"'{file}' imports '{missing_package}', but '{missing_package}' is not installed locally - install python package '{missing_package}' to link functions from '{file}' to Letta.",
-        )
-    except SyntaxError as e:
-        # Handle syntax errors in the module
-        return False, f"{CLI_WARNING_PREFIX}skipped loading python file '{file}' due to a syntax error: {e}"
-    except Exception as e:
-        # Handle other general exceptions
-        return False, f"{CLI_WARNING_PREFIX}skipped loading python file '{file}': {e}"
-
-    return True, None
-
-
-def load_function_file(filepath: str) -> dict:
-    file = os.path.basename(filepath)
-    module_name = file[:-3]  # Remove '.py' from filename
-    try:
-        spec = importlib.util.spec_from_file_location(module_name, filepath)
-        module = importlib.util.module_from_spec(spec)
-        spec.loader.exec_module(module)
-    except ModuleNotFoundError as e:
-        # Handle missing module imports
-        missing_package = str(e).split("'")[1]  # Extract the name of the missing package
-        print(f"{CLI_WARNING_PREFIX}skipped loading python file '{filepath}'!")
-        print(
-            f"'{file}' imports '{missing_package}', but '{missing_package}' is not installed locally - install python package '{missing_package}' to link functions from '{file}' to Letta."
-        )
-    # load all functions in the module
-    function_dict = load_function_set(module)
-    return function_dict

letta/functions/helpers.py

@@ -13,8 +13,6 @@ def generate_composio_tool_wrapper(action: "ActionType") -> tuple[str, str]:
 
     wrapper_function_str = f"""
 def {func_name}(**kwargs):
-    if 'self' in kwargs:
-        del kwargs['self']
     from composio import Action, App, Tag
     from composio_langchain import ComposioToolSet
 
@@ -46,8 +44,6 @@ def generate_langchain_tool_wrapper(
     # Combine all parts into the wrapper function
     wrapper_function_str = f"""
 def {func_name}(**kwargs):
-    if 'self' in kwargs:
-        del kwargs['self']
     import importlib
     {import_statement}
     {extra_module_imports}

letta/functions/schema_generator.py

@@ -1,5 +1,5 @@
 import inspect
-from typing import Any, Dict, Optional, Type, Union, get_args, get_origin
+from typing import Any, Dict, List, Optional, Type, Union, get_args, get_origin
 
 from docstring_parser import parse
 from pydantic import BaseModel
@@ -22,7 +22,7 @@ def optional_length(annotation):
         raise ValueError("The annotation is not an Optional type")
 
 
-def type_to_json_schema_type(py_type):
+def type_to_json_schema_type(py_type) -> dict:
     """
     Maps a Python type to a JSON schema type.
     Specifically handles typing.Optional and common Python types.
@@ -36,22 +36,87 @@ def type_to_json_schema_type(py_type):
         # Extract and map the inner type
         return type_to_json_schema_type(type_args[0])
 
+    # Handle Union types (except Optional which is handled above)
+    if get_origin(py_type) is Union:
+        # TODO support mapping Unions to anyOf
+        raise NotImplementedError("General Union types are not yet supported")
+
+    # Handle array types
+    origin = get_origin(py_type)
+    if py_type == list or origin in (list, List):
+        args = get_args(py_type)
+
+        if args and inspect.isclass(args[0]) and issubclass(args[0], BaseModel):
+            # If it's a list of Pydantic models, return an array with the model schema as items
+            return {
+                "type": "array",
+                "items": pydantic_model_to_json_schema(args[0]),
+            }
+
+        # Otherwise, recursively call the basic type checker
+        return {
+            "type": "array",
+            # get the type of the items in the list
+            "items": type_to_json_schema_type(args[0]),
+        }
+
+    # Handle object types
+    if py_type == dict or origin in (dict, Dict):
+        args = get_args(py_type)
+        if not args:
+            # Generic dict without type arguments
+            return {
+                "type": "object",
+                # "properties": {}
+            }
+        else:
+            raise ValueError(
+                f"Dictionary types {py_type} with nested type arguments are not supported (consider using a Pydantic model instead)"
+            )
+
+        # NOTE: the below code works for generic JSON schema parsing, but there's a problem with the key inference
+        #       when it comes to OpenAI function schema generation so it doesn't make sense to allow for dict[str, Any] type hints
+        # key_type, value_type = args
+
+        # # Ensure dict keys are strings
+        # # Otherwise there's no JSON schema equivalent
+        # if key_type != str:
+        #     raise ValueError("Dictionary keys must be strings for OpenAI function schema compatibility")
+
+        # # Handle value type to determine property schema
+        # value_schema = {}
+        # if inspect.isclass(value_type) and issubclass(value_type, BaseModel):
+        #     value_schema = pydantic_model_to_json_schema(value_type)
+        # else:
+        #     value_schema = type_to_json_schema_type(value_type)
+
+        # # NOTE: the problem lies here - the key is always "key_placeholder"
+        # return {"type": "object", "properties": {"key_placeholder": value_schema}}
+
+    # Handle direct Pydantic models
+    if inspect.isclass(py_type) and issubclass(py_type, BaseModel):
+        return pydantic_model_to_json_schema(py_type)
+
     # Mapping of Python types to JSON schema types
     type_map = {
+        # Basic types
+        # Optional, Union, and collections are handled above ^
         int: "integer",
         str: "string",
         bool: "boolean",
         float: "number",
-        list[str]: "array",
-        # Add more mappings as needed
+        None: "null",
     }
     if py_type not in type_map:
-        raise ValueError(f"Python type {py_type} has no corresponding JSON schema type")
-
-    return type_map.get(py_type, "string")  # Default to "string" if type not in map
+        raise ValueError(f"Python type {py_type} has no corresponding JSON schema type - full map: {type_map}")
+    else:
+        return {"type": type_map[py_type]}
 
 
-def pydantic_model_to_open_ai(model):
+def pydantic_model_to_open_ai(model: Type[BaseModel]) -> dict:
+    """
+    Converts a Pydantic model as a singular arg to a JSON schema object for use in OpenAI function calling.
+    """
     schema = model.model_json_schema()
     docstring = parse(model.__doc__ or "")
     parameters = {k: v for k, v in schema.items() if k not in ("title", "description")}
@@ -66,7 +131,7 @@ def pydantic_model_to_open_ai(model):
         if docstring.short_description:
             schema["description"] = docstring.short_description
         else:
-            raise
+            raise ValueError(f"No description found in docstring or description field (model: {model}, docstring: {docstring})")
 
     return {
         "name": schema["title"],
@@ -75,6 +140,159 @@ def pydantic_model_to_open_ai(model):
     }
 
 
+def pydantic_model_to_json_schema(model: Type[BaseModel]) -> dict:
+    """
+    Converts a Pydantic model (as an arg that already is annotated) to a JSON schema object for use in OpenAI function calling.
+
+    An example of a Pydantic model as an arg:
+
+    class Step(BaseModel):
+        name: str = Field(
+            ...,
+            description="Name of the step.",
+        )
+        key: str = Field(
+            ...,
+            description="Unique identifier for the step.",
+        )
+        description: str = Field(
+            ...,
+            description="An exhaustic description of what this step is trying to achieve and accomplish.",
+        )
+
+    def create_task_plan(steps: list[Step]):
+        '''
+        Creates a task plan for the current task.
+
+        Args:
+            steps: List of steps to add to the task plan.
+        ...
+
+    Should result in:
+    {
+      "name": "create_task_plan",
+      "description": "Creates a task plan for the current task.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "steps": {  # <= this is the name of the arg
+            "type": "object",
+            "description": "List of steps to add to the task plan.",
+            "properties": {
+              "name": {
+                "type": "str",
+                "description": "Name of the step.",
+              },
+              "key": {
+                "type": "str",
+                "description": "Unique identifier for the step.",
+              },
+              "description": {
+                "type": "str",
+                "description": "An exhaustic description of what this step is trying to achieve and accomplish.",
+              },
+            },
+            "required": ["name", "key", "description"],
+          }
+        },
+        "required": ["steps"],
+      }
+    }
+
+    Specifically, the result of pydantic_model_to_json_schema(steps) (where `steps` is an instance of BaseModel) is:
+    {
+        "type": "object",
+        "properties": {
+            "name": {
+                "type": "str",
+                "description": "Name of the step."
+            },
+            "key": {
+                "type": "str",
+                "description": "Unique identifier for the step."
+            },
+            "description": {
+                "type": "str",
+                "description": "An exhaustic description of what this step is trying to achieve and accomplish."
+            },
+        },
+        "required": ["name", "key", "description"],
+    }
+    """
+    schema = model.model_json_schema()
+
+    def clean_property(prop: dict) -> dict:
+        """Clean up a property schema to match desired format"""
+
+        if "description" not in prop:
+            raise ValueError(f"Property {prop} lacks a 'description' key")
+
+        return {
+            "type": "string" if prop["type"] == "string" else prop["type"],
+            "description": prop["description"],
+        }
+
+    def resolve_ref(ref: str, schema: dict) -> dict:
+        """Resolve a $ref reference in the schema"""
+        if not ref.startswith("#/$defs/"):
+            raise ValueError(f"Unexpected reference format: {ref}")
+
+        model_name = ref.split("/")[-1]
+        if model_name not in schema.get("$defs", {}):
+            raise ValueError(f"Reference {model_name} not found in schema definitions")
+
+        return schema["$defs"][model_name]
+
+    def clean_schema(schema_part: dict, full_schema: dict) -> dict:
+        """Clean up a schema part, handling references and nested structures"""
+        # Handle $ref
+        if "$ref" in schema_part:
+            schema_part = resolve_ref(schema_part["$ref"], full_schema)
+
+        if "type" not in schema_part:
+            raise ValueError(f"Schema part lacks a 'type' key: {schema_part}")
+
+        # Handle array type
+        if schema_part["type"] == "array":
+            items_schema = schema_part["items"]
+            if "$ref" in items_schema:
+                items_schema = resolve_ref(items_schema["$ref"], full_schema)
+            return {"type": "array", "items": clean_schema(items_schema, full_schema), "description": schema_part.get("description", "")}
+
+        # Handle object type
+        if schema_part["type"] == "object":
+            if "properties" not in schema_part:
+                raise ValueError(f"Object schema lacks 'properties' key: {schema_part}")
+
+            properties = {}
+            for name, prop in schema_part["properties"].items():
+                if "items" in prop:  # Handle arrays
+                    if "description" not in prop:
+                        raise ValueError(f"Property {prop} lacks a 'description' key")
+                    properties[name] = {
+                        "type": "array",
+                        "items": clean_schema(prop["items"], full_schema),
+                        "description": prop["description"],
+                    }
+                else:
+                    properties[name] = clean_property(prop)
+
+            pydantic_model_schema_dict = {
+                "type": "object",
+                "properties": properties,
+                "required": schema_part.get("required", []),
+            }
+            if "description" in schema_part:
+                pydantic_model_schema_dict["description"] = schema_part["description"]
+
+            return pydantic_model_schema_dict
+
+        # Handle primitive types
+        return clean_property(schema_part)
+
+    return clean_schema(schema_part=schema, full_schema=schema)
+
+
 def generate_schema(function, name: Optional[str] = None, description: Optional[str] = None) -> dict:
     # Get the signature of the function
     sig = inspect.signature(function)
@@ -93,9 +311,14 @@ def generate_schema(function, name: Optional[str] = None, description: Optional[
 
     for param in sig.parameters.values():
         # Exclude 'self' parameter
+        # TODO: eventually remove this (only applies to BASE_TOOLS)
         if param.name == "self":
             continue
 
+        # exclude 'agent_state' parameter
+        if param.name == "agent_state":
+            continue
+
         # Assert that the parameter has a type annotation
         if param.annotation == inspect.Parameter.empty:
             raise TypeError(f"Parameter '{param.name}' in function '{function.__name__}' lacks a type annotation")
@@ -107,28 +330,66 @@ def generate_schema(function, name: Optional[str] = None, description: Optional[
         if not param_doc or not param_doc.description:
             raise ValueError(f"Parameter '{param.name}' in function '{function.__name__}' lacks a description in the docstring")
 
-        if inspect.isclass(param.annotation) and issubclass(param.annotation, BaseModel):
-            schema["parameters"]["properties"][param.name] = pydantic_model_to_open_ai(param.annotation)
+        # If the parameter is a pydantic model, we need to unpack the Pydantic model type into a JSON schema object
+        # if inspect.isclass(param.annotation) and issubclass(param.annotation, BaseModel):
+        if (
+            (inspect.isclass(param.annotation) or inspect.isclass(get_origin(param.annotation) or param.annotation))
+            and not get_origin(param.annotation)
+            and issubclass(param.annotation, BaseModel)
+        ):
+            # print("Generating schema for pydantic model:", param.annotation)
+            # Extract the properties from the pydantic model
+            schema["parameters"]["properties"][param.name] = pydantic_model_to_json_schema(param.annotation)
+            schema["parameters"]["properties"][param.name]["description"] = param_doc.description
+
+        # Otherwise, we convert the Python typing to JSON schema types
+        # NOTE: important - if a dict or list, the internal type can be a Pydantic model itself
+        #                   however in that
         else:
-            # Add parameter details to the schema
+            # print("Generating schema for non-pydantic model:", param.annotation)
+            # Grab the description for the parameter from the extended docstring
+            # If it doesn't exist, we should raise an error
             param_doc = next((d for d in docstring.params if d.arg_name == param.name), None)
-            schema["parameters"]["properties"][param.name] = {
-                # "type": "string" if param.annotation == str else str(param.annotation),
-                "type": type_to_json_schema_type(param.annotation) if param.annotation != inspect.Parameter.empty else "string",
-                "description": param_doc.description,
-            }
-        if param.default == inspect.Parameter.empty:
+            if not param_doc:
+                raise ValueError(f"Parameter '{param.name}' in function '{function.__name__}' lacks a description in the docstring")
+            elif not isinstance(param_doc.description, str):
+                raise ValueError(
+                    f"Parameter '{param.name}' in function '{function.__name__}' has a description in the docstring that is not a string (type: {type(param_doc.description)})"
+                )
+            else:
+                # If it's a string or a basic type, then all you need is: (1) type, (2) description
+                # If it's a more complex type, then you also need either:
+                # - for array, you need "items", each of which has "type"
+                # - for a dict, you need "properties", which has keys which each have "type"
+                if param.annotation != inspect.Parameter.empty:
+                    param_generated_schema = type_to_json_schema_type(param.annotation)
+                else:
+                    # TODO why are we inferring here?
+                    param_generated_schema = {"type": "string"}
+
+                # Add in the description
+                param_generated_schema["description"] = param_doc.description
+
+                # Add the schema to the function arg key
+                schema["parameters"]["properties"][param.name] = param_generated_schema
+
+        # If the parameter doesn't have a default value, it is required (so we need to add it to the required list)
+        if param.default == inspect.Parameter.empty and not is_optional(param.annotation):
             schema["parameters"]["required"].append(param.name)
 
+        # TODO what's going on here?
+        # If the parameter is a list of strings we need to hard cast to "string" instead of `str`
         if get_origin(param.annotation) is list:
             if get_args(param.annotation)[0] is str:
                 schema["parameters"]["properties"][param.name]["items"] = {"type": "string"}
 
+        # TODO is this not duplicating the other append directly above?
         if param.annotation == inspect.Parameter.empty:
             schema["parameters"]["required"].append(param.name)
 
     # append the heartbeat
     # TODO: don't hard-code
+    # TODO: if terminal, don't include this
     if function.__name__ not in ["send_message", "pause_heartbeats"]:
         schema["parameters"]["properties"]["request_heartbeat"] = {
             "type": "boolean",