CampusTrace

Проверяемый визуальный профиль университета. Вводите название вуза — получаете фотографии кампуса, общежитий, аудиторий, библиотек, спортивных объектов, лабораторий и студенческой жизни, где у каждого кадра есть кликабельный первоисточник, лицензия, автор, даты и явно названное основание, почему он связан именно с этим вузом. Там, где материалов нет, сервис так и говорит — и отдельно различает «проверено, ничего не нашлось» и «источник не ответил, проверить не успели».

Кейс: LOCUS Startup Hackathon 2026, Кейс 01 «Визуальный профиль университета».

---

СОДЕРЖАНИЕ

1. Задача и решение
2. Как запустить за 3 минуты
3. Тестовый сценарий для жюри
4. Стек и архитектура
5. Как принимается решение по каждому кадру
6. Источники, API и AI — полный список
7. Готовые компоненты и их происхождение
8. Производительность: как мы её измеряем
9. Продуктовое решение по Instagram/Threads
10. Роли команды
11. Развёртывание
12. Тесты
13. Ограничения — честно
14. Чек-лист правил кейса
15. Что записать в демо-видео

---

1. Задача и решение

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

Наше решение — не «ещё одна галерея», а проверяемый паспорт. Ключевая идея: разделять находку и доказательство. CampusTrace никогда не утверждает больше, чем может показать:

Что мы говорим	Что за этим стоит
«Вероятно»	Файл найден в тематическом источнике вуза, лицензия есть, но конкретный корпус не доказан
«Городской контекст»	Это кадр города, и мы прямо говорим, что это не кампус
«Требует проверки»	Источник и лицензия есть, но что изображено — не удалось определить ни по тексту, ни по изображению
«Не проверено: источник был недоступен»	Раздел пуст не потому, что материалов нет, а потому что источник упал на середине

Слова «подтверждено» в значении «доказано место съёмки» в интерфейсе нет вообще — потому что доказать это по открытым данным мы не можем, а притворяться нельзя.

Три вещи, которых обычно нет у аналогов:

1. Доказательства вместо «уверенности». У каждого кадра есть список независимых подтверждений: здание вуза в Wikidata с типом (библиотека, общежитие, стадион), отметка «на фото изображено» (depicts) в структурированных данных Commons, категория Commons, название вуза в файле, геотег рядом с точкой кампуса, визуальная проверка изображения. Карточка показывает уровень достоверности (высокая — 3 и более вида подтверждений, средняя — 2, низкая — 1 или 0; понижается при расхождении проверок и неопределённой категории), число подтверждений и каждое из них ссылкой — а не выдуманный процент.
2. «Откуда мы это знаем» — лента источников. Под названием вуза медленно движется строка логотипов (Wikipedia, Commons, Wikidata, Reddit, YouTube, Instagram, 2ГИС…) — только тех, где для этого вуза реально что-то нашлось, с числом находок. Клик открывает всё, что пришло из этого источника: фото, обсуждения, факты, новости.
3. «Спросите о вузе». Вопрос обычными словами («есть ли общежитие?») — ответ собирается только из пронумерованных источников этого профиля (реестр, Wikidata, Википедия, фото, обсуждения) с номерами ссылок. Ответ без действительной ссылки заменяется на «в собранных источниках ответа нет». Модель не спрашивают, что она сама знает о вузе.
4. Независимая визуальная проверка. Категория Commons и подпись к файлу часто написаны одним человеком — это один источник, а не два. Vision-модель (Groq qwen/qwen3.8-27b или xAI Grok) смотрит на пиксели и называет тип места. При расхождении слоёв статус понижается.
5. Карта пробелов. Профиль показывает, каких категорий не хватает, и почему — это готовый запрос вузу «дайте официальные материалы под открытой лицензией».
6. Воронка отбора видна пользователю. Кандидатов → прошли лицензию → уникальных после дедупликации → опубликовано. Ничего не происходит «в чёрном ящике».

---

2. Как запустить за 3 минуты

Требуется Python 3.11+ и интернет.

cd campustrace-mvp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# ОБЯЗАТЕЛЬНО: в .env замените [email protected] на реальный контакт.
# Nominatim и Wikimedia требуют, чтобы клиент себя идентифицировал.
set -a; source .env; set +a

uvicorn app.main:app --host 127.0.0.1 --port 8765

Откройте http://127.0.0.1:8765. API-документация: /docs. Health-check: /api/health.

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

