urok 0.1.0__py3-none-any.whl

urok/__init__.py

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

urok/__main__.py

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

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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+urok/__init__.py,sha256=IMnqO2q_JlajuDMQq65g-JPoupYL7WS1RkdGY0b27IE,95
+urok/__main__.py,sha256=aCil-iFaToZsL_hBt2MdL_sZiMgDtaELunVGHWfOhmk,83
+urok/cli.py,sha256=7FIVEUJJciuEkQDGf5VwYoJCcIKiby1owFNwaD2M8CE,9879
+urok/llm.py,sha256=NrGWjzgJiGQ5bxntutkVWM0UvYK2nt9kiF_ETLZnwVM,6821
+urok/store.py,sha256=IYsNq16wou-jnqYY_Q-y8sJ8hnxGewNccc-r0qC5UAc,2974
+urok-0.1.0.dist-info/METADATA,sha256=576ZwBkHZb6UGPXPgpA0gP8xO2Cnbuqn97Dg8uTTXWk,6059
+urok-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+urok-0.1.0.dist-info/entry_points.txt,sha256=HXbdNP-X6iOBB63oFjbwljJ0xhOau1qou6TfmNg_nKs,39
+urok-0.1.0.dist-info/RECORD,,

urok-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

urok-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+urok = urok.cli:main