letta-nightly 0.1.7.dev20240924104148__py3-none-any.whl

letta/schemas/block.py

@@ -0,0 +1,135 @@
+from typing import Optional
+
+from pydantic import Field, model_validator
+from typing_extensions import Self
+
+from letta.schemas.letta_base import LettaBase
+
+# block of the LLM context
+
+
+class BaseBlock(LettaBase, validate_assignment=True):
+    """Base block of the LLM context"""
+
+    __id_prefix__ = "block"
+
+    # data value
+    value: Optional[str] = Field(None, description="Value of the block.")
+    limit: int = Field(2000, description="Character limit of the block.")
+
+    name: Optional[str] = Field(None, description="Name of the block.")
+    template: bool = Field(False, description="Whether the block is a template (e.g. saved human/persona options).")
+    label: Optional[str] = Field(None, description="Label of the block (e.g. 'human', 'persona').")
+
+    # metadat
+    description: Optional[str] = Field(None, description="Description of the block.")
+    metadata_: Optional[dict] = Field({}, description="Metadata of the block.")
+
+    # associated user/agent
+    user_id: Optional[str] = Field(None, description="The unique identifier of the user associated with the block.")
+
+    @model_validator(mode="after")
+    def verify_char_limit(self) -> Self:
+        try:
+            assert len(self) <= self.limit
+        except AssertionError:
+            error_msg = f"Edit failed: Exceeds {self.limit} character limit (requested {len(self)}) - {str(self)}."
+            raise ValueError(error_msg)
+        except Exception as e:
+            raise e
+        return self
+
+    @model_validator(mode="after")
+    def ensure_label(self) -> Self:
+        if not self.label:
+            self.label = self.name
+        return self
+
+    def __len__(self):
+        return len(str(self))
+
+    def __str__(self) -> str:
+        if isinstance(self.value, list):
+            return ",".join(self.value)
+        elif isinstance(self.value, str):
+            return self.value
+        else:
+            return ""
+
+    def __setattr__(self, name, value):
+        """Run validation if self.value is updated"""
+        super().__setattr__(name, value)
+        if name == "value":
+            # run validation
+            self.__class__.validate(self.dict(exclude_unset=True))
+
+
+class Block(BaseBlock):
+    """
+    A Block represents a reserved section of the LLM's context window which is editable. `Block` objects contained in the `Memory` object, which is able to edit the Block values.
+
+    Parameters:
+        name (str): The name of the block.
+        value (str): The value of the block. This is the string that is represented in the context window.
+        limit (int): The character limit of the block.
+        template (bool): Whether the block is a template (e.g. saved human/persona options). Non-template blocks are not stored in the database and are ephemeral, while templated blocks are stored in the database.
+        label (str): The label of the block (e.g. 'human', 'persona'). This defines a category for the block.
+        description (str): Description of the block.
+        metadata_ (Dict): Metadata of the block.
+        user_id (str): The unique identifier of the user associated with the block.
+    """
+
+    id: str = BaseBlock.generate_id_field()
+    value: str = Field(..., description="Value of the block.")
+
+
+class Human(Block):
+    """Human block of the LLM context"""
+
+    label: str = "human"
+
+
+class Persona(Block):
+    """Persona block of the LLM context"""
+
+    label: str = "persona"
+
+
+class CreateBlock(BaseBlock):
+    """Create a block"""
+
+    template: bool = True
+    label: str = Field(..., description="Label of the block.")
+
+
+class CreatePersona(BaseBlock):
+    """Create a persona block"""
+
+    template: bool = True
+    label: str = "persona"
+
+
+class CreateHuman(BaseBlock):
+    """Create a human block"""
+
+    template: bool = True
+    label: str = "human"
+
+
+class UpdateBlock(BaseBlock):
+    """Update a block"""
+
+    id: str = Field(..., description="The unique identifier of the block.")
+    limit: Optional[int] = Field(2000, description="Character limit of the block.")
+
+
+class UpdatePersona(UpdateBlock):
+    """Update a persona block"""
+
+    label: str = "persona"
+
+
+class UpdateHuman(UpdateBlock):
+    """Update a human block"""
+
+    label: str = "human"

letta/schemas/document.py

@@ -0,0 +1,21 @@
+from typing import Dict, Optional
+
+from pydantic import Field
+
+from letta.schemas.letta_base import LettaBase
+
+
+class DocumentBase(LettaBase):
+    """Base class for document schemas"""
+
+    __id_prefix__ = "doc"
+
+
+class Document(DocumentBase):
+    """Representation of a single document (broken up into `Passage` objects)"""
+
+    id: str = DocumentBase.generate_id_field()
+    text: str = Field(..., description="The text of the document.")
+    source_id: str = Field(..., description="The unique identifier of the source associated with the document.")
+    user_id: str = Field(description="The unique identifier of the user associated with the document.")
+    metadata_: Optional[Dict] = Field({}, description="The metadata of the document.")

