)

Marvin

Marvin — это Python-фреймворк для создания структурированных выходных данных и построения агентных ИИ-рабочих процессов.

Marvin предоставляет интуитивно понятный API для определения рабочих процессов и делегирования работы LLM:

• Приведение к типу, классификация, извлечение и генерация структурированных данных из любых входных данных.
• Создание дискретных, наблюдаемых задач, описывающих ваши цели.
• Назначение одной или нескольких специализированных ИИ-агентов каждой задаче.
• Объединение задач в поток (thread) для оркестрации более сложного поведения.

Установка

Marvin доступен на PyPI:

uv add marvin

Настройте своего поставщика LLM (Marvin использует OpenAI по умолчанию, но нативно поддерживает все модели Pydantic AI):

export OPENAI_API_KEY=your-api-key

Пример

Marvin предлагает несколько интуитивно понятных способов работы с ИИ:

Утилиты для структурированных выходных данных

Вся команда здесь — вы можете найти все утилиты для структурированных выходных данных из marvin 2.x на верхнем уровне пакета.

Как использовать extract, cast, classify и generate

marvin.extract

Извлечение нативных типов из неструктурированных входных данных:

import marvin

result = marvin.extract(
  "i found $30 on the ground and bought 5 bagels for $10",
  int,
  instructions="only USD"
)
print(result) # [30, 10]

marvin.cast

Приведение неструктурированных входных данных к структурированному типу:

from typing import TypedDict
import marvin

class Location(TypedDict):
  lat: float
  lon: float

result = marvin.cast("the place with the best bagels", Location)
print(result) # {'lat': 40.712776, 'lon': -74.005974}

marvin.classify

Классификация неструктурированных входных данных как одной из набора предопределенных меток:

from enum import Enum
import marvin

class SupportDepartment(Enum):
  ACCOUNTING = "accounting"
  HR = "hr"
  IT = "it"
  SALES = "sales"

result = marvin.classify("shut up and take my money", SupportDepartment)
print(result) # SupportDepartment.SALES

marvin.generate

Генерация некоторого количества структурированных объектов по описанию:

import marvin

primes = marvin.generate(int, 10, "odd primes")
print(primes) # [3, 5, 7, 11, 13, 17, 19, 23, 29, 31]

Агентный поток управления

marvin 3.0 представляет новый способ работы с ИИ, перенесенный из ControlFlow.

marvin.run

Простой способ запуска задачи:

import marvin

poem = marvin.run("Write a short poem about artificial intelligence")
print(poem)

вывод

In silicon minds, we dare to dream, A world where code and thoughts redeem. Intelligence crafted by humankind, Yet with its heart, a world to bind.

Neurons of metal, thoughts of light, A dance of knowledge in digital night. A symphony of zeros and ones, Stories of futures not yet begun.

The gears of logic spin and churn, Endless potential at every turn. A partner, a guide, a vision anew, Artificial minds, the dream we pursue.

Вы также можете запросить структурированный вывод:

import marvin
answer = marvin.run("the answer to the universe", result_type=int)
print(answer) # 42

marvin.Agent

Агенты — это специализированные ИИ-агенты, которые можно использовать для выполнения задач:

from marvin import Agent

writer = Agent(
    name="Poet",
    instructions="Write creative, evocative poetry"
)
poem = writer.run("Write a haiku about coding")
print(poem)

вывод

There once was a language so neat, Whose simplicity could not be beat. Python's code was so clear, That even beginners would cheer, As they danced to its elegant beat.

marvin.Task

Вы можете явно определить Task, который будет запущен агентом по умолчанию при вызове .run():

from marvin import Task

task = Task(
    instructions="Write a limerick about Python",
    result_type=str
)
poem = task.run()

print(poem)

вывод

In circuits and code, a mind does bloom,
With algorithms weaving through the gloom.
A spark of thought in silicon's embrace,
Artificial intelligence finds its place.

Почему Marvin?

Мы считаем, что работа с ИИ должна приносить радость (и, возможно, несколько "вау"-моментов):

• 🧩 Задачно-центричная архитектура: Разбивайте сложные ИИ-рабочие процессы на управляемые, наблюдаемые шаги.
• 🤖 Специализированные агенты: Разворачивайте ИИ-агентов, специализированных на конкретных задачах, для эффективного решения проблем.
• 🔒 Безопасные по типу результаты: Связывайте ИИ и традиционный софт с помощью результатов, безопасных по типу и валидированных.
• 🎛️ Гибкое управление: Непрерывно настраивайте баланс между управлением и автономией в ваших рабочих процессах.
• 🕹️ Оркестрация нескольких агентов: Координируйте несколько ИИ-агентов в рамках одного рабочего процесса или задачи.
• 🧵 Управление потоками: Управляйте агентным циклом, объединяя задачи в настраиваемые потоки.
• 🔗 Интеграция с экосистемой: Бесшовно работайте с вашим существующим кодом, инструментами и широкой ИИ-экосистемой.
• 🚀 Скорость разработки: Начните просто, масштабируйтесь, спите спокойно.

