Graphon

Graphon — движок исполнения графов на Python для агентных AI-воркфлоу.

Репозиторий всё ещё развивается, но уже содержит рабочий движок исполнения, встроенные узлы воркфлоу, абстракции рантайма моделей, протоколы интеграции и рабочий end-to-end пример.

Основное

• Оркестрация GraphEngine на очередях, событийное исполнение
• Парсинг графа, валидация, fluent-построение графа
• Общее состояние рантайма, пул переменных, доменные модели исполнения воркфлоу
• Встроенные реализации узлов для типовых паттернов воркфлоу
• Поддержка импорта DSL с LLM-узлами на Slim
• Протоколы интеграции HTTP, файлов, инструментов, human-input
• Расширяемые слои движка и внешние командные каналы

Модули репозитория сейчас покрывают такие типы узлов: start, end, answer, llm, if-else, code, template-transform, question-classifier, http-request, tool, variable-aggregator, variable-assigner, loop, iteration, parameter-extractor, document-extractor, list-operator и human-input.

Быстрый старт

Проще всего оценить Graphon из исходников (source checkout).

Требования

• Python 3.12 или 3.13
• uv
• just
• fd

Python 3.14 пока не поддерживается — unstructured, часть стека извлечения документов, сейчас объявляет Requires-Python: <3.14.

Настройка репозитория

just dev
source .venv/bin/activate
just test

just dev устанавливает проект, синхронизирует dev-зависимости и настраивает Git-хуки prek. just test — точка входа последовательной локальной проверки: форматирует, применяет автофиксы линта, запускает ty check, затем pytest.

Запуск примеров воркфлоу

В репозитории есть минимальные рабочие примеры Slim LLM в examples/slim_llm.

Обе версии выполняют такой воркфлоу:

start -> llm -> answer

Запуск:

just dev
source .venv/bin/activate
cd examples/slim_llm
cp credentials.example.json credentials.json
python3 dsl.py "Reply with only the word Graphon."
python3 code.py "Reply with only the word Graphon."

Перед запуском заполните нужные значения в credentials.json.

Пример сейчас ожидает:

• OpenAI-совместимые credentials модели в model_credentials
• slim.mode — local или remote
• arkady-plugin-daemon-slim в PATH, SLIM_BINARY_PATH, либо локальный бинарник slim в директории примера
• для remote-режима — daemon_addr и daemon_key

Точный формат credentials и заметки по рантайму — в examples/slim_llm/README.md.

Как устроен Graphon

На высоком уровне прямое использование Graphon выглядит так:

1. Построить или загрузить граф, инстанцировать узлы в Graph.
2. Подготовить GraphRuntimeState и заполнить VariablePool.
3. Настроить адаптеры модели, файлов, HTTP, инструментов или human-input по необходимости.
4. Запустить GraphEngine и обрабатывать события графа.
5. Прочитать финальные выходные данные из состояния рантайма.

Для DSL-документов Arkady используйте arkady_graphon.dsl.loads(), чтобы построить движок из YAML-воркфлоу и credentials. Получившийся движок использует DSL Slim-адаптер для LLM-узлов:

engine = loads(
    dsl,
    credentials=credentials,
    workflow_id="example-dsl-openai-slim",
    start_inputs={"query": query},
)

events = list(engine.run())

См. examples/slim_llm/dsl.py для версии с импортом DSL и examples/slim_llm/code.py для версии с построением графа на Python.

Импорт DSL по умолчанию сейчас поддерживает start, end, answer, if-else, template-transform, code, llm, tool, http-request, variable-aggregator, assigner, list-operator, question-classifier и parameter-extractor. Импорт HTTP-запросов покрывает текстовые тела запросов и текстовые ответы; тела запросов с файлами всё ещё требуют файловых адаптеров на уровне приложения.

Для прямого построения графа на Python используйте arkady_graphon.dsl.slim.SlimLLM как стандартный Slim-рантайм для LLM. Интеграциям, которым нужно заменить исполнение модели, роутинг, инъекцию credentials или подсчёт токенов, стоит реализовать arkady_graphon.protocols.LLMProtocol. Более высокоуровневый слой фабрики/резолвера моделей запланирован отдельным доработкой.

Структура проекта

• src/arkady_graphon/graph: структуры графа, парсинг, валидация, построители
• src/arkady_graphon/graph_engine: оркестрация, воркеры, командные каналы и слои
• src/arkady_graphon/runtime: состояние рантайма, read-only обёртки, пул переменных
• src/arkady_graphon/nodes: встроенные реализации узлов воркфлоу
• src/arkady_graphon/model_runtime: абстракции провайдера/модели и общие сущности моделей
• src/arkady_graphon/dsl: поддержка импорта DSL, включая Slim-адаптеры рантайма
• src/arkady_graphon/graph_events: модели событий, испускаемых при исполнении
• src/arkady_graphon/http: абстракции HTTP-клиента и реализация по умолчанию
• src/arkady_graphon/file: модели файлов воркфлоу и хелперы файлового рантайма
• src/arkady_graphon/protocols: публичные ре-экспорты протоколов для интеграций
• examples/: рабочие примеры
• tests/: unit- и integration-тесты

Внутренняя документация

• CONTRIBUTING.md: процесс контрибьютора, CI, правила commit/PR
• examples/slim_llm/README.md: настройка рабочего примера Slim LLM
• src/arkady_graphon/model_runtime/README.md: обзор рантайма моделей
• src/arkady_graphon/graph_engine/layers/README.md: точки расширения слоёв движка
• src/arkady_graphon/graph_engine/command_channels/README.md: локальные и распределённые командные каналы

Разработка

Настройка для контрибьюторов, детали инструментов, заметки по CLA и конвенции commit/PR — в CONTRIBUTING.md.

CI сейчас проверяет заголовки pull request'ов, запускает just check (включая проверку актуальности uv.lock) и uv run pytest на Python 3.12 и 3.13. Python 3.14 пока исключён — unstructured его ещё не поддерживает.

Лицензия

Apache-2.0. См. LICENSE.

English version: README.en.md