Переменная	Что включает	Что будет без неё
GROQ_API_KEY	Визуальную проверку фото (qwen/qwen3.8-27b, мозаика 2×2) и сводку по отзывам студентов	Категории только по структурированным данным и тексту; профиль прямо сообщает, что визуальная проверка не выполнена
GROK_API_KEY	Альтернативный vision-провайдер (xAI); если задан, используется вместо Groq	—
CEREBRAS_API_KEY	Запасной текстовый ИИ (бесплатно ~1 млн токенов/сутки): включается, когда у Groq кончился минутный или суточный лимит (~200 тыс. токенов на модель)	Когда лимит Groq исчерпан, ИИ-функции честно пишут «дневной лимит исчерпан»
TAVILY_API_KEY	Быстрый веб-поиск отзывов и статей со сниппетами (бесплатно, без карты)	Поиск идёт через browser_search Groq — ~35 тыс. токенов за сессию
MAPBOX_TOKEN	Второй геокодер + альтернативные изохроны	Карта работает (MapLibre + OpenFreeMap, без ключа); координата помечается «только один источник»
BRAVE_API_KEY	Поиск обсуждений на форумах и офиц. страниц	Работает только Reddit через PullPush
FLICKR_API_KEY	Дополнительные фото под CC-лицензиями	Только Wikimedia Commons
REDDIT_CLIENT_ID + REDDIT_CLIENT_SECRET	Официальный Reddit API (бесплатное приложение типа script) для блока «Голоса студентов»; без него используется архив PullPush, который часто отвечает 429	Меньше обсуждений; блок честно пишет, что найдено недостаточно
OPENROUTESERVICE_API_KEY	Изохроны пешей доступности	Зона не рисуется (и не подменяется кругом)
YOUTUBE_API_KEY	Видео с проверенного офиц. канала	Блок видео пуст

Базовая карта — MapLibre GL + OpenFreeMap, без API-ключа. Это сознательный выбор: демонстрация не должна падать из-за чужой квоты во время защиты.

---

3. Тестовый сценарий для жюри

Сценарий рассчитан на то, что вы введёте вуз, которого нет в нашем демо-видео.

Шаг 1. Любой незнакомый вуз. Введите на главной, например, Universität Heidelberg, Kyoto University или МГУ. Поиск понимает кириллицу, короткие аббревиатуры (MIT, NYU) и локальные написания. Вуз выбирается вручную — первый результат не подставляется автоматически, потому что одноимённых организаций много.

Шаг 2. Галерея — первое, что вы увидите. Фильтры слева переключают 8 разделов кейса + «Требует проверки». Под каждым фото сразу видны автор, лицензия (ссылкой на её условия) и ссылка на источник.

Шаг 3. Нажмите «Проверить источник» на любом кадре. Откроется паспорт: категория, статус, откуда найден файл, автор, лицензия, дата загрузки и дата съёмки (это разные даты), SHA-1, перцептивный хеш, вердикт визуального классификатора и — главное — согласуются ли две независимые проверки.

Шаг 4. Проверьте честность пустот. Прокрутите до «Полнота источников». Ноль в разделе подписан либо «Проверено — материалов не найдено», либо «Не проверено: источник был недоступен». Это разные утверждения, и мы их не смешиваем.

Шаг 5. Проверьте, что мы не выдаём город за кампус. Откройте фильтр «Город» — эти кадры имеют статус «Городской контекст» и явную пометку, что связь с кампусом не утверждается.

Шаг 6. Два вуза одного города. Соберите Nazarbayev University, затем в блоке «Сравнить покрытие» найдите Astana IT University. Общая городская фотография корректно принадлежит обоим профилям (составной ключ (ror_id, asset_id) в БД). В таблице сравниваются все 8 разделов, и ноль из-за упавшего источника подписан отдельно.

Шаг 7. Отказ источника. Нажмите «Обновить данные» несколько раз подряд. Wikimedia ответит 429; профиль станет partial, предыдущая сохранённая версия останется доступной, и сервис скажет, что именно не успел проверить.

---

4. Стек и архитектура

Backend: Python 3.11, FastAPI, httpx (async), SQLite, Pillow (перцептивные хеши). Frontend: ванильный JS без фреймворка и сборщика, MapLibre GL JS, COBE (глобус). Никакого npm-бандла — страница отдаётся статикой. Хранилище: SQLite (профили, материалы, кэш источников, журнал событий).

Поиск по названию
  └─ ROR v2 + локальные синонимы/транслитерация  ──> institution_id (ROR ID)
       │  (идентичность: город, страна, алиасы, домен, Wikidata QID)
       ▼
  Сбор кандидатов (параллельно, у каждого адаптера свой таймаут и учёт отказа)
       ├─ Wikidata search (haswbstatement): здания вуза (P361/P137/P127) с фото и типом P31  ← категория по типу; SPARQL — запасной путь
       ├─ Commons depicts: haswbstatement:P180=<вуз|здания>                 ← «на фото изображено»
       ├─ Commons geosearch у точки кампуса (P625) — только вместе с названием вуза/здания
       ├─ Wikimedia Commons: категория вуза + подкатегории (без коллекций/карт/сканов, ≤6 файлов из одной)
       ├─ Commons search: визуальные запросы по названию
       ├─ Wikipedia (en/ru): изображения статьи, если Commons беден
       ├─ Wikidata P18: официальное изображение
       ├─ Flickr: поиск по CC-лицензиям (опционально)
       └─ Отдельно: поиск по городу — это ДРУГОЕ утверждение
       ▼
  Фильтр лицензии  ──> только открытые лицензии (CC0 / CC BY / CC BY-SA / PD / GFDL); остальное отбрасывается и считается
       ▼
  Слой 1: текстовая классификация
       (название + описание + провенанс подкатегории; стоп-слова событий;
        по умолчанию НЕ «кампус», а «unknown»)
       ▼
  Дедупликация: SHA-1 (точные копии) + dhash/Hamming≤5 (визуально похожие)
       ▼
  Слой 2: визуальная классификация (Groq qwen3.8 или xAI Grok; миниатюры 330 px
          уходят base64 мозаикой 2×2 — 4 фото за запрос; при 429 проверка
          останавливается и профиль сообщает, сколько кадров не проверено)
       ├─ «не место» ──────────> кандидат снимается с публикации
       ├─ «город, не кампус» ──> переносится в раздел «Город»
       ├─ совпало с текстом ───> основание добавляется, статус НЕ повышается
       └─ РАСХОЖДЕНИЕ ─────────> статус понижается до «не подтверждено»
       ▼
  evidence[] + evidence_level (число независимых подтверждений) у каждого кадра
       ▼
  Снимок профиля: complete | partial + состояние каждой из 8 категорий
  (параллельно /preview отдаёт первые лицензированные кадры из Wikidata за ~3 с)
       ▼
  SQLite: profiles + assets(ror_id, id) + source_events + research_cache
       ▼
  Одностраничный UI: галерея → описание по источникам → полнота → карта → сравнение

