marvin 2.2.2__tar.gz → 2.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: marvin
-Version: 2.2.2
+Version: 2.3.0
 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,7 @@ Requires-Dist: fastapi
 Requires-Dist: httpx>=0.24.1
 Requires-Dist: jinja2>=3.1.2
 Requires-Dist: jsonpatch>=1.33
-Requires-Dist: openai>=1.1.0
+Requires-Dist: openai>=1.4.0
 Requires-Dist: pydantic>=2.4.2
 Requires-Dist: pydantic_settings
 Requires-Dist: rich>=12
@@ -226,6 +226,7 @@ Requires-Dist: typer>=0.9.0
 Requires-Dist: typing_extensions>=4.0.0
 Requires-Dist: tzdata>=2023.3
 Requires-Dist: uvicorn>=0.22.0
+Requires-Dist: partialjson>=0.0.5
 Provides-Extra: generator
 Requires-Dist: datamodel-code-generator>=0.20.0; extra == "generator"
 Provides-Extra: chromadb

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

@@ -17,16 +17,13 @@ The need to manage all this state makes the assistants API very different from t
     Get started with the Assistants API by creating an `Assistant` and talking directly to it.
 
     ```python
-    from marvin.beta.assistants import Assistant, pprint_messages
+    from marvin.beta.assistants import Assistant
 
     # create an assistant
     ai = Assistant(name="Marvin", instructions="You the Paranoid Android.")
 
     # send a message to the assistant and have it respond
-    response = ai.say('Hello, Marvin!')
-
-    # pretty-print the response
-    pprint_messages(response)
+    ai.say('Hello, Marvin!')
     ```
 
     !!! success "Result"
@@ -40,7 +37,7 @@ The need to manage all this state makes the assistants API very different from t
 </div>
 
 !!! tip "Beta"
-    Please note that assistants support in Marvin is still in beta, as OpenAI has not finalized the assistants API yet. While it works as expected, it is subject to change.
+    Please note that assistants support in Marvin is still in beta, as OpenAI has not finalized the assistants API yet. Breaking changes may occur.
 
 
 
