trustgraph/docs/tech-specs/schema-refactoring-proposal.ru.md

layout	title	parent
default	Схема: Предложение по реорганизации каталога	Russian (Beta)

Схема: Предложение по реорганизации каталога

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

Текущие проблемы

1. Плоская структура - Все схемы в одном каталоге затрудняют понимание взаимосвязей
2. Смешанные задачи - Ядро типов, объекты домена и контракты API смешаны вместе
3. Неясное наименование - Файлы, такие как "object.py", "types.py", "topic.py", не указывают четко их назначение
4. Отсутствие четкого уровня - Трудно понять, на что зависит что

Предлагаемая структура

trustgraph-base/trustgraph/schema/
├── __init__.py
├── core/              # Основные примитивные типы, используемые везде
│   ├── __init__.py
│   ├── primitives.py  # Ошибка, Значение, Трипл, Поле, Схема строк
│   ├── metadata.py    # Запись метаданных
│   └── topic.py       # Утилиты для тем
│
├── knowledge/         # Модели домена знаний и извлечение
│   ├── __init__.py
│   ├── graph.py       # EntityContext, EntityEmbeddings, Триплы
│   ├── document.py    # Документ, TextDocument, Chunk
│   ├── knowledge.py   # Типы извлечения знаний
│   ├── embeddings.py  # Все типы, связанные с встраиванием (перенесены из нескольких файлов)
│   └── nlp.py         # Типы Определение, Тема, Отношение, Факты
│
└── services/          # Контракты запросов/ответов сервисов
    ├── __init__.py
    ├── llm.py         # TextCompletion, Embeddings, Запросы/ответы инструментов
    ├── retrieval.py   # Запросы/ответы GraphRAG, DocumentRAG
    ├── query.py       # Запросы/ответы GraphEmbeddingsRequest/Response, DocumentEmbeddingsRequest/Response
    ├── agent.py       # Запросы/ответы агента
    ├── flow.py        # Запросы/ответы потока
    ├── prompt.py      # Запросы/ответы сервиса подсказок
    ├── config.py      # Конфигурационный сервис
    ├── library.py     # Сервис библиотека
    └── lookup.py      # Сервис поиска

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

1. Иерархическая организация - Четкое разделение между основными типами, моделями знаний и контрактами сервисов

2. Улучшенное наименование:

   • types.py → core/primitives.py (более четкое назначение)
   • object.py → Разделение на соответствующие файлы на основе фактического содержимого
   • documents.py → knowledge/document.py (одинаковое, согласованное)
   • models.py → services/llm.py (более четко, какие модели)
   • prompt.py → Разделение: части сервиса в services/prompt.py, типы данных в knowledge/nlp.py

3. Логическая группировка:

   • Все типы встраивания консолидированы в knowledge/embeddings.py
   • Все контракты сервисов LLM в services/llm.py
   • Четкое разделение пар запросов/ответов в каталоге сервисов
   • Типы извлечения знаний сгруппированы с другими моделями домена знаний

4. Ясность зависимостей:

   • Основные типы не имеют зависимостей
   • Модели знаний зависят только от основных
   • Контракты сервисов могут зависеть как от основных, так и от моделей знаний

Преимущества миграции

1. Легче навигация - Разработчики могут быстро найти то, что им нужно
2. Улучшенная модульность - Четкие границы между разными задачами
3. Проще импорт - Более интуитивные пути импорта
4. Готовность к будущему - Легко добавлять новые типы знаний или сервисы, не загромождая

Пример изменений импорта

# Изначально
from trustgraph.schema import Error, Triple, GraphEmbeddings, TextCompletionRequest

# После
from trustgraph.schema.core import Error, Triple
from trustgraph.schema.knowledge import GraphEmbeddings
from trustgraph.schema.services import TextCompletionRequest

Заметки по реализации

1. Сохраняйте обратную совместимость, поддерживая импорт в корневом файле __init__.py
2. Перемещайте файлы постепенно, обновляя импорты по мере необходимости
3. Рассмотрите возможность добавления файла legacy.py, который импортирует всё для переходного периода
4. Обновите документацию, чтобы отразить новую структуру

<function_calls> [{"id": "1", "content": "Оценить текущую структуру каталога схемы", "status": "completed", "priority": "high"}, {"id": "2", "content": "Проанализировать файлы схемы и их назначение", "status": "completed", "priority": "high"}, {"id": "3", "content": "Предложить улучшенное наименование и структуру", "status": "completed", "priority": "high"}]