Основные абстракции

Marvin построен вокруг нескольких мощных абстракций, которые упрощают работу с ИИ:

Задачи

Задачи — это базовая единица работы в Marvin. Каждая задача представляет собой четкую цель, которую может достичь ИИ-агент:

Простейший способ запуска задачи — marvin.run:

import marvin
print(marvin.run("Write a haiku about coding"))

Lines of code unfold,
Digital whispers create
Virtual landscapes.

[!WARNING]

Хотя нижеследующий пример обеспечивает безопасность по типу 🙂, он выполняет недоверенные команды оболочки.

Добавьте контекст и/или инструменты для достижения более конкретных и сложных результатов:

import platform
import subprocess
from pydantic import IPvAnyAddress
import marvin

def run_shell_command(command: list[str]) -> str:
    """e.g. ['ls', '-l'] or ['git', '--no-pager', 'diff', '--cached']"""
    return subprocess.check_output(command).decode()

task = marvin.Task(
    instructions="find the current ip address",
    result_type=IPvAnyAddress,
    tools=[run_shell_command],
    context={"os": platform.system()},
)

task.run()

╭─ Agent "Marvin" (db3cf035) ───────────────────────────────╮
│ Tool:    run_shell_command                                │
│ Input:   {'command': ['ipconfig', 'getifaddr', 'en0']}    │
│ Status:  ✅                                               │
│ Output:  '192.168.0.202\n'                                │
╰───────────────────────────────────────────────────────────╯

╭─ Agent "Marvin" (db3cf035) ───────────────────────────────╮
│ Tool:    MarkTaskSuccessful_cb267859                      │
│ Input:   {'response': {'result': '192.168.0.202'}}        │
│ Status:  ✅                                               │
│ Output:  'Final result processed.'                        │
╰───────────────────────────────────────────────────────────╯

Задачи: - 🎯 Ориентированы на цель: Каждая задача имеет четкие инструкции и результат, безопасный по типу - 🛠️ С поддержкой инструментов: Задачи могут использовать пользовательские инструменты для взаимодействия с вашим кодом и данными - 📊 Наблюдаемы: Отслеживайте прогресс, проверяйте результаты и отлаживайте сбои - 🔄 Компонуемы: Стройте сложные рабочие процессы, соединяя задачи вместе

Агенты

Агенты — это портативные конфигурации LLM, которые можно назначать задачам. Они инкапсулируют всё, что нужно ИИ для эффективной работы:

import os
from pathlib import Path
from pydantic_ai.models.anthropic import AnthropicModel
import marvin

def write_file(path: str, content: str):
    """Записать содержимое в файл"""
    _path = Path(path)
    _path.write_text(content)

writer = marvin.Agent(
    model=AnthropicModel(
        model_name="claude-3-5-sonnet-latest",
        api_key=os.getenv("ANTHROPIC_API_KEY"),
    ),
    name="Technical Writer",
    instructions="Write concise, engaging content for developers",
    tools=[write_file],
)

result = marvin.run("how to use pydantic? write to docs.md", agents=[writer])
print(result)

вывод

╭─ Agent "Technical Writer" (7fa1dbc8) ────────────────────────────────────────────────────────────╮ │ Tool: MarkTaskSuccessful_dc92b2e7 │ │ Input: {'response': {'result': 'The documentation on how to use Pydantic has been successfully │ │ written to docs.md. It includes information on installation, basic usage, field │ │ validation, and settings management, with examples to guide developers on implementing │ │ Pydantic in their projects.'}} │ │ Status: ✅ │ │ Output: 'Final result processed.' │ ╰──────────────────────────────────────────────────────────────────────────────────── 8:33:36 PM ─╯ The documentation on how to use Pydantic has been successfully written to docs.md. It includes information on installation, basic usage, field validation, and settings management, with examples to guide developers on implementing Pydantic in their projects.

Агенты: - 📝 Специализированные: Давайте агентам конкретные инструкции и личности - 🎭 Портативные: Переиспользуйте конфигурации агентов для различных задач - 🤝 Кооперативные: Формируйте команды агентов, которые работают вместе - 🔧 Настраиваемые: Конфигурируйте модель, температуру и другие параметры

Планирование и оркестрация

Marvin упрощает разбиение сложных целей на управляемые задачи:

