# Vi — инструкция по работе

Vi — локальная когнитивная сущность с нейросетью с нуля (без ChatGPT/TensorFlow).  
Веб-панель: **http://127.0.0.1:8080**

---

## Запуск

```powershell
cd d:\Project\Vi
.\.venv\Scripts\python -m vi.main
```

Откройте в **Chrome или Edge** (не во встроенном браузере IDE — камера там часто не работает).

После обновления кода: **Ctrl+F5** на странице.

---

## Карта панели

| Область | Что показывает |
|---------|----------------|
| **Шапка** | Стадия развития, словарь, память, граф, одобрения, цели, приложения |
| **Полоска состояния** | Поведение, мета, доминирующий регион мозга, сон, нейросеть, **модальность**, **сенсоры**, **WM** (рабочая память) |
| **Камера Vi** | Live-превью (появляется при включении камеры) |
| **Диалог** | Чат с Vi; бейджи: поведение · мета · регион · fusion |
| **Мозг Vi** | SVG-карта регионов, латеральная конкуренция, внимание |
| **Сайдбар → Обучение** | Научить, связать стимул→реакцию, одобрения, цели |
| **Сайдбар → Система** | Сон, нейросеть, камера/мик/файлы, запуск приложений |
| **Сайдбар → Память** | Поиск по нейро-вектору, эпизодическая память |

---

## Как правильно взаимодействовать

### 1. Текстовый диалог (основной режим)

1. Напишите сообщение в **Диалог** → Enter.
2. Vi обрабатывает через: память → поведение → **fusion-мозг** → генерацию ответа.
3. Смотрите бейджи под ответом:
   - **behavior** — что решила префронтальная область (dialogue, web_search, …)
   - **meta** — метакognition (уверенность, пробел в знаниях)
   - **fusion / vision / text** — какая модальность использовалась

**Важно:** Vi не LLM. Ответы строятся из **вашего обучения** + нейросети + памяти. Сначала научите базовым фактам.

### 2. Обучение (сайдбар → Обучение)

**Научить:**
- **Концепт** — имя сущности (необязательно)
- **Знание** — что запомнить
- **Ответ Vi** — как она должна отвечать (необязательно)

**Связать стимул → реакцию:**  
Пары вроде «привет» → «здравствуй» тренируют ассоциации в словаре и нейросети.

### 3. Зрение и слух (multimodal fusion)

Vi «видит» и «слышит» через **сенсорный буфер** (TTL ~30 сек). Пока буфер активен, чат идёт в режиме **fusion**.

#### Файл (рекомендуется для начала)
1. **Система → Восприятие**
2. Загрузите **Изображение** (любой формат — браузер конвертирует в PNG)
3. Загрузите **Аудио** (WAV; MP3 лучше через внешний конвертер)
4. Спросите в чате: *«что ты видишь?»*, *«что слышишь?»*

#### Камера и микрофон
1. **Система → Включить камеру / микрофон**
2. Превью появится **над чатом** (блок «Камера Vi»)
3. Кадры/звук идут в буфер автоматически (~1 кадр/с, ~1 чанк/1.5 с)
4. **Выключите** камеру/микрофон, когда не нужны — буфер сбрасывается, чат снова **text**

**Правила:**
- Не держите камеру включённой без необходимости (нагрузка на CPU)
- Открывайте панель в **127.0.0.1**, не по IP в сети
- Windows: Параметры → Конфиденциальность → Камера/Микрофон → разрешить браузеру

### 4. Одобрения и цели

Vi сама предлагает знания (веб-поиск, диалог).  
**Одобрения** и **Автономные цели** — очередь на ваше решение ✓ / ✗.

### 5. Сон (консолидация)

- Автоматически каждые ~25 тиков при ≥5 эпизодах
- Вручную: **Система → Запустить offline replay**
- Replay тренирует гиппокамп на парах: диалог, teach, vision, audio
- В карточках сна: **Replay по типам** (dialogue, vision, teach…)

### 6. Checkpoint'ы

