Metadata-Version: 2.4
Name: arkady-graphon
Version: 0.7.0
Summary: Graph execution engine for agentic AI workflows.
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Dist: charset-normalizer>=2.1
Requires-Dist: httpx>=0.28
Requires-Dist: json-repair>=0.55
Requires-Dist: jsonschema>=4
Requires-Dist: orjson>=3
Requires-Dist: pandas[excel]>=2.1
Requires-Dist: pydantic>=2.7
Requires-Dist: pydantic-extra-types>=2
Requires-Dist: pypdf>=6.14.2
Requires-Dist: pypdfium2>=5
Requires-Dist: python-docx>=1.2
Requires-Dist: pyyaml>=6
Requires-Dist: tiktoken>=0.12
Requires-Dist: transformers>=4
Requires-Dist: typing-extensions>=4.10.0
Requires-Dist: unstructured[docx,epub,md,ppt,pptx]>=0.21
Requires-Dist: pypandoc>=1.13
Requires-Dist: webvtt-py>=0.5
Requires-Python: >=3.12, <3.14
Project-URL: source, https://github.com/reraaaaa/arkady-graphon
Project-URL: homepage, https://github.com/reraaaaa/arkady-graphon
Project-URL: issues, https://github.com/reraaaaa/arkady-graphon/issues
Description-Content-Type: text/markdown

# 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`](https://docs.astral.sh/uv/)
- [`just`](https://just.systems/)
- [`fd`](https://github.com/sharkdp/fd)

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

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

```bash
just dev
source .venv/bin/activate
just test
```

`just dev` устанавливает проект, синхронизирует dev-зависимости и настраивает
Git-хуки [`prek`](https://prek.j178.dev/). `just test` — точка входа
последовательной локальной проверки: форматирует, применяет автофиксы линта,
запускает `ty check`, затем [`pytest`](https://docs.pytest.org/).

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

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

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

```text
start -> llm -> answer
```

Запуск:

```bash
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](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-узлов:

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

events = list(engine.run())
```

См. [examples/slim_llm/dsl.py](examples/slim_llm/dsl.py) для версии с импортом
DSL и [examples/slim_llm/code.py](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](CONTRIBUTING.md): процесс контрибьютора, CI, правила commit/PR
- [examples/slim_llm/README.md](examples/slim_llm/README.md):
  настройка рабочего примера Slim LLM
- [src/arkady_graphon/model_runtime/README.md](src/arkady_graphon/model_runtime/README.md):
  обзор рантайма моделей
- [src/arkady_graphon/graph_engine/layers/README.md](src/arkady_graphon/graph_engine/layers/README.md):
  точки расширения слоёв движка
- [src/arkady_graphon/graph_engine/command_channels/README.md](src/arkady_graphon/graph_engine/command_channels/README.md):
  локальные и распределённые командные каналы

## Разработка

Настройка для контрибьюторов, детали инструментов, заметки по CLA и
конвенции commit/PR — в [CONTRIBUTING.md](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](LICENSE).

---
English version: [README.en.md](README.en.md)
