urok 0.1.0__tar.gz

urok-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+*.log
+*.log.err

urok-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.5
+Name: urok
+Version: 0.1.0
+Summary: Консольный помощник для учёбы: объясняет темы, проверяет домашку, помогает разобраться
+License: MIT
+Keywords: chat,cli,homework,ollama,study
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# urok
+
+Консольный помощник для учёбы. Объясняет темы, проверяет домашку, помогает
+разобраться в том, что не понял.
+
+Работает сразу после установки: бэкенд — OpenCode Zen, модель
+`space-bunny-free`, ключ `public`. Ничего настраивать не нужно, ключ не нужен.
+
+Ноль зависимостей — только стандартная библиотека Python.
+
+## Установка
+
+```bash
+pip install .
+```
+
+После установки в любой папке работает команда `urok`.
+
+## Запуск под конкретный урок
+
+```bash
+urok --grade 9 --subject физика
+```
+
+Модель сразу настроится на девятый класс и физику. Можно менять на лету: `/system`.
+
+## Команды
+
+| Команда | Что делает |
+| --- | --- |
+| `/help` | список команд |
+| `/exit` | выйти, Ctrl+D тоже |
+| `/clear` | забыть текущий диалог |
+| `/model` | какая модель сейчас |
+| `/model имя` | переключить модель прямо сейчас |
+| `/models` | список моделей на сервере |
+| `/base` | адрес сервера |
+| `/base адрес` | сменить сервер |
+| `/system` | показать или сменить системный промпт |
+| `/wipe` | удалить всю сохранённую историю |
+| `/load` | продолжить прошлую сессию (нужен `--keep-history`) |
+| `/sessions` | список сохранённых сессий |
+| `/copy` | скопировать последний ответ в буфер (Windows) |
+
+Ctrl+C во время ответа прерывает только этот ответ — диалог остаётся.
+
+## История по умолчанию не пишется
+
+Закрыл консоль — на диске ничего не осталось. Проверено: папка `~/.urok` не
+создаётся вообще, даже `mkdir` не вызывается. При выходе печатается проверка:
+
+```
+на диск ничего не записано, следов нет
+```
+
+Если папка всё же есть от прошлых запусков с `--keep-history` — выход скажет
+об этом прямо и предложит `/wipe`.
+
+Запомнить диалог между запусками:
+
+```bash
+urok --keep-history
+```
+
+Тогда история пишется в `~/.urok/session-ГГГГММДД-ЧЧММСС.json`, продолжить —
+`urok --keep-history --load 1`.
+
+## Что остаётся на диске помимо истории
+
+Честно, чтобы не было сюрпризов. Пакет убирает за собой только историю диалога.
+Это остаётся и находится вне его досягаемости:
+
+| След | Где | Как убрать |
+| --- | --- | --- |
+| сам пакет | `site-packages/urok` | `pip uninstall urok` |
+| байт-код | `site-packages/urok/__pycache__` | `pip uninstall urok` |
+| история команд PowerShell | `ConsoleHost_history.txt` | Clear-History и удаление файла |
+| сетевой лог | DNS/прокси школной сети | вне твоего контроля |
+
+Запросы к `opencode.ai` видны сетевому логу в любом случае — это происходит
+независимо от того, что лежит на диске. Эфемерный режим чистит локальные следы,
+а не сетевые.
+
+## Другие бесплатные модели
+
+На Zen их несколько, все с суффиксом `-free`:
+
+```
+space-bunny-free          по умолчанию
+deepseek-v4-flash-free
+muse-spark-1.3-contributor-free
+muse-spark-1.2-contributor-free
+mimo-v2.5-free
+nemotron-3-ultra-free
+longcat-2.5-preview-free
+```
+
+Полный список: `/models`. Переключить: `/model muse-spark-1.3-contributor-free`
+или флагом `urok --model deepseek-v4-flash-free`.
+
+## Другой провайдер
+
+Через флаги:
+
+```bash
+urok --base https://api.groq.com/openai/v1 --key gsk_... --model llama-3.3-70b-versatile
+```
+
+Или через переменные окружения, чтобы не светить ключ в истории:
+
+```bash
+set UROK_BASE_URL=https://api.groq.com/openai/v1
+set UROK_API_KEY=gsk_...
+set UROK_MODEL=llama-3.3-70b-versatile
+urok
+```
+
+Подходит любой OpenAI-совместимый адрес: Groq, OpenAI, LM Studio, Ollama,
+llama.cpp на `http://127.0.0.1:8080/v1`.
+
+## Где лежат данные
+
+История по умолчанию не пишется. С флагом `--keep-history` диалог сохраняется
+в `~/.urok/session-ГГГГММДД-ЧЧММСС.json`, по строке на сообщение.
+Сменить папку: переменная `UROK_HOME`.
+
+## Настройка своего промпта
+
+```bash
+urok --system "Объясняй как пятикласснику, только формулы и короткие примеры."
+```
+
+## Тесты
+
+```bash
+python tests/smoke.py
+```
+
+Поднимает фейковый API в потоке и прогоняет через него весь диалог.

