@iola_adm/iola-cli 0.2.1 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iola_adm/iola-cli",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "CLI и AI-агент городского округа Йошкар-Ола.",
   "license": "MIT",
   "homepage": "https://github.com/adm-iola/iola-cli#readme",

package/src/cli.js

@@ -6695,7 +6695,7 @@ async function aiAsk(args, context = {}) {
   const historyEnabled = !options.bare && !options["no-history"] && isFeatureEnabled("sqlite-history");
   const sessionId = historyEnabled && isFeatureEnabled("sessions") ? ensureSessionForAsk(options, providerConfig, question) : null;
   const history = context.history || (sessionId ? getSessionAiHistory(sessionId) : []);
-  const directAnswer = buildDirectDataAnswer(question, dataContext);
+  const directAnswer = await buildDirectDataAnswer(question, dataContext);
   if (directAnswer) {
     if (historyEnabled) {
       recordAskHistory({ question, answer: directAnswer, providerConfig, dataContext, error: "", sessionId });
@@ -6758,10 +6758,12 @@ async function aiAsk(args, context = {}) {
   return answer;
 }
 
-function buildDirectDataAnswer(question, dataContext) {
+async function buildDirectDataAnswer(question, dataContext) {
   const normalized = question.toLocaleLowerCase("ru-RU");
   const requestedFields = detectDirectDataFields(normalized);
   if (requestedFields.length === 0) return "";
+  const educationAnswer = await buildDeterministicEducationAnswer(question, requestedFields);
+  if (educationAnswer) return educationAnswer;
   const rows = [
     ...dataContext.schools.map((item) => ({ layer: "schools", layerName: "школы", ...item })),
     ...dataContext.kindergartens.map((item) => ({ layer: "kindergartens", layerName: "детские сады", ...item })),
@@ -6791,6 +6793,140 @@ function detectDirectDataFields(normalizedQuestion) {
   return [...new Set(fields)];
 }
 
+async function buildDeterministicEducationAnswer(question, requestedFields) {
+  const normalized = String(question || "").toLocaleLowerCase("ru-RU");
+  const layer = /(сад|детсад|детск\w*\s+сад|садик)/iu.test(normalized)
+    ? "kindergartens"
+    : /(школ|сош|лице|гимнази)/iu.test(normalized)
+      ? "schools"
+      : "";
+  if (!layer) return "";
+
+  const requests = extractEducationFactRequests(question, requestedFields, layer);
+  if (requests.length === 0) return "";
+
+  const items = normalizeItems(await fetchAllApiItems(`${await getApiBaseUrl()}/${DATASETS[layer].endpoint}`))
+    .map((item) => ({ layer, layerName: layer === "schools" ? "школы" : "детские сады", ...selectPublicSummary(item) }));
+  const answers = [];
+
+  for (const request of requests) {
+    const answer = resolveEducationFactRequest(request, items, layer);
+    if (answer) answers.push(answer);
+  }
+
+  return answers.filter(Boolean).join("\n");
+}
+
+function extractEducationFactRequests(question, requestedFields, layer) {
+  const normalized = String(question || "").toLocaleLowerCase("ru-RU");
+  const segments = splitEducationQuestionSegments(question);
+  const requests = [];
+
+  for (const segment of segments) {
+    const segmentFields = detectDirectDataFields(segment.toLocaleLowerCase("ru-RU"));
+    const fields = segmentFields.length > 0 ? segmentFields : (segments.length === 1 ? requestedFields : []);
+    if (fields.length === 0) continue;
+    const place = detectEducationPlace(segment) || detectEducationPlace(question);
+    const number = extractEntityNumberFromQuestion(segment, layer)
+      || (segments.length === 1 ? extractEntityNumberFromQuestion(question, layer) : "");
+    const hasEntitySignal = Boolean(number || place || /(школ|сош|лице|гимнази|сад|детсад|детск\w*\s+сад|садик)/iu.test(segment));
+    if (!hasEntitySignal) continue;
+    requests.push({ segment, fields, number, place });
+  }
+
+  if (requests.length === 0 && requestedFields.length > 0 && /(школ|сош|лице|гимнази|сад|детсад|детск\w*\s+сад|садик)/iu.test(normalized)) {
+    requests.push({
+      segment: question,
+      fields: requestedFields,
+      number: extractEntityNumberFromQuestion(question, layer),
+      place: detectEducationPlace(question),
+    });
+  }
+
+  return requests;
+}
+
+function splitEducationQuestionSegments(question) {
+  const text = String(question || "").trim();
+  if (!text) return [];
+  return text
+    .split(/\s+(?:и|а также|,|;)\s+(?=(?:кто|какой|какая|адрес|телефон|инн|сайт|почт|email|директ|руковод|завед|где))/iu)
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+function detectEducationPlace(text) {
+  const normalized = normalizeEntityText(text || "");
+  if (/(козьмодемьянск|козьмодемьянск[аеуом]?|козьмодемьянск\w*)/iu.test(normalized)) {
+    return { id: "kozmodemyansk", label: "Козьмодемьянск", locative: "Козьмодемьянске", supported: false, aliases: ["козьмодемьянск", "козмодемьянск"] };
+  }
+  if (/(семеновк|семёновк)/iu.test(normalized)) {
+    return { id: "semenovka", label: "Семёновка", locative: "Семёновке", supported: true, aliases: ["семеновк", "семёновк"] };
+  }
+  if (/(йошкар|йошкар-ола|йошкар ола)/iu.test(normalized)) {
+    return { id: "yoshkar_ola", label: "Йошкар-Ола", locative: "Йошкар-Оле", supported: true, aliases: ["йошкар", "йошкар-ола", "йошкар ола"] };
+  }
+  return null;
+}
+
+function resolveEducationFactRequest(request, items, layer) {
+  const entityLabel = layer === "schools" ? "школу" : "детский сад";
+  if (request.place && !request.place.supported) {
+    return `В текущих открытых данных iola-cli есть данные городского округа Йошкар-Ола. Данных по ${request.place.locative || request.place.label} в этом слое нет, поэтому ответить по этому объекту не могу.`;
+  }
+
+  let candidates = items;
+  if (request.place) {
+    candidates = candidates.filter((item) => itemMatchesPlace(item, request.place));
+  }
+
+  if (request.number) {
+    const exactByNumber = candidates.filter((item) => itemNameHasNumber(item, request.number));
+    if (exactByNumber.length === 0) {
+      if (request.place && candidates.length > 0) {
+        return [
+          `Точную ${entityLabel} № ${request.number} в ${request.place.locative || request.place.label} в открытом слое не нашел.`,
+          `В ${request.place.locative || request.place.label} есть:`,
+          ...candidates.slice(0, 5).map((item) => `- ${getDirectDataItemName(item)}${item.address ? `; адрес: ${item.address}` : ""}${item.inn ? `; ИНН ${item.inn}` : ""}`),
+        ].join("\n");
+      }
+      return `В открытом слое не нашел ${entityLabel} № ${request.number}.`;
+    }
+    candidates = exactByNumber;
+  }
+
+  if (candidates.length === 0) {
+    const placeText = request.place ? ` в ${request.place.locative || request.place.label}` : "";
+    return `В открытом слое не нашел ${entityLabel}${placeText}.`;
+  }
+
+  if (candidates.length > 1 && !request.number) {
+    return [
+      `Нашел несколько подходящих записей${request.place ? ` для ${request.place.locative || request.place.label}` : ""}:`,
+      ...candidates.slice(0, 5).flatMap((item) => [
+        `- ${getDirectDataItemName(item)}`,
+        ...request.fields.map((field) => `  ${formatDirectDataField(field, item)}`).filter(Boolean),
+        `  Источник: слой ${item.layer}, ИНН ${item.inn || "-"}.`,
+      ]),
+    ].join("\n");
+  }
+
+  const item = candidates[0];
+  const lines = request.fields.map((field) => formatDirectDataField(field, item)).filter(Boolean);
+  if (lines.length === 0) return "";
+  return [
+    ...lines,
+    `Источник: слой ${item.layer}, ${getDirectDataItemName(item)}, ИНН ${item.inn || "-"}.`,
+  ].join("\n");
+}
+
+function itemMatchesPlace(item, place) {
+  if (!place) return true;
+  const text = normalizeEntityText(`${item.name || ""} ${item.address || ""} ${item.legal_address || ""} ${item.fns_full_name || ""} ${item.fns_short_name || ""}`);
+  if (place.id === "yoshkar_ola") return /йошкар|йошкар-ола|йошкар ола/u.test(text) && !/семеновк/u.test(text);
+  return place.aliases.some((alias) => text.includes(normalizeEntityText(alias)));
+}
+
 function pickDirectDataItem(question, dataContext, rows) {
   const patterns = dataContext.query?.patterns || extractStructuredPatterns(question);
   const targetLayers = patterns.targetLayers || [];

package/test/smoke-test.js

@@ -84,4 +84,18 @@ if (deletePlan.willKeep.includes("npm package files")) {
   throw new Error("delete dry-run should not keep npm package files");
 }
 
+const multiSchoolAnswer = await runCli(["ask", "Кто директор школы № 2 и адрес школы № 7?", "--profile", "yandexgpt", "--no-history"]);
+assertIncludes(multiSchoolAnswer, "Адамова Наталья Васильевна", "multi school answer");
+assertIncludes(multiSchoolAnswer, "улица Первомайская, дом 89", "multi school answer");
+assertNotIncludes(multiSchoolAnswer, "улица Осипенко, дом 46\nИсточник: слой schools, МБОУ \"Средняя общеобразовательная школа № 7", "multi school answer");
+
+const externalTownAnswer = await runCli(["ask", "Адрес школы № 1 Козьмодемьянска", "--profile", "yandexgpt", "--no-history"]);
+assertIncludes(externalTownAnswer, "Данных по Козьмодемьянске", "external town answer");
+assertNotIncludes(externalTownAnswer, "улица Петрова, дом 15", "external town answer");
+
+const semenovkaAnswer = await runCli(["ask", "Адрес школы № 1 Семеновки", "--profile", "yandexgpt", "--no-history"]);
+assertIncludes(semenovkaAnswer, "Точную школу № 1 в Семёновке", "semenovka answer");
+assertIncludes(semenovkaAnswer, "село Семёновка", "semenovka answer");
+assertNotIncludes(semenovkaAnswer, "улица Петрова, дом 15", "semenovka answer");
+
 console.log("smoke tests passed");

package/wiki/AI-/320/277/321/200/320/276/321/204/320/270/320/273/320/270.md

@@ -29,40 +29,126 @@ iola ask "найди школы на Петрова"
 
 ### YandexGPT
 
-Официальные страницы:
+Для CLI нужны две вещи: API key и ID каталога Yandex Cloud.
+
+Пошаговая настройка:
+
+1. Откройте консоль Yandex Cloud: `https://console.yandex.cloud/`.
+2. Войдите в аккаунт Яндекса.
+3. Если Yandex Cloud попросит создать облако, создайте облако. Название может быть любым, например `iola-cli`.
+4. Откройте каталог внутри облака. Если каталога нет, создайте каталог. Название может быть любым, например `default`.
+5. На верхней панели страницы каталога найдите название каталога и его идентификатор. В нашем примере рядом с `default` был показан ID вида `b1g8...`.
+6. Нажмите кнопку `Копировать` рядом с идентификатором каталога. Это значение будет `YANDEXGPT_FOLDER_ID`.
+7. В левом меню или через поиск сервисов откройте `Identity and Access Management`.
+8. Внутри `Identity and Access Management` откройте раздел `Сервисные аккаунты`.
+9. Нажмите `Создать сервисный аккаунт`.
+10. В поле `Имя` введите понятное имя, например `iola-cli`.
+11. В поле `Описание` можно написать `API-доступ iola-cli к YandexGPT`.
+12. В блоке `Роли в каталоге` нажмите `Добавить роль`.
+13. В поле поиска роли введите `ai.languageModels.user`.
+14. В найденной группе `ai.languageModels` выберите роль `user`. В форме должна появиться роль `ai.languageModels.user`.
+15. Нажмите `Создать`.
+16. После создания откройте созданный сервисный аккаунт `iola-cli`.
+17. На странице сервисного аккаунта нажмите кнопку `Создать новый ключ`.
+18. В выпадающем меню выберите `Создать API-ключ`. Не выбирайте `Создать статический ключ доступа` и не выбирайте `Создать авторизованный ключ`.
+19. В поле `Описание` напишите, например, `iola-cli YandexGPT API key`.
+20. В поле `Область действия` выберите `yc.ai.foundationModels.execute`. Если список пустой, начните вводить это значение в поле фильтра и выберите найденный вариант.
+21. Поле `Срок действия` можно оставить пустым или выбрать дату окончания действия ключа по вашей политике безопасности.
+22. Нажмите `Создать`.
+23. Yandex Cloud покажет `Идентификатор ключа` и `Ваш секретный ключ`. Секретный ключ показывается только один раз.
+24. Скопируйте `Ваш секретный ключ` и сохраните его локально. Это значение будет `YANDEXGPT_API_KEY`.
+25. Сохраните ключ в CLI:
 
-- документация Foundation Models: `https://yandex.cloud/ru/docs/foundation-models/`;
-- аутентификация API: `https://yandex.cloud/ru/docs/ai-studio/api-ref/authentication`;
-- тарифы: `https://yandex.cloud/ru/docs/foundation-models/pricing`.
+```bash
+iola ai key set yandexgpt
+```
+
+CLI попросит ввести:
 
-Для CLI нужны API key и ID каталога Yandex Cloud:
+- `YANDEXGPT_API_KEY` - API-ключ сервисного аккаунта;
+- `YANDEXGPT_FOLDER_ID` - ID каталога Yandex Cloud.
+
+Важно: `Идентификатор ключа` - это не API-ключ для CLI. Для CLI нужен именно `Ваш секретный ключ`. Если закрыть окно создания ключа, секретный ключ больше нельзя посмотреть. В этом случае удалите старый API-ключ и создайте новый.
+
+После сохранения ключа выберите профиль и модель:
 
 ```bash
-iola ai key set yandexgpt
 iola ai setup yandexgpt --model yandexgpt-lite/latest
 ```
 
+Через интерактивное меню:
+
+```text
+/model
+2. Российские AI (YandexGPT/GigaChat)
+1. YandexGPT API
+```
+
+Доступные модели в CLI:
+
+- `yandexgpt-lite/latest` - быстрый и более дешевый вариант;
+- `yandexgpt/latest` - YandexGPT Pro latest;
+- `yandexgpt/rc` - release candidate.
+
 CLI также понимает env-переменные `YANDEXGPT_API_KEY` или `YANDEX_CLOUD_API_KEY`, а для каталога - `YANDEXGPT_FOLDER_ID` или `YANDEX_CLOUD_FOLDER_ID`.
 
 ### GigaChat
 
-Официальные страницы:
+Для CLI нужен authorization key. Это не одноразовый OAuth access token: CLI сам получает OAuth-токен перед запросом, используя сохраненный authorization key.
 
-- документация GigaChat: `https://developers.sber.ru/docs/ru/gigachat/overview`;
-- получение OAuth-токена: `https://developers.sber.ru/docs/ru/gigachat/api/reference/rest/post-token`;
-- тарифы: `https://developers.sber.ru/docs/ru/gigachat/tariffs`.
+Пошаговая настройка:
 
-Для CLI нужен authorization key:
+1. Перейдите на портал разработчиков Сбера: `https://developers.sber.ru/`.
+2. Войдите в аккаунт.
+3. Откройте раздел GigaChat.
+4. Если нужно, подключите доступ к GigaChat API для физического лица или организации.
+5. Откройте кабинет/проект, в котором доступны учетные данные GigaChat API.
+6. Найдите authorization key для REST API. В документации GigaChat он используется в OAuth-запросе в заголовке `Authorization: Basic ...`.
+7. Скопируйте authorization key и сохраните его локально в CLI:
 
 ```bash
 iola ai key set gigachat
+```
+
+CLI попросит ввести:
+
+- `GIGACHAT_AUTH_KEY` - authorization key;
+- `scope` - по умолчанию `GIGACHAT_API_PERS` для персонального доступа.
+
+После сохранения ключа выберите профиль и модель:
+
+```bash
 iola ai setup gigachat --model GigaChat-2
 ```
 
+Через интерактивное меню:
+
+```text
+/model
+2. Российские AI (YandexGPT/GigaChat)
+2. GigaChat API
+```
+
+Доступные модели в CLI:
+
+- `GigaChat-2` - основная модель;
+- `GigaChat-2-Pro` - повышенное качество;
+- `GigaChat-2-Max` - максимальное качество;
+- `GigaChat` - legacy/fallback.
+
 CLI также понимает env-переменные `GIGACHAT_AUTH_KEY` или `GIGACHAT_API_KEY`. По умолчанию используется scope `GIGACHAT_API_PERS`; при необходимости его можно задать через `GIGACHAT_SCOPE`.
 
 По тарифам: у GigaChat для физических лиц есть Freemium-лимит на токены; для больших объемов используются платные пакеты. У YandexGPT тарификация идет через Yandex Cloud по токенам и квотам аккаунта, поэтому актуальные бесплатные гранты или лимиты нужно проверять в консоли Yandex Cloud.
 
+Официальная документация:
+
+- Yandex Foundation Models: `https://yandex.cloud/ru/docs/foundation-models/`;
+- Yandex AI Studio authentication: `https://yandex.cloud/ru/docs/ai-studio/api-ref/authentication`;
+- Yandex Foundation Models pricing: `https://yandex.cloud/ru/docs/foundation-models/pricing`;
+- GigaChat overview: `https://developers.sber.ru/docs/ru/gigachat/overview`;
+- GigaChat OAuth token: `https://developers.sber.ru/docs/ru/gigachat/api/reference/rest/post-token`;
+- GigaChat tariffs: `https://developers.sber.ru/docs/ru/gigachat/tariffs`.
+
 ## OpenAI
 
 Получение ключа OpenAI Platform: