Graphify-Labs: Превращение кода в запросную графовую БД

Graphify-Labs: Превращение кода в запросную графовую БД

Превращает кодовые репозитории с документацией, SQL-скемами и конфигами в запросную графовую БД. Локальный AST-парсинг без векторного хранилища.

Основные возможности

Основные возможности

Интеграция с документацией

Graphify-Labs устанавливает прямую связь между исходным кодом и его документацией, превращая веб-страницы, README-файлы и документацию в полноценные графы зависимостей. Это позволяет не просто парсить текст, а строить структурированные связи между функциями, модулями и их описаниями.

Автоматическое построение графов из документации

Система анализирует структуру документации и создаёт граф, где узлы — это элементы кода или документации, а ребра — связи между ними. Например, если в README описано, что функция calculate_tax вызывает validate_income, граф автоматически формирует ребро зависимости.

yamlКопировать
# Пример конфигурации интеграции с документацией
graphify_config:
  docs_source: "docs"
  graph_type: "functional-dependency"
  auto_link_docs: true
  include_markdown: true
  exclude_patterns:
    - "TODO"
    - "FIXME"
    - "XXX"

Работа с API документации

Для проектов с документацией в формате OpenAPI или Markdown GraphQL-шайпова система может извлекать схемы напрямую. Это упрощает настройку и исключает необходимость ручного парсинга файлов.

bashКопировать
# Скачиваем документацию и строим граф
graphify init -d docs -o graph.yaml
graphify build --format=graphml

После выполнения команды в папке graph.yaml появится файл с полным графом зависимостей, который можно импортировать в downstream-системы анализа кода.

SQL-скемы и конфигурации

Graphify-Labs не требует внешнего векторного хранилища — все данные остаются локально в формате, удобном для SQL-баз. Это позволяет сохранять приватность и избегать накладных расходов на хранение векторов.

Парсинг SQL-скем

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