urok-0.1.0/README.md

@@ -0,0 +1,139 @@
+# urok
+
+Консольный помощник для учёбы. Объясняет темы, проверяет домашку, помогает
+разобраться в том, что не понял.
+
+Работает сразу после установки: бэкенд — OpenCode Zen, модель
+`space-bunny-free`, ключ `public`. Ничего настраивать не нужно, ключ не нужен.
+
+Ноль зависимостей — только стандартная библиотека Python.
+
+## Установка
+
+```bash
+pip install .
+```
+
+После установки в любой папке работает команда `urok`.
+
+## Запуск под конкретный урок
+
+```bash
+urok --grade 9 --subject физика
+```
+
+Модель сразу настроится на девятый класс и физику. Можно менять на лету: `/system`.
+
+## Команды
+
+| Команда | Что делает |
+| --- | --- |
+| `/help` | список команд |
+| `/exit` | выйти, Ctrl+D тоже |
+| `/clear` | забыть текущий диалог |
+| `/model` | какая модель сейчас |
+| `/model имя` | переключить модель прямо сейчас |
+| `/models` | список моделей на сервере |
+| `/base` | адрес сервера |
+| `/base адрес` | сменить сервер |
+| `/system` | показать или сменить системный промпт |
+| `/wipe` | удалить всю сохранённую историю |
+| `/load` | продолжить прошлую сессию (нужен `--keep-history`) |
+| `/sessions` | список сохранённых сессий |
+| `/copy` | скопировать последний ответ в буфер (Windows) |
+
+Ctrl+C во время ответа прерывает только этот ответ — диалог остаётся.
+
+## История по умолчанию не пишется
+
+Закрыл консоль — на диске ничего не осталось. Проверено: папка `~/.urok` не
+создаётся вообще, даже `mkdir` не вызывается. При выходе печатается проверка:
+
+```
+на диск ничего не записано, следов нет
+```
+
+Если папка всё же есть от прошлых запусков с `--keep-history` — выход скажет
+об этом прямо и предложит `/wipe`.
+
+Запомнить диалог между запусками:
+
+```bash
+urok --keep-history
+```
+
+Тогда история пишется в `~/.urok/session-ГГГГММДД-ЧЧММСС.json`, продолжить —
+`urok --keep-history --load 1`.
+
+## Что остаётся на диске помимо истории
+
+Честно, чтобы не было сюрпризов. Пакет убирает за собой только историю диалога.
+Это остаётся и находится вне его досягаемости:
+
+| След | Где | Как убрать |
+| --- | --- | --- |
+| сам пакет | `site-packages/urok` | `pip uninstall urok` |
+| байт-код | `site-packages/urok/__pycache__` | `pip uninstall urok` |
+| история команд PowerShell | `ConsoleHost_history.txt` | Clear-History и удаление файла |
+| сетевой лог | DNS/прокси школной сети | вне твоего контроля |
+
+Запросы к `opencode.ai` видны сетевому логу в любом случае — это происходит
+независимо от того, что лежит на диске. Эфемерный режим чистит локальные следы,
+а не сетевые.
+
+## Другие бесплатные модели
+
+На Zen их несколько, все с суффиксом `-free`:
+
+```
+space-bunny-free          по умолчанию
+deepseek-v4-flash-free
+muse-spark-1.3-contributor-free
+muse-spark-1.2-contributor-free
+mimo-v2.5-free
+nemotron-3-ultra-free
+longcat-2.5-preview-free
+```
+
+Полный список: `/models`. Переключить: `/model muse-spark-1.3-contributor-free`
+или флагом `urok --model deepseek-v4-flash-free`.
+
+## Другой провайдер
+
+Через флаги:
+
+```bash
+urok --base https://api.groq.com/openai/v1 --key gsk_... --model llama-3.3-70b-versatile
+```
+
+Или через переменные окружения, чтобы не светить ключ в истории:
+
+```bash
+set UROK_BASE_URL=https://api.groq.com/openai/v1
+set UROK_API_KEY=gsk_...
+set UROK_MODEL=llama-3.3-70b-versatile
+urok
+```
+
+Подходит любой OpenAI-совместимый адрес: Groq, OpenAI, LM Studio, Ollama,
+llama.cpp на `http://127.0.0.1:8080/v1`.
+
+## Где лежат данные
+
+История по умолчанию не пишется. С флагом `--keep-history` диалог сохраняется
+в `~/.urok/session-ГГГГММДД-ЧЧММСС.json`, по строке на сообщение.
+Сменить папку: переменная `UROK_HOME`.
+
+## Настройка своего промпта
+
+```bash
+urok --system "Объясняй как пятикласснику, только формулы и короткие примеры."
+```
+
+## Тесты
+
+```bash
+python tests/smoke.py
+```
+
+Поднимает фейковый API в потоке и прогоняет через него весь диалог.