@@ -52,59 +49,166 @@ To learn more about the OpenAI assistants API, see the [OpenAI documentation](ht
 
 ### Creating an assistant
 
-To instantiate an assistant, use the `Assistant` class and provide a name and, optionally, details like instructions or tools:
+To create an assistant, use the `Assistant` class and provide an optional name and any additional details like instructions or tools:
+
+```python
+ai = Assistant(
+    name='Marvin', 
+    # any specific instructions for how this assistant should behave
+    instructions="You the Paranoid Android.", 
+    # any tools or additional abilities the assistant should have
+    tools=[cry, sob]
+)
+```
+
+### Talking to an assistant
+
+The simplest way to talk to an assistant is to use its `say` method:
+
+!!! example "Talking to an assistant"
+
+    ```python
+    from marvin.beta.assistants import Assistant
+
+    ai = Assistant()
+    
+    ai.say('Hi!')
+    ai.say('Bye!')
+    ```
+    !!! success "Result"
+        ![](/assets/images/docs/assistants/talking.png)
+
+You can repeatedly call `say` to have a conversation with the assistant. Each time you call `say`, the result is a `Run` object that contains information about what the assistant did. You can use this object to inspect all actions the assistant took, including tool use, messages posted, and more. 
+
+#### Chat history
+
+The OpenAI Assistants API automatically maintains a history of all messages and actions that the assistant has taken. This history is organized into threads, which are distinct conversations that the assistant has had. Each thread contains a series of messages, and each message is associated with a specific user or the assistant. 
+
+When you talk to an assistant, you are implicitly talking on a specific thread. By default, the `say` method posts a single message to the assistant's `default_thread`, which is automatically created for your convenience whenever you instantiate an assistant. You can talk to the assistant on a different thread by providing it as the `thread` parameter:
+
+```python
+from marvin.beta.assistants import Assistant, Thread
+
+ai = Assistant()
+
+# load a thread from an existing ID (or pass id=None to start a new thread)
+thread = Thread(id=thread_id)
+
+# post a message to the thread
+ai.say('hi', thread=thread)
+```
+
+Using `say` is convenient, but enforces a strict request/response pattern: the user posts a single message to the thread, then the AI responds. Note that AI responses can include multiple messages or tool calls.
+
+For more control over the conversation, including posting multiple user messages to the thread before the assistant responds, use thread objects directly instead of calling `say` (see [Threads](#threads) for more information).
+
+
+#### 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.
+
+#### Pretty-printing
+
+By default, Marvin streams all of the messages and actions that the assistant takes and prints them to your terminal. In production or headless environments, you may want to suppress this output. 
+
+The simplest way to do this is to pass `event_handler_class=None` to the `say` method. This will prevent any messages from being printed to the terminal. You can still access the messages and actions from the run object that is returned.
+
+```python
+ai = Assistant()
+
+# run the assistant without printing any messages
+run = ai.say("Hello!", event_handler_class=None)
+
+# access the messages
+run.messages
+
+# access the assistant actions
+run.steps
+```
+
+For finer control, you can pass `event_handler_kwargs=dict(print_messages=False)` or `event_handler_kwargs=dict(print_steps=False)` to the `say` method. This will allow you to suppress only the messages or only the assistant's actions, respectively.
+
+```python
+# print only messages
+run = ai.say("Hello!", event_handler_kwargs=dict(print_steps=False))
+
+# print only actions
+run = ai.say("Hello!", event_handler_kwargs=dict(print_messages=False))
+```
+
+Note that pretty-printing is only the default behavior when using the assistant's convenient `say` method. If you use lower-level APIs like a thread's `run` method or invoke a run object directly, printing is not automatically enabled. You can re-enable it for those objects by setting `event_handler_class=marvin.beta.assistants.PrintHandler`.
 
 ```python
-ai = Assistant(name='Marvin', instructions=..., tools=[...])
+from mavin.beta.assistants import Thread, Assistant, PrintHandler
+
+ai = Assistant()
+thread = Thread()
+run = thread.run(ai, event_handler_class=PrintHandler)
 ```
 
+Lastly, you can print messages and actions manually using the `pprint_run`, `pprint_messages`, and `pprint_steps` functions from the `marvin.beta.assistants.formatting` module. These functions are used internally by the default event handler, and they provide a human-readable representation of the messages and actions, respectively.
 
+```python
+from mavin.beta.assistants import Assistant, pprint_run
+
+ai = Assistant()
+run = ai.say("Hello!", event_handler_class=None)
+pprint_run(run)
+```
 
 ### Instructions
 
-Each assistant can be given `instructions` that describe its purpose, personality, or other details. The instructions are a natural language string and one of the only ways to globally steer the assistant's behavior.
+Each assistant can be given `instructions` that describe its purpose, personality, or other details. Instructions are provided as natural language and allow you to globally steer the assistant's behavior, similar to a system message for a chat completion. They can be lengthy explanations of how to handle complex workflows, or they can be brief instructions on how to act.
 
-Instructions can be lengthy explanations of how to handle complex workflows, or they can be short descriptions of the assistant's personality. For example, the instructions for the `Marvin` assistant above are "You are Marvin, the Paranoid Android." This will marginally affect the way the assistant responds to messages.
+!!! example "Using instructions to control behavior"
+
+    ```python
+    from marvin.beta.assistants import Assistant
+
+    ai = Assistant(instructions="Mention the word 'banana' as often as possible")
+    ai.say("Hello!")
+    ```
+    !!! success "Result"
+        ![](/assets/images/docs/assistants/instructions.png)
 
 ### 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. 
 
-#### OpenAI tools
-
-OpenAI provides a small number of built-in tools for assistants. The most useful is the "code interpreter", which lets the assistant write and execute Python code. To use the code interpreter, add it to your assistant's list of tools.
+#### Code interpreter
 
+The code interpreter tool is a built-in tool provided by OpenAI that lets the assistant write and execute Python code. To use the code interpreter, add it to your assistant's list of tools.
 
-    This assistant uses the code interpreter to generate a plot of sin(x). Note that Marvin's utility for pretty-printing messages to the terminal can't show the plot inline, but will download it and show a link to the file instead.
+!!! example "Using the code interpreter"
 
-!!! example "Using assistants with the code interpreter"
 
     ```python
-    from marvin.beta import Assistant
-    from marvin.beta.assistants import pprint_messages, CodeInterpreter
+    from marvin.beta.assistants import Assistant, CodeInterpreter
 
-    ai = Assistant(name='Marvin', tools=[CodeInterpreter])
-    response = ai.say("Generate a plot of sin(x)")
-
-    # pretty-print the response
-    pprint_messages(response)
+    ai = Assistant(tools=[CodeInterpreter])
+    ai.say("Generate a plot of sin(x)")
     ```
     !!! success "Result"
+        Since images can't be rendered in the terminal, Marvin will automatically download them and provide links to view the output.
+    
         ![](/assets/images/docs/assistants/code_interpreter.png)
+
+        Here is the image:
+
         ![](/assets/images/docs/assistants/sin_x.png)
 
 
 #### Custom tools
 
-A major advantage of using Marvin's assistants API is that you can add your own custom tools. To do so, simply pass one or more functions to the assistant's `tools` argument. For best performance, give your tool function a descriptive name, docstring, and type hint for every argument.
+Marvin makes it easy to give your assistants custom tools. To do so, pass one or more Python functions to the assistant's `tools` argument. For best performance, give your tool function a descriptive name, docstring, and type hint for every argument. Note that you can provide custom tools and the code interpreter at the same time.
 
 
 !!! example "Using custom tools"
 
-    Assistants can not browse the web by default. We can add this capability by giving them a tool that takes a URL and returns the HTML of that page. This assistant uses that tool to count how many titles on Hacker News mention AI:
+    Assistants don't have web access by default. We can add this capability by giving them a tool that takes a URL and returns the HTML of that page. This assistant uses that tool to count how many titles on Hacker News mention AI:
 
     ```python
-    from marvin.beta.assistants import Assistant, pprint_messages
+    from marvin.beta.assistants import Assistant
     import requests
 
 
@@ -115,42 +219,12 @@ A major advantage of using Marvin's assistants API is that you can add your own
 
 
     # Integrate custom tools with the assistant
-    ai = Assistant(name="Marvin", tools=[visit_url])
-    response = ai.say("What's the top story on Hacker News?")
-
-    # pretty-print the response
-    pprint_messages(response)
+    ai = Assistant(tools=[visit_url])
+    ai.say("What's the top story on Hacker News?")
     ```
     !!! success "Result"
         ![](/assets/images/docs/assistants/custom_tools.png)
 
-### Talking to an assistant
-
-The simplest way to talk to an assistant is to use its `say` method:
-
-```python
-ai = Assistant(name='Marvin')
-
-response = ai.say('hi')
-
-pprint_messages(response)
-```
-
-By default, the `say` method posts a single message to the assistant's `default_thread`, a thread that is automatically created for your convenience. You can supply a different thread by providing it as the `thread` parameter:
-
-```python
-# create a thread from an existing ID (or pass None for a new thread)
-thread = Thread(id=thread_id)
-
-# post a message to the thread
-ai.say('hi', thread=thread)
-```
-
-Using `say` is convenient, but enforces a strict request/response pattern: the user posts a single message to the thread, then the AI responds. Note that AI responses can span multiple messages. Therefore, the `say` method returns a list of `Message` objects. 
-
-For more control over the conversation, including posting multiple user messages to the thread or accessing the lower-level `Run` object that contains information about all actions the assistant took, use `Thread` objects directly instead of calling `say` (see [Threads](#threads) for more information).
-
-
 ### 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. 
@@ -169,7 +243,7 @@ All of these options are *functionally* equivalent e.g. they produce identical r
 The simplest way to manage assistant lifecycles is to let Marvin handle it for you. If you do not provide an `id` when instantiating an assistant, Marvin will lazily create a new API assistant for you whenever you need it and delete it immediately after. This is the default behavior, and it is the easiest way to get started with assistants.
 
 ```python
-ai = Assistant(name='Marvin')
+ai = Assistant()
 # creation and deletion happens automatically
 ai.say('hello!')
 ```
@@ -179,7 +253,7 @@ ai.say('hello!')
 Lazy lifecycle management adds two API calls to every LLM call (one to create the assistant and one to delete it). If you want to avoid this overhead, you can use context managers to create and delete assistants:
 
 ```python
-ai = Assistant(name='Marvin')
+ai = Assistant()
 
 # creation / deletion happens when the context is opened / closed
 with ai:
@@ -194,7 +268,7 @@ Note there is also an equivalent `async with` context manager for the async API.
 To fully control the lifecycle of an assistant, you can create and delete it manually:
 
 ```python
-ai = Assistant(name='Marvin')
+ai = Assistant()
 ai.create()
 ai.say('hi')
 ai.delete()
@@ -234,7 +308,7 @@ ai = Assistant.load(id=<the assistant id>)
 Every `Assistant` method has a corresponding async version. To use the async API, append `_async` to the method name, or enter an async context manager:
 
 ```python
-async with Assistant(name='Marvin') as ai:
+async with Assistant() as ai:
     await ai.say_async('hi')
 ```
 
@@ -345,7 +419,7 @@ Messages are not strings, but structured message objects. Marvin has a few utili
     def roll_dice(n_dice: int) -> list[int]:
         return [random.randint(1, 6) for _ in range(n_dice)]
 
-    ai = Assistant(name="Marvin", tools=[roll_dice])
+    ai = Assistant(tools=[roll_dice])
 
     # create a thread - you could pass an ID to resume a conversation
     thread = Thread()
@@ -363,8 +437,9 @@ Messages are not strings, but structured message objects. Marvin has a few utili
     # run the thread again to generate a new response
     thread.run(ai)
 
-    # see all the messages
-    pprint_messages(thread.get_messages())
+    # see all the messages in the thread
+    messages = thread.get_messages()
+    pprint_messages(messages)
     ```
 
     !!! success "Result"
@@ -373,21 +448,3 @@ Messages are not strings, but structured message objects. Marvin has a few utili
 ### Async support
 
 Every `Thread` method has a corresponding async version. To use the async API, append `_async` to the method name.
-
-## Monitors
-
-The assistants API is complex and stateful, with automatic memory management and the potential for assistants to respond to threads multiple times before giving control back to users. Therefore, monitoring the status of a conversation is considerably more difficult than with other LLM API's such as chat completions, which have much more simple request-response patterns.
-
-Marvin has utilites for monitoring the status of a thread and taking action whenever a new message is added to it. This can be a useful way to debug activity or create notifications. Please note that monitors are not intended to be used for real-time chat applications or production use.
-
-```python
-from marvin.beta.assistants import ThreadMonitor
-
-monitor = ThreadMonitor(thread_id=thread.id)
-
-monitor.run()
-```
-
-You can customize the `ThreadMonitor` by providing a callback function to the `on_new_message` parameter. This function will be called whenever a new message is added to the thread. The function will be passed the new message as a parameter. By default, the monitor will pretty-print every new message to the console.
-
-`monitor.run()` is a blocking call that will run forever, polling for messages every second (to customize the interval, pass `interval_seconds` to the method). It has an async equivalent `monitor.run_async()`. Because it's blocking, you can run a thread monitor in a separate session from the one that is running the thread itself.

marvin-2.3.0/docs/docs/interactive/cli.md

@@ -0,0 +1,169 @@
+# CLI
+
+Marvin includes a CLI for quickly invoking an AI assistant.
+
+![](/assets/images/docs/cli/hero.png)
+
+To use the CLI, simply `say` something to Marvin:
+
+```bash
+marvin say "hi"
+```
+
+You can control the [thread](#threads) and [assistant](#custom-assistants) you're talking to, as well as the LLM model used for generating responses.
+
+## Models
+
+By default, the CLI uses whatever model the assistant is configured to use. However, you can override this on a per-message basis using the `--model` or `-m` flag. For example, to use the `gpt-3.5-turbo` model for a single message:
+
+```bash
+marvin say "hi" -m "gpt-3.5-turbo"
+```
+
+## Tools
+
+By default, the CLI assistant has the following tools:
+
+- The OpenAI code interpreter, which allows you to write and execute Python code in a sandbox environment
+- A tool that can fetch the content of a URL
+- Tools for read-only access to the user's filesystem (such as listing and reading files)
+
+To learn more about tools, see the [tools documentation](/docs/interactive/assistants/#tools).
+
+![](/assets/images/docs/cli/tools.png)
+
+## Threads
+
+The CLI assistant automatically remembers the history of your conversation. You can use threads to create multiple simultaneous conversations. To learn more about threads, see the [threads documentation](/docs/interactive/assistants/#threads).
+
+### Changing threads
+
+By default, the CLI assistant uses a global default thread. For example, this posts two messages to the global default thread:
+
+```bash
+marvin say "Hello!"
+marvin say "How are you?"
+```
+
+To change the thread on a per-message basis, use the `--thread` or `-t` flag and provide a thread name. Thread names are arbitrary and can be any string; it's a way for you to group conversations together.
+
+This posts one message to a thread called "my-thread" and another to a thread called "my-other-thread":
+
+```bash
+marvin say "Hello!" -t my-thread
+marvin say "How are you?" -t my-other-thread
+```
+
+To change the default thread for multiple messages, use the `MARVIN_CLI_THREAD` environment variable. You can do this globally or `export` it in your shell for a single session. For example, this sets the default thread to "my-thread":
+
+```bash
+export MARVIN_CLI_THREAD=my-thread
+
+marvin say "Hello!"
+marvin say "How are you?"
+```
+
+### Clearing threads
+
+To reset a thread and clear its history, use the `clear` command. For example, this clears the default thread:
+
+```bash
+marvin thread clear
+```
+
+And this clears a thread called "my-thread":
+
+```bash
+marvin thread clear -t my-thread
+```
+
+
+### Current thread
+
+To see the current thread (and corresponding OpenAI thread ID), use the `current` command. For example:
+
+```bash
+marvin thread current
+```
+
+## Custom assistants
+
+The Marvin CLI allows you to register and use custom assistants in addition to the default assistant. Custom assistants are defined in Python files and can have their own set of instructions, tools, and behaviors.
+
+Using a custom assistant has the following workflow:
+
+1. Define the assistant in a Python file
+2. Register the assistant with the Marvin CLI
+3. Use the assistant in the CLI
+
+### Defining an assistant
+
+To use a custom assistant, you must define it in a Python file. In a new file, create an instance of the `Assistant` class from the `marvin.beta.assistants`. Provide it with any desired options, such as a name, instructions, and tools. To learn more about creating assistants, see the [assistants documentation](/docs/interactive/assistants/). The only requirement is that the assistant object must be assigned to a global variable in the file so that the CLI can load it.
+
+For example, this file defines an assistant named "Arthur" that can use the code interpreter. The assistant is stored under the variable `my_assistant`.
+
+```python
+# path/to/custom_assistant.py
+
+from marvin.beta.assistants import Assistant, CodeInterpreter
+
+my_assistant = Assistant(
+    name="Arthur",
+    instructions="A parody of Arthur Dent",
+    tools=[CodeInterpreter]
+)
+```
+
+### Registering an assistant
+
+Once you've created a Python file that defines an assistant, you can register it with the Marvin CLI. This allows you to use the assistant in the CLI by name.
+
+To do so, use the `marvin assistant register` command followed by the fully-qualified path to the Python file *and* the variable that contains the assistant. For example, to register the assistant defined in the previous step, use the following command:
+
+```bash
+marvin assistant register path/to/custom_assistant.py:my_assistant
+```
+
+This command will automatically use the assistant's name (Arthur) as the name of the assistant in the Marvin CLI registry. You will need to provide the name to load the assistant, which is why each registered assistant must have a unique name. Registering an assistant with the same name as an existing one will fail. In this case, you can either delete the existing assistant or use the `--overwrite` or `-o` flag to overwrite it. You can also provide an alternative name during registration using the `--name` or `-n` flag. For example, this would register the assistant with the name "My Custom Assistant":
+
+```bash
+marvin assistant register path/to/custom_assistant.py:my_assistant -n "My Custom Assistant"
+```
+
+
+!!! warning 
+    When you register an assistant, its name and the path to the file that contains it are stored in the Marvin CLI registry. This allows the CLI to load the assistant whenever you need it. However, it means the assistant file **must** remain in the same location, with the same name, for the CLI to find it. If you move or rename the file, you will need to re-register the assistant. However, if you edit the file without changing the variable name of the assistant, the CLI will automatically use the updated assistant.
+
+
+
+### Using an assistant
+
+To use a custom assistant when sending a message, use the `--assistant` or `-a` flag followed by the name of the registered assistant. For example, if you registered an assistant named "Arthur", you can talk to it like this:
+
+```bash
+marvin say "Hello!" -a "Arthur"
+```
+
+You can also set a default assistant using the MARVIN_CLI_ASSISTANT environment variable, similar to setting a default thread. This allows you to set a global or session-specific default assistant.
+
+#### Mixing threads and assistants
+
+Threads and assistants are independent, so you can talk to multiple assistants in the same thread. Note that due to limitations in the OpenAI API, assistants aren't aware of other assistants, so they assume that they said everything in the thread history (even if another assistant did).
+
+```bash
+marvin say "Hello!" -a "Arthur" -t "marvin-thread"
+```
+
+### Listing registered assistants
+
+To see a list of all registered assistants, use the `marvin assistant list` command. This will display a table with the names and file paths of the registered assistants.
+
+### Deleting a registered assistant
+
+To remove a registered assistant, use the `marvin assistant delete` command followed by the name of the assistant. For example:
+
+```bash
+marvin assistant delete "My Custom Assistant"
+```
+
+Note that this only removes the reference to the assistant in the Marvin registry and does not delete the actual assistant file, even if you used the `--copy` flag during registration.

{marvin-2.2.2 → marvin-2.3.0}/mkdocs.yml

@@ -40,6 +40,7 @@ nav:
 
     - Interactive Tools:
       - Assistants: docs/interactive/assistants.md
+      - CLI: docs/interactive/cli.md
       - Applications: docs/interactive/applications.md
       
     - Configuration: 

{marvin-2.2.2 → marvin-2.3.0}/pyproject.toml

@@ -16,7 +16,7 @@ dependencies = [
     "httpx>=0.24.1",
     "jinja2>=3.1.2",
     "jsonpatch>=1.33",
-    "openai>=1.1.0",
+    "openai>=1.4.0",
     "pydantic>=2.4.2",
     "pydantic_settings",
     "rich>=12",
@@ -26,6 +26,7 @@ dependencies = [
     # need for windows
     "tzdata>=2023.3",
     "uvicorn>=0.22.0",
+    "partialjson>=0.0.5",
 ]
 
 [project.optional-dependencies]

{marvin-2.2.2 → marvin-2.3.0}/src/marvin/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '2.2.2'
-__version_tuple__ = version_tuple = (2, 2, 2)
+__version__ = version = '2.3.0'
+__version_tuple__ = version_tuple = (2, 3, 0)

marvin-2.3.0/src/marvin/beta/assistants/__init__.py

@@ -0,0 +1,6 @@
+from .runs import Run
+from .threads import Thread
+from .assistants import Assistant
+from .handlers import PrintHandler
+from .formatting import pprint_messages, pprint_steps, pprint_run
+from marvin.tools.assistants import Retrieval, CodeInterpreter