letta-nightly 0.6.27.dev20250219104103__py3-none-any.whl → 0.6.28.dev20250220163833__py3-none-any.whl

letta/llm_api/llm_api_tools.py

@@ -1,3 +1,4 @@
+import json
 import random
 import time
 from typing import List, Optional, Union
@@ -13,6 +14,7 @@ from letta.llm_api.anthropic import (
 )
 from letta.llm_api.aws_bedrock import has_valid_aws_credentials
 from letta.llm_api.azure_openai import azure_openai_chat_completions_request
+from letta.llm_api.deepseek import build_deepseek_chat_completions_request, convert_deepseek_response_to_chatcompletion
 from letta.llm_api.google_ai import convert_tools_to_google_ai_format, google_ai_chat_completions_request
 from letta.llm_api.helpers import add_inner_thoughts_to_functions, unpack_all_inner_thoughts_from_kwargs
 from letta.llm_api.openai import (
@@ -29,8 +31,9 @@ from letta.schemas.openai.chat_completion_request import ChatCompletionRequest,
 from letta.schemas.openai.chat_completion_response import ChatCompletionResponse
 from letta.settings import ModelSettings
 from letta.streaming_interface import AgentChunkStreamingInterface, AgentRefreshStreamingInterface
+from letta.tracing import log_event, trace_method
 
-LLM_API_PROVIDER_OPTIONS = ["openai", "azure", "anthropic", "google_ai", "cohere", "local", "groq"]
+LLM_API_PROVIDER_OPTIONS = ["openai", "azure", "anthropic", "google_ai", "cohere", "local", "groq", "deepseek"]
 
 
 def retry_with_exponential_backoff(
@@ -68,9 +71,28 @@ def retry_with_exponential_backoff(
                 if http_err.response.status_code in error_codes:
                     # Increment retries
                     num_retries += 1
+                    log_event(
+                        "llm_retry_attempt",
+                        {
+                            "attempt": num_retries,
+                            "delay": delay,
+                            "status_code": http_err.response.status_code,
+                            "error_type": type(http_err).__name__,
+                            "error": str(http_err),
+                        },
+                    )
 
                     # Check if max retries has been reached
                     if num_retries > max_retries:
+                        log_event(
+                            "llm_max_retries_exceeded",
+                            {
+                                "max_retries": max_retries,
+                                "status_code": http_err.response.status_code,
+                                "error_type": type(http_err).__name__,
+                                "error": str(http_err),
+                            },
+                        )
                         raise RateLimitExceededError("Maximum number of retries exceeded", max_retries=max_retries)
 
                     # Increment the delay
@@ -84,15 +106,21 @@ def retry_with_exponential_backoff(
                     time.sleep(delay)
                 else:
                     # For other HTTP errors, re-raise the exception
+                    log_event(
+                        "llm_non_retryable_error",
+                        {"status_code": http_err.response.status_code, "error_type": type(http_err).__name__, "error": str(http_err)},
+                    )
                     raise
 
             # Raise exceptions for any errors not specified
             except Exception as e:
+                log_event("llm_unexpected_error", {"error_type": type(e).__name__, "error": str(e)})
                 raise e
 
     return wrapper
 
 
+@trace_method("LLM Request")
 @retry_with_exponential_backoff
 def create(
     # agent_state: AgentState,
@@ -453,10 +481,62 @@ def create(
             ),
         )
 
+    elif llm_config.model_endpoint_type == "deepseek":
+        if model_settings.deepseek_api_key is None and llm_config.model_endpoint == "":
+            # only is a problem if we are *not* using an openai proxy
+            raise LettaConfigurationError(message="DeepSeek key is missing from letta config file", missing_fields=["deepseek_api_key"])
+
+        data = build_deepseek_chat_completions_request(
+            llm_config,
+            messages,
+            user_id,
+            functions,
+            function_call,
+            use_tool_naming,
+            llm_config.max_tokens,
+        )
+        if stream:  # Client requested token streaming
+            data.stream = True
+            assert isinstance(stream_interface, AgentChunkStreamingInterface) or isinstance(
+                stream_interface, AgentRefreshStreamingInterface
+            ), type(stream_interface)
+            response = openai_chat_completions_process_stream(
+                url=llm_config.model_endpoint,
+                api_key=model_settings.deepseek_api_key,
+                chat_completion_request=data,
+                stream_interface=stream_interface,
+            )
+        else:  # Client did not request token streaming (expect a blocking backend response)
+            data.stream = False
+            if isinstance(stream_interface, AgentChunkStreamingInterface):
+                stream_interface.stream_start()
+            try:
+                response = openai_chat_completions_request(
+                    url=llm_config.model_endpoint,
+                    api_key=model_settings.deepseek_api_key,
+                    chat_completion_request=data,
+                )
+            finally:
+                if isinstance(stream_interface, AgentChunkStreamingInterface):
+                    stream_interface.stream_end()
+        """
+        if llm_config.put_inner_thoughts_in_kwargs:
+            response = unpack_all_inner_thoughts_from_kwargs(response=response, inner_thoughts_key=INNER_THOUGHTS_KWARG)
+        """
+        response = convert_deepseek_response_to_chatcompletion(response)
+        return response
+
     # local model
     else:
         if stream:
             raise NotImplementedError(f"Streaming not yet implemented for {llm_config.model_endpoint_type}")
+
+        if "DeepSeek-R1".lower() in llm_config.model.lower():  # TODO: move this to the llm_config.
+            messages[0].content[0].text += f"<available functions> {''.join(json.dumps(f) for f in functions)} </available functions>"
+            messages[0].content[
+                0
+            ].text += f'Select best function to call simply by responding with a single json block with the keys "function" and "params". Use double quotes around the arguments.'
+
         return get_chat_completion(
             model=llm_config.model,
             messages=messages,

letta/llm_api/openai.py

@@ -166,6 +166,11 @@ def openai_chat_completions_process_stream(
     create_message_id: bool = True,
     create_message_datetime: bool = True,
     override_tool_call_id: bool = True,
+    # if we expect reasoning content in the response,
+    # then we should emit reasoning_content as "inner_thoughts"
+    # however, we don't necessarily want to put these
+    # expect_reasoning_content: bool = False,
+    expect_reasoning_content: bool = True,
 ) -> ChatCompletionResponse:
     """Process a streaming completion response, and return a ChatCompletionRequest at the end.
 
@@ -250,6 +255,7 @@ def openai_chat_completions_process_stream(
                         chat_completion_chunk,
                         message_id=chat_completion_response.id if create_message_id else chat_completion_chunk.id,
                         message_date=chat_completion_response.created if create_message_datetime else chat_completion_chunk.created,
+                        expect_reasoning_content=expect_reasoning_content,
                     )
                 elif isinstance(stream_interface, AgentRefreshStreamingInterface):
                     stream_interface.process_refresh(chat_completion_response)
@@ -290,6 +296,13 @@ def openai_chat_completions_process_stream(
                     else:
                         accum_message.content += content_delta
 
+                if expect_reasoning_content and message_delta.reasoning_content is not None:
+                    reasoning_content_delta = message_delta.reasoning_content
+                    if accum_message.reasoning_content is None:
+                        accum_message.reasoning_content = reasoning_content_delta
+                    else:
+                        accum_message.reasoning_content += reasoning_content_delta
+
                 # TODO(charles) make sure this works for parallel tool calling?
                 if message_delta.tool_calls is not None:
                     tool_calls_delta = message_delta.tool_calls

letta/local_llm/chat_completion_proxy.py

@@ -14,7 +14,7 @@ from letta.local_llm.grammars.gbnf_grammar_generator import create_dynamic_model
 from letta.local_llm.koboldcpp.api import get_koboldcpp_completion
 from letta.local_llm.llamacpp.api import get_llamacpp_completion
 from letta.local_llm.llm_chat_completion_wrappers import simple_summary_wrapper
-from letta.local_llm.lmstudio.api import get_lmstudio_completion
+from letta.local_llm.lmstudio.api import get_lmstudio_completion, get_lmstudio_completion_chatcompletions
 from letta.local_llm.ollama.api import get_ollama_completion
 from letta.local_llm.utils import count_tokens, get_available_wrappers
 from letta.local_llm.vllm.api import get_vllm_completion
@@ -141,11 +141,24 @@ def get_chat_completion(
             f"Failed to convert ChatCompletion messages into prompt string with wrapper {str(llm_wrapper)} - error: {str(e)}"
         )
 
+    # get the schema for the model
+
+    """
+    if functions_python is not None:
+        model_schema = generate_schema(functions)
+    else:
+        model_schema = None
+    """
+
+    # Run the LLM
     try:
+        result_reasoning = None
         if endpoint_type == "webui":
             result, usage = get_webui_completion(endpoint, auth_type, auth_key, prompt, context_window, grammar=grammar)
         elif endpoint_type == "webui-legacy":
             result, usage = get_webui_completion_legacy(endpoint, auth_type, auth_key, prompt, context_window, grammar=grammar)
+        elif endpoint_type == "lmstudio-chatcompletions":
+            result, usage, result_reasoning = get_lmstudio_completion_chatcompletions(endpoint, auth_type, auth_key, model, messages)
         elif endpoint_type == "lmstudio":
             result, usage = get_lmstudio_completion(endpoint, auth_type, auth_key, prompt, context_window, api="completions")
         elif endpoint_type == "lmstudio-legacy":
@@ -214,7 +227,7 @@ def get_chat_completion(
                 index=0,
                 message=Message(
                     role=chat_completion_result["role"],
-                    content=chat_completion_result["content"],
+                    content=result_reasoning if result_reasoning is not None else chat_completion_result["content"],
                     tool_calls=(
                         [ToolCall(id=get_tool_call_id(), type="function", function=chat_completion_result["function_call"])]
                         if "function_call" in chat_completion_result

letta/local_llm/lmstudio/api.py

@@ -1,3 +1,4 @@
+import json
 from urllib.parse import urljoin
 
 from letta.local_llm.settings.settings import get_completions_settings
@@ -6,6 +7,73 @@ from letta.utils import count_tokens
 
 LMSTUDIO_API_CHAT_SUFFIX = "/v1/chat/completions"
 LMSTUDIO_API_COMPLETIONS_SUFFIX = "/v1/completions"
+LMSTUDIO_API_CHAT_COMPLETIONS_SUFFIX = "/v1/chat/completions"
+
+
+def get_lmstudio_completion_chatcompletions(endpoint, auth_type, auth_key, model, messages):
+    """
+    This is the request we need to send
+
+    {
+    "model": "deepseek-r1-distill-qwen-7b",
+    "messages": [
+      { "role": "system", "content": "Always answer in rhymes. Today is Thursday" },
+      { "role": "user", "content": "What day is it today?" },
+      { "role": "user", "content": "What day is it today?" }],
+    "temperature": 0.7,
+    "max_tokens": -1,
+    "stream": false
+    """
+    from letta.utils import printd
+
+    URI = endpoint + LMSTUDIO_API_CHAT_COMPLETIONS_SUFFIX
+    request = {"model": model, "messages": messages}
+
+    response = post_json_auth_request(uri=URI, json_payload=request, auth_type=auth_type, auth_key=auth_key)
+
+    # Get the reasoning from the model
+    if response.status_code == 200:
+        result_full = response.json()
+        result_reasoning = result_full["choices"][0]["message"].get("reasoning_content")
+        result = result_full["choices"][0]["message"]["content"]
+        usage = result_full["usage"]
+
+    # See if result is json
+    try:
+        function_call = json.loads(result)
+        if "function" in function_call and "params" in function_call:
+            return result, usage, result_reasoning
+        else:
+            print("Did not get json on without json constraint, attempting with json decoding")
+    except Exception as e:
+        print(f"Did not get json on without json constraint, attempting with json decoding: {e}")
+
+    request["messages"].append({"role": "assistant", "content": result_reasoning})
+    request["messages"].append({"role": "user", "content": ""})  # last message must be user
+    # Now run with json decoding to get the function
+    request["response_format"] = {
+        "type": "json_schema",
+        "json_schema": {
+            "name": "function_call",
+            "strict": "true",
+            "schema": {
+                "type": "object",
+                "properties": {"function": {"type": "string"}, "params": {"type": "object"}},
+                "required": ["function", "params"],
+            },
+        },
+    }
+
+    response = post_json_auth_request(uri=URI, json_payload=request, auth_type=auth_type, auth_key=auth_key)
+    if response.status_code == 200:
+        result_full = response.json()
+        printd(f"JSON API response:\n{result_full}")
+        result = result_full["choices"][0]["message"]["content"]
+        # add usage with previous call, merge with prev usage
+        for key, value in result_full["usage"].items():
+            usage[key] += value
+
+    return result, usage, result_reasoning
 
 
 def get_lmstudio_completion(endpoint, auth_type, auth_key, prompt, context_window, api="completions"):
@@ -24,7 +92,8 @@ def get_lmstudio_completion(endpoint, auth_type, auth_key, prompt, context_windo
             # This controls how LM studio handles context overflow
             # In Letta we handle this ourselves, so this should be disabled
             # "context_overflow_policy": 0,
-            "lmstudio": {"context_overflow_policy": 0},  # 0 = stop at limit
+            # "lmstudio": {"context_overflow_policy": 0},  # 0 = stop at limit
+            # "lmstudio": {"context_overflow_policy": "stopAtLimit"}, # https://github.com/letta-ai/letta/issues/1782
             "stream": False,
             "model": "local model",
         }
@@ -72,6 +141,11 @@ def get_lmstudio_completion(endpoint, auth_type, auth_key, prompt, context_windo
             elif api == "completions":
                 result = result_full["choices"][0]["text"]
                 usage = result_full.get("usage", None)
+            elif api == "chat/completions":
+                result = result_full["choices"][0]["content"]
+                result_full["choices"][0]["reasoning_content"]
+                usage = result_full.get("usage", None)
+
         else:
             # Example error: msg={"error":"Context length exceeded. Tokens in context: 8000, Context length: 8000"}
             if "context length" in str(response.text).lower():

letta/orm/__init__.py

@@ -4,6 +4,7 @@ from letta.orm.base import Base
 from letta.orm.block import Block
 from letta.orm.blocks_agents import BlocksAgents
 from letta.orm.file import FileMetadata
+from letta.orm.identity import Identity
 from letta.orm.job import Job
 from letta.orm.job_messages import JobMessage
 from letta.orm.message import Message

letta/orm/agent.py

@@ -1,11 +1,12 @@
 import uuid
 from typing import TYPE_CHECKING, List, Optional
 
-from sqlalchemy import JSON, Boolean, Index, String
+from sqlalchemy import JSON, Boolean, ForeignKey, Index, String
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from letta.orm.block import Block
 from letta.orm.custom_columns import EmbeddingConfigColumn, LLMConfigColumn, ToolRulesColumn
+from letta.orm.identity import Identity
 from letta.orm.message import Message
 from letta.orm.mixins import OrganizationMixin
 from letta.orm.organization import Organization
@@ -15,10 +16,11 @@ from letta.schemas.agent import AgentType
 from letta.schemas.embedding_config import EmbeddingConfig
 from letta.schemas.llm_config import LLMConfig
 from letta.schemas.memory import Memory
-from letta.schemas.tool_rule import TerminalToolRule, ToolRule
+from letta.schemas.tool_rule import ToolRule
 
 if TYPE_CHECKING:
     from letta.orm.agents_tags import AgentsTags
+    from letta.orm.identity import Identity
     from letta.orm.organization import Organization
     from letta.orm.source import Source
     from letta.orm.tool import Tool
@@ -59,6 +61,14 @@ class Agent(SqlalchemyBase, OrganizationMixin):
     template_id: Mapped[Optional[str]] = mapped_column(String, nullable=True, doc="The id of the template the agent belongs to.")
     base_template_id: Mapped[Optional[str]] = mapped_column(String, nullable=True, doc="The base template id of the agent.")
 
+    # Identity
+    identity_id: Mapped[Optional[str]] = mapped_column(
+        String, ForeignKey("identities.id", ondelete="CASCADE"), nullable=True, doc="The id of the identity the agent belongs to."
+    )
+    identifier_key: Mapped[Optional[str]] = mapped_column(
+        String, nullable=True, doc="The identifier key of the identity the agent belongs to."
+    )
+
     # Tool rules
     tool_rules: Mapped[Optional[List[ToolRule]]] = mapped_column(ToolRulesColumn, doc="the tool rules for this agent.")
 
@@ -69,6 +79,7 @@ class Agent(SqlalchemyBase, OrganizationMixin):
 
     # relationships
     organization: Mapped["Organization"] = relationship("Organization", back_populates="agents")
+    identity: Mapped["Identity"] = relationship("Identity", back_populates="agents")
     tool_exec_environment_variables: Mapped[List["AgentEnvironmentVariable"]] = relationship(
         "AgentEnvironmentVariable",
         back_populates="agent",
@@ -119,14 +130,12 @@ class Agent(SqlalchemyBase, OrganizationMixin):
         viewonly=True,  # Ensures SQLAlchemy doesn't attempt to manage this relationship
         doc="All passages derived created by this agent.",
     )
+    identity: Mapped[Optional["Identity"]] = relationship("Identity", back_populates="agents")
 
     def to_pydantic(self) -> PydanticAgentState:
         """converts to the basic pydantic model counterpart"""
         # add default rule for having send_message be a terminal tool
         tool_rules = self.tool_rules
-        if not tool_rules:
-            tool_rules = [TerminalToolRule(tool_name="send_message"), TerminalToolRule(tool_name="send_message_to_agent_async")]
-
         state = {
             "id": self.id,
             "organization_id": self.organization_id,

letta/orm/custom_columns.py

@@ -1,159 +1,80 @@
-import base64
-from typing import List, Union
-
-import numpy as np
-from openai.types.chat.chat_completion_message_tool_call import ChatCompletionMessageToolCall as OpenAIToolCall
-from openai.types.chat.chat_completion_message_tool_call import Function as OpenAIFunction
 from sqlalchemy import JSON
 from sqlalchemy.types import BINARY, TypeDecorator
 
-from letta.schemas.embedding_config import EmbeddingConfig
-from letta.schemas.enums import ToolRuleType
-from letta.schemas.llm_config import LLMConfig
-from letta.schemas.tool_rule import ChildToolRule, ConditionalToolRule, InitToolRule, TerminalToolRule
+from letta.helpers.converters import (
+    deserialize_embedding_config,
+    deserialize_llm_config,
+    deserialize_tool_calls,
+    deserialize_tool_rules,
+    deserialize_vector,
+    serialize_embedding_config,
+    serialize_llm_config,
+    serialize_tool_calls,
+    serialize_tool_rules,
+    serialize_vector,
+)
 
 
-class EmbeddingConfigColumn(TypeDecorator):
-    """Custom type for storing EmbeddingConfig as JSON."""
+class LLMConfigColumn(TypeDecorator):
+    """Custom SQLAlchemy column type for storing LLMConfig as JSON."""
 
     impl = JSON
     cache_ok = True
 
-    def load_dialect_impl(self, dialect):
-        return dialect.type_descriptor(JSON())
-
     def process_bind_param(self, value, dialect):
-        if value and isinstance(value, EmbeddingConfig):
-            return value.model_dump()
-        return value
+        return serialize_llm_config(value)
 
     def process_result_value(self, value, dialect):
-        if value:
-            return EmbeddingConfig(**value)
-        return value
+        return deserialize_llm_config(value)
 
 
-class LLMConfigColumn(TypeDecorator):
-    """Custom type for storing LLMConfig as JSON."""
+class EmbeddingConfigColumn(TypeDecorator):
+    """Custom SQLAlchemy column type for storing EmbeddingConfig as JSON."""
 
     impl = JSON
     cache_ok = True
 
-    def load_dialect_impl(self, dialect):
-        return dialect.type_descriptor(JSON())
-
     def process_bind_param(self, value, dialect):
-        if value and isinstance(value, LLMConfig):
-            return value.model_dump()
-        return value
+        return serialize_embedding_config(value)
 
     def process_result_value(self, value, dialect):
-        if value:
-            return LLMConfig(**value)
-        return value
+        return deserialize_embedding_config(value)
 
 
 class ToolRulesColumn(TypeDecorator):
-    """Custom type for storing a list of ToolRules as JSON"""
+    """Custom SQLAlchemy column type for storing a list of ToolRules as JSON."""
 
     impl = JSON
     cache_ok = True
 
-    def load_dialect_impl(self, dialect):
-        return dialect.type_descriptor(JSON())
-
     def process_bind_param(self, value, dialect):
-        """Convert a list of ToolRules to JSON-serializable format."""
-        if value:
-            data = [rule.model_dump() for rule in value]
-            for d in data:
-                d["type"] = d["type"].value
-
-            for d in data:
-                assert not (d["type"] == "ToolRule" and "children" not in d), "ToolRule does not have children field"
-            return data
-        return value
-
-    def process_result_value(self, value, dialect) -> List[Union[ChildToolRule, InitToolRule, TerminalToolRule]]:
-        """Convert JSON back to a list of ToolRules."""
-        if value:
-            return [self.deserialize_tool_rule(rule_data) for rule_data in value]
-        return value
-
-    @staticmethod
-    def deserialize_tool_rule(data: dict) -> Union[ChildToolRule, InitToolRule, TerminalToolRule, ConditionalToolRule]:
-        """Deserialize a dictionary to the appropriate ToolRule subclass based on the 'type'."""
-        rule_type = ToolRuleType(data.get("type"))  # Remove 'type' field if it exists since it is a class var
-        if rule_type == ToolRuleType.run_first or rule_type == "InitToolRule":
-            data["type"] = ToolRuleType.run_first
-            return InitToolRule(**data)
-        elif rule_type == ToolRuleType.exit_loop or rule_type == "TerminalToolRule":
-            data["type"] = ToolRuleType.exit_loop
-            return TerminalToolRule(**data)
-        elif rule_type == ToolRuleType.constrain_child_tools or rule_type == "ToolRule":
-            data["type"] = ToolRuleType.constrain_child_tools
-            rule = ChildToolRule(**data)
-            return rule
-        elif rule_type == ToolRuleType.conditional:
-            rule = ConditionalToolRule(**data)
-            return rule
-        else:
-            raise ValueError(f"Unknown tool rule type: {rule_type}")
+        return serialize_tool_rules(value)
+
+    def process_result_value(self, value, dialect):
+        return deserialize_tool_rules(value)
 
 
 class ToolCallColumn(TypeDecorator):
+    """Custom SQLAlchemy column type for storing OpenAI ToolCall objects as JSON."""
 
     impl = JSON
     cache_ok = True
 
-    def load_dialect_impl(self, dialect):
-        return dialect.type_descriptor(JSON())
-
     def process_bind_param(self, value, dialect):
-        if value:
-            values = []
-            for v in value:
-                if isinstance(v, OpenAIToolCall):
-                    values.append(v.model_dump())
-                else:
-                    values.append(v)
-            return values
-
-        return value
+        return serialize_tool_calls(value)
 
     def process_result_value(self, value, dialect):
-        if value:
-            tools = []
-            for tool_value in value:
-                if "function" in tool_value:
-                    tool_call_function = OpenAIFunction(**tool_value["function"])
-                    del tool_value["function"]
-                else:
-                    tool_call_function = None
-                tools.append(OpenAIToolCall(function=tool_call_function, **tool_value))
-            return tools
-        return value
+        return deserialize_tool_calls(value)
 
 
 class CommonVector(TypeDecorator):
-    """Common type for representing vectors in SQLite"""
+    """Custom SQLAlchemy column type for storing vectors in SQLite."""
 
     impl = BINARY
     cache_ok = True
 
-    def load_dialect_impl(self, dialect):
-        return dialect.type_descriptor(BINARY())
-
     def process_bind_param(self, value, dialect):
-        if value is None:
-            return value
-        if isinstance(value, list):
-            value = np.array(value, dtype=np.float32)
-        return base64.b64encode(value.tobytes())
+        return serialize_vector(value)
 
     def process_result_value(self, value, dialect):
-        if not value:
-            return value
-        if dialect.name == "sqlite":
-            value = base64.b64decode(value)
-        return np.frombuffer(value, dtype=np.float32)
+        return deserialize_vector(value, dialect)

letta/orm/identity.py

@@ -0,0 +1,39 @@
+import uuid
+from typing import List, Optional
+
+from sqlalchemy import String, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from letta.orm.mixins import OrganizationMixin
+from letta.orm.sqlalchemy_base import SqlalchemyBase
+from letta.schemas.identity import Identity as PydanticIdentity
+
+
+class Identity(SqlalchemyBase, OrganizationMixin):
+    """Identity ORM class"""
+
+    __tablename__ = "identities"
+    __pydantic_model__ = PydanticIdentity
+    __table_args__ = (UniqueConstraint("identifier_key", "project_id", "organization_id", name="unique_identifier_pid_org_id"),)
+
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: f"identity-{uuid.uuid4()}")
+    identifier_key: Mapped[str] = mapped_column(nullable=False, doc="External, user-generated identifier key of the identity.")
+    name: Mapped[str] = mapped_column(nullable=False, doc="The name of the identity.")
+    identity_type: Mapped[str] = mapped_column(nullable=False, doc="The type of the identity.")
+    project_id: Mapped[Optional[str]] = mapped_column(nullable=True, doc="The project id of the identity.")
+
+    # relationships
+    organization: Mapped["Organization"] = relationship("Organization", back_populates="identities")
+    agents: Mapped[List["Agent"]] = relationship("Agent", lazy="selectin", back_populates="identity")
+
+    def to_pydantic(self) -> PydanticIdentity:
+        state = {
+            "id": self.id,
+            "identifier_key": self.identifier_key,
+            "name": self.name,
+            "identity_type": self.identity_type,
+            "project_id": self.project_id,
+            "agents": [agent.to_pydantic() for agent in self.agents],
+        }
+
+        return self.__pydantic_model__(**state)

letta/orm/organization.py

@@ -9,6 +9,7 @@ if TYPE_CHECKING:
 
     from letta.orm.agent import Agent
     from letta.orm.file import FileMetadata
+    from letta.orm.identity import Identity
     from letta.orm.provider import Provider
     from letta.orm.sandbox_config import AgentEnvironmentVariable
     from letta.orm.tool import Tool
@@ -47,6 +48,7 @@ class Organization(SqlalchemyBase):
     )
     agent_passages: Mapped[List["AgentPassage"]] = relationship("AgentPassage", back_populates="organization", cascade="all, delete-orphan")
     providers: Mapped[List["Provider"]] = relationship("Provider", back_populates="organization", cascade="all, delete-orphan")
+    identities: Mapped[List["Identity"]] = relationship("Identity", back_populates="organization", cascade="all, delete-orphan")
 
     @property
     def passages(self) -> List[Union["SourcePassage", "AgentPassage"]]: