Graphify-Labs/graphify: локальный AST‑парсинг

Graphify-Labs/graphify: локальный AST‑парсинг

Turn any codebase, docs, SQL schemas, configs and PDFs into a queryable knowledge graph using /graphify skill with local deterministic AST parsing, no vector store.

Обзор Graphify-Labs/graphify

Обзор Graphify-Labs/graphify

Превращение кода, документации и схем в знание

Graphify‑Labs/graphify позволяет превратить любой код‑баз, техническую документацию, SQL‑схемы, конфиги и даже PDF‑файлы в запроемый граф знаний. В отличие от решений, полагающихся на векторы, он использует локальный детерминированный парсинг AST, что гарантирует воспроизводимость и отсутствие «чёрных ящиков».

Пример: у вас есть небольшой Python‑модуль example.py. Чтобы получить граф, достаточно выполнить:

bashКопировать
graphify parse --input example.py --output graph.json

Полученный graph.json можно затем загрузить в локальный UI‑просмотрщик или передать в ваш собственный поисковый движок.

Для конфигурационных файлов удобно использовать YAML‑спецификацию:

yamlКопировать
# graphify.yaml
sources:
  - path: ./src/
    type: python
  - path: ./docs/*.md
    type: markdown
  - path: ./schema.sql
    type: sql
output:
  file: ./graph/graph.json

Запуск производится одной командой:

bashКопировать
graphify run --config graphify.yaml

В результате в каталоге graph появится graph.json, а также вспомогательные индексы, которые можно быстро открыть в браузере:

bashКопировать
graphify ui --data graph/graph.json

Эти возможности позволяют превратить разрозненные artefacts в единую структуру, откуда можно строить запросы типа « какие функции вызываются из process_data » или « какие таблицы используются в схеме public ».

Смотрите подробнее в статье о локальных ИИ‑агентах и инструментах Локальные ИИ‑агенты и инструменты.

Локальный детерминированный парсинг AST

Главная фишка Graphify‑Labs/graphify – использование локального парсера абстрактного синтаксического дерева (AST). Парсер работает полностью офлайн, не требует отправки данных на сторонние серверы и не зависит от внешних API. Это обеспечивает предсказуемость: один и тот же файл всегда даёт одинаковый граф, независимо от текущей загрузки сети или наличия доступа к интернету.

Как это выглядит в коде

Для Python‑файла utils.py парсер строит дерево, где каждый узел представляет функцию, класс или оператор. Пример вывода в JSON‑формате:

jsonКопировать
{
  "file": "utils.py",
  "functions": [
    {
      "name": "calculate",
      "args": ["x", "y"],
      "returns": "int",
      "docstring": "Вычисляет сумму двух чисел."
    }
  ],
  "classes": [],
  "imports": [
    {"module": "os", "as": null}
  ]
}

Для SQL‑схемы schema.sql парсер выделяет таблицы, столбцы и связи:

jsonКопировать
{
  "file": "schema.sql",
  "tables": [
    {
      "name": "users",
      "columns": [
        {"name": "id", "type": "BIGINT", "primary": true},
        {"name": "email", "type": "VARCHAR", "nullable": false}
      ],
      "indexes": [
        {"columns": ["email"], "unique": true}
      ]
    }
  ],
  "relationships": [
    {
      "from": {"table": "users", "column": "id"},
      "to": {"table": "orders", "column": "user_id"},
      "type": "one_to_many"
    }
  ]
}

Эти структуры удобно использовать в собственных скриптах. Например, Python‑скрипт, который ищет все функции, принимающие более двух аргументов:

pythonКопировать
import json

with open('graph.json') as f:
    g = json.load(f)

for func in g.get('functions', []):
    if len(func.get('args', [])) > 2:
        print(func['name'])

Преимущества локального подхода

• Детерминированность – один файл → один и тот же граф при каждой генерации.
• Конфиденциальность – никаких данных не покидают ваш сервер.
• Скорость – парсинг происходит за доли секунды даже на modest‑hardware (Raspberry Pi 4 с 4 ГБ RAM).

Если вам интересны детали реализации парсера, см. материал о автономной разработке на Rust с помощью Claw‑Code Автономная разработка на Rust с помощью Claw-Code.

---

Готовый граф знаний уже ждет вас в домашней лаборатории – достаточно лишь запустить пару команд и приступить к анализу.

Локальный AST‑парсинг без векторного хранилища

Локальный AST‑парсинг — это способ превратить любой код, документацию, схемы БД, конфиги и PDF в запросимый граф, не прибегая к внешним векторным хранилищам.

Детерминированный разбор абстрактного синтаксического дерева

graphify использует собственный детерминированный парсер AST, который строит структуру дерева без случайных выборов и без обращения к сторонним моделям.

bashКопировать
# Пример запуска парсера
graphify parse \
  --input ./src/main.py \
  --output ./graph.json \
  --lang python

yamlКопировать
# graphify.yaml – минимальная конфигурация
version: 1
parser:
  language: python
  mode: deterministic
output:
  format: json
  path: ./graph.json

В результате парсер выдаёт JSON‑файл, где каждый узел имеет уникальный идентификатор и явно указанный тип (class, function, variable и т.п.).

Пример фрагмента graph.json для простого скрипта:

jsonКопировать
{
  "nodes": [
    { "id": "1", "type": "module", "name": "main" },
    { "id": "2", "type": "function", "name": "run", "args": [] },
    { "id": "3", "type": "call", "function": "run", "target": "2" }
  ],
  "edges": [
    { "from": "1", "to": "2", "relation": "contains" },
    { "from": "2", "to": "3", "relation": "invokes" }
  ]
}

Таким образом, дерево строится однозначно, и повторный запуск с тем же входом даёт идентичный результат.

Каждая связь объясняется, без «чёрных ящиков»

graphify не скрывает, как формируются связи между узлами. В каждом ребре указано, какое отношение выполняется: calls, uses, inherits, referenced_by и т.д. Это позволяет сразу понять, почему определённый элемент попал в граф.

bashКопировать
# Пример запроса к готовому графу
curl -s http://localhost:8080/graphql -d '{
  query {
    nodes(id: "2") {
      name
      edges {
        target {
          name
          type
        }
        relation
      }
    }
  }
}'

Ответ покажет, что узел 2 — функция run, которая вызывает узел 3 — вызов функции run. Каждая связь снабжена пояснением, поэтому нет необходимости гадать, что «чёрный ящик» скрывает.

Для сравнения, в типичных векторных подходах связь определяется на основе схожести векторов, и её смысл часто не очевиден. graphify же делает всё явно, как в обычных схемах UML.

Локальные ИИ-агенты и инструменты — в этой статье описаны сценарии, где детерминированный AST‑парсинг может быть полезен для построения локальных агентов, работающих без облачных сервисов.

Автономная разработка на Rust с помощью Claw-Code — пример, где локальный разбор кода позволяетClawhost — автономный агент, который не зависит от внешних API.

В итоге, детерминированный разбор AST и прозрачные связи делают graphify надёжным инструментом для создания локальных знани‑графов, которые легко проверять, модифицировать и интегрировать в собственные пайплайны.

Интеграция с инструментами разработки

Интеграция с инструментами разработки

Когда мы говорим об использовании AST-парсинга для построения графа знаний, важно понимать: это не просто способ «скормить» код нейросети. Это способ сделать контекст предсказуемым. Вместо того чтобы полагаться на векторный поиск, который часто ошибается в связях между функциями, мы даём агенту структурную карту проекта.

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

Скилл /graphify для Claude Code, Cursor, Codex, Gemini CLI

Большинство современных локальных ИИ-агентов и инструментов работают по принципу «окна контекста». Если проект большой, агент начинает «галлюцинировать», теряя связи между модулями. Использование Graphify через кастомные навыки (skills) позволяет агенту не гадать, а запрашивать конкретные узлы графа.

Для Claude Code или Gemini CLI интеграция выглядит как добавление нового инструмента в конфигурацию агента. Если вы используете CLI-интерфейсы, вам нужно прописать вызов парсера в системном промпте или через конфигурационный файл инструментов.

Пример того, как можно описать доступность навыка в конфигурации агента (JSON-схема):

jsonКопировать
{
  "skill_name": "graphify",
  "description": "Преобразует код, SQL-схемы или документацию в графовую структуру для точного поиска связей",
  "parameters": {
    "path": "путь к директории или файлу",
    "query": "запрос к графу (например, 'найти все зависимости функции X')"
  },
  "execution_command": "graphify --path {{path}} --query '{{query}}'"
}

В Cursor или подобных IDE, где агент имеет доступ к файловой системе, Graphify выступает в роли «умного индексатора». Вместо того чтобы индексировать каждый файл как отдельный кусок текста, инструмент строит дерево зависимостей. Это критически важно при автономной разработке, когда агенту нужно понимать не только синтаксис, но и архитектурную логику.

Подключение к CI/CD и мониторингу

Я всегда придерживаюсь правила: если процесс можно автоматизировать и сделать проверяемым, его нужно автоматизировать. Graphify отлично вписывается в пайплайны CI/CD, где его можно использовать для статического анализа архитектурных изменений.

Например, при создании Pull Request можно запускать проверку на «архитектурную чистоту». Если новый код нарушает установленные связи в графе (например, внедряет циклическую зависимость там, где её быть не должно), пайплайн должен упасть.

Пример шага в GitHub Actions для анализа изменений:

yamlКопировать
jobs:
  arch-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Graphify
        run: pip install graphify-labs # Условный пример установки
      - name: Analyze architectural changes
        run: |
          # Сравниваем текущий граф с эталонным из ветки main
          graphify diff --base origin/main --head HEAD --output report.json
      - name: Check for violations
        run: |
          if jq '.violations | length > 0' report.json; then
            echo "Архитектурные нарушения обнаружены"
            exit 1
          fi

С точки зрения мониторинга, результаты работы парсера можно направлять в системы логирования. Если мы рассматриваем оптимизацию ИИ-агентов, то отслеживание того, насколько часто агент обращается к графу и находит ли он нужные узлы, помогает понять, насколько эффективно выстроена ваша база знаний.

Если вы строите сложные системы, подобные тем, что описываются в работах по оптимизации производительности агентных сред, наличие детерминированного AST-парсера вместо нестабильного векторного поиска — это шаг к созданию промышленного решения, а не просто игрушки.

Часто задаваемые вопросы

Чем AST-парсинг отличается от векторного поиска в таких задачах?

Векторный поиск работает на основе семантической близости, что часто приводит к галлюцинациям или потере точности в сложных структурах. AST-парсинг — это детерминированный метод, который извлекает реальные связи между объектами кода или схем на основе синтаксиса. С практической точки зрения это даёт предсказуемость: если функция вызывает другую функцию, в графе это будет зафиксировано как жёсткая связь, а не как «похожий по смыслу текст».

Нужно ли разворачивать отдельную векторную базу данных для работы инструмента?

Нет, для работы Graphify не требуется установка векторных хранилищ или специализированных БД для эмбеддингов. Инструмент формирует граф знаний на основе синтаксического анализа и сохраняет результат в обычный JSON-файл. Это упрощает размещение на своём оборудовании и позволяет использовать полученные данные в любом поисковом движке, поддерживающем графовые структуры.

Можно ли использовать Graphify для анализа больших репозиториев?

Да, инструмент поддерживает пакетную обработку через конфигурационные файлы YAML, где можно указать различные типы источников. Однако стоит учитывать, что при работе с очень крупными проектами время генерации графа будет расти пропорционально объёму кода. Для обеспечения стабильности при анализе больших массивов данных рекомендую выделять достаточно оперативной памяти, так как построение дерева для огромных файлов требует ресурсов.

Как обеспечить точность извлечения данных из PDF-файлов?

Точность парсинга PDF напрямую зависит от того, насколько структурирован исходный документ. Если PDF представляет собой текстовый слой, Graphify сможет корректно обработать содержимое, но сложные многоколоночные верстки или таблицы могут потребовать предварительной очистки. Для достижения максимальной предсказуемости лучше всего использовать документы с чёткой иерархией заголовков.