Файлы:

Файл	Ответственность
app/main.py	HTTP API, бюджет времени, объединение одинаковых запросов, кэш
app/pipeline.py	Сбор кандидатов, текстовая классификация, дедупликация, описание
app/vision.py	Независимая визуальная классификация и правила согласования слоёв
app/integrations.py	Адаптеры внешних API: таймаут, кэш, rate limit, учёт отказов
app/atlas.py	География: перекрёстная проверка координат, границы OSM, изохроны
app/discovery.py	Поиск и ранжирование организаций, транслитерация, пагинация
app/db.py	Схема SQLite и миграция
app/voices.py	Поиск публичных обсуждений + сводка со ссылками
scripts/benchmark.py	Замер реального времени ожидания на выборке вузов

Ключевые архитектурные решения:

• Каждый адаптер обязан вернуть: идентификатор, лицензию, дату, основание связи с вузом, и — при отказе — состояние отказа. Источник, который этого не даёт, не подключается.
• Отказ не стирает данные: если обновление упало, показывается предыдущий сохранённый профиль с явной пометкой.
• Один процесс, один uvicorn worker: rate limiter Wikimedia и объединение одновременных запросов работают в пределах процесса.

---

5. Как принимается решение по каждому кадру

1. Идентичность. ROR ID — стабильный идентификатор организации. Пользователь выбирает вуз сам, из списка с городом и страной.
2. Лицензия — жёсткий фильтр. Файл без явно указанной лицензии не попадает в галерею ни при каких условиях.
3. Текстовый слой. Название файла, описание и провенанс подкатегории. Здесь исправлен главный дефект: раньше campus был категорией по умолчанию, поэтому наградные знаки, концерт, заседание сената и выпускной попадали в «кампус». Теперь по умолчанию — unknown, а список стоп-слов событий (en/ru/et/kk) запрещает общую догадку «кампус» для кадра, в названии которого описано событие, а не место.
4. Дедупликация. SHA-1 ловит точные копии, dhash по миниатюре — визуально похожие (Hamming ≤ 5). Раньше хеширование молча не выполнялось вообще (миниатюры Commons отдаются с thumb.wikimedia.org, а проверка хоста этого не знала), и 0 дублей означало «не проверяли». Теперь пользователю показывается, сколько кандидатов реально захешировано.
5. Визуальный слой. Grok vision получает только те кадры, что уже прошли фильтр лицензии, — квота не тратится на то, что мы всё равно не опубликуем. Ответ модели ограничен фиксированным словарём сцен; свободный текст модели игнорируется. Результат кэшируется по asset_id.
6. Согласование. Если слои расходятся — статус понижается. Модель с низкой уверенностью не может быть единственным основанием ни опубликовать, ни удалить кадр.
7. Описание кампуса (требование 7 кейса) собирается только из найденного: какие объекты имеют лицензированное фото, за какие годы, сколько кадров с геотегами, чего не нашли и чего не успели проверить. Маркетинговая генерация без источников отсутствует как класс.

---

6. Источники, API и AI — полный список

Обязательные (работают без ключа)

Источник	Назначение	Лицензия/условия
ROR API v2	Идентичность организации, алиасы, город, домен	CC0, без ключа
Wikidata	Commons-категория P373, координата P625, студенты P2196, канал P2397, изображения P18/P8517/P3451/P5775	CC0, без ключа
Wikidata Search API (haswbstatement) + Query Service как запасной путь	Здания и объекты вуза с фото и типом P31; факты вуза (тип, объединения, руководитель, девиз, адрес, сотрудники, эндаумент)	CC0, без ключа
Wikimedia Commons	Файлы, метаданные прав, структурированные данные depicts (P180), геопоиск	Лицензия у каждого файла своя; требуется корректный User-Agent
Openverse API	Открытые фото (в основном Flickr) с автором и ссылкой на первоисточник; берутся только лицензии CC BY, CC BY-SA, CC0, PDM; название вуза обязано быть в названии или тегах, категория — только из названия	Без ключа: 20 запросов/мин и 200/сутки; ответы кэшируются на 24 ч
Wikipedia REST summary	Блок «Об университете»: краткое описание (ru, иначе en) с атрибуцией CC BY-SA	Без ключа
GDELT DOC 2.0	«В новостях»: заголовки за 12 месяцев, где вуз назван в заголовке; только ссылки	Без ключа; не чаще 1 запроса в 5 с, кэш 6 ч; часто отвечает 429 — тогда блок скрыт
Официальные виджеты YouTube / Instagram / TikTok

