titlemark 1.2.0__py3-none-any.whl

titlemark/__init__.py

@@ -0,0 +1,8 @@
+"""titlemark — give every document its true name.
+
+Detects the title and author of a document (PDF, EPUB, FB2, MOBI, DJVU,
+DOCX) and renames the file into "Author - Title [year].ext".
+"""
+
+__version__ = "1.2.0"
+__author__ = "Sergei Korneev (AI coded)"

titlemark/__main__.py

@@ -0,0 +1,6 @@
+"""Точка входа: python -m titlemark ..."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

titlemark/ai.py

@@ -0,0 +1,185 @@
+"""Интеграция с vision-LLM (OpenAI-совместимый API) для разбора обложки.
+
+ИИ включается только явным флагом (--ai): утилита рендерит первую страницу
+в картинку, показывает её модели вместе с кандидатами эвристик и получает
+строгий JSON {"title", "author", "year"}. Понимает любые совместимые
+эндпоинты: OpenAI, DeepSeek, GigaChat, YandexGPT, локальная Ollama
+(http://localhost:11434/v1), llama.cpp, vLLM.
+
+Внешних библиотек нет — только стандартная библиотека.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+import shutil
+import subprocess
+import tempfile
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+
+from .models import DocumentInfo, Source
+
+DEFAULT_URL = "https://api.openai.com/v1"
+DEFAULT_MODEL = "gpt-4o-mini"
+
+_SYSTEM_PROMPT = (
+    "Ты — библиографический ассистент. По обложке или титулу документа "
+    "определи точное название, автора и год издания. "
+    "Ответь СТРОГО одним JSON-объектом вида "
+    '{"title": "...", "author": "...", "year": "YYYY"} без пояснений и markdown. '
+    "Название — на языке оригинала, ровно как на обложке (без служебных слов "
+    "вида «Скачать», «читать онлайн»). Автор — полное имя, как на обложке. "
+    "Если данных нет — пустая строка."
+)
+
+
+@dataclass
+class AiConfig:
+    """Параметры подключения к ИИ."""
+
+    url: str = DEFAULT_URL
+    model: str = DEFAULT_MODEL
+    api_key: str = ""
+    timeout: int = 60
+
+    @property
+    def is_local(self) -> bool:
+        return "localhost" in self.url or "127.0.0.1" in self.url
+
+
+# ---------------------------------------------------------------------------
+# обложка
+# ---------------------------------------------------------------------------
+
+def render_cover(path: Path, page: int = 1, dpi: int = 150) -> bytes | None:
+    """Отрендерить страницу документа в PNG (pdftoppm) или None."""
+    from .tools import find_tool, tool_env
+
+    exe = find_tool("pdftoppm")
+    if not exe:
+        return None
+    with tempfile.TemporaryDirectory(prefix="titlemark_ai_") as tmp:
+        out = Path(tmp) / "cover"
+        try:
+            subprocess.run(
+                [exe, "-f", str(page), "-l", str(page), "-r", str(dpi),
+                 "-png", "-singlefile", str(path), str(out)],
+                capture_output=True, timeout=60, check=False,
+                env=tool_env(exe),
+            )
+        except (subprocess.TimeoutExpired, OSError):
+            return None
+        img = Path(tmp) / "cover.png"
+        return img.read_bytes() if img.exists() else None
+
+
+# ---------------------------------------------------------------------------
+# запрос и разбор ответа
+# ---------------------------------------------------------------------------
+
+def build_prompt(info: DocumentInfo) -> str:
+    """Текстовая часть запроса: подсказки от эвристик."""
+    lines = [f"Имя файла: {info.path.name}"]
+    if info.title:
+        lines.append(f"Что определили эвристики (может быть ошибкой): {info.title}")
+    if info.author:
+        lines.append(f"Предполагаемый автор: {info.author}")
+    if info.year:
+        lines.append(f"Предполагаемый год: {info.year}")
+    if info.title_candidates:
+        cands = "; ".join(c for c, _s in info.title_candidates[:5])
+        lines.append(f"Кандидаты в заголовок из текста: {cands}")
+    if info.text_snippet:
+        lines.append(f"Фрагмент текста: {info.text_snippet[:300]}")
+    return "\n".join(lines)
+
+
+def _request(config: AiConfig, payload: dict) -> dict:
+    """POST /chat/completions. Выделено для подмены в тестах."""
+    url = config.url.rstrip("/") + "/chat/completions"
+    headers = {"Content-Type": "application/json"}
+    if config.api_key:
+        headers["Authorization"] = f"Bearer {config.api_key}"
+    req = urllib.request.Request(
+        url, data=json.dumps(payload).encode("utf-8"),
+        headers=headers, method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=config.timeout) as resp:
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def parse_json_answer(text: str) -> dict:
+    """Достать JSON-объект из ответа модели (терпимо к markdown-обёрткам)."""
+    if not text:
+        return {}
+    cleaned = re.sub(r"```(?:json)?", "", text).strip()
+    m = re.search(r"\{.*?\}", cleaned, re.S)
+    if not m:
+        return {}
+    try:
+        data = json.loads(m.group(0))
+    except json.JSONDecodeError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _apply_answer(info: DocumentInfo, data: dict) -> bool:
+    """Перенести поля ответа в DocumentInfo (пустые значения не мешают)."""
+    changed = False
+    for key, attr in (("title", "title"), ("author", "author"), ("year", "year")):
+        value = data.get(key)
+        if isinstance(value, str) and value.strip():
+            setattr(info, attr, value.strip())
+            changed = True
+    if changed:
+        if info.title:
+            info.title_source = Source.AI
+        if info.author:
+            info.author_source = Source.AI
+    return changed
+
+
+def enrich_with_ai(path: Path, info: DocumentInfo, config: AiConfig) -> bool:
+    """Спросить ИИ про обложку и обновить info. False — ИИ не ответил."""
+    cover = render_cover(path)
+    prompt = build_prompt(info)
+
+    if cover:
+        content: str | list = [{
+            "type": "image_url",
+            "image_url": {
+                "url": "data:image/png;base64,"
+                       + base64.b64encode(cover).decode("ascii"),
+            },
+        }, {"type": "text", "text": prompt}]
+    else:
+        info.warnings.append("could not render the cover — the AI got text only")
+        content = prompt
+
+    payload = {
+        "model": config.model,
+        "temperature": 0,
+        "messages": [
+            {"role": "system", "content": _SYSTEM_PROMPT},
+            {"role": "user", "content": content},
+        ],
+    }
+
+    try:
+        data = _request(config, payload)
+        answer = data["choices"][0]["message"]["content"]
+    except (urllib.error.URLError, OSError, KeyError, IndexError,
+            json.JSONDecodeError, ValueError) as exc:
+        info.warnings.append(f"the AI did not respond: {exc}")
+        return False
+
+    parsed = parse_json_answer(answer)
+    if not _apply_answer(info, parsed):
+        info.warnings.append("the AI returned no recognized data")
+        return False
+    return True

titlemark/cli.py

@@ -0,0 +1,224 @@
+"""Command line interface for titlemark."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from . import __author__, __version__
+from .ai import DEFAULT_MODEL as DEFAULT_AI_MODEL, DEFAULT_URL as DEFAULT_AI_URL
+from .extractors import supported_extensions
+from .naming import DEFAULT_TEMPLATE, TEMPLATE_FIELDS, validate_template
+from .renamer import apply_plans, plan_many, write_csv_report
+
+_STATUS_MARK = {
+    "ok": "*",
+    "same": "=",
+    "no-title": "?",
+    "unsupported": "-",
+    "error": "!",
+}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="titlemark",
+        description=(
+            "Reads a document, detects its title and author, and renames the "
+            "file into something a human would recognise "
+            "(default pattern: \"Author - Title [year].ext\"). "
+            "By default it runs in dry-run mode: nothing is renamed, only a "
+            "plan is printed. "
+            f"Supported formats: {', '.join(supported_extensions())}."
+        ),
+        epilog=(
+            "Examples:\n"
+            "  titlemark book.pdf                   # what would the file become\n"
+            "  titlemark --apply book.pdf           # rename it\n"
+            "  titlemark --apply -r ~/Downloads     # whole folder, recursively\n"
+            "  titlemark --report plan.csv -r .     # save the plan as CSV\n"
+            "  titlemark --title-from-text book.pdf # title = whole page text\n"
+            "  titlemark --ai book.pdf              # vision LLM reads the cover\n"
+            '  titlemark --naming-template "{title}-{year}" book.pdf\n'
+            "\n"
+            f"Author:  {__author__}\n"
+            f"Version: {__version__} (see also: titlemark --version)"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version",
+                        version=f"%(prog)s {__version__} — {__author__}")
+    parser.add_argument("paths", nargs="+", type=Path,
+                        help="file(s) or folder(s) with documents")
+    parser.add_argument("-a", "--apply", action="store_true",
+                        help="actually rename (without this flag only a plan "
+                             "is printed)")
+    parser.add_argument("-r", "--recursive", action="store_true",
+                        help="walk folders recursively")
+    parser.add_argument("-n", "--naming-template", metavar="PATTERN",
+                        default=None,
+                        help=f"name pattern with placeholders "
+                             f"{', '.join('{%s}' % t for t in TEMPLATE_FIELDS)}; "
+                             f"the extension is appended automatically "
+                             f"(default: \"{DEFAULT_TEMPLATE}\")")
+    ocr_group = parser.add_mutually_exclusive_group()
+    ocr_group.add_argument("--no-ocr", action="store_true",
+                           help="never OCR scanned pages")
+    ocr_group.add_argument("--force-ocr", action="store_true",
+                           help="always OCR the leading pages and use that "
+                                "text instead of the built-in text layer "
+                                "(for PDFs with a broken encoding)")
+    parser.add_argument("--ocr-pages", type=int, default=2, metavar="N",
+                        help="how many leading pages to OCR (default: 2)")
+
+    ai_group = parser.add_argument_group(
+        "AI (vision LLM over the cover; enabled only by --ai)")
+    ai_group.add_argument("--ai", action="store_true",
+                          help="ask a vision LLM to read the document cover; "
+                               "its answer outranks the heuristics "
+                               "(OpenAI-compatible API: cloud or local Ollama)")
+    ai_group.add_argument("--ai-url", metavar="URL",
+                          default=os.environ.get("TITLEMARK_AI_URL", DEFAULT_AI_URL),
+                          help=f"API endpoint (default: {DEFAULT_AI_URL}; "
+                               "for Ollama: http://localhost:11434/v1; "
+                               "env TITLEMARK_AI_URL)")
+    ai_group.add_argument("--ai-model", metavar="MODEL",
+                          default=os.environ.get("TITLEMARK_AI_MODEL", DEFAULT_AI_MODEL),
+                          help=f"model name (default: {DEFAULT_AI_MODEL}; "
+                               "for Ollama: moondream, llava; "
+                               "env TITLEMARK_AI_MODEL)")
+    ai_group.add_argument("--ai-key", metavar="KEY",
+                          default=os.environ.get("TITLEMARK_AI_KEY", ""),
+                          help="API key (env TITLEMARK_AI_KEY); "
+                               "not needed for local Ollama")
+    ai_group.add_argument("--ai-timeout", type=int, default=60, metavar="SEC",
+                          help="AI request timeout in seconds (default: 60)")
+    parser.add_argument("--no-year", action="store_true",
+                        help="do not append the year to file names")
+    parser.add_argument("--title-from-text", action="store_true",
+                        help="build the title from the WHOLE page text without "
+                             "special characters (title fragments are joined "
+                             "into one), instead of picking candidate lines")
+    parser.add_argument("--title-pages", type=int, default=1, metavar="N",
+                        help="how many leading pages to take for "
+                             "--title-from-text (default: 1)")
+    parser.add_argument("--report", type=Path, metavar="CSV",
+                        help="save the plan as a CSV report")
+    parser.add_argument("-v", "--verbose", action="store_true",
+                        help="show title candidates, warnings and text snippets")
+    parser.add_argument("-q", "--quiet", action="store_true",
+                        help="print only the summary")
+    return parser
+
+
+def _short(text: str, width: int) -> str:
+    return text if len(text) <= width else text[: width - 1] + "…"
+
+
+def _print_plan(plans, verbose: bool = False) -> None:
+    for plan in plans:
+        mark = _STATUS_MARK.get(plan.status, "?")
+        if plan.status == "ok" and plan.new_name:
+            info = plan.info
+            src = info.title_source.value if info else "?"
+            print(f"{mark} {plan.path.name}")
+            print(f"  -> {_short(plan.new_name, 150)}  [{src}]")
+        elif plan.status == "same":
+            print(f"{mark} {plan.path.name}  (name already fits)")
+        else:
+            print(f"{mark} {plan.path.name}  ({plan.detail or plan.status})")
+
+        if verbose and plan.info and plan.status == "ok":
+            info = plan.info
+            if info.author:
+                print(f"     author: {info.author} [{info.author_source.value}]")
+            if info.year:
+                print(f"     year:   {info.year}")
+            for cand, score in info.title_candidates[:3]:
+                print(f"     candidate ({score}): {_short(cand, 90)}")
+            for warn in info.warnings:
+                print(f"     ! {warn}")
+            if info.text_snippet:
+                snippet = _short(info.text_snippet.replace("\n", " ⏎ "), 160)
+                print(f"     text: {snippet}")
+
+
+def _print_summary(plans) -> None:
+    counts: dict[str, int] = {}
+    for plan in plans:
+        counts[plan.status] = counts.get(plan.status, 0) + 1
+    print()
+    print(f"Total files: {len(plans)}")
+    for status in ("ok", "same", "no-title", "unsupported", "error"):
+        if counts.get(status):
+            print(f"  {status:<12}: {counts[status]}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.naming_template:
+        problem = validate_template(args.naming_template)
+        if problem:
+            print(f"bad --naming-template: {problem}", file=sys.stderr)
+            return 2
+
+    missing = [p for p in args.paths if not p.exists()]
+    if missing:
+        for path in missing:
+            print(f"path not found: {path}", file=sys.stderr)
+        return 2
+
+    ai_config = None
+    if args.ai:
+        from .ai import AiConfig
+
+        if not args.ai_key and not ("localhost" in args.ai_url
+                                    or "127.0.0.1" in args.ai_url):
+            print("a cloud API key is required: --ai-key or TITLEMARK_AI_KEY "
+                  "(local Ollama needs no key)", file=sys.stderr)
+            return 2
+        ai_config = AiConfig(url=args.ai_url, model=args.ai_model,
+                             api_key=args.ai_key, timeout=args.ai_timeout)
+
+    plans = plan_many(
+        args.paths,
+        recursive=args.recursive,
+        use_ocr=not args.no_ocr,
+        ocr_pages=args.ocr_pages,
+        include_year=not args.no_year,
+        force_ocr=args.force_ocr,
+        ai=ai_config,
+        title_from_text=args.title_pages if args.title_from_text else 0,
+        naming_template=args.naming_template,
+    )
+
+    if not plans:
+        print("No supported files found.", file=sys.stderr)
+        return 1
+
+    if not args.quiet:
+        mode = "RENAMING" if args.apply else "PLAN (dry-run, no files changed)"
+        print(f"=== {mode} ===")
+        _print_plan(plans, verbose=args.verbose)
+
+    if args.apply:
+        renamed = apply_plans(plans)
+        print(f"Renamed: {len(renamed)}")
+    else:
+        to_rename = sum(1 for p in plans if p.status == "ok")
+        print(f"Will rename: {to_rename} (run with --apply)")
+
+    if args.report:
+        write_csv_report(plans, args.report)
+        print(f"Report saved: {args.report}")
+
+    _print_summary(plans)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

titlemark/extractors/__init__.py

@@ -0,0 +1,56 @@
+"""Реестр экстракторов: выбираем обработчик по расширению файла.
+
+Если расширения нет или оно неизвестное (файлы-хэши из папок загрузок),
+формат определяется по сигнатуре — см. titlemark.signature.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .base import Extractor
+from .djvu import DjvuExtractor
+from .docx import DocxExtractor
+from .epub import EpubExtractor
+from .fb2 import Fb2Extractor
+from .mobi import MobiExtractor
+from .pdf import PdfExtractor
+from ..signature import detect_extension
+
+_EXTRACTORS: list[Extractor] = [
+    PdfExtractor(),
+    EpubExtractor(),
+    Fb2Extractor(),
+    MobiExtractor(),
+    DjvuExtractor(),
+    DocxExtractor(),
+]
+
+_BY_EXT: dict[str, Extractor] = {}
+for _ext in _EXTRACTORS:
+    for _suffix in _ext.extensions:
+        _BY_EXT[_suffix] = _ext
+
+
+def supported_extensions() -> tuple[str, ...]:
+    """Все расширения, которые умеет обрабатывать проект."""
+    return tuple(sorted(_BY_EXT))
+
+
+def get_extractor(path: Path) -> Extractor | None:
+    """Экстрактор для файла или None, если формат не поддерживается.
+
+    Сначала смотрим на расширение; если его нет или оно неизвестное —
+    определяем формат по сигнатуре содержимого.
+    """
+    extractor = _BY_EXT.get(path.suffix.lower())
+    if extractor is not None:
+        return extractor
+    return _BY_EXT.get(detect_extension(path))
+
+
+__all__ = [
+    "Extractor",
+    "get_extractor",
+    "supported_extensions",
+]

titlemark/extractors/base.py

@@ -0,0 +1,135 @@
+"""Базовый интерфейс экстракторов и общий конвейер разбора текста."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from ..models import DocumentInfo, Source, TextQuality
+from ..textclean import clean_author, clean_title, is_junk_title, text_quality
+from ..titlefinder import find_author, find_title, merge_title
+
+
+class Extractor(ABC):
+    """Извлекает сведения о документе из файла своего формата."""
+
+    #: расширения, которые обслуживает экстрактор
+    extensions: tuple[str, ...] = ()
+    #: умеет ли формат «лечить» отсутствие текста через OCR
+    ocr_capable: bool = False
+
+    @abstractmethod
+    def read_metadata(self, path: Path) -> tuple[str, str, str]:
+        """Вернуть (title, author, year) из метаданных файла."""
+
+    def read_text(self, path: Path, max_pages: int = 3) -> str:
+        """Вернуть текст первых страниц (пустая строка, если формат не умеет)."""
+        return ""
+
+    # ------------------------------------------------------------------
+    def extract(self, path: Path, use_ocr: bool = True, ocr_pages: int = 2,
+                force_ocr: bool = False,
+                title_from_full_text: int = 0) -> DocumentInfo:
+        """Полный разбор файла: метаданные → текстовый слой → (опц.) OCR.
+
+        force_ocr=True — распознать первые страницы через OCR обязательно
+        и использовать именно этот текст (штатный текстовый слой бывает
+        кривым: неверная кодировка, раздробленные слова).
+
+        title_from_full_text=N — название собирается из ВСЕГО текста первых
+        N страниц без спецсимволов, а не из отдельных строк-кандидатов.
+        """
+        info = DocumentInfo(path=path, format=path.suffix.lower().lstrip("."))
+
+        meta_title, meta_author, year = self.read_metadata(path)
+        # мусорность проверяем по СЫРОЙ строке метаданных («Pamyat_text 02.indd»)
+        # и ещё раз после очистки («… @bookinier», «… издательство …»)
+        if meta_title and not is_junk_title(meta_title):
+            meta_title = clean_title(meta_title)
+            if meta_title and not is_junk_title(meta_title):
+                info.title = meta_title
+                info.title_source = Source.METADATA
+        meta_author = clean_author(meta_author)
+        if meta_author:
+            info.author = meta_author
+            info.author_source = Source.METADATA
+        if year:
+            info.year = year
+
+        pages = title_from_full_text if title_from_full_text > 0 else 3
+        text = self.read_text(path, max_pages=pages)
+        quality = text_quality(text)
+        info.text_snippet = text[:400]
+        used_text, used_source = text, Source.TEXT
+
+        used_forced_ocr = False
+        if force_ocr and self.ocr_capable:
+            from ..ocr import ocr_first_pages
+
+            ocr_text = ocr_first_pages(path, pages=ocr_pages)
+            if ocr_text.strip():
+                info.warnings.append("OCR forced by --force-ocr")
+                self._fill_from_text(info, ocr_text, source=Source.OCR, override=True)
+                used_text, used_source = ocr_text, Source.OCR
+                used_forced_ocr = True
+            else:
+                info.warnings.append("OCR produced no text — text layer used")
+
+        if not used_forced_ocr:
+            if quality is TextQuality.GOOD:
+                self._fill_from_text(info, text, source=Source.TEXT)
+            elif use_ocr and self.ocr_capable:
+                from ..ocr import ocr_first_pages
+
+                ocr_text = ocr_first_pages(path, pages=ocr_pages)
+                if ocr_text.strip():
+                    info.warnings.append("text layer missing/broken — OCR used")
+                    self._fill_from_text(info, ocr_text, source=Source.OCR)
+                    used_text, used_source = ocr_text, Source.OCR
+                elif not info.title:
+                    info.warnings.append("no text layer and OCR failed")
+
+        # режим «название из всего текста»: склеиваем содержательные строки
+        if title_from_full_text > 0 and used_text.strip():
+            from ..titlefinder import full_text_title
+
+            full_title = full_text_title(used_text, exclude_author=info.author)
+            if full_title:
+                info.title = full_title
+                info.title_source = used_source
+                info.warnings.append(
+                    f"title built from the full text of the first "
+                    f"{title_from_full_text} page(s) (--title-from-text)")
+
+        return info
+
+    # ------------------------------------------------------------------
+    def _fill_from_text(self, info: DocumentInfo, text: str,
+                        source: Source = Source.TEXT,
+                        override: bool = False) -> None:
+        """Заполнить title/author из текста, если метаданных не хватило.
+
+        override=True — текст главнее метаданных (принудительный OCR).
+        """
+        from ..titlefinder import join_fragment_lines
+
+        lines = join_fragment_lines(
+            [ln.rstrip() for ln in text.splitlines() if ln.strip()])
+        if not lines:
+            return
+
+        title, _score, candidates = find_title(lines)
+        info.title_candidates = candidates
+        if title:
+            title = clean_title(merge_title(lines, title))
+        if title and (override or not info.title
+                      or info.title_source is not Source.METADATA):
+            info.title = title
+            info.title_source = source
+
+        # строки, вошедшие в название, уже не автор
+        author = clean_author(find_author(lines, exclude_title=title))
+        if author and (override or not info.author
+                       or info.author_source is not Source.METADATA):
+            info.author = author
+            info.author_source = source