sqlКопировать
-- Пример структуры, которая будет построена Graphify
CREATE TABLE users (
    id UUID PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE orders (
    id UUID PRIMARY KEY,
    user_id UUID REFERENCES users(id),
    total DECIMAL(10,2),
    status VARCHAR(50)
);

CREATE TABLE order_items (
    id UUID PRIMARY KEY,
    order_id UUID REFERENCES orders(id),
    product_id VARCHAR(100),
    quantity INT
);

Интеграция с конфигурационными файлами

Конфигурации проекта (YAML, JSON, TOML) также подключаются к графу. Это позволяет отслеживать, какие настройки влияют на какие части приложения, и визуализировать зависимости между конфиг-переменными и логикой кода.

yamlКопировать
# Пример конфигурации приложения
app_config:
  database:
    type: "postgresql"
    host: "localhost"
    port: 5432
    pool_size: 20
  cache:
    type: "redis"
    host: "cache.internal"
    ttl: 300
  analytics:
    enabled: true
    endpoint: "https://analytics.internal/api"

Практический пример

Рассмотрим, как Graphify-Labs связывает SQL-скемы и конфигурации в единую модель:

bashКопировать
# Создаём граф на основе существующей базы
graphify sync --db "postgresql://app:5432/myproject" --graph-dir ./graphs

# Просматриваем сгенерированный граф
graphify view ./graphs/myproject/graph.dot

Результатом будет DOT-файл, который можно открыть в Graphviz для визуализации связей. Такой подход позволяет инженерам быстро понять, как изменения в конфигурации базы данных отражаются на остальной архитектуре приложения.

Связанные материалы

Для углублённого понимания возможностей Graphify-Labs рекомендуется ознакомиться с примерами использования и практиками реальных инженеров. Создание музейного экспоната с помощью агента на Rust демонстрирует, как интеграция с AI-агентами может быть организована через Graphify. Навыки реальных инженеров: коллекция .agents содержат практические примеры работы с агентами, которые легко масштабируются на построение графовых баз данных. CLAUDE Code: оптимизация на основе практик Андрея Карпаты предлагает лучшие практики оптимизации кода, применимые при настройке Graphify. Reverse Engineer with Agents: From App Behavior to Binaries показывает, как агенты могут анализировать бинарный код и генерировать графы зависимостей. Ponytail: как заставить AI-агента думать как старший полезна для понимания методологии взаимодействия между AI-агентами и системой Graphify.

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

Техническая реализация

Техническая реализация

Локальный AST-парсинг

Graphify-Labs работает без внешних vector-базов, обрабатывая код на уровне локального абстрактного синтаксического дерева (AST). Парсинг происходит в режиме «offline-first» — инструмент не отправляет данные в облако, а строит граф запросов напрямую из исходного репозитория.

Сбор и разбор кода

Первый этап — извлечение AST из файлов проекта с помощью встроенного парсера. Для C/C++/Rust используется локальный компилятор с флагом -fsyntax-only, для Python — ast‑модуль, а для JavaScript — babel или esprima.

bashКопировать
# Сбор AST всех разделяемых файлов в папке src
find . -type f \( -name "*.py" -o -name "*.c" -o -name "*.rs" -o -name "*.js" -o -name "*.go" \) -exec python3 -c "
import ast, sys
with open(sys.argv[1]) as f:
    tree = ast.parse(f.read())
    # Сохраняем дерево в JSON для дальнейшего анализа
    import json
    print(json.dumps(ast.dump(tree, indent=2), sort_keys=True))
" {} \;

Конфигурация парсера

Главный конфиг graphify-config.yaml определяет, какие файлы включать в анализ и какие правила применять при построении графа:

yamlКопировать
# graphify-config.yaml
parsers:
  python:
    include: "*.py"
    flags:
      - "--no-return"
      - "--ast"
  rust:
    include: "*.rs"
    flags:
      - "-G"
      - "-C debug"
  c:
    include: "*.c"
    flags:
      - "-fsyntax-only"
  javascript:
    include: "*.js"
    flags:
      - "--preserve"
      - "--no-unsafe"

graph:
  mode: "query"
  max_depth: 20
  normalize: true
  deduplicate: true

Построение запросной графа

После парсинга каждого файла строится узел графа, представляющий функцию, класс или модуль. Связи между узлами отражают зависимости: вызовы функций, использование переменных, обращения к БД. Например, вызов user_service.get_profile() создаёт ребро от узла user_service к узлу get_profile.

yamlКопировать
# Пример структуры графа (JSON-LD)
{
  "nodes": [
    {
      "id": "user_service",
      "type": "function",
      "label": "User Service",
      "dependencies": ["user_repository", "db_connection"]
    },
    {
      "id": "db_connection",
      "type": "resource",
      "label": "Database Connection",
      "dependencies": []
    }
  ],
  "edges": [
    {"from": "user_service", "to": "db_connection", "relation": "uses"}
  ]
}

Интеграция с AI-агентами

Готовая графовая структура передаётся в LLM‑агента (Claude, LFM и др.) для дальнейшего анализа. Агент получает не просто список файлов, а семантическую карту зависимостей, что позволяет ему делать более точные рекомендации по оптимизации.

bashКопировать
# Вызов агента с графом как контекстом
graphify-analyze --graph /path/to/graph.json --agent claude-code

Отсутствие векторного хранилища

Graphify-Labs сознательно отказывается от vector‑store (например, Pinecone, Weaviate, Milvus) в пользу чистого локального AST‑графа. Это решение продиктовано тремя причинами: производительность, приватность данных и предсказуемость стоимости.

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

• Скорость запросов — обход графа выполняется за O(1) в среднем, так как связь между сущностями хранится в памяти.
• Приватность — никакие данные не уходят в облако, что критично для компаний с требованиями GDPR и внутренней политикой хранения.
• Предсказуемость — нет задержек на синхронизацию с внешним хранилищем, что важно для реального времени.

Ограничения и компенсации

Отсутствие vector‑indexа означает, что поиск по семантическому содержимому (например, «найти все функции, связанные с пользовательскими данными») требует дополнительных шагов. Graphify-Labs решает это двумя путями:

1. Точный поиск по узлам — благодаря структуре графа можно быстро находить все функции, принадлежащие конкретному модулю или классу.
2. Контекстные аннотации — к каждому узлу привязываются текстовые сноски из документации и комментариев, что позволяет агенту инференса понимать семантику без векторного приближения.

bashКопировать
# Пример поиска всех функций, используемых в модуле
graphify-query --module user_service --fields "function,dependencies" --limit 10

В отличие от подходов, опирающихся на embedding‑модели, локальный AST‑парсинг не требует дополнительного хранилища и не накапливает расходы на индексы. Это особенно выгодно для репозиториев с большим количеством файлов, где vector‑store может стать узким местом.

Сравнение с аналогами

Подход	Vector‑store (Pinecone)	Graph‑DB (Graphify-Labs)
Производительность	O(log n) через ANN	O(1) через индекс в памяти
Приватность	Требует доверия к провайдеру	Полная локальность
Стоимость	Лицензия на хранилище + инференс	Один разовый расход на инфраструктуру
Семантический поиск	Высокий	Через точный обход графа + аннотации

Для практических задач Graphify-Labs показывает превосходство при анализе кода с известной структурой, тогда как vector‑store остаётся полезен при необходимости семантического поиска по описаниям функций в больших данных.

Применение и польза

Применение и польза

Работа с кодами и документами

Graphify-Labs — это инструмент, который превращает кодовые репозитории в поисковую графовую базу данных. Он парсит AST-коды, извлекает связи между функциями, классами и переменными, а также индексирует документацию и конфигурационные файлы.

Основной принцип работы

bashКопировать
# Инициализация Graphify-Labs в проекте
graphify-labs init my-project

# Парсинг репозитория с помощью локального AST-анализатора
graphify-labs parse --source /path/to/repo --output ./graph.db

# Индексация документации и конфигурационных файлов
graphify-labs index --docs ./docs --configs ./config

Пример обработки кода

Представим, что у нас есть простой Go-проект:

goКопировать
// main.go
package main

import (
    "fmt"
    "log"
    "net/http"
)

func main() {
    http.HandleFunc("/", homeHandler)
    http.HandleFunc("/status", statusHandler)
    
    log.Println("Server starting on :8080")
    if err := http.ListenAndServe(":8080", nil); err != nil {
        log.Fatalf("Server failed: %v", err)
    }
}

func homeHandler(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "Welcome to Graphify-Labs!")
}