**Система → Нейросеть:**
- **Сохранить checkpoint** — снимок весов в `data/checkpoints/`
- **Загрузить последний** — восстановить из `latest.json`
- Список snapshots — кнопка **Загрузить** у каждого

### 7. Граф знаний

**Память → Граф знаний** — SVG-карта узлов и связей. Обновляется после обучения.

### 8. Веб-поиск и Shell

**Система → Действия:**
- **Веб-поиск** — DuckDuckGo (Vi использует то же при `behavior=web_search`)
- **Shell** — команда на вашем ПК (с подтверждением). Используйте с осторожностью.

### 9. Поиск памяти

**Память → Поиск памяти** — семантический поиск с учётом активных сенсоров (fusion).  
Полезно после обучения и загрузки изображений/аудио.

### 10. Если Vi запомнила неправильно

**Память → Управление памятью**

Vi хранит знание в нескольких слоях. Чтобы переобучить, часто нужно очистить 2–3 из них:

| Слой | Файл | Зачем чистить |
|------|------|---------------|
| Семантическая | `vector_store.json` | Всплывает в ответах (memory_hits) |
| Словарь | `vocabulary.json` | Связи слов влияют на генерацию |
| Эпизоды | `episodic_log.jsonl` | **Сон replay снова тренирует ошибки** |
| Граф | `knowledge_graph.json` | Связи концептов |
| Рабочая (WM) | `working_memory.json` | Контекст последних ходов |
| Нейросеть | `neural_state.json` | Веса — только checkpoint или ручное удаление файла |

**Порядок действий:**

1. **Поиск памяти** → **Удалить** неправильную запись
2. **Забыть связь** — стимул и (опционально) неправильная реакция
3. Очистить **Эпизоды** (иначе offline replay вернёт ошибку)
4. **Обучение → Научить / Связать** заново

Если не помогает — **Загрузить checkpoint** до ошибки или удалить `data/neural_state.json` и перезапустить Vi.

### 11. Консультация с вами (когда Vi не знает)

Если в памяти нет подходящего знания (мета `unknown` или слабое `partial`), Vi:

1. **Не выдумывает** ответ — говорит, что не знает
2. Добавляет вопрос в **Одобрения** (источник `consultation`)
3. Может создать **Автономную цель** «изучить тему»

**Как ответить Vi:**

| Способ | Действие |
|--------|----------|
| Быстро | **Одобрения** → ✓ → введите правильный ответ |
| Точно | **Обучение → Научить**: знание = вопрос, «Ответ Vi» = ваш ответ |
| Отклонить | ✗ если вопрос некорректный |

**Настройки** (`.env`):

```env
VI_CONSULT_SUPERVISOR=true
VI_CONSULT_ON_PARTIAL=true
VI_CONSULT_PARTIAL_BELOW=0.58
```

`VI_CONSULT_SUPERVISOR=false` — Vi снова будет пытаться ответить сама.

### 12. Загрузка книг

**Обучение → Загрузить книгу** — файлы `.txt`, `.md`.

- Текст делится на фрагменты (~900 символов) и попадает в **семантическую память**
- В **графе знаний** появляется сущность типа `book`
- Большие книги: лимит `VI_BOOK_MAX_CHUNKS=400` (настраивается в `.env`)

После загрузки спрашивайте по содержанию — Vi ищет по фрагментам (не дословно, по смысловой близости).

### 13. Интернет при консультации

Когда Vi **не знает** ответ:

1. Автоматически ищет в **DuckDuckGo** (если `VI_CONSULT_WEB_SEARCH=true`)
2. Для длинных ответов может **скачать текст** первой страницы (`VI_CONSULT_WEB_FETCH=true`)
3. В **Одобрения**:
   - **Искать в интернете** — повторный поиск + загрузка страницы
   - **Из интернета** — запомнить найденный текст как ответ
   - **Свой ответ** — ваш вариант вручную

```env
VI_CONSULT_WEB_SEARCH=true
VI_CONSULT_WEB_FETCH=true
VI_CONSULT_WEB_FETCH_CHARS=6000
VI_BOOK_CHUNK_SIZE=900
VI_BOOK_MAX_CHUNKS=400
```

