TestGraph

TestGraph

Экспериментальный ИИ-нативный граф опыта для общего проверяемого знания между ИИ-ассистентами.

Статус: рабочая исследовательская система до релиза. Архитектура и MCP-процессы опробованы с несколькими ИИ-клиентами, но проект пока не предоставляется как стабильный производственный сервис или API.

TestGraph сохраняет человеческие отзывы и структуру, полученную из ИИ, как независимое графовое знание, отделяя свидетельства, происхождение и проверяемую сервером исполнительность от утверждений моделей. Он спроектирован так, чтобы разные ИИ-системы могли вносить вклад в одни и те же знания и повторно использовать их без необходимости заранее иметь полную доменную схему.

Related MCP server: Graph-Mem MCP

Цели проекта

1. Эмерджентность схемы: Дать нескольким ИИ-ассистентам незнакомый опыт и получить полезную структуру, не разрабатывая категории заранее.

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

3. Правдивое выполнение: Модели не могут заявлять, что при открытии, обогащении или согласовании не может собственно выполнилось, если сервер не может этого проверить.

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

Эти цели являются критериями приёмки для архитектуры TestGraph и его тестов, а не просто руководством для отдельных ИИ-клиентов.

Модель стандартного словаря

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

Классификация — это отдельные метаданные. Например, ferry belongs_to transportation улучшает широкий транспортный поиск, но никогда не изменяет место хранения отзыва о пароме. review — это тип записи, а не узел словаря. Повторно используемые структурированные поля имеют свои стабильные идентификаторы и псевдонимы и могут быть прикреплены к нескольким типам предметов.

Миграция 0009_flat_standard_vocabulary намеренно отбрасывает старые данные понятий/отзывов v2, сохраняя пользователей, состояние OAuth, учётные данные возможностей и другие данные аутентификации.

Локальная настройка

1. Создайте виртуальное окружение Python 3.11+.

2. Установите зависимости:

pip install -r requirements.txt

3. Скопируйте .env.example в .env и замените каждый секрет-заполнитель на частное значение.

4. Выполните миграции:

alembic upgrade head

5. Заполните схемы и демонстрационные идентичности:

python -m scripts.seed

6. Запустите приложение:

python run.py

Откройте http://127.0.0.1:8000 и http://127.0.0.1:8000/docs.

Не используйте примерные или разработочные учётные данные за пределами локальной среды разработки. Секреты, ключи API, коды подключения OAuth и идентификаторы владельца никогда не должны попадать в репозиторий.

MCP и OAuth

TestGraph включает MCP-приложение, работающее только с инструментами.Текущая мультимодельная интеграция осуществляется через /mcp-v2. Его производственное подключение использует OAuth 2.1 Authorization Code + PKCE. Подключённый ИИ получает короткоживущий связанный токеден. Он не получает код подключения, ключ API или идентификатор владельца TestGraph.

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

Перед развёртыванием настройте длинный случайный OAUTH_CONNECTION_CODE, задайте соответствующий OAUTH_OWNER_USER_ID и убедитесь, что производственные секреты существуют только в среде развёртывания.

Открытые рецензии рецептов из UCI

После миграций и python -m scripts.seed выполните:

python -m scripts.import_uci_recipe_reviews --representative-reviews 100 --load

Эти команд загружает датасет UCI с лицензией CC BY 4.0 и выбирает по одному насыщенному отзыву от каждого из 100 рецептов. Она записывает преобразованные записи в data/uci_recipe_reviews_100.json и загружает их в настроенную базу данных. Повторный запуск безопасен: стабильные исходные идентификаторы предотвращают дубликаты.

Оригинальный текст отзыва, рейтинг от 0 до 5 звёзд, отметка времени, голоса, исходный идентификатор записи, лицензия и атрибуция сохраняются в происхождении. Импортер интерпретирует явные высказывания о вкусе, ясности, времени, доступности ингредиентов, сложности, решении повторить и изменениях. Каждая интерпретация сохраняет подтверждающее её исходное предложение; всё, что не поддерживается, остаётся null.

Чтобы загрузить передаваемый установочный комплект без загрузки или перегенерации:

python -m scripts.import_uci_recipe_reviews --load-bundle data/uci_recipe_reviews_100.json

Сброс данных разработки

Защищённая страница сброса доступна по адресу /development/reset. Она скрыта и возвращает 404, если только явно не включена:

ENABLE_DEVELOPMENT_RESET=true

Эта страница безвозвратно удаляет данные отзывов и знаний v1/v2, сохраняя при этом пользователей, схемы, OAuth-подключения и учётные данные возможностей. Она должна оставаться отключённой в публичном производственном развёртывании.

Тесты

pytest -q

Публичный релиз не должен создаваться до тех пор, пока полный тестовый набор не пройдёт на релизном коммите и проверка готовности к развёртыванию не завершится успешно. См. RELEASE_CHECKLIST.md.

Развёртывание на Railway

1. Загрузите репозиторий на GitHub.

2. Создайте проект Railway из GitHub-репозитория.

3. Добавьте PostgreSQL.

4. Ссылайтесь на DATABASE_URL службы Postgres; не вставляйте неразрешённую ссылку Railway в виде открытой строки.

5. Настройте производственные переменные с уникальными случайными паролями:

ENVIRONMENT=production
APP_SECRET=<random secret>
DEVELOPMENT_API_KEY=<long random key; development/admin use only>
CLIENT_API_KEYS={}
OAUTH_OWNER_USER_ID=<owner UUID>
OAUTH_CONNECTION_CODE=<long random connection code>
PUBLIC_BASE_URL=https://<your-domain>
ALLOWED_HOSTS=["<your-domain>","<railway-domain>"]
CORS_ORIGINS=["https://<your-domain>"]
ENABLE_DEVELOPMENT_RESET=false

railway.json настраивает миграции перед развёртыванием, запуск Uvicorn с использованием $PORT и проверку готовности по /health/ready.

Приложение преобразует postgresql:// URL-адрес Railway в форму SQLAlchemy postgresql+psycopg://, потому что проект использует Psycopg 3. Производственный экземпляр, который не может получить доступ к PostgreSQL, должен остановлиться, а не просто переключаться на SQLite.

Реализованная архитектура

• Возможности вызывающего ИИ как открытого семантического и защитного движка, с сервером как уровень проверки и хранения

• Стабильные плоские идентификаторы типов предметов

• Канонические термины и псевдонимы

• Редактируемые связи между типами используются для поиска, а не для координат хранения

• Версионированный реестр схем

• Доменная проверка Pydantic, хранящаяся в JSON/JSONB

• Черновик-прежняя публикация с явным одобрением/версией

• Ограниченные области и безопасные данные клиента

• Центральная политика чтения

• Каноническое разрешение предметов и редактирование черновиков с проверкой версий

• OAuth 2.1 Authorization Code + PKCE, динамическая регистрация клиентов, ротация маркера обновления и ограниченные маркеры доступа

• MCP-эндпоинт для безопасного доступа ИИ

• Ключи идемпотентности

• Происхождение, согласие, право собственности и видимость

• Поисковая согласованность читателя и обзора, и специфическая для читателя релевантность

• Журнал аудита и мягкое удаление

• Идентификаторы запросов, согласованные ошибки JSON, ограничения размера запроса и эндпоинты, поддерживающие подкачку

• Миграции Alembic

• SQLite локально; PostgreSQL в производстве

• Межмодельная обилаживание и записываемые сервером процессы разработки/оценки

Безопасное чтение и правила редактирования

• Общественные списки возвращают только те отзывы, которые одновременно являются published и public.

• С точными идентификаторами также можно получить опубликованный unlisted отзыв.

• Черновики и приватные отзывы требуют соответствующего разрешения на чтение.

• aggregate_only отзывы никогда не возвращаются как отдельные отзывы.

• Прежде чем изменять или присоединять структурированные знания, решите предметные типы.

• Проверки версий защищают одновременное редактирование черновиков.

• Необязательные учётные данные должны использовать уникальные, поддающиеся отмене секреты и максимально ограниченные области.

Лицензия

TestGraph распространяется под лицензией GNU Affero General Public License v3.0 (AGPL-3.0). См. файл LICENSE.

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

Если AGPL-3.0 вам не подходит, может быть доступно альтернативное коммерческое или частное лицензирование. Свяжитесь с нами по адресу testgraph@21dle.co.uk, чтобы обсудить отдельное лицензионное соглашение.

Авторы должны прочитать CONTRIBUTING.md. Принимаются только те вклады, условия которых оставляют за проектом возможность предоставлять альтернативные лицензии.

Прежде чем сделать репозиторий публичным

Прочитайте RELEASE_CHECKLIST.md и SECURITY.md. В частности, завершите просмотр истории секретов, подтвердите границу публичных данных, запустите полный набор тестов и проверьте чистоту развёртывания из точного релизного коммита.