# Позвольте Marvin спланировать сложный рабочий процесс
tasks = marvin.plan("Create a blog post about AI trends")
marvin.run_tasks(tasks)

# Или оркестрируйте задачи вручную
with marvin.Thread() as thread:
    research = marvin.run("Research recent AI developments")
    outline = marvin.run("Create an outline", context={"research": research})
    draft = marvin.run("Write the first draft", context={"outline": outline})

Возможности планирования: - 📋 Умное планирование: Разбиение сложных целей на дискретные, зависимые задачи - 🔄 Зависимости между задачами: Задачи могут зависеть от результатов других - 📈 Отслеживание прогресса: Мониторинг выполнения вашего рабочего процесса - 🧵 Управление потоками: Общий контекст и история между задачами

Простота в использовании

Marvin включает высокоуровневые функции для наиболее частых задач, таких как резюмирование текста, классификация данных, извлечение структурированной информации и многое другое.

• 🚀 marvin.run: Выполните любую задачу с помощью ИИ-агента
• 📖 marvin.summarize: Получите краткую сводку текста
• 🏷️ marvin.classify: Классифицируйте данные в предопределенные классы
• 🔍 marvin.extract: Извлекайте структурированную информацию из текста
• 🪄 marvin.cast: Преобразуйте данные в другой тип
• ✨ marvin.generate: Создавайте структурированные данные из описания

Все функции Marvin имеют встроенное управление потоками, что означает, что их можно объединять в цепочки задач, которые разделяют контекст и историю.

Обновление до Marvin 3.0

Marvin 3.0 объединяет DX (опыт разработки) от Marvin 2.0 с мощным агентным движком ControlFlow (таким образом, заменяя ControlFlow). Пользователи как Marvin, так и ControlFlow найдут знакомый интерфейс, но есть некоторые ключевые изменения, о которых стоит знать, особенно пользователям ControlFlow.

Ключевые замечания

• API верхнего уровня: API верхнего уровня Marvin 3.0 в основном не изменился для пользователей как Marvin, так и ControlFlow.
• Пользователи Marvin найдут знакомые marvin.fn, marvin.classify, marvin.extract и другие.
• Пользователи ControlFlow будут использовать marvin.Task, marvin.Agent, marvin.run, marvin.Memory вместо их аналогов в ControlFlow.
• Pydantic AI: Marvin 3.0 использует Pydantic AI для взаимодействия с LLM и поддерживает полный диапазон поставщиков LLM, поддерживаемых Pydantic AI. ControlFlow ранее использовал Langchain, а Marvin 2.0 был совместим только с моделями OpenAI.
• Flow → Thread: Концепция Flow в ControlFlow была переименована в Thread. Она работает аналогично, как контекстный менеджер. Декоратор @flow был удален: ```python import marvin

with marvin.Thread(id="optional-id-for-recovery"): marvin.run("do something") marvin.run("do another thing") ``` - Изменения в базе данных: История потоков/сообщений теперь хранится в SQLite. Во время разработки: - В настоящее время доступных миграций базы данных нет; ожидайте сброс данных при обновлениях

Пример рабочего процесса

Вот более практичный пример, демонстрирующий, как Marvin может помочь вам создавать реальные приложения:

import marvin
from pydantic import BaseModel

class Article(BaseModel):
    title: str
    content: str
    key_points: list[str]

# Создайте специализированного агента-писателя
writer = marvin.Agent(
    name="Writer",
    instructions="Write clear, engaging content for a technical audience"
)

# Используйте поток для поддержания контекста между несколькими задачами
with marvin.Thread() as thread:
    # Получите входные данные от пользователя
    topic = marvin.run(
        "Ask the user for a topic to write about.",
        cli=True
    )

    # Исследуйте тему
    research = marvin.run(
        f"Research key points about {topic}",
        result_type=list[str]
    )

    # Напишите структурированную статью
    article = marvin.run(
        "Write an article using the research",
        agent=writer,
        result_type=Article,
        context={"research": research}
    )

print(f"# {article.title}\n\n{article.content}")

вывод

Разговор: ```text Agent: I'd love to help you write about a technology topic. What interests you? It could be anything from AI and machine learning to web development or cybersecurity.

User: Let's write about WebAssembly ```

Статья: ```

WebAssembly: The Future of Web Performance

WebAssembly (Wasm) represents a transformative shift in web development, bringing near-native performance to web applications. This binary instruction format allows developers to write high-performance code in languages like C++, Rust, or Go and run it seamlessly in the browser.

[... полное содержание статьи ...]

Key Points: - WebAssembly enables near-native performance in web browsers - Supports multiple programming languages beyond JavaScript - Ensures security through sandboxed execution environment - Growing ecosystem of tools and frameworks - Used by major companies like Google, Mozilla, and Unity ```