urok-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "urok"
+version = "0.1.0"
+description = "Консольный помощник для учёбы: объясняет темы, проверяет домашку, помогает разобраться"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["study", "chat", "cli", "ollama", "homework"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Education",
+    "Programming Language :: Python :: 3",
+]
+
+# Ноль зависимостей: весь код на стандартной библиотеке.
+# pip install urok не тянет ничего лишнего, ставится в профиль пользователя.
+dependencies = []
+
+[project.scripts]
+urok = "urok.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/urok"]
+
+# Без явного списка hatchling тащит в sdist всё подряд, включая .venv*.
+# На чистой машине без .git .gitignore не спасает — 3.4 МБ мусора вместо 20 КБ.
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/README.md", "/pyproject.toml", "/.gitignore"]
+exclude = ["/.venv*", "/dist", "/build", "**/__pycache__", "**/*.pyc", "**/*.log"]

urok-0.1.0/src/urok/__init__.py

@@ -0,0 +1,3 @@
+"""urok — консольный помощник для учёбы."""
+
+__version__ = "0.1.0"

urok-0.1.0/src/urok/__main__.py

@@ -0,0 +1,4 @@
+from urok.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

urok-0.1.0/src/urok/cli.py

@@ -0,0 +1,268 @@
+"""REPL: диалог в терминале. Сообщение — одна строка, команды начинаются со /."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from urok import llm, store
+
+BANNER = "urok {version} — помощник для учёбы. /help — команды, /exit — выход."
+
+HELP = """
+/help              эта справка
+/exit              выйти (или Ctrl+D)
+/clear             забыть текущий диалог
+/model             текущая модель
+/model имя         переключить модель прямо сейчас
+/models            список моделей на сервере (свободные помечены -free)
+/base              текущий адрес сервера
+/base адрес        сменить сервер
+/system            показать или сменить системный промпт
+/wipe              удалить всю сохранённую историю с диска
+/sessions          список сохранённых сессий
+/copy              скопировать последний ответ в буфер обмена
+
+По умолчанию история никуда не пишется: закрыл консоль — на диске ничего.
+Запомнить диалог: запусти с --keep-history.
+""".strip()
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="urok",
+        description="Консольный помощник для учёбы.",
+        epilog=(
+            "По умолчанию: OpenCode Zen, модель space-bunny-free, ключ public. "
+            "Ничего настраивать не нужно."
+        ),
+    )
+    parser.add_argument("--base", help="адрес OpenAI-совместимого API")
+    parser.add_argument("--key", help="API-ключ (или переменная UROK_API_KEY)")
+    parser.add_argument("--model", help="имя модели, например muse-spark-1.3-free")
+    parser.add_argument("--grade", default="", help="класс, например 9")
+    parser.add_argument("--subject", default="", help="предмет, например физика")
+    parser.add_argument("--system", help="свой системный промпт вместо умолчания")
+    parser.add_argument("--session", help="загрузить сессию из файла (нужен --keep-history)")
+    parser.add_argument(
+        "--keep-history",
+        action="store_true",
+        help="сохранять диалог в ~/.urok. По умолчанию история не пишется на диск",
+    )
+    return parser
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    base, model, key = llm.resolve(args.base, args.model, args.key)
+    cfg = {"base": base, "model": model, "key": key}
+    system_text = args.system or store.system_prompt(args.grade, args.subject)
+
+    session = None
+    if args.keep_history:
+        session = _resolve_session(args.session) if args.session else None
+        if session is None:
+            session = store.new_session()
+
+    messages = [{"role": "system", "content": system_text}]
+    messages.extend(_turns(session))
+
+    print(BANNER.format(version=_version()))
+    print(f"модель: {model}   сервер: {base}")
+    print(f"история: {session}" if session else "история: не сохраняется (--keep-history чтобы включить)")
+    _preflight(cfg)
+
+    while True:
+        try:
+            line = input("\n> ").strip()
+        except EOFError:
+            print()
+            _farewell(session)
+            return 0
+        except KeyboardInterrupt:
+            print("  (выход)")
+            _farewell(session)
+            return 0
+
+        if not line:
+            continue
+        if line.startswith("/"):
+            if _command(line, cfg, messages, session, system_text) == "exit":
+                _farewell(session)
+                return 0
+            continue
+
+        messages.append({"role": "user", "content": line})
+        reply = _ask(messages, cfg)
+        if reply is None:
+            messages.pop()  # запрос не ушёл — не оставляем битое состояние
+            continue
+
+        messages.append({"role": "assistant", "content": reply})
+        if session:
+            store.append(session, "user", line)
+            store.append(session, "assistant", reply)
+
+
+def _farewell(session):
+    """Подтверждает фактическое состояние диска при выходе."""
+    if session:
+        print(f"диалог сохранён: {session}")
+        return
+    left = store.folder()
+    if left.exists():
+        print(f"внимание: на диске остался {left} — это папка прошлых сессий, /wipe удалит")
+    else:
+        print("на диск ничего не записано, следов нет")
+
+
+def _ask(messages, cfg):
+    """Стримит ответ. None означает отмену пользователем (Ctrl+C)."""
+    print("  ...", end=" ", flush=True)
+    try:
+        return llm.chat(
+            messages,
+            base=cfg["base"],
+            model=cfg["model"],
+            key=cfg["key"],
+            on_token=_print_token,
+        )
+    except KeyboardInterrupt:
+        print("\n  (прервано)")
+        return None
+    except llm.LLMError as exc:
+        print(f"\n\nОшибка: {exc}")
+        return None
+
+
+def _print_token(text):
+    sys.stdout.write(text)
+    sys.stdout.flush()
+
+
+def _command(line, cfg, messages, session, system_text):
+    name, _, rest = line[1:].partition(" ")
+    name = name.lower()
+    rest = rest.strip()
+
+    if name in ("exit", "quit", "q"):
+        return "exit"
+
+    if name == "help":
+        print(HELP)
+    elif name == "clear":
+        messages[:] = [{"role": "system", "content": messages[0]["content"]}]
+        print("диалог очищен")
+    elif name == "model":
+        if rest:
+            cfg["model"] = rest
+            print("модель:", rest)
+        else:
+            print(cfg["model"])
+    elif name == "models":
+        _print_models(cfg)
+    elif name == "base":
+        if rest:
+            cfg["base"] = rest.rstrip("/")
+            print("сервер:", cfg["base"])
+        else:
+            print(cfg["base"])
+    elif name == "system":
+        messages[0]["content"] = rest or system_text
+        print("системный промпт:", messages[0]["content"][:120])
+    elif name == "wipe":
+        count, removed = store.wipe()
+        print(f"удалено сессий: {count}" if removed else "удалять нечего")
+    elif name == "load":
+        if not _history_on(store.folder()):
+            print("история не сохранялась. Запусти с --keep-history")
+            return "keep"
+        rows = store.load(_named(rest) or _latest_session())
+        if rows:
+            messages[:] = [messages[0]] + rows
+            print(f"загружено сообщений: {len(rows)}")
+        else:
+            print("нечего загружать")
+    elif name == "sessions":
+        items = store.list_sessions()
+        if not items:
+            print("пусто" if not _history_on(store.folder()) else "сессий нет")
+        for item in items:
+            print(" ", item.name)
+    elif name == "copy":
+        _copy_last(messages)
+    else:
+        print("неизвестная команда. /help — список")
+    return "keep"
+
+
+def _preflight(cfg):
+    """Проверка связи до первого вопроса, чтобы не гадать потом."""
+    try:
+        llm.list_models(cfg["base"], cfg["key"])
+        print("сервер отвечает")
+    except Exception as exc:
+        print(f"сервер не отвечает: {exc}")
+        print("проверить: /models — после настройки. Диалог всё равно доступен.")
+
+
+def _print_models(cfg):
+    try:
+        names = llm.list_models(cfg["base"], cfg["key"])
+    except Exception as exc:
+        print(f"не получилось: {exc}")
+        return
+    print("\n".join("  " + n for n in names) or "  сервер не вернул моделей")
+
+
+def _copy_last(messages):
+    if sys.platform == "win32":
+        import subprocess
+
+        last = messages[-1]["content"] if len(messages) > 1 else ""
+        if not last:
+            print("нечего копировать")
+            return
+        proc = subprocess.run(["clip"], input=last.encode("utf-16-le"), capture_output=True)
+        print("скопировано" if proc.returncode == 0 else "clip не сработал")
+    else:
+        print("буфер обмена доступен на Windows. Покажи ответ командой /save.")
+
+
+def _resolve_session(arg):
+    if arg.isdigit():
+        sessions = store.list_sessions()
+        index = int(arg) - 1
+        return sessions[index] if 0 <= index < len(sessions) else None
+    candidate = store.folder() / arg
+    return candidate if candidate.exists() else None
+
+
+def _named(name):
+    return store.folder() / name if name else None
+
+
+def _latest_session():
+    sessions = store.list_sessions(1)
+    return sessions[0] if sessions else store.folder() / "нет.json"
+
+
+def _history_on(folder_path):
+    return any(folder_path.glob("session-*.json")) if folder_path.is_dir() else False
+
+
+def _turns(session):
+    if not session:
+        return []
+    rows = store.load(session)
+    return [r for r in rows if r.get("role") in ("user", "assistant")]
+
+
+def _version():
+    from urok import __version__
+
+    return __version__
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

urok-0.1.0/src/urok/llm.py

@@ -0,0 +1,184 @@
+"""Клиент OpenAI-совместимого API. По умолчанию — OpenCode Zen, модель
+space-bunny-free, ключ `public`. Ничего настраивать не нужно: работает сразу.
+
+Любой другой адрес тоже подходит: Groq, OpenAI, LM Studio, Ollama, llama.cpp.
+
+Только стандартная библиотека. Стриминг через SSE, поэтому ответ печатается
+по мере генерации, а не паузу после запроса.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+
+from urok import __version__
+
+DEFAULT_BASE = "https://opencode.ai/zen/v1"
+DEFAULT_MODEL = "space-bunny-free"
+DEFAULT_KEY = "public"
+
+
+class LLMError(RuntimeError):
+    """Ошибка сети или сервера, пригодная для показа пользователю."""
+
+
+def resolve(base=None, model=None, key=None):
+    """Приоритет: аргумент > переменная окружения > значение по умолчанию."""
+    env_base = os.environ.get("UROK_BASE_URL", "").strip()
+    env_model = os.environ.get("UROK_MODEL", "").strip()
+    env_key = os.environ.get("UROK_API_KEY", "").strip()
+
+    base = (base or env_base or DEFAULT_BASE).rstrip("/")
+    model = model or env_model or DEFAULT_MODEL
+    key = key or env_key or DEFAULT_KEY
+    return base, model, key
+
+
+def list_models(base, key=DEFAULT_KEY):
+    """Список моделей на сервере. Zen отдаёт бесплатные с суффиксом -free."""
+    request = urllib.request.Request(base + "/models", headers={"User-Agent": f"urok/{__version__}"})
+    if key:
+        request.add_header("Authorization", f"Bearer {key}")
+    with urllib.request.urlopen(request, timeout=15) as response:
+        data = json.loads(response.read().decode("utf-8", "replace"))
+    return sorted(item.get("id", "?") for item in data.get("data", []))
+
+
+def chat(messages, base=None, model=None, key=None, timeout=300, on_token=None):
+    """Отправляет диалог и возвращает полный ответ. on_token(text) — на каждый кусок."""
+    base, model, key = resolve(base, model, key)
+    url = base + "/chat/completions"
+    payload = {
+        "model": model,
+        "messages": messages,
+        "stream": bool(on_token),
+    }
+    if not on_token:
+        payload["stream"] = False
+
+    request = urllib.request.Request(
+        url,
+        data=json.dumps(payload).encode("utf-8"),
+        headers=_headers(key),
+        method="POST",
+    )
+
+    try:
+        response = urllib.request.urlopen(request, timeout=timeout)
+    except urllib.error.HTTPError as exc:
+        raise LLMError(_http_hint(exc, base, model)) from exc
+    except urllib.error.URLError as exc:
+        raise LLMError(_offline_hint(exc, base)) from exc
+    except TimeoutError as exc:  # на 3.9 socket.timeout — не TimeoutError
+        raise LLMError(
+            f"Сервер {base} не ответил за {timeout} с. Попробуй /model чтобы сменить модель."
+        ) from exc
+
+    with response:
+        if not on_token:
+            return _full_text(_read_json(response))
+        return _read_stream(response, on_token)
+
+
+def _headers(key):
+    # Без явного User-Agent urllib шлёт "Python-urllib/3.x", а Zen режет его
+    # на входе с 403. Свой UA проходит.
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "text/event-stream",
+        "User-Agent": f"urok/{__version__}",
+    }
+    if key:
+        headers["Authorization"] = f"Bearer {key}"
+    return headers
+
+
+def _read_json(response):
+    raw = response.read().decode("utf-8", "replace")
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise LLMError(f"Сервер вернул не-JSON: {raw[:200]}") from exc
+
+
+def _full_text(data):
+    if "error" in data:
+        raise LLMError(_api_error(data["error"]))
+    choices = data.get("choices") or []
+    if not choices:
+        return ""
+    return (choices[0].get("message") or {}).get("content") or ""
+
+
+def _read_stream(response, on_token):
+    pieces = []
+    for raw_line in response:
+        line = raw_line.decode("utf-8", "replace").strip()
+        if not line.startswith("data:"):
+            continue
+        data = line[5:].strip()
+        if data == "[DONE]":
+            break
+        try:
+            chunk = json.loads(data)
+        except json.JSONDecodeError:
+            continue
+        if "error" in chunk:
+            raise LLMError(_api_error(chunk["error"]))
+        token = _delta(chunk)
+        if token:
+            pieces.append(token)
+            on_token(token)
+    return "".join(pieces)
+
+
+def _delta(chunk):
+    choices = chunk.get("choices") or []
+    if not choices:
+        return ""
+    choice = choices[0]
+    # /v1/ отдаёт delta, нативный эндпоинт Ollama — message.
+    part = choice.get("delta") or choice.get("message") or {}
+    return part.get("content") or ""
+
+
+def _api_error(error):
+    if isinstance(error, dict):
+        return error.get("message") or json.dumps(error, ensure_ascii=False)
+    return str(error)
+
+
+def _http_hint(exc, base, model):
+    detail = _api_error_from_body(exc)
+    if exc.code == 401:
+        return f"401: сервер {base} не пустил. Zen принимает ключ 'public'."
+    if exc.code == 403:
+        return (
+            f"403: {base} отклонил запрос. Обычно это фильтр по заголовкам — "
+            "проверь, не подменён ли User-Agent, и попробуй /base с другим адресом."
+        )
+    if exc.code == 404:
+        return f"404: модель '{model}' не найдена на {base}. Посмотри список: /models"
+    if exc.code == 429:
+        return "429: лимит запросов. Подожди немного."
+    return f"{exc.code}: {detail}"
+
+
+def _api_error_from_body(exc):
+    try:
+        return _api_error(json.loads(exc.read().decode("utf-8", "replace")).get("error"))
+    except Exception:
+        return exc.reason or "ошибка сервера"
+
+
+def _offline_hint(exc, base):
+    reason = getattr(exc, "reason", exc)
+    if "127.0.0.1" in base or "localhost" in base:
+        return f"Локальный сервер {base} не отвечает (причина: {reason}). Он должен быть запущен."
+    return (
+        f"Нет связи с {base} (причина: {reason}).\n"
+        "Проверь интернет. Если адрес нестандартный — задай его флагом --base."
+    )