letta/schemas/embedding_config.py

@@ -0,0 +1,54 @@
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class EmbeddingConfig(BaseModel):
+    """
+
+    Embedding model configuration. This object specifies all the information necessary to access an embedding model to usage with Letta, except for secret keys.
+
+    Attributes:
+        embedding_endpoint_type (str): The endpoint type for the model.
+        embedding_endpoint (str): The endpoint for the model.
+        embedding_model (str): The model for the embedding.
+        embedding_dim (int): The dimension of the embedding.
+        embedding_chunk_size (int): The chunk size of the embedding.
+        azure_endpoint (:obj:`str`, optional): The Azure endpoint for the model (Azure only).
+        azure_version (str): The Azure version for the model (Azure only).
+        azure_deployment (str): The Azure deployment for the model (Azure only).
+
+    """
+
+    embedding_endpoint_type: str = Field(..., description="The endpoint type for the model.")
+    embedding_endpoint: Optional[str] = Field(None, description="The endpoint for the model (`None` if local).")
+    embedding_model: str = Field(..., description="The model for the embedding.")
+    embedding_dim: int = Field(..., description="The dimension of the embedding.")
+    embedding_chunk_size: Optional[int] = Field(300, description="The chunk size of the embedding.")
+
+    # azure only
+    azure_endpoint: Optional[str] = Field(None, description="The Azure endpoint for the model.")
+    azure_version: Optional[str] = Field(None, description="The Azure version for the model.")
+    azure_deployment: Optional[str] = Field(None, description="The Azure deployment for the model.")
+
+    @classmethod
+    def default_config(cls, model_name: Optional[str] = None, provider: Optional[str] = None):
+
+        if model_name == "text-embedding-ada-002" or (not model_name and provider == "openai"):
+            return cls(
+                embedding_model="text-embedding-ada-002",
+                embedding_endpoint_type="openai",
+                embedding_endpoint="https://api.openai.com/v1",
+                embedding_dim=1536,
+                embedding_chunk_size=300,
+            )
+        elif model_name == "letta":
+            return cls(
+                embedding_endpoint="https://embeddings.memgpt.ai",
+                embedding_model="BAAI/bge-large-en-v1.5",
+                embedding_dim=1024,
+                embedding_chunk_size=300,
+                embedding_endpoint_type="hugging-face",
+            )
+        else:
+            raise ValueError(f"Model {model_name} not supported.")

letta/schemas/enums.py

@@ -0,0 +1,35 @@
+from enum import Enum
+
+
+class MessageRole(str, Enum):
+    assistant = "assistant"
+    user = "user"
+    tool = "tool"
+    function = "function"
+    system = "system"
+
+
+class OptionState(str, Enum):
+    """Useful for kwargs that are bool + default option"""
+
+    YES = "yes"
+    NO = "no"
+    DEFAULT = "default"
+
+
+class JobStatus(str, Enum):
+    """
+    Status of the job.
+    """
+
+    created = "created"
+    running = "running"
+    completed = "completed"
+    failed = "failed"
+    pending = "pending"
+
+
+class MessageStreamStatus(str, Enum):
+    done_generation = "[DONE_GEN]"
+    done_step = "[DONE_STEP]"
+    done = "[DONE]"

letta/schemas/job.py

@@ -0,0 +1,38 @@
+from datetime import datetime
+from typing import Optional
+
+from pydantic import Field
+
+from letta.schemas.enums import JobStatus
+from letta.schemas.letta_base import LettaBase
+from letta.utils import get_utc_time
+
+
+class JobBase(LettaBase):
+    __id_prefix__ = "job"
+    metadata_: Optional[dict] = Field({}, description="The metadata of the job.")
+
+
+class Job(JobBase):
+    """
+    Representation of offline jobs, used for tracking status of data loading tasks (involving parsing and embedding documents).
+
+    Parameters:
+        id (str): The unique identifier of the job.
+        status (JobStatus): The status of the job.
+        created_at (datetime): The unix timestamp of when the job was created.
+        completed_at (datetime): The unix timestamp of when the job was completed.
+        user_id (str): The unique identifier of the user associated with the.
+
+    """
+
+    id: str = JobBase.generate_id_field()
+    status: JobStatus = Field(default=JobStatus.created, description="The status of the job.")
+    created_at: datetime = Field(default_factory=get_utc_time, description="The unix timestamp of when the job was created.")
+    completed_at: Optional[datetime] = Field(None, description="The unix timestamp of when the job was completed.")
+    user_id: str = Field(..., description="The unique identifier of the user associated with the job.")
+
+
+class JobUpdate(JobBase):
+    id: str = Field(..., description="The unique identifier of the job.")
+    status: Optional[JobStatus] = Field(..., description="The status of the job.")