AI-компоненты

Модель / сервис	Где используется	Что именно делает	Границы
Groq vision, qwen/qwen3.8-27b (по умолчанию) или Grok vision (xAI) при наличии GROK_API_KEY	app/vision.py	Смотрит на изображение и называет тип места из фиксированного словаря (кампус снаружи, общежитие, аудитория, библиотека, лаборатория, спорт, студенческая жизнь, город-не-кампус, не относится)	Никогда не определяет, какой это вуз — только вид места. Ответ вне словаря отбрасывается. Низкая уверенность не даёт права ни публиковать, ни удалять
Groq, openai/gpt-oss-20b (ИИ-разбор подписей)	app/triage.py	Один пакетный запрос на профиль: читает только заголовок и описание файла и отвечает на два закрытых вопроса — о чём текст (этот вуз / другая организация / человек или событие / город / неясно) и какой тип места назван. Работает на любом языке (эстонский «ühiselamu» → общежитие, японский 図書館 → библиотека)	Не считается независимым подтверждением — модель читает те же слова, что и человек, только лучше. Может заполнить unknown и понизить подпись о другой организации или человеке; не повышает достоверность; структурированное подтверждение (Wikidata, depicts) она не отменяет. Словарь ответов закрыт, ответ вне словаря отбрасывается, вердикты кэшируются
Groq, openai/gpt-oss-20b	app/voices.py	Нейтральная сводка только по переданным фрагментам публичных постов	Каждый вывод обязан ссылаться на номера источников; вывод без ссылки отбрасывается
Groq compound-mini (web search)	app/voices.py	Поиск обсуждений	Принимаются только URL из результатов инструмента; ссылки, придуманные моделью в тексте, игнорируются (есть регрессионный тест)

Лимит vision честно ограничен. Бесплатный Groq даёт ~7000 входных токенов в минуту, а одно изображение стоит ~1600–1800 токенов независимо от размера. Поэтому 4 миниатюры склеиваются в одну мозаику 2×2 (≈1600 токенов на четыре кадра) и получают четыре независимых вердикта. Вердикты кэшируются на 30 дней по asset_id; при исчерпании квоты профиль пишет «проверено N из M».

Ни одна модель не генерирует изображения, не описывает кампус «своими словами» и не выставляет оценок вузу.

Опциональные (по ключу)

Источник	Назначение
Mapbox	Второй геокодер для перекрёстной проверки координаты; альтернативные изохроны
openrouteservice	Изохроны пешей/вело доступности
Flickr	Фото с CC-лицензиями (только id 4,5,9,11,12)
Brave Search	Ссылки на официальные страницы и форумы
YouTube Data API	Видео проверенного официального канала

Ключи хранятся только в переменных окружения. .env в .gitignore. В репозитории нет ни одного секрета — проверьте git log -p | grep -i "api_key".

---

7. Готовые компоненты и их происхождение

Компонент	Версия	Происхождение	Лицензия	Как используется
FastAPI	0.115.x	Sebastián Ramírez / open source	MIT	HTTP-слой, автодокументация
uvicorn	0.30.x	encode	BSD-3	ASGI-сервер
httpx	0.27.x	encode	BSD-3	Асинхронные HTTP-запросы к источникам
Pillow	10.4.x	Python Imaging Library fork	HPND/MIT-подобная	Перцептивный хеш (dhash) миниатюр
MapLibre GL JS	5.8.0	MapLibre (форк Mapbox GL JS v1)	BSD-3	Интерактивная карта; поставляется локально в static/vendor/
COBE	bundled	shuding/cobe	MIT	WebGL-глобус на главной; static/vendor/cobe.bundle.mjs
box-loader	—	CSS-анимация загрузки, написана для проекта	—	static/box-loader.css
SQLite	встроен в Python	D. R. Hipp	Public domain	Хранилище

Что написано нами: весь код в app/ и scripts/, весь static/app.js, static/atlas.js, static/globe.js, static/style.css, схема БД, правила классификации и согласования слоёв, промпты.

Использование AI при разработке: код писался совместно с ассистентами (Claude, GPT). Дизайн-направление главной страницы проработано с помощью design-taste-frontend, промпт сохранён рядом с проектом в CAMPUS_TRACE_ASTRA_PROMPT.md. Все архитектурные решения, правила достоверности и формулировки статусов проверены и приняты командой вручную; каждое изменение сопровождается тестом.

