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

---
layout: default
title: "Схема: Предложение по реорганизации каталога"
parent: "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. **Готовность к будущему** - Легко добавлять новые типы знаний или сервисы, не загромождая

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

```python
# Изначально
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>
<invoke name="TodoWrite">
<parameter name="todos">[{"id": "1", "content": "Оценить текущую структуру каталога схемы", "status": "completed", "priority": "high"}, {"id": "2", "content": "Проанализировать файлы схемы и их назначение", "status": "completed", "priority": "high"}, {"id": "3", "content": "Предложить улучшенное наименование и структуру", "status": "completed", "priority": "high"}]