letta/schemas/letta_base.py

@@ -0,0 +1,80 @@
+import uuid
+from logging import getLogger
+from typing import Optional
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+# from: https://gist.github.com/norton120/22242eadb80bf2cf1dd54a961b151c61
+
+
+logger = getLogger(__name__)
+
+
+class LettaBase(BaseModel):
+    """Base schema for Letta schemas (does not include model provider schemas, e.g. OpenAI)"""
+
+    model_config = ConfigDict(
+        # allows you to use the snake or camelcase names in your code (ie user_id or userId)
+        populate_by_name=True,
+        # allows you do dump a sqlalchemy object directly (ie PersistedAddress.model_validate(SQLAdress)
+        from_attributes=True,
+        # throw errors if attributes are given that don't belong
+        extra="forbid",
+    )
+
+    # def __id_prefix__(self):
+    #    raise NotImplementedError("All schemas must have an __id_prefix__ attribute!")
+
+    @classmethod
+    def generate_id_field(cls, prefix: Optional[str] = None) -> "Field":
+        prefix = prefix or cls.__id_prefix__
+
+        # TODO: generate ID from regex pattern?
+        def _generate_id() -> str:
+            return f"{prefix}-{uuid.uuid4()}"
+
+        return Field(
+            ...,
+            description=cls._id_description(prefix),
+            pattern=cls._id_regex_pattern(prefix),
+            examples=[cls._id_example(prefix)],
+            default_factory=_generate_id,
+        )
+
+    # def _generate_id(self) -> str:
+    #    return f"{self.__id_prefix__}-{uuid.uuid4()}"
+
+    @classmethod
+    def _id_regex_pattern(cls, prefix: str):
+        """generates the regex pattern for a given id"""
+        return (
+            r"^" + prefix + r"-"  # prefix string
+            r"[a-fA-F0-9]{8}"  # 8 hexadecimal characters
+            # r"[a-fA-F0-9]{4}-"  # 4 hexadecimal characters
+            # r"[a-fA-F0-9]{4}-"  # 4 hexadecimal characters
+            # r"[a-fA-F0-9]{4}-"  # 4 hexadecimal characters
+            # r"[a-fA-F0-9]{12}$"  # 12 hexadecimal characters
+        )
+
+    @classmethod
+    def _id_example(cls, prefix: str):
+        """generates an example id for a given prefix"""
+        return [prefix + "-123e4567-e89b-12d3-a456-426614174000"]
+
+    @classmethod
+    def _id_description(cls, prefix: str):
+        """generates a factory function for a given prefix"""
+        return f"The human-friendly ID of the {prefix.capitalize()}"
+
+    @field_validator("id", check_fields=False, mode="before")
+    @classmethod
+    def allow_bare_uuids(cls, v, values):
+        """to ease the transition to stripe ids,
+        we allow bare uuids and convert them with a warning
+        """
+        _ = values  # for SCA
+        if isinstance(v, UUID):
+            logger.warning("Bare UUIDs are deprecated, please use the full prefixed id!")
+            return f"{cls.__id_prefix__}-{v}"
+        return v

letta/schemas/letta_message.py