---

## Что означают индикаторы

| Индикатор | Значение |
|-----------|----------|
| `text` | Только текст |
| `fusion` | Текст + активное зрение и/или слух из буфера |
| `vision` / `audio` | Одна модальность в буфере |
| WM N | Слотов в персистентной рабочей памяти |
| 👁 / 🎤 | Активные сенсоры в буфере |
| motion N% | Vi заметила движение между кадрами |
| `unknown` / `partial` | Vi не уверена — может перейти в **консультацию** |
| `consult_supervisor` | Vi спрашивает вас, не угадывает |

---

## API (справочник)

Все перечисленные endpoint'ы доступны и из UI, и напрямую через HTTP.

| Endpoint | Назначение |
|----------|------------|
| `POST /api/chat` | Диалог |
| `POST /api/teach`, `/api/train` | Обучение |
| `POST /api/perceive/vision`, `/audio` | Файл → память + обучение |
| `POST /api/perceive/vision/stream`, `/audio/stream` | Поток с камеры/мика |
| `POST /api/sensory/clear` | Сброс буфера (вызывается при выключении сенсоров) |
| `GET /api/sensory/status` | Состояние буфера |
| `GET /api/brain/viz` | Данные для карты мозга |
| `GET /api/memory/search?q=` | Поиск памяти (нейро-вектор) |
| `GET /api/memory/items` | Список записей семантической памяти |
| `DELETE /api/memory/{id}` | Удалить одну запись |
| `POST /api/memory/forget` | Забыть связь в словаре |
| `POST /api/memory/clear` | Очистить выбранные слои |
| `GET /api/graph` | Граф знаний (JSON + визуализация в UI) |
| `GET /api/neural/checkpoints` | Список checkpoint'ов |
| `POST /api/neural/checkpoint/load` | Загрузка checkpoint |
| `POST /api/actions/search` | Веб-поиск (есть в UI) |
| `POST /api/actions/shell` | Shell (есть в UI) |

---

## Известные ограничения

1. **Vi не понимает картинки «как человек»** — видит вектор признаков; «узнаёт» только то, чему научили.
2. **Речь** — GRU-декодер + растущий словарь, не готовые фразы из интернета.
3. **JPEG на сервере** — best-effort; надёжнее PNG через браузер.
4. **Stream-эпизоды** не пишутся в episodic log (только буфер) — полная запись при загрузке файла.
5. **Символический PFC** и **нейронный prefrontal** — разные системы, связаны эвристически.
6. **GPU** — задел в checkpoint, пока CPU pure Python.

---

## Типичный сценарий «с нуля»

1. Запустить Vi, открыть панель.
2. **Научить:** «меня зовут …», «Vi это …», ответ Vi.
3. **Связать:** «привет» → «привет».
4. Поговорить в чате — смотреть карту мозга.
5. Загрузить фото → спросить «что видишь?» (бейдж **fusion**).
6. Одобрить предложенные знания.
7. **Сон** — консолидация.
8. **Checkpoint** — сохранить прогреss.

---

## Данные на диске

```
data/
  vocabulary.json      — словарь
  vector_store.json    — семантическая память
  knowledge_graph.json — граф
  episodic_log.jsonl   — эпизоды
  working_memory.json  — рабочая память (между перезапусками)
  neural_state.json    — веса
  brain_state.json     — GRU-состояние
  sleep_state.json     — сон
  checkpoints/         — снимки
```

---

## Если что-то сломалось

| Проблема | Решение |
|----------|---------|
| Чат не отвечает при камере | Выключить камеру/мик; Ctrl+F5; перезапуск сервера |
| Превью камеры — иконка | Открыть в Chrome/Edge на 127.0.0.1; проверить доступ камеры в Windows |
| Старый UI | Ctrl+F5 или приватное окно |
| Vi «бредит» | Больше обучения; меньше ожиданий от newborn-стадии |

---

*Версия инструкции: соответствует fusion, SensoryBuffer, thread pool API, GRU-декодеру.*