func statusHandler(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "OK")
}

Graphify-Labs строит граф, в котором узлы — это функции, структуры и импорты, а ребра — связи между ними:

(главная функция main) → вызывает (homeHandler)
(главная функция main) → вызывает (statusHandler)
(http.ListenAndServe) → обрабатывает (обработчик запросов)

Индексация документации

yamlКопировать
# docs/api.md
---
title: API Graphify-Labs
---

## Эндпоинты

- `GET /` — главная страница
- `GET /status` — проверка работоспособности
- `POST /parse` — начать парсинг репозитория

Graphify-Labs извлекает структуру документации и делает её поисковой:

Узел: Эндпоинты
Свойства:
  - `GET /` → описание: "главная страница"
  - `GET /status` → описание: "проверка работоспособности"

Конфигурация для автоматизации

bashКопировать
# .graphify.yml
sources:
  - path: ./src
    type: code
  - path: ./docs
    type: documentation
  - path: ./configs
    type: configuration

output:
  format: graphdb
  path: ./graph.db
  
parser:
  ast:
    enabled: true
    language: multi
  vector_store: false  # Локальный парсинг без векторного хранилища

Сравнение с векторными решениями

Когда векторные решения не подходят

Векторные базы данных отлично подходят для семантического поиска, но они имеют ограничения при работе с кодом:

pythonКопировать
# Пример векторного поиска (не для кода)
from sentence_transformers import SentenceTransformer

# Кодовые фрагменты теряют точность в векторном пространстве
code_embedding = model.encode("func Add(a, b int) int")
similarity = cosine_similarity(code_embedding, database_embedding)

Преимущества графовой базы данных

1. Точное соответствие типов — Graphify-Labs знает, что func Add(a, b int) int — это функция, а не текстовый фрагмент

2. Явные зависимости — граф хранит связи между функциями, файлами и модулями:

(функция Add) → использует (тип int)
(функция Add) → импортирует (пакет main)

3. Быстрый обход связей — запросы типа "найти все функции, которые используют тип DataStore" выполняются мгновенно:

bashКопировать
# Графовый запрос к Graphify-Labs
graphify query '
  MATCH (func:Function)-[:USES]->(type:DataStore)
  RETURN func.name, type.name
'

Практический пример: поиск зависимостей

Векторный подход не может reliably найти, какие функции используют конкретный тип:

pythonКопировать
# Нечеткий векторный поиск — может пропустить совпадения
results = vector_db.similarity_search(
    "использует DataStore", 
    k=10,
    threshold=0.85
)

Graphify-Labs обеспечивает точный результат:

bashКопировать
# Точный графовый запрос
graphify query '
  MATCH (func:Function)-[:USES]->(type:DataStore {name: "DataStore"})
  RETURN func.file_path, func.name, func.line_number
'

Результат:

func.file_path    | func.name      | line_number
-------------------|----------------|------------
./models/user.go   | CreateUser     | 42
./services/api.go  | UpdateUserData | 128

Сравнительная производительность

Операция	Graphify-Labs	Векторная база
Поиск функций по типу	12 мс	245 мс
Обход зависимостей	8 мс	198 мс
Поиск по документации	5 мс	156 мс

Когда использовать Graphify-Labs

• Анализ кода — поиск зависимостей, рефакторинг, обнаружение дублирования
• Поиск в документации — точный поиск по API и конфигурациям
• Автоматизация сборки — отслеживание изменений в зависимостях
• Обнаружение уязвимостей — нахождение использования устаревших типов

Graphify-Labs excels when you need predictable relationships and exact type matching, which vector databases struggle with due to their continuous vector space representation.

Создание музейного экспоната с помощью агента на Rust Навыки реальных инженеров: коллекция .agents CLAUDE Code: оптимизация на основе практик Андрея Карпаты Reverse Engineer with Agents: From App Behavior to Binaries Ponytail: как заставить AI-агента думать как старший