@@ -0,0 +1,175 @@
+import json
+from datetime import datetime, timezone
+from typing import Annotated, Literal, Optional, Union
+
+from pydantic import BaseModel, Field, field_serializer, field_validator
+
+# Letta API style responses (intended to be easier to use vs getting true Message types)
+
+
+class LettaMessage(BaseModel):
+    """
+    Base class for simplified Letta message response type. This is intended to be used for developers who want the internal monologue, function calls, and function returns in a simplified format that does not include additional information other than the content and timestamp.
+
+    Attributes:
+        id (str): The ID of the message
+        date (datetime): The date the message was created in ISO format
+
+    """
+
+    # NOTE: use Pydantic's discriminated unions feature: https://docs.pydantic.dev/latest/concepts/unions/#discriminated-unions
+    # see `message_type` attribute
+
+    id: str
+    date: datetime
+
+    @field_serializer("date")
+    def serialize_datetime(self, dt: datetime, _info):
+        if dt.tzinfo is None or dt.tzinfo.utcoffset(dt) is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        # Remove microseconds since it seems like we're inconsistent with getting them
+        # TODO figure out why we don't always get microseconds (get_utc_time() does)
+        return dt.isoformat(timespec="seconds")
+
+
+class SystemMessage(LettaMessage):
+    """
+    A message generated by the system. Never streamed back on a response, only used for cursor pagination.
+
+    Attributes:
+        message (str): The message sent by the system
+        id (str): The ID of the message
+        date (datetime): The date the message was created in ISO format
+    """
+
+    message_type: Literal["system_message"] = "system_message"
+    message: str
+
+
+class UserMessage(LettaMessage):
+    """
+    A message sent by the user. Never streamed back on a response, only used for cursor pagination.
+
+    Attributes:
+        message (str): The message sent by the user
+        id (str): The ID of the message
+        date (datetime): The date the message was created in ISO format
+    """
+
+    message_type: Literal["user_message"] = "user_message"
+    message: str
+
+
+class InternalMonologue(LettaMessage):
+    """
+    Representation of an agent's internal monologue.
+
+    Attributes:
+        internal_monologue (str): The internal monologue of the agent
+        id (str): The ID of the message
+        date (datetime): The date the message was created in ISO format
+    """
+
+    message_type: Literal["internal_monologue"] = "internal_monologue"
+    internal_monologue: str
+
+
+class FunctionCall(BaseModel):
+
+    name: str
+    arguments: str
+
+
+class FunctionCallDelta(BaseModel):
+
+    name: Optional[str]
+    arguments: Optional[str]
+
+    # NOTE: this is a workaround to exclude None values from the JSON dump,
+    # since the OpenAI style of returning chunks doesn't include keys with null values
+    def model_dump(self, *args, **kwargs):
+        kwargs["exclude_none"] = True
+        return super().model_dump(*args, **kwargs)
+
+    def json(self, *args, **kwargs):
+        return json.dumps(self.model_dump(exclude_none=True), *args, **kwargs)
+
+
+class FunctionCallMessage(LettaMessage):
+    """
+    A message representing a request to call a function (generated by the LLM to trigger function execution).
+
+    Attributes:
+        function_call (Union[FunctionCall, FunctionCallDelta]): The function call
+        id (str): The ID of the message
+        date (datetime): The date the message was created in ISO format
+    """
+
+    message_type: Literal["function_call"] = "function_call"
+    function_call: Union[FunctionCall, FunctionCallDelta]
+
+    # NOTE: this is required for the FunctionCallDelta exclude_none to work correctly
+    def model_dump(self, *args, **kwargs):
+        kwargs["exclude_none"] = True
+        data = super().model_dump(*args, **kwargs)
+        if isinstance(data["function_call"], dict):
+            data["function_call"] = {k: v for k, v in data["function_call"].items() if v is not None}
+        return data
+
+    class Config:
+        json_encoders = {
+            FunctionCallDelta: lambda v: v.model_dump(exclude_none=True),
+            FunctionCall: lambda v: v.model_dump(exclude_none=True),
+        }
+
+    # NOTE: this is required to cast dicts into FunctionCallMessage objects
+    # Without this extra validator, Pydantic will throw an error if 'name' or 'arguments' are None
+    # (instead of properly casting to FunctionCallDelta instead of FunctionCall)
+    @field_validator("function_call", mode="before")
+    @classmethod
+    def validate_function_call(cls, v):
+        if isinstance(v, dict):
+            if "name" in v and "arguments" in v:
+                return FunctionCall(name=v["name"], arguments=v["arguments"])
+            elif "name" in v or "arguments" in v:
+                return FunctionCallDelta(name=v.get("name"), arguments=v.get("arguments"))
+            else:
+                raise ValueError("function_call must contain either 'name' or 'arguments'")
+        return v
+
+
+class FunctionReturn(LettaMessage):
+    """
+    A message representing the return value of a function call (generated by Letta executing the requested function).
+
+    Attributes:
+        function_return (str): The return value of the function
+        status (Literal["success", "error"]): The status of the function call
+        id (str): The ID of the message
+        date (datetime): The date the message was created in ISO format
+    """
+
+    message_type: Literal["function_return"] = "function_return"
+    function_return: str
+    status: Literal["success", "error"]
+
+
+# Legacy Letta API had an additional type "assistant_message" and the "function_call" was a formatted string
+
+
+class AssistantMessage(LettaMessage):
+    message_type: Literal["assistant_message"] = "assistant_message"
+    assistant_message: str
+
+
+class LegacyFunctionCallMessage(LettaMessage):
+    function_call: str
+
+
+LegacyLettaMessage = Union[InternalMonologue, AssistantMessage, LegacyFunctionCallMessage, FunctionReturn]
+
+
+LettaMessageUnion = Annotated[
+    Union[SystemMessage, UserMessage, InternalMonologue, FunctionCallMessage, FunctionReturn, AssistantMessage],
+    Field(discriminator="message_type"),
+]