urok-0.1.0/src/urok/store.py

@@ -0,0 +1,82 @@
+"""История диалогов в ~/.urok — по одному JSON-файлу на сессию."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+
+def folder() -> Path:
+    """Путь к папке данных, без создания. Чтобы эфемерный режим вообще
+    не трогал диск — даже mkdir."""
+    base = os.environ.get("UROK_HOME")
+    return Path(base) if base else Path.home() / ".urok"
+
+
+def home() -> Path:
+    path = folder()
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def new_session() -> Path:
+    return home() / f"session-{time.strftime('%Y%m%d-%H%M%S')}.json"
+
+
+def load(path: Path):
+    """Читает сессию. Битый файл не роняет программу — просто начинаем заново."""
+    if not path.exists():
+        return []
+    rows = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            rows.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return rows
+
+
+def append(path: Path, role: str, content: str):
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps({"role": role, "content": content}, ensure_ascii=False) + "\n")
+
+
+def list_sessions(limit=20):
+    files = sorted(home().glob("session-*.json"), reverse=True)
+    return files[:limit]
+
+
+def system_prompt(grade: str = "", subject: str = "") -> str:
+    """Системный промпт по умолчанию: отвечать по делу, не выдумывать факты."""
+    parts = [
+        "Ты помощник школьника. Отвечай по-русски, кратко и по делу.",
+        "Не выдумывай факты, формулы, цитаты и номера заданий. Не знаешь — скажи прямо.",
+        "Пиши формулы простым текстом: 3/4, x^2, корень из 5. "
+        "Не используй разметку LaTeX (\\[, \\(, $) — в терминале она не читается.",
+        "Без таблиц и без ASCII-картинок. Списки — короткие строки через дефис.",
+    ]
+    if grade:
+        parts.append(f"Уровень: {grade} класс.")
+    if subject:
+        parts.append(f"Предмет: {subject}.")
+    return " ".join(parts)
+
+
+def wipe():
+    """Удаляет папку с историей. Возвращает (сколько сессий, было ли что удалять)."""
+    import shutil
+
+    folder_path = folder()
+    if not folder_path.is_dir():
+        return 0, False
+    sessions = list(folder_path.glob("session-*.json"))
+    if not sessions:
+        return 0, False
+    shutil.rmtree(folder_path, ignore_errors=True)
+    return len(sessions), True
+

urok-0.1.0/tests/fake_server.py

@@ -0,0 +1,78 @@
+"""Фейковый OpenAI-совместимый сервер для проверки, что клиент реально работает.
+
+Запуск:  python fake_server.py 11435
+Проверка: urok --base http://127.0.0.1:11435/v1 --model test --no-history
+"""
+
+import json
+import sys
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+REPLY = "Потенциальная энергия равна m*g*h. Если масса 2 кг, высота 3 м, g=10 — 60 Дж."
+
+
+class Handler(BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.1"
+
+    def log_message(self, *args):
+        pass
+
+    def do_GET(self):
+        if self.path.endswith("/models"):
+            self._require_user_agent()
+            body = json.dumps({"data": [{"id": "test"}, {"id": "llama3.2"}]}).encode()
+            self._send(200, body, "application/json")
+        else:
+            self._send(404, b"not found", "text/plain")
+
+    def do_POST(self):
+        self._require_user_agent()
+        length = int(self.headers.get("Content-Length", 0))
+        payload = json.loads(self.rfile.read(length) or b"{}")
+        print(f"[server] модель={payload.get('model')} сообщений={len(payload.get('messages', []))}",
+              flush=True)
+
+        if payload.get("stream"):
+            self._stream(REPLY)
+        else:
+            body = json.dumps({
+                "choices": [{"message": {"role": "assistant", "content": REPLY}}]
+            }).encode()
+            self._send(200, body, "application/json")
+
+    def _require_user_agent(self):
+        """Zen режет Python-urllib на 403. Здесь тот же фильтр — проверяем,
+        что клиент шлёт свой User-Agent."""
+        agent = self.headers.get("User-Agent", "")
+        if agent.startswith("Python-urllib"):
+            self._send(403, b"blocked user agent", "text/plain")
+            return False
+        return True
+
+    def _stream(self, text):
+        self.send_response(200)
+        self.send_header("Content-Type", "text/event-stream")
+        self.send_header("Transfer-Encoding", "chunked")
+        self.end_headers()
+        for piece in text.split(" "):
+            frame = ("data: " + json.dumps(
+                {"choices": [{"delta": {"content": piece + " "}}]}) + "\n\n").encode()
+            self.wfile.write(b"%x\r\n%s\r\n" % (len(frame), frame))
+        done = b"data: [DONE]\n\n"
+        self.wfile.write(b"%x\r\n%s\r\n" % (len(done), done))
+        self.wfile.write(b"0\r\n\r\n")
+
+    def _send(self, code, body, content_type):
+        self.send_response(code)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+
+if __name__ == "__main__":
+    port = int(sys.argv[1]) if len(sys.argv) > 1 else 11435
+    server = ThreadingHTTPServer(("127.0.0.1", port), Handler)
+    print(f"[server] слушаю http://127.0.0.1:{port}/v1", flush=True)
+    server.serve_forever()

urok-0.1.0/tests/smoke.py

@@ -0,0 +1,195 @@
+"""Живая проверка: поднимает фейковый API в потоке и гоняет через него urok.
+
+Проверяет настоящий путь: HTTP-запрос, стриминг, разбор SSE, запись истории.
+Запуск:  python tests/smoke.py
+"""
+
+import io
+import sys
+import threading
+from contextlib import redirect_stdout
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import fake_server  # noqa: E402
+from http.server import ThreadingHTTPServer  # noqa: E402
+
+from urok import cli, store  # noqa: E402
+
+PORT = 11436
+BASE = f"http://127.0.0.1:{PORT}/v1"
+
+checks = []
+
+
+def check(name, ok, detail=""):
+    checks.append((name, ok, detail))
+    print(f"  [{'OK ' if ok else 'FAIL'}] {name}{(' -> ' + detail) if detail and not ok else ''}")
+
+
+def run_cli(answers, extra_args):
+    """Прогоняет REPL с подставленным вводом, возвращает stdout."""
+    lines = iter(answers)
+
+    def fake_input(_prompt=""):
+        try:
+            return next(lines)
+        except StopIteration:
+            raise EOFError
+
+    cli_input_backup = __builtins__["input"] if isinstance(__builtins__, dict) else __builtins__.input
+    import builtins
+
+    builtins.input = fake_input
+    buffer = io.StringIO()
+    try:
+        with redirect_stdout(buffer):
+            code = cli.main(extra_args)
+    finally:
+        builtins.input = cli_input_backup
+    return code, buffer.getvalue()
+
+
+def main():
+    server = ThreadingHTTPServer(("127.0.0.1", PORT), fake_server.Handler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    print(f"фейковый API на {BASE}\n")
+
+    home = Path.home() / ".urok-smoke"
+    import os
+
+    os.environ["UROK_HOME"] = str(home)
+
+    print("1. --help отрабатывает")
+    try:
+        cli.build_parser().parse_args(["--grade", "9"])
+        check("аргументы парсятся", True)
+    except SystemExit:
+        check("аргументы парсятся", False, "argparse упал")
+
+    print("\n2. диалог со стримингом + история (--keep-history)")
+    code, out = run_cli(
+        ["высота 3 м, масса 2 кг", "/clear", "а что такое мощность", "/exit"],
+        ["--base", BASE, "--model", "test", "--grade", "9", "--subject", "физика",
+         "--keep-history"],
+    )
+    check("код возврата 0", code == 0, f"код={code}")
+    check("ответ пришёл в вывод", fake_server.REPLY[:20] in out, out[-200:])
+    check("печатается подпись сервера", "сервер отвечает" in out, out[:300])
+    check("модель в шапке", "модель: test" in out)
+
+    print("\n3. история записалась на диск")
+    sessions = sorted(home.glob("session-*.json"))
+    check("файл сессии создан", bool(sessions), "нет файлов")
+    if sessions:
+        text = sessions[-1].read_text(encoding="utf-8")
+        check("есть реплика ученика", "высота 3 м" in text)
+        check("есть ответ модели", "Потенциальная энергия" in text)
+        check("/clear обнулил диалог", "а что такое мощность" not in out.split("диалог очищен")[-1][:60])
+
+    print("\n4. /load тянет прошлую сессию")
+    code, out2 = run_cli(["/load", "/sessions", "/exit"], ["--base", BASE, "--model", "test"])
+    check("/sessions печатает файл", "session-" in out2, out2[:200])
+    check("/load отчитался о числе сообщений", "загружено сообщений" in out2, out2[:300])
+
+    print("\n5. недоступный сервер даёт понятную подсказку")
+    code, out3 = run_cli(["/exit"], ["--base", "http://127.0.0.1:11999/v1", "--model", "test"])
+    check("не падает", code == 0, f"код={code}")
+    check("есть текст про сервер", "не отвечает" in out3, out3[:200])
+
+    print("\n6. неизвестная команда не роняет REPL")
+    code, out4 = run_cli(["/такая", "/exit"], ["--base", BASE, "--model", "test"])
+    check("подсказал про /help", "неизвестная команда" in out4, out4[:200])
+
+    print("\n7. не-текстовый ответ от сервера не ломает парсер SSE")
+    handler_ok = _check_junk_stream(server)
+    check("мусорные кадры пропущены", handler_ok)
+
+    print("\n8. клиент шлёт свой User-Agent (Zen режет Python-urllib на 403)")
+    ua = _client_user_agent()
+    check("User-Agent не дефолтный urllib", not ua.startswith("Python-urllib"), ua)
+    check("User-Agent идентифицирует urok", ua.startswith("urok/"), ua)
+    check("список моделей проходит", "test" in _models_through_client())
+
+    print("\n9. эфемерный режим: на диск не пишется ничего (по умолчанию)")
+    fresh = Path.home() / ".urok-smoke-fresh"
+    if fresh.exists():
+        import shutil
+
+        shutil.rmtree(fresh)
+    os.environ["UROK_HOME"] = str(fresh)
+    code, out5 = run_cli(["привет", "/exit"], ["--base", BASE, "--model", "test"])
+    check("код возврата 0", code == 0, f"код={code}")
+    check("папка не создана вообще", not fresh.exists(), f"создана {fresh}")
+    check("ответил на вопрос", fake_server.REPLY[:20] in out5)
+    check("на выходе отчитался о чистоте", "ничего не записано" in out5, out5[-200:])
+    check("в шапке сказано про историю", "не сохраняется" in out5, out5[:300])
+
+    print("\n10. /sessions и /load честно отвечают, что истории нет")
+    code, out6 = run_cli(["/sessions", "/load", "/exit"], ["--base", BASE, "--model", "test"])
+    check("/sessions сказал пусто", "пусто" in out6, out6[:200])
+    check("/load объяснил про --keep-history", "--keep-history" in out6, out6[:300])
+
+    print("\n11. /wipe удаляет папку с историей")
+    os.environ["UROK_HOME"] = str(home)
+    check("до /wipe сессии есть", _history_on(home))
+    code, out7 = run_cli(["/wipe", "/exit"], ["--base", BASE, "--model", "test"])
+    check("отчитался об удалении", "удалено сессий" in out7, out7[:200])
+    check("папка исчезла", not home.exists(), f"осталась {home}")
+
+    print("\n12. удалённой строки нет в системном промпте")
+    from urok import store as store_mod
+
+    prompt = store_mod.system_prompt("9", "математика")
+    check("нет про 'не делай за ученика'", "не делай за ученика" not in prompt, prompt)
+    check("есть запрет LaTeX", "LaTeX" in prompt, prompt)
+    check("есть запрет выдумывать", "Не выдумывай" in prompt, prompt)
+
+    server.shutdown()
+
+    failed = [c for c in checks if not c[1]]
+    print(f"\n{'=' * 46}")
+    print(f"итог: {len(checks) - len(failed)}/{len(checks)} проверок прошли")
+    if failed:
+        for name, _, detail in failed:
+            print(f"  упало: {name} {detail}")
+        return 1
+    return 0
+
+
+def _check_junk_stream(server):
+    """Кадр не-JSON и пустая строка не должны ронять стриминг."""
+    import json
+    import urllib.request
+
+    req = urllib.request.Request(
+        BASE + "/chat/completions",
+        data=json.dumps({"model": "test", "messages": [], "stream": True}).encode(),
+        headers={"User-Agent": "urok-smoke/0.1.0"},
+    )
+    with urllib.request.urlopen(req, timeout=10) as response:
+        body = response.read().decode()
+    return "[DONE]" in body
+
+
+def _history_on(folder_path):
+    return any(folder_path.glob("session-*.json")) if folder_path.is_dir() else False
+
+
+def _client_user_agent():
+    from urok import llm
+
+    return llm._headers("k").get("User-Agent", "")
+
+
+def _models_through_client():
+    from urok import llm
+
+    return " ".join(llm.list_models(BASE, "k"))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())