marvin 2.3.0__tar.gz → 2.3.2__tar.gz

{marvin-2.3.0 → marvin-2.3.2}/.github/workflows/static-analysis.yml

@@ -15,7 +15,6 @@ permissions:
   contents: read
 
 jobs:
-
   static_analysis:
     timeout-minutes: 1
 

{marvin-2.3.0 → marvin-2.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: marvin
-Version: 2.3.0
+Version: 2.3.2
 Summary: A lightweight AI engineering toolkit for building natural language interfaces that are reliable, scalable, and easy to trust.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -217,7 +217,8 @@ Requires-Dist: fastapi
 Requires-Dist: httpx>=0.24.1
 Requires-Dist: jinja2>=3.1.2
 Requires-Dist: jsonpatch>=1.33
-Requires-Dist: openai>=1.4.0
+Requires-Dist: openai>=1.21.0
+Requires-Dist: prompt-toolkit>=3.0.33
 Requires-Dist: pydantic>=2.4.2
 Requires-Dist: pydantic_settings
 Requires-Dist: rich>=12
@@ -248,6 +249,7 @@ Requires-Dist: pre-commit<4.0,>=2.21; extra == "dev"
 Requires-Dist: pydantic[dotenv]; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
 Provides-Extra: tests
+Requires-Dist: flaky; extra == "tests"
 Requires-Dist: pytest-asyncio!=0.22.0,<0.23.0,>=0.18.2; extra == "tests"
 Requires-Dist: pytest-env<2.0,>=0.8; extra == "tests"
 Requires-Dist: pytest-rerunfailures<14,>=10; extra == "tests"
@@ -258,9 +260,6 @@ Requires-Dist: pytest-xdist; extra == "tests"
 Provides-Extra: audio
 Requires-Dist: SpeechRecognition>=3.10; extra == "audio"
 Requires-Dist: PyAudio>=0.2.11; extra == "audio"
-Requires-Dist: playsound>=1.0; extra == "audio"
-Requires-Dist: wheel>=0.43.0; extra == "audio"
-Requires-Dist: PyObjC; extra == "audio"
 Requires-Dist: pydub>=0.25; extra == "audio"
 Requires-Dist: simpleaudio>=1.0; extra == "audio"
 Provides-Extra: video
@@ -268,7 +267,8 @@ Requires-Dist: opencv-python>=4.5; extra == "video"
 Provides-Extra: slackbot
 Requires-Dist: marvin[prefect]; extra == "slackbot"
 Requires-Dist: numpy; extra == "slackbot"
-Requires-Dist: marvin[chromadb]; extra == "slackbot"
+Requires-Dist: raggy; extra == "slackbot"
+Requires-Dist: turbopuffer; extra == "slackbot"
 
 <p align="center">
   <img src="docs/assets/images/heroes/it_hates_me_hero.png" style="width: 95%; height: auto;"/>
@@ -514,7 +514,7 @@ In addition to text, Marvin has beta support for captioning, classifying, transf
 
 ```python
 marvin.beta.classify(
-    marvin.Image("docs/images/coffee.png"),
+    marvin.beta.Image("docs/images/coffee.png"),
     labels=["drink", "food"],
 )
 

{marvin-2.3.0 → marvin-2.3.2}/README.md

@@ -242,7 +242,7 @@ In addition to text, Marvin has beta support for captioning, classifying, transf
 
 ```python
 marvin.beta.classify(
-    marvin.Image("docs/images/coffee.png"),
+    marvin.beta.Image("docs/images/coffee.png"),
     labels=["drink", "food"],
 )
 

{marvin-2.3.0 → marvin-2.3.2}/cookbook/azure/README.md

@@ -26,7 +26,7 @@ As an alternative to setting environment variables, you can pass the `AzureOpenA
 
 ```python
 import marvin
-from marvin.client import MarvinClient
+from marvin.client import AsyncMarvinClient
 
 from openai import AzureOpenAI
 
@@ -37,7 +37,7 @@ azure_openai_client = AzureOpenAI(
 )
 
 @marvin.fn(
-    client=MarvinClient(client=azure_openai_client),
+    client=AsyncMarvinClient(client=azure_openai_client),
     model_kwargs={"model": "your_deployment_name"}
 )
 def list_fruits(n: int) -> list[str]:

marvin-2.3.2/cookbook/gh_util/custom_assistant.py

@@ -0,0 +1,20 @@
+from gh_util.api import functions  # pip install gh-util
+from marvin.beta.applications import Application
+from pydantic import BaseModel, Field
+
+
+class Memory(BaseModel):
+    notes: list[str] = Field(default_factory=list)
+
+
+octocat = Application(
+    name="octocat",
+    state=Memory(),
+    tools=[f for f in functions if f.__name__ != "run_git_command"],
+)
+
+# $ marvin assistant register cookbook/gh_util/custom_assistant.py:octocat
+
+# > what's the latest release of prefecthq/marvin?
+
+# see https://github.com/PrefectHQ/marvin/pull/875

marvin-2.3.2/cookbook/logfire/README.md

@@ -0,0 +1,41 @@
+## using logfire with marvin
+
+[logfire](https://github.com/pydantic/logfire?tab=readme-ov-file#pydantic-logfire--uncomplicated-observability) is brand new (Apr 2024) and is an observability tool for python applications - [otel](https://opentelemetry.io/docs/what-is-opentelemetry/)-based tracing, metrics, and logging. its pretty [awesome](https://docs.pydantic.dev/logfire/#pydantic-logfire-the-observability-platform-you-deserve).
+
+they also happen to wrap OpenAI pretty well out of the box! see `hello.py` for a simple example.
+
+### setup
+```conosle
+pip install marvin
+```
+> [!NOTE]
+> optionally, if you want to try out the fastapi integration
+> ```console
+> pip install 'logfire[fastapi]' uvicorn
+> ```
+
+login to logfire
+```console
+logfire auth
+```
+
+### usage
+use of marvin should be no different than any other library. check out [logfire's documentation](https://docs.pydantic.dev/logfire/#pydantic-logfire-the-observability-platform-you-deserve) for more information.
+
+
+### examples
+```console
+gh repo clone prefecthq/marvin && cd marvin
+uvicorn cookbook.logfire.demo_app:app
+```
+
+in another terminal
+```console
+python cookbook/logfire/send_demo_request.py
+```
+
+check out the api docs at http://localhost:8000/docs or your logfire dashboard to see the traces and logs like:
+
+<p align="center">
+  <img src="/docs/assets/images/docs/examples/logfire-span.jpeg" alt="logfire span"/>
+</p>

marvin-2.3.2/cookbook/logfire/auto_trace.py

@@ -0,0 +1,7 @@
+import logfire
+
+logfire.install_auto_tracing(modules=["hello"])
+
+from hello import main  # noqa
+
+main()

marvin-2.3.2/cookbook/logfire/demo_app.py

@@ -0,0 +1,79 @@
+from enum import Enum
+
+import logfire
+import openai
+from fastapi import Body, FastAPI
+from marvin import fn
+from marvin.client import AsyncMarvinClient
+from pydantic import BaseModel
+
+app = FastAPI()
+client = openai.AsyncClient()
+
+logfire.configure(pydantic_plugin=logfire.PydanticPlugin(record="all"))
+logfire.instrument_openai(client)
+logfire.instrument_fastapi(app)
+
+
+class Seniority(Enum):
+    """ranked seniority levels for candidates"""
+
+    JUNIOR = 1
+    MID = 2
+    SENIOR = 3
+    STAFF = 4
+
+
+class Candidate(BaseModel):
+    name: str
+    self_identified_seniority: Seniority
+    bio: str
+
+
+class Role(BaseModel):
+    title: str
+    desired_seniority: Seniority
+    description: str
+
+
+@fn(client=AsyncMarvinClient(client=client))
+def choose_among_candidates(cohort: list[Candidate], role: Role) -> Candidate:
+    return (
+        f"We need a {role.desired_seniority.name} (at least) {role.title} that can "
+        f"most likely fulfill a job of this description:\n{role.description}\n"
+    )
+
+
+@logfire.instrument("Dystopian Interview Process", extract_args=True)
+def dystopian_interview_process(candidates: list[Candidate], role: Role) -> Candidate:
+    senior_enough_candidates = [
+        candidate
+        for candidate in candidates
+        if candidate.self_identified_seniority.value >= role.desired_seniority.value
+    ]
+    logfire.info(
+        "Candidates at or above {seniority} level: {cohort}",
+        cohort=[c.name for c in senior_enough_candidates],
+        seniority=role.desired_seniority,
+    )
+    if len(senior_enough_candidates) == 1:
+        return senior_enough_candidates[0]
+
+    with logfire.span("Choosing among candidates"):
+        return choose_among_candidates(senior_enough_candidates, role)
+
+
+@app.post("/interview")
+async def interview(
+    candidates: list[Candidate] = Body(..., description="List of candidates"),
+    role: Role = Body(..., description="Role to fill"),
+) -> Candidate:
+    best_candidate = dystopian_interview_process(candidates, role)
+    logfire.info("Best candidate: {best_candidate}", best_candidate=best_candidate)
+    return best_candidate
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="localhost", port=8000)

marvin-2.3.2/cookbook/logfire/hello.py

@@ -0,0 +1,40 @@
+"""
+Example of using logfire to instrument OpenAI API calls
+
+see https://x.com/Nathan_Nowack/status/1785413529232708087
+"""
+
+import logfire
+import openai
+from marvin import fn
+from marvin.client import AsyncMarvinClient
+from pydantic import BaseModel, Field
+
+client = openai.AsyncClient()
+
+logfire.instrument_openai(client)
+
+
+class Ingredients(BaseModel):
+    name: str
+    approximate_price: float = Field(..., gt=0, description="Price in USD")
+    quantity: int
+
+
+class Recipe(BaseModel):
+    ingredients: list[Ingredients]
+    steps: list[str]
+
+
+@fn(client=AsyncMarvinClient(client=client))
+def make_recipe(vibe: str) -> Recipe:
+    """Generate a recipe based on a vibe"""
+
+
+def main():
+    recipe = make_recipe("italian, for 4 people")
+    assert isinstance(recipe, Recipe)
+
+
+if __name__ == "__main__":
+    main()

marvin-2.3.2/cookbook/logfire/send_demo_request.py

@@ -0,0 +1,47 @@
+import asyncio
+import json
+
+import httpx
+
+
+async def main():
+    candidates = [
+        {
+            "name": "Alice",
+            "self_identified_seniority": 3,
+            "bio": "10 years with postgres, 5 years with python, 3 years with django.",
+        },
+        {
+            "name": "Bob",
+            "self_identified_seniority": 1,
+            "bio": "I just graduated from a coding bootcamp and I'm ready to take on the world!",
+        },
+        {
+            "name": "Charlie",
+            "self_identified_seniority": 2,
+            "bio": "graduated 2 years ago and i can make you a react app in no time",
+        },
+        {
+            "name": "David",
+            "self_identified_seniority": 3,
+            "bio": "i just been riding that SCRUM wave for 10 years fam",
+        },
+    ]
+
+    role = {
+        "title": "Senior Software Engineer",
+        "desired_seniority": 3,
+        "description": "Build and maintain a large-scale web application with a team of 10+ engineers.",
+    }
+
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            "http://localhost:8000/interview",
+            json={"candidates": candidates, "role": role},
+        )
+        result = response.json()
+        print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

marvin-2.3.2/cookbook/reasking.py

@@ -0,0 +1,24 @@
+from typing import Annotated
+
+import marvin
+from marvin.beta.retries import retry_fn_on_validation_error
+from pydantic import AfterValidator
+
+
+def verify_random_number(number: int) -> int:
+    if number != 37:
+        raise ValueError("Everyone knows the most random number is 37!")
+    return number
+
+
+RandomNumber = Annotated[int, AfterValidator(verify_random_number)]
+
+
+@retry_fn_on_validation_error  # shows the validation error message in subsequent retries
+@marvin.fn
+def get_random_number() -> RandomNumber:
+    """returns a random number"""
+
+
+if __name__ == "__main__":
+    print(get_random_number())

marvin-2.3.2/cookbook/slackbot/Dockerfile.slackbot

@@ -0,0 +1,23 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY . /app
+
+RUN apt-get update && \
+    apt-get install -y git build-essential curl && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+RUN pip install uv && uv venv
+
+ENV VIRTUAL_ENV=/app/.venv
+RUN uv venv
+
+ENV PATH="$VIRTUAL_ENV/bin:$PATH"
+
+RUN uv pip install ".[slackbot]"
+
+EXPOSE 4200
+
+CMD ["python", "cookbook/slackbot/start.py"]

{marvin-2.3.0 → marvin-2.3.2}/cookbook/slackbot/start.py

@@ -1,13 +1,14 @@
 import asyncio
+import os
 import re
 
+import marvin
 import uvicorn
 from fastapi import FastAPI, HTTPException, Request
 from keywords import handle_keywords
 from marvin.beta.applications import Application
 from marvin.beta.applications.state.json_block import JSONBlockState
 from marvin.beta.assistants import Assistant, Thread
-from marvin.tools.chroma import store_document
 from marvin.tools.github import search_github_issues
 from marvin.utilities.logging import get_logger
 from marvin.utilities.slack import (
@@ -38,7 +39,7 @@ def get_feature_flag_value(flag_name: str) -> bool:
 ENABLE_PARENT_APP = get_feature_flag_value("enable-parent-app")
 
 
-@flow(name="Handle Slack Message")
+@flow(name="Handle Slack Message", retries=1)
 async def handle_message(payload: SlackPayload) -> Completed:
     user_message = (event := payload.event).text
     cleaned_message = re.sub(BOT_MENTION, "", user_message).strip()
@@ -83,16 +84,6 @@ async def handle_message(payload: SlackPayload) -> Completed:
         )
         user_name, user_notes = (await get_notes_for_user(user_id=event.user)).popitem()
 
-        task(store_document).submit(
-            document=cleaned_message,
-            metadata={
-                "user": f"{user_name} ({event.user})",
-                "user_notes": user_notes or "",
-                "channel": await get_channel_name(event.channel),
-                "thread": thread,
-            },
-        )
-
         with Assistant(
             name="Marvin",
             tools=[
@@ -114,6 +105,9 @@ async def handle_message(payload: SlackPayload) -> Completed:
                 " prioritize brevity in your responses, and format text prettily for Slack."
                 f"{ ('here are some notes on the user:' + user_notes) if user_notes else ''}"
                 " ALWAYS provide links to the source of your information - let's think step-by-step."
+                " If a tool returns an irrelevant/bad result, you should try another tool."
+                " KEEP IN MIND that agents are deprecated in favor of workers, so you should"
+                " never recommend `prefect agent` commands, suggest `prefect worker` instead."
             ),
         ) as ai:
             logger.debug_kv(
@@ -197,4 +191,7 @@ async def chat_endpoint(request: Request):
 
 
 if __name__ == "__main__":
+    if not os.getenv("OPENAI_API_KEY", None):  # TODO: Remove this
+        os.environ["OPENAI_API_KEY"] = marvin.settings.openai.api_key.get_secret_value()
+
     uvicorn.run(app, host="0.0.0.0", port=4200)

{marvin-2.3.0 → marvin-2.3.2}/cookbook/slackbot/tools.py

@@ -3,7 +3,9 @@ from typing import Literal
 
 import httpx
 import marvin
-from marvin.tools.chroma import multi_query_chroma
+import turbopuffer as tpuf
+from prefect.blocks.system import Secret
+from raggy.vectorstores.tpuf import multi_query_tpuf
 
 Topic = Literal["latest_prefect_version"]
 
@@ -21,7 +23,10 @@ async def search_prefect_docs(queries: list[str]) -> str:
     - "retrieve run metadata dynamically"
 
     """
-    return await multi_query_chroma(queries=queries, n_results=3)
+    if not tpuf.api_key:
+        tpuf.api_key = (await Secret.load("tpuf-api-key")).get()
+
+    return await multi_query_tpuf(queries, namespace="marvin-slackbot")
 
 
 async def get_latest_release_notes() -> str:

marvin-2.3.2/cookbook/translate_schemas.py

@@ -0,0 +1,18 @@
+import marvin
+from pydantic import BaseModel
+
+
+class FooModel(BaseModel):
+    identifier: str
+    name: str
+
+
+class BarModel(BaseModel):
+    id: int
+    first_name: str
+    last_name: str
+
+
+bar = marvin.cast(FooModel(identifier="42", name="Marvin Robot"), BarModel)
+
+assert bar.model_dump() == {"id": 42, "first_name": "Marvin", "last_name": "Robot"}

{marvin-2.3.0 → marvin-2.3.2}/docs/docs/audio/speech.md

@@ -24,7 +24,7 @@ Marvin can generate speech from text.
 
         !!! success "Result"
             ```python
-            audio.stream_to_file("fancy_computer.mp3")
+            audio.play("fancy_computer.mp3")
             ```
             <audio controls>
               <source src="/assets/audio/fancy_computer.mp3" type="audio/mpeg">
@@ -47,7 +47,7 @@ Marvin can generate speech from text.
 
         !!! success "Result"
             ```python
-            audio.stream_to_file("hello_arthur.mp3")
+            audio.play("hello_arthur.mp3")
             ```
             <audio controls>
               <source src="/assets/audio/hello_arthur.mp3" type="audio/mpeg">
@@ -61,11 +61,11 @@ Marvin can generate speech from text.
   </p>
 </div>
 
-## Speaking text verbatim
+!!! tip "Text is generated verbatim"
 
-Unlike the images API, OpenAI's speech API does not modify or revise your input prompt in any way. Whatever text you provide is exactly what will be spoken. 
+    Unlike the images API, OpenAI's speech API does not modify or revise your input prompt in any way. Whatever text you provide is exactly what will be spoken. 
 
-Therefore, you can use the `speak` function to generate speech from any string, or use the `@speech` decorator to generate speech from the string output of any function.
+    Therefore, you can use the `speak` function to generate speech from any string, or use the `@speech` decorator to generate speech from the string output of any function.
 
 
 
@@ -95,19 +95,45 @@ ai_say('hello')
       Your browser does not support the audio element.
     </audio>
 
-## Choosing a voice
+### Playing audio
 
-Both `speak` and `@speech` accept a `voice` parameter that allows you to choose from a variety of voices. You can preview the available voices [here](https://platform.openai.com/docs/guides/text-to-speech/voice-options).
+The result of `speak` and `@speech` is an `Audio` object that can be played by calling its `play` method. By default, playback will start as soon as the first bytes of audio are available. See the note on [streaming audio](#streaming-audio) for more information.
 
 ```python
+audio = marvin.speak("Hello, world!")
+audio.play()
+```
 
-## Saving audio files
+#### Streaming audio
+By default, Marvin streams audio from the OpenAI API, which means that playback can start as soon as the first bytes of audio are available. This can be useful for long audio files, as it allows you to start listening to the audio before it has finished generating. If you want to wait for the entire audio file to be generated before starting playback, you can pass `stream=False`:
 
-The result of the `speak` function and `@speech` decorator is an audio stream. You can save this stream to disk like this:
+```python
+audio = marvin.speak("Hello, world!", stream=False)
+```
+Note that streaming is only supported with the `pcm` (or raw) audio file format, and an error will be raised if you try to generate speech in a different format with `stream=True`. However, you can always save `pcm` audio to a file in a different format after it has been generated.
+
+### Saving audio
+To save an `Audio` object to a file, you can call its `save` method:
 
 ```python
 audio = marvin.speak("Hello, world!")
-audio.stream_to_file("hello_world.mp3")
+audio.save("hello_world.mp3")
+```
+
+Marvin will attempt to infer the correct file format from the file extension you provide. If you want to save the audio in a different format, you can pass a `format` argument to `save`.
+
+### Saving audio
+
+
+## Choosing a voice
+
+Both `speak` and `@speech` accept a `voice` parameter that allows you to choose from a variety of voices. You can preview the available voices [here](https://platform.openai.com/docs/guides/text-to-speech/voice-options).
+
+```python
+The result of the `speak` function and `@speech` decorator is an audio stream.
+
+audio = marvin.speak("Hello, world!", voice="nova")
+audio.play("hello_world.mp3") 
 ```
 
 

{marvin-2.3.0 → marvin-2.3.2}/docs/docs/images/generation.md

@@ -50,6 +50,7 @@ Marvin can generate images from text.
   </p>
 </div>
 
+
 ## Generating images from functions
 
 In addition to passing prompts directly to the DALLE-3 API via the `paint` function, you can also use the `@image` decorator to generate images from the output of a function. This is useful for adding more complex logic to your image generation process or capturing aesthetic preferences programmatically.
@@ -279,3 +280,13 @@ marvin.utilities.images.base64_to_image(
 ```
 
 To change this behavior globally set `MARVIN_IMAGE_RESPONSE_FORMAT=b64_json` in your environment, or equivalently change `marvin.settings.images.response_format = "b64_json"` in your code.
+
+## Async support
+
+If you are using Marvin in an async environment, you can use `paint_async`:
+  
+```python
+image = await marvin.paint_async(
+    "A cup of coffee, still warm"
+)
+```

{marvin-2.3.0 → marvin-2.3.2}/docs/docs/interactive/applications.md

@@ -309,7 +309,7 @@ app = Application(
 
 ### Running the app
 
-Now we can interact with our app. After each command, you can print the resulting message to see the LLM's response, or use the experimental `app.chat()` interface to interact with the application in real time. You can also see the updated application state.
+Now we can interact with our app. You can also see the updated application state.
 
 ```python
 response = app.say("I need to go to the store tomorrow afternoon")

{marvin-2.3.0 → marvin-2.3.2}/docs/docs/interactive/assistants.md

@@ -105,7 +105,7 @@ For more control over the conversation, including posting multiple user messages
 
 #### Event handlers
 
-Marvin uses the OpenAI streaming API to provide real-time updates on the assistant's actions. To customize how these updates are handled, you can provide a custom event handler class to the `event_handler_class` parameter of `Assistant.say`, `Thread.run`, or `Run.run`. This class must inherit from `openai.AssistantEventHandler` or `openai.AsyncAssistantEventHandler`. For more control, you can also provide `event_handler_kwargs` that will be provided to the event handler when it is instantiated.
+Marvin uses the OpenAI streaming API to provide real-time updates on the assistant's actions. To customize how these updates are handled, you can provide a custom event handler class to the `event_handler_class` parameter of `Assistant.say`, `Thread.run`, or `Run.run`. This class must inherit from `openai.AsyncAssistantEventHandler` (so all methods must be async). For more control, you can also provide `event_handler_kwargs` that will be provided to the event handler when it is instantiated.
 
 #### Pretty-printing
 
@@ -171,6 +171,9 @@ Each assistant can be given `instructions` that describe its purpose, personalit
     !!! success "Result"
         ![](/assets/images/docs/assistants/instructions.png)
 
+Instructions are rendered as a Jinja template, which means you can use variables and conditionals to customize the assistant's behavior. A special variable, `self_` is provided to the template, which represents the assistant object itself. This allows you to template the assistant's name, tools, or other attributes into the instructions.
+
+
 ### Tools
 
 Each assistant can be given a list of `tools` that it can use when responding to a message. Tools are a way to extend the assistant's capabilities beyond its default behavior, including giving it access to external systems like the internet, a database, your computer, or any API. 
@@ -225,6 +228,41 @@ Marvin makes it easy to give your assistants custom tools. To do so, pass one or
     !!! success "Result"
         ![](/assets/images/docs/assistants/custom_tools.png)
 
+#### Ending a run early
+
+Normally, the assistant will continue to run until it decides to stop, which usually happens after generating a response. Sometimes it may be useful to end a run early, for example if the assistant uses a tool that indicates the conversation is over. To do this, you can raise an `EndRun` exception from within a tool. This will cause the assistant to cancel the current run and return control. EndRun exceptions can contain data.
+
+There are three ways to raise an `EndRun` exception:
+
+1. Raise the exception directly from the tool function:
+```python
+from marvin.beta.assistants import Assistant, EndRun
+
+def my_tool():
+    raise EndRun(data="The final result")
+
+ai = Assistant(tools=[my_tool])
+```
+1. Return the exception from the tool function. This is useful if e.g. your tools are wrapped in custom exception handlers:
+```python
+from marvin.beta.assistants import Assistant, EndRun
+
+def my_tool():
+    return EndRun(data="The final result")
+
+ai = Assistant(tools=[my_tool])
+```
+1. Return a special string value from the tool function. This is useful if you don't have full control over the tool itself, or need to ensure the tool output is JSON-compatible. Note that this approach does not allow you to attach any data to the exception:
+```python
+from marvin.beta.assistants import Assistant, ENDRUN_TOKEN
+
+def my_tool():
+    return ENDRUN_TOKEN
+
+ai = Assistant(tools=[my_tool])
+```
+
+
 ### Lifecycle management
 
 Assistants are Marvin objects that correspond to remote objects in the OpenAI API. You can not communicate with an assistant unless it has been registered with the API. 
@@ -384,7 +422,7 @@ This will return a `Run` object that represents the OpenAI run. You can use this
     When threads are `run` with an assistant, the same lifecycle management rules apply as when you use the assistant's `say` method. In the above example, lazy lifecycle management is used for conveneince. See [lifecycle management](#lifecycle-management) for more information.
 
 !!! warning "Threads are locked while running"
-    When an assistant is running a thread, the thread is locked and no other messages can be added to it. This applies to both user and assistant messages.
+    When an assistant is running a thread, the thread is locked and no other messages can be added to it. This applies to both user and assistant messages. To end a run early, you must [use a custom tool](#ending-a-run-early).
 
 ### Reading messages