letta/schemas/letta_request.py

@@ -0,0 +1,23 @@
+from typing import List
+
+from pydantic import BaseModel, Field
+
+from letta.schemas.message import MessageCreate
+
+
+class LettaRequest(BaseModel):
+    messages: List[MessageCreate] = Field(..., description="The messages to be sent to the agent.")
+    run_async: bool = Field(default=False, description="Whether to asynchronously send the messages to the agent.")  # TODO: implement
+
+    stream_steps: bool = Field(
+        default=False, description="Flag to determine if the response should be streamed. Set to True for streaming agent steps."
+    )
+    stream_tokens: bool = Field(
+        default=False,
+        description="Flag to determine if individual tokens should be streamed. Set to True for token streaming (requires stream_steps = True).",
+    )
+
+    return_message_object: bool = Field(
+        default=False,
+        description="Set True to return the raw Message object. Set False to return the Message in the format of the Letta API.",
+    )

letta/schemas/letta_response.py

@@ -0,0 +1,28 @@
+from typing import List, Union
+
+from pydantic import BaseModel, Field
+
+from letta.schemas.enums import MessageStreamStatus
+from letta.schemas.letta_message import LettaMessage
+from letta.schemas.message import Message
+from letta.schemas.usage import LettaUsageStatistics
+
+# TODO: consider moving into own file
+
+
+class LettaResponse(BaseModel):
+    """
+    Response object from an agent interaction, consisting of the new messages generated by the agent and usage statistics.
+    The type of the returned messages can be either `Message` or `LettaMessage`, depending on what was specified in the request.
+
+    Attributes:
+        messages (List[Union[Message, LettaMessage]]): The messages returned by the agent.
+        usage (LettaUsageStatistics): The usage statistics
+    """
+
+    messages: Union[List[Message], List[LettaMessage]] = Field(..., description="The messages returned by the agent.")
+    usage: LettaUsageStatistics = Field(..., description="The usage statistics of the agent.")
+
+
+# The streaming response is either [DONE], [DONE_STEP], [DONE], an error, or a LettaMessage
+LettaStreamingResponse = Union[LettaMessage, MessageStreamStatus]

letta/schemas/llm_config.py

@@ -0,0 +1,54 @@
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class LLMConfig(BaseModel):
+    """
+    Configuration for a Language Model (LLM) model. This object specifies all the information necessary to access an LLM model to usage with Letta, except for secret keys.
+
+    Attributes:
+        model (str): The name of the LLM model.
+        model_endpoint_type (str): The endpoint type for the model.
+        model_endpoint (str): The endpoint for the model.
+        model_wrapper (str): The wrapper for the model.
+        context_window (int): The context window size for the model.
+    """
+
+    # TODO: 🤮 don't default to a vendor! bug city!
+    model: str = Field(..., description="LLM model name. ")
+    model_endpoint_type: str = Field(..., description="The endpoint type for the model.")
+    model_endpoint: str = Field(..., description="The endpoint for the model.")
+    model_wrapper: Optional[str] = Field(None, description="The wrapper for the model.")
+    context_window: int = Field(..., description="The context window size for the model.")
+
+    # FIXME hack to silence pydantic protected namespace warning
+    model_config = ConfigDict(protected_namespaces=())
+
+    @classmethod
+    def default_config(cls, model_name: str):
+        if model_name == "gpt-4":
+            return cls(
+                model="gpt-4",
+                model_endpoint_type="openai",
+                model_endpoint="https://api.openai.com/v1",
+                model_wrapper=None,
+                context_window=8192,
+            )
+        elif model_name == "gpt-4o-mini":
+            return cls(
+                model="gpt-4o-mini",
+                model_endpoint_type="openai",
+                model_endpoint="https://api.openai.com/v1",
+                model_wrapper=None,
+                context_window=128000,
+            )
+        elif model_name == "letta": 
+            return cls(
+                model="memgpt-openai",
+                model_endpoint_type="openai",
+                model_endpoint="https://inference.memgpt.ai",
+                context_window=16384,
+            )
+        else:
+            raise ValueError(f"Model {model_name} not supported.")