Данные OSM-слоёв (data/atlas_nu.json, data/atlas_upenn.json) — снимок открытых данных OpenStreetMap от 16 сентября 2026, каждый объект содержит ссылку на исходный OSM-объект, атрибуция ODbL. Это подтверждает наличие объекта в OSM, а не его официальный статус.

---

8. Производительность: как мы её измеряем

Жюри оценивает полное время: от ввода названия до полезного результата, лимит 30 секунд. Поэтому:

• Замер начинается до запроса в ROR (раньше поиск организации был вне измерения — и цифра получалась красивее реальности).
• Серверный бюджет — PROFILE_BUDGET_SECONDS (по умолчанию 24 с) плюс 3 с страховочного таймаута; остальное оставлено на поиск, передачу и отрисовку.
• Первые кадры приходят отдельно через /api/profiles/{id}/preview (изображения Wikidata вуза и его зданий, один запрос к Commons) и показываются прямо на экране загрузки.
• Бюджет проверяется на каждой дорогой стадии: пагинация Commons, дополнительные поисковые запросы и визуальная классификация пропускаются, если времени не осталось, и профиль честно помечается неполным.
• В ответе есть timings (по стадиям), elapsed_ms и time_to_first_asset_ms.

Замер на выборке вузов

# 1) сервер в отдельном терминале
uvicorn app.main:app --port 8765

# 2) холодный прогон (единственный честный)
python3 scripts/benchmark.py --base http://127.0.0.1:8765 --refresh \
    --out docs/benchmark.json --markdown docs/benchmark.md

Выборка по умолчанию — 15 вузов: Казахстан, Европа, Северная Америка, Азия, Африка, Южная Америка; большие и малые; латиница и кириллица; короткая аббревиатура (MIT); два вуза одного города. Скрипт считает p50/p95 для submit → первое фото и submit → полный профиль, число неполных профилей и число превышений 30 секунд.

Замер на проде (19.09.2026, 10:10 Asia/Almaty) — основной

Стенд: https://campustraceapp.vercel.app (Vercel, функция Python), запросы из Казахстана, --refresh, вузы по очереди, версия пайплайна 0.8.0, бюджет сервера 21 с. Ключей ИИ на проде в момент замера не было, поэтому столбец Vision = 0. 14 из 15 сборок прошли без единого попадания в кэш источников.

Запрос	Определён как	Материалов	Разделов	submit→первое фото	submit→полный профиль	Из кэша источников	Vision	Статус
Nazarbayev University	Nazarbayev University	20	4	8.9 с	8.9 с	0/16	0	complete
Astana IT University	Astana IT University	14	5	6.9 с	6.9 с	0/8	0	complete
Al-Farabi Kazakh National University	Al-Farabi Kazakh National University	12	2	1.5 с	9.7 с	0/16	0	complete
University of Tartu	University of Tartu	40	3	1.3 с	15.8 с	0/20	0	partial
МГУ	Lomonosov Moscow State University	83	5	2.4 с	16.7 с	1/19	0	complete
MIT	Massachusetts Institute of Technology	63	7	2.9 с	13.0 с	0/17	0	complete
University of Pennsylvania	University of Pennsylvania	60	6	2.3 с	13.7 с	0/18	0	complete
Universität Heidelberg	Heidelberg University

Замер: 2026-09-19 10:10:44+0500. Вузов: 15, с материалами: 15, пустых: 0, не найдено в реестре: 0, ошибок: 0, недоступен реестр: 0, неполных профилей: 4. Сборок без единого попадания в кэш источников: 14. Стенд: https://campustraceapp.vercel.app.

submit → первое фото: p50 2180 мс, p95 8936 мс. submit → полный профиль: p50 12979 мс, p95 16693 мс, максимум 16935 мс, превысили 30 с: 0.

Итог: у всех 15 вузов есть фото с открытой лицензией (в среднем 42,8), ошибок нет, ни один вуз не превысил 30 секунд; первое фото — p50 2,2 с; полный профиль — p50 13,0 с, максимум 16,9 с. Сырые строки — docs/benchmark-prod.json.

Предыдущий локальный замер (18.09.2026, 21:14 Asia/Almaty)

Стенд: MacBook, домашняя сеть в Казахстане, локальный сервер с пустой SQLite (кэш источников холодный), --refresh, вузы по очереди. Код — коммит 36790f9, запущенный с REQUEST_TIMEOUT_SECONDS=6 (в самом коммите значение по умолчанию уже 8 с — почему, см. ниже; воспроизвести: REQUEST_TIMEOUT_SECONDS=6 DATABASE_PATH=/tmp/cold.sqlite3 uvicorn app.main:app --port 8766). «Из кэша источников» — сколько ответов внешних API пришло из кэша: это поиск и предпросмотр того же вуза, запущенные браузером одновременно со сборкой. «submit→первое фото» — момент, когда ответил /preview с кадрами (так же, как это видит пользователь); если предпросмотр пуст, первое фото приходит вместе с полным профилем. Vision — сколько кадров проверено по изображению за эту сборку (бесплатный лимит Groq — примерно 4 мозаики в минуту).

