letta-nightly 0.5.0.dev20241015104156__tar.gz → 0.5.0.dev20241016104103__tar.gz

letta_nightly-0.5.0.dev20241016104103/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.1
+Name: letta-nightly
+Version: 0.5.0.dev20241016104103
+Summary: Create LLM agents with long-term memory and custom tools
+License: Apache License
+Author: Letta Team
+Author-email: contact@letta.com
+Requires-Python: >=3.10,<3.13
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Provides-Extra: autogen
+Provides-Extra: dev
+Provides-Extra: external-tools
+Provides-Extra: milvus
+Provides-Extra: ollama
+Provides-Extra: postgres
+Provides-Extra: qdrant
+Provides-Extra: server
+Provides-Extra: tests
+Requires-Dist: alembic (>=1.13.3,<2.0.0)
+Requires-Dist: autoflake (>=2.3.0,<3.0.0) ; extra == "dev"
+Requires-Dist: black[jupyter] (>=24.2.0,<25.0.0) ; extra == "dev"
+Requires-Dist: chromadb (>=0.4.24,<0.5.0)
+Requires-Dist: composio-core (>=0.5.28,<0.6.0) ; extra == "external-tools"
+Requires-Dist: composio-langchain (>=0.5.28,<0.6.0) ; extra == "external-tools"
+Requires-Dist: crewai (>=0.41.1,<0.42.0) ; extra == "external-tools"
+Requires-Dist: crewai-tools (>=0.8.3,<0.9.0) ; extra == "external-tools"
+Requires-Dist: datasets (>=2.14.6,<3.0.0) ; extra == "dev"
+Requires-Dist: demjson3 (>=3.0.6,<4.0.0)
+Requires-Dist: docker (>=7.1.0,<8.0.0) ; extra == "external-tools"
+Requires-Dist: docstring-parser (>=0.16,<0.17)
+Requires-Dist: docx2txt (>=0.8,<0.9)
+Requires-Dist: fastapi (>=0.104.1,<0.105.0) ; extra == "server"
+Requires-Dist: html2text (>=2020.1.16,<2021.0.0)
+Requires-Dist: httpx (>=0.27.2,<0.28.0)
+Requires-Dist: httpx-sse (>=0.4.0,<0.5.0)
+Requires-Dist: isort (>=5.13.2,<6.0.0) ; extra == "dev"
+Requires-Dist: jinja2 (>=3.1.4,<4.0.0)
+Requires-Dist: langchain (>=0.2.16,<0.3.0) ; extra == "external-tools"
+Requires-Dist: langchain-community (>=0.2.17,<0.3.0) ; extra == "external-tools"
+Requires-Dist: llama-index (>=0.11.9,<0.12.0)
+Requires-Dist: llama-index-embeddings-ollama (>=0.3.1,<0.4.0) ; extra == "ollama"
+Requires-Dist: llama-index-embeddings-openai (>=0.2.5,<0.3.0)
+Requires-Dist: locust (>=2.31.5,<3.0.0)
+Requires-Dist: nltk (>=3.8.1,<4.0.0)
+Requires-Dist: numpy (>=1.26.2,<2.0.0)
+Requires-Dist: pexpect (>=4.9.0,<5.0.0) ; extra == "dev"
+Requires-Dist: pg8000 (>=1.30.3,<2.0.0) ; extra == "postgres"
+Requires-Dist: pgvector (>=0.2.3,<0.3.0) ; extra == "postgres"
+Requires-Dist: pre-commit (>=3.5.0,<4.0.0) ; extra == "dev"
+Requires-Dist: prettytable (>=3.9.0,<4.0.0)
+Requires-Dist: pyautogen (==0.2.22) ; extra == "autogen"
+Requires-Dist: pydantic (>=2.7.4,<3.0.0)
+Requires-Dist: pydantic-settings (>=2.2.1,<3.0.0)
+Requires-Dist: pymilvus (>=2.4.3,<3.0.0) ; extra == "milvus"
+Requires-Dist: pyright (>=1.1.347,<2.0.0) ; extra == "dev"
+Requires-Dist: pytest-asyncio (>=0.23.2,<0.24.0) ; extra == "dev"
+Requires-Dist: pytest-order (>=1.2.0,<2.0.0) ; extra == "dev"
+Requires-Dist: python-box (>=7.1.1,<8.0.0)
+Requires-Dist: python-multipart (>=0.0.9,<0.0.10)
+Requires-Dist: pytz (>=2023.3.post1,<2024.0)
+Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
+Requires-Dist: qdrant-client (>=1.9.1,<2.0.0) ; extra == "qdrant"
+Requires-Dist: questionary (>=2.0.1,<3.0.0)
+Requires-Dist: setuptools (>=68.2.2,<69.0.0)
+Requires-Dist: sqlalchemy (>=2.0.25,<3.0.0)
+Requires-Dist: sqlalchemy-json (>=0.7.0,<0.8.0)
+Requires-Dist: sqlalchemy-utils (>=0.41.2,<0.42.0)
+Requires-Dist: sqlmodel (>=0.0.16,<0.0.17)
+Requires-Dist: tiktoken (>=0.7.0,<0.8.0)
+Requires-Dist: tqdm (>=4.66.1,<5.0.0)
+Requires-Dist: typer[all] (>=0.9.0,<0.10.0)
+Requires-Dist: uvicorn (>=0.24.0.post1,<0.25.0) ; extra == "server"
+Requires-Dist: websockets (>=12.0,<13.0) ; extra == "server"
+Requires-Dist: wikipedia (>=1.4.0,<2.0.0) ; extra == "external-tools" or extra == "tests"
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/Letta-logo-RGB_GreyonTransparent_cropped_small.png">
+    <source media="(prefers-color-scheme: light)" srcset="assets/Letta-logo-RGB_OffBlackonTransparent_cropped_small.png">
+    <img alt="Letta logo" src="assets/Letta-logo-RGB_GreyonOffBlack_cropped_small.png" width="500">
+  </picture>
+</p>
+
+<div align="center">
+<h1>Letta (previously MemGPT)</h1>
+
+<h3>
+
+[Homepage](https://letta.com) // [Documentation](https://docs.letta.com) // [Letta Cloud](https://forms.letta.com/early-access)
+
+</h3>
+
+**👾 Letta** is an open source framework for building stateful LLM applications. You can use Letta to build **stateful agents** with advanced reasoning capabilities and transparent long-term memory. The Letta framework is white box and model-agnostic.
+  
+[![Discord](https://img.shields.io/discord/1161736243340640419?label=Discord&logo=discord&logoColor=5865F2&style=flat-square&color=5865F2)](https://discord.gg/letta)
+[![Twitter Follow](https://img.shields.io/badge/Follow-%40Letta__AI-1DA1F2?style=flat-square&logo=x&logoColor=white)](https://twitter.com/Letta_AI)
+[![arxiv 2310.08560](https://img.shields.io/badge/Research-2310.08560-B31B1B?logo=arxiv&style=flat-square)](https://arxiv.org/abs/2310.08560)
+[![Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-silver?style=flat-square)](LICENSE)
+[![Release](https://img.shields.io/github/v/release/cpacker/MemGPT?style=flat-square&label=Release&color=limegreen)](https://github.com/cpacker/MemGPT/releases)
+[![GitHub](https://img.shields.io/github/stars/cpacker/MemGPT?style=flat-square&logo=github&label=Stars&color=gold)](https://github.com/cpacker/MemGPT)
+
+</div>
+
+> [!NOTE]
+> **Looking for MemGPT?** You're in the right place!
+>
+> The MemGPT package and Docker image have been renamed to `letta` to clarify the distinction between MemGPT agents and the API server / runtime that runs LLM agents as *services*.
+>
+> You use the **Letta _framework_** to create **MemGPT _agents_**. Read more about the relationship between MemGPT and Letta [here](https://www.letta.com/blog/memgpt-and-letta).
+
+## ⚡ Quickstart
+
+The two main ways to install Letta are through **pypi** (`pip`) or via **Docker**:
+* **`pip`** (guide below) - the easiest way to try Letta, will default to using SQLite and ChromaDB for the database backends
+* **Docker** (guide [here](https://docs.letta.com/install#run-letta-with-docker)) - recommended for production settings, will default to using Postgres (+ pgvector) for the database backend
+
+### Step 1 - Install Letta using `pip`
+```sh
+$ pip install -U letta
+```
+
+### Step 2 - Set your environment variables for your chosen LLM / embedding providers
+```sh
+$ export OPENAI_API_KEY=sk-...
+```
+
+For Ollama (see our full [documentation](https://docs.letta.com/install) for examples of how to set up various providers):
+```sh
+$ export OLLAMA_BASE_URL=http://localhost:11434
+```
+
+### Step 3 - Run the Letta CLI
+
+You can create agents and chat with them via the Letta CLI tool (`letta run`):
+```sh
+$ letta run
+```
+```
+🧬 Creating new agent...
+? Select LLM model: letta-free [type=openai] [ip=https://inference.memgpt.ai]
+? Select embedding model: letta-free [type=hugging-face] [ip=https://embeddings.memgpt.ai]
+->  🤖 Using persona profile: 'sam_pov'
+->  🧑 Using human profile: 'basic'
+->  🛠️  8 tools: send_message, pause_heartbeats, conversation_search, conversation_search_date, archival_memory_insert, archival_memory_search, core_memory_append, core_memory_replace
+
+🎉 Created new agent 'InspiringSpinach'
+
+Hit enter to begin (will request first Letta message)
+
+💭 User engaged. Recognize as Chad. Acknowledge presence and establish connection. Explore interests and engage in meaningful discourse.
+🤖 Hello, Chad. It's nice to meet you. I am keen on learning and exploring new ideas and concepts. Is there a specific topic you'd like to discuss today?
+
+> Enter your message: my name is Brad, not Chad...
+
+💭 A discrepancy in identity. Reflect this change in core memory. Apologize for the oversight, and rectify the error.
+⚡🧠 [function] updating memory with core_memory_replace
+         First name: Chad
+        → First name: Brad
+💭 Apologize for the mistake in recognizing his name, and begin the conversation anew, addressing him by the correct name this time.
+🤖 I apologize for the oversight, Brad. Let's restart. It's a pleasure to meet you, Brad. Is there a specific topic you'd like to discuss today?
+
+> Enter your message:
+```
+
+### Step 4 - Run the Letta server
+
+You can start the Letta API server with `letta server` (see the full API reference [here](https://docs.letta.com/api-reference)):
+```sh
+$ letta server
+```
+```
+Initializing database...
+Running: uvicorn server:app --host localhost --port 8283
+INFO:     Started server process [47750]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+INFO:     Uvicorn running on http://localhost:8283 (Press CTRL+C to quit)
+```
+
+When you start the Letta API server, the ADE (Agent Development Environment) will be available on `http://localhost:8283`:
+<img alt="Screenshot of the Letta ADE (Agent Development Environment)" src="assets/letta_ade_screenshot.png" width="1600">
+
+In Letta, all agents are stored/persisted in the same database, so the agents you create in the CLI are accessible via the API and ADE, and vice versa. Check out the [quickstart guide on our docs](https://docs.letta.com/quickstart) for a tutorial where you create an agent in the Letta CLI and message the same agent via the Letta API.
+
+## 🤗 How to contribute
+
+Letta is an open source project built by over a hundred contributors. There are many ways to get involved in the Letta OSS project!
+
+* **Contribute to the project**: Interested in contributing? Start by reading our [Contribution Guidelines](https://github.com/cpacker/MemGPT/tree/main/CONTRIBUTING.md).
+* **Ask a question**: Join our community on [Discord](https://discord.gg/letta) and direct your questions to the `#support` channel.
+* **Report ssues or suggest features**: Have an issue or a feature request? Please submit them through our [GitHub Issues page](https://github.com/cpacker/MemGPT/issues).
+* **Explore the roadmap**: Curious about future developments? View and comment on our [project roadmap](https://github.com/cpacker/MemGPT/issues/1533).
+* **Join community events**: Stay updated with the [event calendar](https://lu.ma/berkeley-llm-meetup) or follow our [Twitter account](https://twitter.com/Letta_AI).
+
+---
+
+***Legal notices**: By using Letta and related Letta services (such as the Letta endpoint or hosted service), you are agreeing to our [privacy policy](https://www.letta.com/privacy-policy) and [terms of service](https://www.letta.com/terms-of-service).*
+

letta_nightly-0.5.0.dev20241016104103/README.md

@@ -0,0 +1,122 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/Letta-logo-RGB_GreyonTransparent_cropped_small.png">
+    <source media="(prefers-color-scheme: light)" srcset="assets/Letta-logo-RGB_OffBlackonTransparent_cropped_small.png">
+    <img alt="Letta logo" src="assets/Letta-logo-RGB_GreyonOffBlack_cropped_small.png" width="500">
+  </picture>
+</p>
+
+<div align="center">
+<h1>Letta (previously MemGPT)</h1>
+
+<h3>
+
+[Homepage](https://letta.com) // [Documentation](https://docs.letta.com) // [Letta Cloud](https://forms.letta.com/early-access)
+
+</h3>
+
+**👾 Letta** is an open source framework for building stateful LLM applications. You can use Letta to build **stateful agents** with advanced reasoning capabilities and transparent long-term memory. The Letta framework is white box and model-agnostic.
+  
+[![Discord](https://img.shields.io/discord/1161736243340640419?label=Discord&logo=discord&logoColor=5865F2&style=flat-square&color=5865F2)](https://discord.gg/letta)
+[![Twitter Follow](https://img.shields.io/badge/Follow-%40Letta__AI-1DA1F2?style=flat-square&logo=x&logoColor=white)](https://twitter.com/Letta_AI)
+[![arxiv 2310.08560](https://img.shields.io/badge/Research-2310.08560-B31B1B?logo=arxiv&style=flat-square)](https://arxiv.org/abs/2310.08560)
+[![Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-silver?style=flat-square)](LICENSE)
+[![Release](https://img.shields.io/github/v/release/cpacker/MemGPT?style=flat-square&label=Release&color=limegreen)](https://github.com/cpacker/MemGPT/releases)
+[![GitHub](https://img.shields.io/github/stars/cpacker/MemGPT?style=flat-square&logo=github&label=Stars&color=gold)](https://github.com/cpacker/MemGPT)
+
+</div>
+
+> [!NOTE]
+> **Looking for MemGPT?** You're in the right place!
+>
+> The MemGPT package and Docker image have been renamed to `letta` to clarify the distinction between MemGPT agents and the API server / runtime that runs LLM agents as *services*.
+>
+> You use the **Letta _framework_** to create **MemGPT _agents_**. Read more about the relationship between MemGPT and Letta [here](https://www.letta.com/blog/memgpt-and-letta).
+
+## ⚡ Quickstart
+
+The two main ways to install Letta are through **pypi** (`pip`) or via **Docker**:
+* **`pip`** (guide below) - the easiest way to try Letta, will default to using SQLite and ChromaDB for the database backends
+* **Docker** (guide [here](https://docs.letta.com/install#run-letta-with-docker)) - recommended for production settings, will default to using Postgres (+ pgvector) for the database backend
+
+### Step 1 - Install Letta using `pip`
+```sh
+$ pip install -U letta
+```
+
+### Step 2 - Set your environment variables for your chosen LLM / embedding providers
+```sh
+$ export OPENAI_API_KEY=sk-...
+```
+
+For Ollama (see our full [documentation](https://docs.letta.com/install) for examples of how to set up various providers):
+```sh
+$ export OLLAMA_BASE_URL=http://localhost:11434
+```
+
+### Step 3 - Run the Letta CLI
+
+You can create agents and chat with them via the Letta CLI tool (`letta run`):
+```sh
+$ letta run
+```
+```
+🧬 Creating new agent...
+? Select LLM model: letta-free [type=openai] [ip=https://inference.memgpt.ai]
+? Select embedding model: letta-free [type=hugging-face] [ip=https://embeddings.memgpt.ai]
+->  🤖 Using persona profile: 'sam_pov'
+->  🧑 Using human profile: 'basic'
+->  🛠️  8 tools: send_message, pause_heartbeats, conversation_search, conversation_search_date, archival_memory_insert, archival_memory_search, core_memory_append, core_memory_replace
+
+🎉 Created new agent 'InspiringSpinach'
+
+Hit enter to begin (will request first Letta message)
+
+💭 User engaged. Recognize as Chad. Acknowledge presence and establish connection. Explore interests and engage in meaningful discourse.
+🤖 Hello, Chad. It's nice to meet you. I am keen on learning and exploring new ideas and concepts. Is there a specific topic you'd like to discuss today?
+
+> Enter your message: my name is Brad, not Chad...
+
+💭 A discrepancy in identity. Reflect this change in core memory. Apologize for the oversight, and rectify the error.
+⚡🧠 [function] updating memory with core_memory_replace
+         First name: Chad
+        → First name: Brad
+💭 Apologize for the mistake in recognizing his name, and begin the conversation anew, addressing him by the correct name this time.
+🤖 I apologize for the oversight, Brad. Let's restart. It's a pleasure to meet you, Brad. Is there a specific topic you'd like to discuss today?
+
+> Enter your message:
+```
+
+### Step 4 - Run the Letta server
+
+You can start the Letta API server with `letta server` (see the full API reference [here](https://docs.letta.com/api-reference)):
+```sh
+$ letta server
+```
+```
+Initializing database...
+Running: uvicorn server:app --host localhost --port 8283
+INFO:     Started server process [47750]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+INFO:     Uvicorn running on http://localhost:8283 (Press CTRL+C to quit)
+```
+
+When you start the Letta API server, the ADE (Agent Development Environment) will be available on `http://localhost:8283`:
+<img alt="Screenshot of the Letta ADE (Agent Development Environment)" src="assets/letta_ade_screenshot.png" width="1600">
+
+In Letta, all agents are stored/persisted in the same database, so the agents you create in the CLI are accessible via the API and ADE, and vice versa. Check out the [quickstart guide on our docs](https://docs.letta.com/quickstart) for a tutorial where you create an agent in the Letta CLI and message the same agent via the Letta API.
+
+## 🤗 How to contribute
+
+Letta is an open source project built by over a hundred contributors. There are many ways to get involved in the Letta OSS project!
+
+* **Contribute to the project**: Interested in contributing? Start by reading our [Contribution Guidelines](https://github.com/cpacker/MemGPT/tree/main/CONTRIBUTING.md).
+* **Ask a question**: Join our community on [Discord](https://discord.gg/letta) and direct your questions to the `#support` channel.
+* **Report ssues or suggest features**: Have an issue or a feature request? Please submit them through our [GitHub Issues page](https://github.com/cpacker/MemGPT/issues).
+* **Explore the roadmap**: Curious about future developments? View and comment on our [project roadmap](https://github.com/cpacker/MemGPT/issues/1533).
+* **Join community events**: Stay updated with the [event calendar](https://lu.ma/berkeley-llm-meetup) or follow our [Twitter account](https://twitter.com/Letta_AI).
+
+---
+
+***Legal notices**: By using Letta and related Letta services (such as the Letta endpoint or hosted service), you are agreeing to our [privacy policy](https://www.letta.com/privacy-policy) and [terms of service](https://www.letta.com/terms-of-service).*

{letta_nightly-0.5.0.dev20241015104156 → letta_nightly-0.5.0.dev20241016104103}/letta/agent.py

@@ -11,14 +11,19 @@ from letta.agent_store.storage import StorageConnector
 from letta.constants import (
     CLI_WARNING_PREFIX,
     FIRST_MESSAGE_ATTEMPTS,
+    FUNC_FAILED_HEARTBEAT_MESSAGE,
     IN_CONTEXT_MEMORY_KEYWORD,
     LLM_MAX_TOKENS,
     MESSAGE_SUMMARY_TRUNC_KEEP_N_LAST,
     MESSAGE_SUMMARY_TRUNC_TOKEN_FRAC,
     MESSAGE_SUMMARY_WARNING_FRAC,
+    REQ_HEARTBEAT_MESSAGE,
 )
+from letta.errors import LLMError
 from letta.interface import AgentInterface
+from letta.llm_api.helpers import is_context_overflow_error
 from letta.llm_api.llm_api_tools import create
+from letta.local_llm.utils import num_tokens_from_messages
 from letta.memory import ArchivalMemory, RecallMemory, summarize_messages
 from letta.metadata import MetadataStore
 from letta.persistence_manager import LocalStateManager
@@ -26,17 +31,21 @@ from letta.schemas.agent import AgentState, AgentStepResponse
 from letta.schemas.block import Block
 from letta.schemas.embedding_config import EmbeddingConfig
 from letta.schemas.enums import MessageRole, OptionState
-from letta.schemas.memory import Memory
+from letta.schemas.memory import ContextWindowOverview, Memory
 from letta.schemas.message import Message, UpdateMessage
 from letta.schemas.openai.chat_completion_response import ChatCompletionResponse
 from letta.schemas.openai.chat_completion_response import (
     Message as ChatCompletionMessage,
 )
+from letta.schemas.openai.chat_completion_response import UsageStatistics
 from letta.schemas.passage import Passage
 from letta.schemas.tool import Tool
+from letta.schemas.usage import LettaUsageStatistics
 from letta.system import (
+    get_heartbeat,
     get_initial_boot_messages,
     get_login_event,
+    get_token_limit_warning,
     package_function_response,
     package_summarize_message,
     package_user_message,
@@ -56,9 +65,6 @@ from letta.utils import (
     verify_first_message_correctness,
 )
 
-from .errors import LLMError
-from .llm_api.helpers import is_context_overflow_error
-
 
 def compile_memory_metadata_block(
     memory_edit_timestamp: datetime.datetime,
@@ -202,7 +208,7 @@ class BaseAgent(ABC):
     def step(
         self,
         messages: Union[Message, List[Message]],
-    ) -> AgentStepResponse:
+    ) -> LettaUsageStatistics:
         """
         Top-level event message handler for the agent.
         """
@@ -721,18 +727,105 @@ class Agent(BaseAgent):
         return messages, heartbeat_request, function_failed
 
     def step(
+        self,
+        messages: Union[Message, List[Message]],
+        # additional args
+        chaining: bool = True,
+        max_chaining_steps: Optional[int] = None,
+        ms: Optional[MetadataStore] = None,
+        **kwargs,
+    ) -> LettaUsageStatistics:
+        """Run Agent.step in a loop, handling chaining via heartbeat requests and function failures"""
+        # assert ms is not None, "MetadataStore is required"
+
+        next_input_message = messages if isinstance(messages, list) else [messages]
+        counter = 0
+        total_usage = UsageStatistics()
+        step_count = 0
+        while True:
+            kwargs["ms"] = ms
+            kwargs["first_message"] = False
+            step_response = self.inner_step(
+                messages=next_input_message,
+                **kwargs,
+            )
+            step_response.messages
+            heartbeat_request = step_response.heartbeat_request
+            function_failed = step_response.function_failed
+            token_warning = step_response.in_context_memory_warning
+            usage = step_response.usage
+
+            step_count += 1
+            total_usage += usage
+            counter += 1
+            self.interface.step_complete()
+
+            # logger.debug("Saving agent state")
+            # save updated state
+            if ms:
+                save_agent(self, ms)
+
+            # Chain stops
+            if not chaining:
+                printd("No chaining, stopping after one step")
+                break
+            elif max_chaining_steps is not None and counter > max_chaining_steps:
+                printd(f"Hit max chaining steps, stopping after {counter} steps")
+                break
+            # Chain handlers
+            elif token_warning:
+                assert self.agent_state.user_id is not None
+                next_input_message = Message.dict_to_message(
+                    agent_id=self.agent_state.id,
+                    user_id=self.agent_state.user_id,
+                    model=self.model,
+                    openai_message_dict={
+                        "role": "user",  # TODO: change to system?
+                        "content": get_token_limit_warning(),
+                    },
+                )
+                continue  # always chain
+            elif function_failed:
+                assert self.agent_state.user_id is not None
+                next_input_message = Message.dict_to_message(
+                    agent_id=self.agent_state.id,
+                    user_id=self.agent_state.user_id,
+                    model=self.model,
+                    openai_message_dict={
+                        "role": "user",  # TODO: change to system?
+                        "content": get_heartbeat(FUNC_FAILED_HEARTBEAT_MESSAGE),
+                    },
+                )
+                continue  # always chain
+            elif heartbeat_request:
+                assert self.agent_state.user_id is not None
+                next_input_message = Message.dict_to_message(
+                    agent_id=self.agent_state.id,
+                    user_id=self.agent_state.user_id,
+                    model=self.model,
+                    openai_message_dict={
+                        "role": "user",  # TODO: change to system?
+                        "content": get_heartbeat(REQ_HEARTBEAT_MESSAGE),
+                    },
+                )
+                continue  # always chain
+            # Letta no-op / yield
+            else:
+                break
+
+        return LettaUsageStatistics(**total_usage.model_dump(), step_count=step_count)
+
+    def inner_step(
         self,
         messages: Union[Message, List[Message]],
         first_message: bool = False,
         first_message_retry_limit: int = FIRST_MESSAGE_ATTEMPTS,
         skip_verify: bool = False,
-        return_dicts: bool = True,
-        # recreate_message_timestamp: bool = True,  # if True, when input is a Message type, recreated the 'created_at' field
         stream: bool = False,  # TODO move to config?
         inner_thoughts_in_kwargs_option: OptionState = OptionState.DEFAULT,
         ms: Optional[MetadataStore] = None,
     ) -> AgentStepResponse:
-        """Top-level event message handler for the Letta agent"""
+        """Runs a single step in the agent loop (generates at most one LLM call)"""
 
         try:
 
@@ -834,13 +927,12 @@ class Agent(BaseAgent):
                 )
 
             self._append_to_messages(all_new_messages)
-            messages_to_return = [msg.to_openai_dict() for msg in all_new_messages] if return_dicts else all_new_messages
 
             # update state after each step
             self.update_state()
 
             return AgentStepResponse(
-                messages=messages_to_return,
+                messages=all_new_messages,
                 heartbeat_request=heartbeat_request,
                 function_failed=function_failed,
                 in_context_memory_warning=active_memory_warning,
@@ -856,15 +948,12 @@ class Agent(BaseAgent):
                 self.summarize_messages_inplace()
 
                 # Try step again
-                return self.step(
+                return self.inner_step(
                     messages=messages,
                     first_message=first_message,
                     first_message_retry_limit=first_message_retry_limit,
                     skip_verify=skip_verify,
-                    return_dicts=return_dicts,
-                    # recreate_message_timestamp=recreate_message_timestamp,
                     stream=stream,
-                    # timestamp=timestamp,
                     inner_thoughts_in_kwargs_option=inner_thoughts_in_kwargs_option,
                     ms=ms,
                 )
@@ -905,7 +994,7 @@ class Agent(BaseAgent):
             # created_at=timestamp,
         )
 
-        return self.step(messages=[user_message], **kwargs)
+        return self.inner_step(messages=[user_message], **kwargs)
 
     def summarize_messages_inplace(self, cutoff=None, preserve_last_N_messages=True, disallow_tool_as_first=True):
         assert self.messages[0]["role"] == "system", f"self.messages[0] should be system (instead got {self.messages[0]})"
@@ -1326,13 +1415,78 @@ class Agent(BaseAgent):
         self.pop_until_user()
         user_message = self.pop_message(count=1)[0]
         assert user_message.text is not None, "User message text is None"
-        step_response = self.step_user_message(user_message_str=user_message.text, return_dicts=False)
+        step_response = self.step_user_message(user_message_str=user_message.text)
         messages = step_response.messages
 
         assert messages is not None
         assert all(isinstance(msg, Message) for msg in messages), "step() returned non-Message objects"
         return messages
 
+    def get_context_window(self) -> ContextWindowOverview:
+        """Get the context window of the agent"""
+
+        system_prompt = self.agent_state.system  # TODO is this the current system or the initial system?
+        num_tokens_system = count_tokens(system_prompt)
+        core_memory = self.memory.compile()
+        num_tokens_core_memory = count_tokens(core_memory)
+
+        # conversion of messages to OpenAI dict format, which is passed to the token counter
+        messages_openai_format = self.messages
+
+        # Check if there's a summary message in the message queue
+        if (
+            len(self._messages) > 1
+            and self._messages[1].role == MessageRole.user
+            and isinstance(self._messages[1].text, str)
+            # TODO remove hardcoding
+            and "The following is a summary of the previous " in self._messages[1].text
+        ):
+            # Summary message exists
+            assert self._messages[1].text is not None
+            summary_memory = self._messages[1].text
+            num_tokens_summary_memory = count_tokens(self._messages[1].text)
+            # with a summary message, the real messages start at index 2
+            num_tokens_messages = (
+                num_tokens_from_messages(messages=messages_openai_format[2:], model=self.model) if len(messages_openai_format) > 2 else 0
+            )
+
+        else:
+            summary_memory = None
+            num_tokens_summary_memory = 0
+            # with no summary message, the real messages start at index 1
+            num_tokens_messages = (
+                num_tokens_from_messages(messages=messages_openai_format[1:], model=self.model) if len(messages_openai_format) > 1 else 0
+            )
+
+        num_archival_memory = self.persistence_manager.archival_memory.storage.size()
+        num_recall_memory = self.persistence_manager.recall_memory.storage.size()
+        external_memory_summary = compile_memory_metadata_block(
+            memory_edit_timestamp=get_utc_time(),  # dummy timestamp
+            archival_memory=self.persistence_manager.archival_memory,
+            recall_memory=self.persistence_manager.recall_memory,
+        )
+        num_tokens_external_memory_summary = count_tokens(external_memory_summary)
+
+        return ContextWindowOverview(
+            # context window breakdown (in messages)
+            num_messages=len(self._messages),
+            num_archival_memory=num_archival_memory,
+            num_recall_memory=num_recall_memory,
+            num_tokens_external_memory_summary=num_tokens_external_memory_summary,
+            # top-level information
+            context_window_size_max=self.agent_state.llm_config.context_window,
+            context_window_size_current=num_tokens_system + num_tokens_core_memory + num_tokens_summary_memory + num_tokens_messages,
+            # context window breakdown (in tokens)
+            num_tokens_system=num_tokens_system,
+            system_prompt=system_prompt,
+            num_tokens_core_memory=num_tokens_core_memory,
+            core_memory=core_memory,
+            num_tokens_summary_memory=num_tokens_summary_memory,
+            summary_memory=summary_memory,
+            num_tokens_messages=num_tokens_messages,
+            messages=self._messages,
+        )
+
 
 def save_agent(agent: Agent, ms: MetadataStore):
     """Save agent to metadata store"""