Запрос	Определён как	Материалов	Разделов	submit→первое фото	submit→полный профиль	Из кэша источников	Vision	Статус
Nazarbayev University	Nazarbayev University	21	4	14.1 с	14.1 с	1/9	8	complete
Astana IT University	Astana IT University	14	5	9.2 с	9.2 с	1/7	0	complete
Al-Farabi Kazakh National University	Al-Farabi Kazakh National University	10	2	23.7 с	23.7 с	0/11	4	partial
University of Tartu	University of Tartu	38	4	5.6 с	26.5 с	0/13	4	complete
МГУ	Lomonosov Moscow State University	0	0	4.3 с	19.1 с	2/12	0	partial
MIT	Massachusetts Institute of Technology	51	6	4.9 с	24.6 с	1/12	4	complete
University of Pennsylvania	University of Pennsylvania	36	3	2.8 с	22.5 с	1/12	4	complete
Universität Heidelberg	Heidelberg University

Замер: 2026-09-18 21:14:38+0500. Вузов: 15, с материалами: 14, пустых: 1, не найдено в реестре: 0, ошибок: 0, недоступен реестр: 0, неполных профилей: 3. Сборок без единого попадания в кэш источников: 5. Стенд: http://127.0.0.1:8766.

submit → первое фото: p50 4648 мс, p95 14093 мс. submit → полный профиль: p50 22208 мс, p95 24621 мс, максимум 26497 мс, превысили 30 с: 0.

Что видно из замера — честно:

• Ни один вуз не превысил 30 с, ошибок нет. Три профиля помечены partial: часть этапов была пропущена по бюджету времени, и профиль прямо это говорит.
• МГУ собрался пустым. Вуз определён верно, предпросмотр показал 2 кадра, но запрос метаданных Commons не уложился в таймаут 6 с. Профиль не сохраняется в кэш и честно помечен partial. После этого таймаут запроса вернули к 8 с; при повторной сборке МГУ даёт 60 материалов, но в таблицу это не вписано, потому что это уже не холодный замер.
• Предыдущие прогоны на этой же выборке нашли три дефекта, которые исправлены до этого замера: 504 вместо частичного профиля у Tartu, Uppsala и Cape Town; неверный выбор вуза для «MIT», «Universität Heidelberg» и «МГУ»; предпросмотр, стоявший в общей очереди Commons. Сырые строки — в docs/benchmark.json.
• Это замер на одной машине и в одной сети. Прод на бесплатном хостинге будет медленнее из-за холодного старта контейнера.

---

9. Продуктовое решение по Instagram/Threads

Соблазн очевиден: в Instagram и Threads больше «живых» фото кампуса, чем в Wikimedia Commons. Мы сознательно не берём оттуда фотографии, и вот почему:

1. У Instagram и Threads нет публичного API для такого поиска, а у контента нет открытой лицензии на переиздание.
2. Правила кейса прямо запрещают «выдавать стоковые или чужие фотографии за конкретный кампус». Встроить чужой снимок из соцсети в галерею «фото кампуса» — ровно это и есть.
3. Нарушение лицензий источников — отдельный пункт запретов кейса.

Что мы делаем вместо этого. Публичные обсуждения (Reddit, студенческие форумы, студенческие издания) используются как текстовое свидетельство: заголовок, короткая цитата, ссылка на первоисточник и нейтральная сводка. Фотографии оттуда не встраиваются. Для изображений источники остаются лицензионно чистыми: Wikimedia Commons и Flickr с фильтром по CC-лицензиям.

Это сознательный размен recall на правовую чистоту. Если вуз захочет более богатую галерею — «карта пробелов» в профиле показывает, каких именно материалов не хватает, и вуз может передать их под открытой лицензией.

---

10. Роли команды

Заполните перед сабмитом. Кейс требует явного указания ролей; выдумывать их за команду нельзя.

Участник	Роль	Зона ответственности
<ФИО>	Backend / пайплайн достоверности	app/pipeline.py, app/vision.py, правила согласования слоёв
<ФИО>	Frontend / UX	static/, дизайн-система, доступность
<ФИО>	Данные и интеграции	app/integrations.py, лицензии, OSM-слои
<ФИО>	Продукт, презентация, демо	README, слайды, видео, коммуникация с жюри

Контакт для жюри: <email>. Промокод сабмита на aistartify.com: LOCUSCASE1.

---

11. Развёртывание

В репозитории лежат готовые конфигурации; выберите одну.

Vercel (развёрнуто: https://campustraceapp.vercel.app)

vercel.json описывает один сервис FastAPI с точкой входа api/index.py (она создаёт схему SQLite при импорте: на Vercel файловая система только для чтения, кроме /tmp). Деплой: vercel link --yes --project campustrace, затем vercel deploy --prod --yes; репозиторий подключён, поэтому каждый push в main выкатывается сам. Переменные окружения проекта: CAMPUS_TRACE_USER_AGENT, DATABASE_PATH=/tmp/campustrace.sqlite3; GROQ_API_KEY добавляется владельцем вручную (vercel env add GROQ_API_KEY production).

Ограничения этого хоста, о которых нужно знать: кэш SQLite живёт в /tmp каждого инстанса и теряется при холодном старте; внутрипроцессный лимитер Commons и объединение одинаковых запросов действуют в пределах одного инстанса; Openverse отвечает 401 анонимным запросам из дата-центров — фото оттуда включаются после регистрации бесплатного клиента (OPENVERSE_CLIENT_ID/SECRET).

Render (альтернатива, есть бесплатный план)

1. Запушьте репозиторий на GitHub.
2. https://dashboard.render.com/blueprints → New Blueprint Instance → выберите репозиторий. render.yaml подхватится автоматически.
3. В разделе Environment задайте CAMPUS_TRACE_USER_AGENT с реальным контактом. Остальные ключи — по желанию.
4. Дождитесь деплоя, проверьте https://<app>.onrender.com/api/health.

На бесплатном плане инстанс засыпает при простое. Откройте ссылку за 5 минут до защиты, чтобы жюри не попало на холодный старт поверх 30-секундного бюджета.

Fly.io (без засыпания)

fly launch --no-deploy        # подхватит fly.toml
fly volumes create campustrace_data --size 1
fly secrets set CAMPUS_TRACE_USER_AGENT="CampusTrace/0.6 (contact: [email protected])"
fly secrets set GROK_API_KEY="..."   # опционально
fly deploy

Railway

New Project → Deploy from GitHub repo. railway.json укажет на Dockerfile. Переменные задаются во вкладке Variables.

Любой Docker-хост

docker build -t campustrace .
docker run -p 8000:8000 -v campustrace-data:/data \
  -e CAMPUS_TRACE_USER_AGENT="CampusTrace/0.6 (contact: [email protected])" \
  campustrace

Чек-лист после деплоя:

• /api/health отвечает {"ok": true}
• Главная открывается, глобус рендерится
• Поиск незнакомого вуза возвращает результаты
• Профиль собирается, фото грузятся
• /api/integrations показывает, какие ключи реально подключены
• Ссылка открывается с телефона и из инкогнито
• Ссылка будет жива до объявления результатов

---

12. Тесты

python3 -m unittest discover -s tests -v   # 88 тестов
python3 -m compileall -q app
node --check static/app.js

Тесты закрывают именно те свойства, которые легко потерять при доработке:

• городской кадр никогда не публикуется как кампус;
• файл без лицензии не публикуется;
• перцептивный хеш действительно считается для thumb.wikimedia.org (регрессия на реальный дефект);
• визуально близкие кадры схлопываются;
• слова о событии не дают категорию «кампус»;
• расхождение двух слоёв понижает статус, а не переписывает категорию;
• неуверенная модель не может в одиночку удалить кадр;
• модель, ответившая вне словаря, игнорируется;
• пагинация Commons реально ходит по cmcontinue;
• короткая аббревиатура (MIT) находится, но не срабатывает внутри слова Summit;
• описание кампуса не выдумывает объектов и разделяет «пусто» и «источник упал»;
• геокодеры, расходящиеся на десятки километров, не дают «подтверждённую» точку;
• изохрона не рисуется без ключа маршрутизации;
• отказ источника не стирает сохранённый профиль;
• блок «Голоса студентов» никогда не возвращает встраиваемое изображение — правовая политика проверяется тестом, а не обещанием в README;
• тип здания из Wikidata задаёт категорию; факультет или спутник не считаются местом;
• проходят только открытые лицензии (в том числе для структурированных источников);
• геотег сам по себе не делает кадр «кампусом»;
• сканы карт и коллекции библиотеки не попадают в «библиотеку» (регрессия Kyoto);
• портреты и визиты не считаются видом кампуса;
• несогласная визуальная проверка не засчитывается как подтверждение;
• мозаика 2×2 разбирается по плиткам независимо, битая плитка — «не проверено», а не догадка.

---

13. Ограничения — честно

• Мы не доказываем место съёмки. Категория Commons — свидетельство связи, не геодоказательство. Визуальный классификатор определяет тип места, а не адрес. Максимальный статус — «вероятно».
• Точность не измерена независимыми разметчиками. Ни один процент точности в этом README не указан, потому что для него нужна ручная разметка двумя проверяющими на выборке вузов. Методика такого замера описана в аудите проекта; сам замер — следующий шаг.
• Охват ROR не равен списку всех вузов мира — реестр ориентирован на организации, связанные с исследованиями. Для небольших колледжей результатов может не быть.
• Полнота зависит от Wikimedia. У многих вузов в Commons просто нет фотографий общежитий и аудиторий. Пустой раздел у нас — это факт о доступности открытых материалов, а не о вузе.
• Wikidata P2196 (число студентов) может быть без года или без первичного источника; мы показываем год и ссылку и предупреждаем об этом.
• Публикации OpenAlex — это не число студентов и не качество обучения.
• Один процесс. Для настоящей нагрузки нужны PostgreSQL, общий распределённый rate limiter, очередь и наблюдаемость.
• OSM-слои построены вручную для трёх вузов (NU, UPenn, AITU). Для остальных карта показывает точку с указанием её точности и происхождения.

---

14. Чек-лист правил кейса

Запрещено кейсом	Как это исключено у нас
Выдавать стоковые/чужие фото за конкретный кампус	Кадр без лицензии не публикуется; городские кадры имеют отдельный статус и прямую пометку; фото из соцсетей не встраиваются вообще
Скрывать ручной подбор под видом автопоиска	Ручных подборок фото нет. Единственные ручные данные — OSM-слои трёх вузов и локальные синонимы поиска; и то и другое описано выше
Подделывать источники, скорость, достоверность	Клик по любому фото открывает первоисточник; таблица скорости — живой замер с датой, стендом и долей ответов из кэша; «показатель достоверности» — не процент, а уровень (высокая / средняя / низкая), вычисляемый по числу независимых видов подтверждений; понижается при расхождении текста и изображения, неопределённой категории и городском контексте, никогда не повышается; каждое подтверждение раскрывается ссылкой
Нарушать лицензии источников	Жёсткий фильтр лицензии; атрибуция на карточке и в паспорте; соблюдение лимита Nominatim и требований User-Agent; ODbL-атрибуция карт
Публиковать секретные ключи	.env в .gitignore; все ключи только через переменные окружения; в коде нет ни одного литерала ключа

Требование кейса	Состояние
1. Поиск по названию + разрешение неоднозначности	Есть: ROR + локальные синонимы, транслитерация, пагинация, выбор вручную
2. Кампус, общежитие, аудитории, библиотека, город	Есть; полнота ограничена доступностью открытых материалов, пробелы показаны явно
3. Автоматическая классификация	Есть: два независимых слоя — текстовый и визуальный
4. Удаление одинаковых, похожих и нерелевантных	Есть: SHA-1 + dhash + снятие нерелевантных визуальным классификатором
5. Проверка связи фото с вузом/объектом/городом	Есть на уровне оснований и статусов; геодоказательства не заявляются
6. Кликабельный источник и дата	Есть: источник, автор, лицензия, дата загрузки и дата съёмки раздельно
7. Краткое описание кампуса из источников	Есть: собирается только из найденных объектов, со ссылками
8. Фильтры общежитие/спорт/лаборатории/студенческая жизнь	Есть, плюс отдельный раздел «Требует проверки»

---

15. Что записать в демо-видео

Ограничение — 3 минуты. Сценарий (показывать экран, говорить коротко):

Время	Что показать	Что сказать
0:00–0:20	Главная, глобус	«Абитуриент выбирает вуз по картинкам, но не знает, чьи это картинки и тот ли это кампус. CampusTrace показывает только то, что может подтвердить источником»
0:20–0:50	Ввод незнакомого вуза, сборка профиля	«Поиск понимает кириллицу и аббревиатуры. Организация выбирается вручную — одноимённых много. Полная сборка укладывается в бюджет 30 секунд»
0:50–1:25	Галерея, фильтры, карточка с автором и лицензией	«Восемь разделов кейса. Автор и лицензия — сразу под кадром, а не спрятаны»
1:25–2:00	«Проверить источник» → паспорт	«Вот главное: две независимые проверки — текст источника и визуальный классификатор. Если они расходятся, мы понижаем уверенность, а не выбираем удобный вариант»
2:00–2:25	Полнота источников: пустой раздел и раздел с упавшим источником	«Ноль ноль рознь. "Проверено, не нашли" и "источник не ответил" — разные утверждения, и мы их различаем»
2:25–2:45	Фильтр «Город» + сравнение двух вузов одного города	«Городской кадр никогда не выдаётся за кампус. Сравниваются все восемь разделов, а ноль из-за отказа источника подписан отдельно»
2:45–3:00	Финал	«Мы не доказываем место съёмки — по открытым данным это невозможно. Мы показываем, что именно проверено, а что нет. Это и есть продукт»

Технически: экран 1920×1080, запись без звука окружения, голос поверх, показывать реальный развёрнутый сайт (не localhost), не ускорять таймер сборки. Вуз в видео должен отличаться от того, который вы покажете на защите.

---

Приложение: маршруты API

GET /api/health
GET /api/integrations
GET /api/search/suggest?q=НУ&page=1
GET /api/institutions?q=Nazarbayev%20University
GET /api/profiles/{ror_id}            # ?refresh=true — принудительная пересборка
GET /api/profiles/{ror_id}/preview    # первые лицензированные кадры из Wikidata за ~3 с
GET /api/profiles/{ror_id}/ask?q=...  # ответ только по источникам профиля, с номерами ссылок
GET /api/profiles/{ror_id}/news       # заголовки GDELT, где назван вуз
GET /api/profiles/{ror_id}/extras     # кэшируется на час
GET /api/profiles/{ror_id}/student-voices
GET /api/assets/{asset_id}?ror_id={ror_id}
GET /api/atlas/{ror_id}
GET /api/atlas/{ror_id}/isochrone?mode=walking&minutes=15
GET /api/compare?left={ror_id}&right={ror_id}

Полезные поля ответа профиля: evidence и evidence_level у каждого кадра, rejected_license_count, institution.buildings, profile_status, category_status, unclassified_count, vision, rejected_by_vision, timings, time_to_first_asset_ms, duplicate_count, license_eligible_count, warnings, source_events, from_cache.