titlemark 1.2.0__tar.gz

titlemark-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergei Korneev (AI coded)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

titlemark-1.2.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: titlemark
+Version: 1.2.0
+Summary: Titlemark — give every document its true name: "Author - Title [year]"
+Author: Sergei Korneev (AI coded)
+License: MIT
+Project-URL: Homepage, https://github.com/Sergei-Korneev/titlemark
+Project-URL: Repository, https://github.com/Sergei-Korneev/titlemark
+Project-URL: Issues, https://github.com/Sergei-Korneev/titlemark/issues
+Keywords: rename,filename,title,author,metadata,ocr,pdf,epub,fb2,mobi,djvu,docx,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Titlemark
+
+> *titlemark (n.)* — in early printing, the short title set at the head of a
+> page to mark the book it came from.
+
+**Titlemark** is a console tool that reads a document, works out its *title*
+and *author*, and renames the file into something a human would recognise:
+
+```
+29623753.pdf                    ->  David Knickerbocker - Network Science with Python [2023].pdf
+43b2956cd82bc62159778acf….pdf   ->  Артур Думчев - ПОМНИТЬ ВСЕ ПРАКТИЧЕСКОЕ РУКОВОДСТВО ПО РАЗВИТИЮ ПАМЯТИ [2013].pdf
+345852.fb2                      ->  Штюрмер Ю. А. - Карманный справочник туриста.fb2
+```
+
+It works **fully offline** — no LLM, no external services. Just heuristics
+over file metadata, the text layer, and OCR for scans.
+
+## Supported formats
+
+| Format | Metadata | Text | OCR |
+|--------|----------|------|-----|
+| PDF    | pdfinfo | pdftotext (poppler) | pdftoppm + tesseract |
+| EPUB   | package.opf (dc:title, dc:creator, dc:date) | – | – |
+| FB2    | title-info (book-title, author, date) | – | – |
+| MOBI   | PalmDB + EXTH (title, author, date) | – | – |
+| DJVU   | ANTa annotations (title, author) | djvutxt (djvulibre) | ddjvu + tesseract |
+| DOCX   | docProps/core.xml | first paragraphs | – |
+
+**Files without an extension** (hash-named downloads) are recognised by their
+signature — magic bytes for PDF/DjVu/MOBI, the container structure for
+EPUB/DOCX, the `FictionBook` root for FB2 — and the renamed file gets the
+proper extension. The same works for files with a wrong or unknown extension.
+
+## Requirements
+
+* Python ≥ 3.10, standard library only;
+* for PDF: `poppler-utils` (`pdfinfo`, `pdftotext`, `pdftoppm`);
+* for scans (optional): `tesseract` with `rus+eng` language packs;
+* for DjVu (optional): `djvulibre` tools (`djvutxt`, `ddjvu`) — without them
+  DjVu text/OCR is unavailable (annotations ANTa are still read).
+
+```bash
+# Debian/Ubuntu
+sudo apt install poppler-utils tesseract-ocr tesseract-ocr-rus tesseract-ocr-eng djvulibre-bin
+```
+
+## Install & run
+
+```bash
+# 1. straight from the source tree, no installation
+cd titlemark
+python3 -m titlemark --help
+
+# 2. user install — the `titlemark` command works from anywhere
+pip install --user .
+titlemark --help
+
+# 3. editable install for development (source edits apply immediately)
+pip install --user -e .
+```
+
+After `pip install --user` the command lands in `~/.local/bin`
+(make sure it is on your `PATH`). If you edit the project sources, either run
+from the project folder or reinstall — the editable install (`-e`) picks up
+changes without reinstalling.
+
+## Usage
+
+```bash
+titlemark book.pdf                   # show the plan (files are NOT touched)
+titlemark --apply book.pdf           # rename the file
+titlemark -r ~/Downloads             # plan for a whole folder, recursively
+titlemark --apply -r ~/Downloads     # rename everything in the folder
+titlemark --report plan.csv -r .     # save the plan as CSV
+titlemark --force-ocr book.pdf       # re-check a PDF whose text layer is broken
+titlemark --ai book.pdf              # let a vision LLM read the cover
+titlemark --title-from-text book.pdf # title = whole page text, fragments joined
+titlemark -n "{title}-{year}" book.pdf # custom name pattern
+titlemark -v book.pdf                # debug: title candidates, text snippet
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `paths` | file(s) or folder(s) to process |
+| `-a, --apply` | actually rename; **without this flag the tool only shows a plan (dry-run)** |
+| `-r, --recursive` | walk folders recursively |
+| `-n, --naming-template PATTERN` | name pattern with `{author}`, `{title}`, `{year}` placeholders; the extension is appended automatically (default: `{author} - {title} [{year}]`) |
+| `--no-ocr` | never OCR scanned pages (faster) |
+| `--force-ocr` | always OCR the leading pages and use that text instead of the built-in text layer (for PDFs with a broken encoding) |
+| `--ocr-pages N` | how many leading pages to OCR (default: 2) |
+| `--no-year` | do not append the year to file names |
+| `--title-from-text` | build the title from the **whole** page text without special characters (title fragments are joined), instead of picking single candidate lines |
+| `--title-pages N` | how many leading pages to take for `--title-from-text` (default: 1) |
+| `--report CSV` | write a report: old name, new name, source, status |
+| `-v, --verbose` | show title candidates and warnings |
+| `-q, --quiet` | print only the summary |
+
+### AI options (vision LLM, opt-in)
+
+| Option | Description |
+|--------|-------------|
+| `--ai` | ask a vision LLM to read the cover; its answer outranks the heuristics |
+| `--ai-url URL` | OpenAI-compatible endpoint (default `https://api.openai.com/v1`; Ollama: `http://localhost:11434/v1`) |
+| `--ai-model MODEL` | model name (default `gpt-4o-mini`; Ollama: `moondream`, `llava`, `llama3.2-vision`) |
+| `--ai-key KEY` | API key (or env `TITLEMARK_AI_KEY`; not needed for local Ollama) |
+| `--ai-timeout SEC` | request timeout (default 60) |
+
+Environment variables: `TITLEMARK_AI_URL`, `TITLEMARK_AI_MODEL`, `TITLEMARK_AI_KEY`.
+
+The AI is used **only when `--ai` is passed**. Titlemark renders the first page
+to PNG, shows it to the model together with the heuristic candidates, and gets
+back strict JSON `{"title", "author", "year"}`. If the model is unreachable or
+answers oddly, the heuristic result is kept and a warning is printed.
+
+```bash
+# cloud (OpenAI, DeepSeek, GigaChat, YandexGPT, … — any compatible API)
+export TITLEMARK_AI_KEY=sk-...
+titlemark --ai book.pdf
+
+# local Ollama, fully offline
+titlemark --ai --ai-url http://localhost:11434/v1 --ai-model moondream book.pdf
+```
+
+## How the name is chosen
+
+By default the name follows the pattern **`Author - Title [year].ext`**
+(just `Title [year].ext` when no author is found). The pattern is
+customizable: `--naming-template "{author} - {title}"`, `"{title}-{year}"`,
+`"{year}_{title}"` — empty values are dropped together with their separators,
+and the file extension is always appended automatically.
+
+Sources are tried from most to least reliable:
+
+1. **File metadata** — Title/Author/date. Junk values (`Microsoft Word - …`,
+   `Layout 1`, `Pamyat_text 02.indd`, hashes, upload ids) are discarded;
+2. **Text layer of the leading pages** — lines are scored by casing
+   (ALL CAPS / Title Case), position on the page, length and punctuation.
+   Service lines (ISBN, UDC, running heads, URLs), publisher imprints
+   («Москва · Санкт-Петербург», «O'Reilly cities»), section headings
+   («Table of Contents», «Preface») and name-like lines are rejected;
+   subtitle lines are merged into the title;
+3. **OCR of the leading pages** — when there is no text layer (a scan) or
+   it is broken: mojibake from exotic font encodings, split words
+   («W ICKED COOL», «SHELL SCRIP T S»);
+4. **The original file name** — used when the other sources produced only a
+   fragment («ВЕСЬ» of «Весь Linux…»), a cipher («М. МЦНМО, 2016»), a broken
+   bibliographic line or a bad OCR guess. Names like `Author - Title`,
+   `Title (Author)` and `03_Title_by_Author` are parsed apart.
+
+Telling a short author name from a short title (both may be set in caps:
+`АРТУР ДУМЧЕВ` vs `DARK MATTER`) is done with a compact dictionary of common
+Russian/English first names and their transliterations
+(`titlemark/names.py`) — easy to extend.
+
+Name lines in the forms «Surname F. M.», «F. M. Surname», «Surname, Name»
+and «by Jane Smith» are recognised by pattern. ALL-CAPS names are normalised
+(`АРТУР ДУМЧЕВ` → `Артур Думчев`), and service words («And Unix Systems»)
+never count as a person's name.
+
+## Safety
+
+* **nothing is renamed by default** — the tool prints a plan first;
+* name collisions are resolved with ` (2)`, ` (3)` suffixes;
+* the file extension is preserved, forbidden characters become spaces;
+* names are capped at 200 **bytes** (the FS limit is 255 bytes per path
+  component, and Cyrillic takes 2 bytes per character), cut at a word
+  boundary with `…`;
+* the year is appended only when it was found in metadata or in the
+  original file name.
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+128 tests: title/author heuristics, text cleaning, mojibake detection,
+file-name building, file-name parsing, synthetic files for every supported
+format, and rename scenarios.
+
+## Project layout
+
+```
+titlemark/
+├── titlemark/
+│   ├── cli.py               # command line, plan output
+│   ├── renamer.py           # rename planning and execution
+│   ├── titlefinder.py       # heuristics: title and author from text
+│   ├── names.py             # name dictionary: "author" vs "title"
+│   ├── textclean.py         # string cleanup, mojibake detection
+│   ├── naming.py            # file-name building, limits, collisions
+│   ├── ocr.py               # OCR of leading pages (pdftoppm + tesseract)
+│   ├── signature.py         # format detection by signature (extensionless files)
+│   ├── ai.py                # vision LLM cover recognition (--ai, OpenAI-compatible)
+│   ├── models.py            # DocumentInfo, Source, TextQuality
+│   └── extractors/          # PDF, EPUB, FB2, MOBI, DJVU, DOCX
+├── tests/
+├── pyproject.toml
+├── README.md                # this file
+└── README.ru.md             # Russian documentation
+```
+
+## Author
+
+**Sergei Korneev (AI coded)** — version 1.1.0 (`titlemark --version`).

titlemark-1.2.0/README.md

@@ -0,0 +1,207 @@
+# Titlemark
+
+> *titlemark (n.)* — in early printing, the short title set at the head of a
+> page to mark the book it came from.
+
+**Titlemark** is a console tool that reads a document, works out its *title*
+and *author*, and renames the file into something a human would recognise:
+
+```
+29623753.pdf                    ->  David Knickerbocker - Network Science with Python [2023].pdf
+43b2956cd82bc62159778acf….pdf   ->  Артур Думчев - ПОМНИТЬ ВСЕ ПРАКТИЧЕСКОЕ РУКОВОДСТВО ПО РАЗВИТИЮ ПАМЯТИ [2013].pdf
+345852.fb2                      ->  Штюрмер Ю. А. - Карманный справочник туриста.fb2
+```
+
+It works **fully offline** — no LLM, no external services. Just heuristics
+over file metadata, the text layer, and OCR for scans.
+
+## Supported formats
+
+| Format | Metadata | Text | OCR |
+|--------|----------|------|-----|
+| PDF    | pdfinfo | pdftotext (poppler) | pdftoppm + tesseract |
+| EPUB   | package.opf (dc:title, dc:creator, dc:date) | – | – |
+| FB2    | title-info (book-title, author, date) | – | – |
+| MOBI   | PalmDB + EXTH (title, author, date) | – | – |
+| DJVU   | ANTa annotations (title, author) | djvutxt (djvulibre) | ddjvu + tesseract |
+| DOCX   | docProps/core.xml | first paragraphs | – |
+
+**Files without an extension** (hash-named downloads) are recognised by their
+signature — magic bytes for PDF/DjVu/MOBI, the container structure for
+EPUB/DOCX, the `FictionBook` root for FB2 — and the renamed file gets the
+proper extension. The same works for files with a wrong or unknown extension.
+
+## Requirements
+
+* Python ≥ 3.10, standard library only;
+* for PDF: `poppler-utils` (`pdfinfo`, `pdftotext`, `pdftoppm`);
+* for scans (optional): `tesseract` with `rus+eng` language packs;
+* for DjVu (optional): `djvulibre` tools (`djvutxt`, `ddjvu`) — without them
+  DjVu text/OCR is unavailable (annotations ANTa are still read).
+
+```bash
+# Debian/Ubuntu
+sudo apt install poppler-utils tesseract-ocr tesseract-ocr-rus tesseract-ocr-eng djvulibre-bin
+```
+
+## Install & run
+
+```bash
+# 1. straight from the source tree, no installation
+cd titlemark
+python3 -m titlemark --help
+
+# 2. user install — the `titlemark` command works from anywhere
+pip install --user .
+titlemark --help
+
+# 3. editable install for development (source edits apply immediately)
+pip install --user -e .
+```
+
+After `pip install --user` the command lands in `~/.local/bin`
+(make sure it is on your `PATH`). If you edit the project sources, either run
+from the project folder or reinstall — the editable install (`-e`) picks up
+changes without reinstalling.
+
+## Usage
+
+```bash
+titlemark book.pdf                   # show the plan (files are NOT touched)
+titlemark --apply book.pdf           # rename the file
+titlemark -r ~/Downloads             # plan for a whole folder, recursively
+titlemark --apply -r ~/Downloads     # rename everything in the folder
+titlemark --report plan.csv -r .     # save the plan as CSV
+titlemark --force-ocr book.pdf       # re-check a PDF whose text layer is broken
+titlemark --ai book.pdf              # let a vision LLM read the cover
+titlemark --title-from-text book.pdf # title = whole page text, fragments joined
+titlemark -n "{title}-{year}" book.pdf # custom name pattern
+titlemark -v book.pdf                # debug: title candidates, text snippet
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `paths` | file(s) or folder(s) to process |
+| `-a, --apply` | actually rename; **without this flag the tool only shows a plan (dry-run)** |
+| `-r, --recursive` | walk folders recursively |
+| `-n, --naming-template PATTERN` | name pattern with `{author}`, `{title}`, `{year}` placeholders; the extension is appended automatically (default: `{author} - {title} [{year}]`) |
+| `--no-ocr` | never OCR scanned pages (faster) |
+| `--force-ocr` | always OCR the leading pages and use that text instead of the built-in text layer (for PDFs with a broken encoding) |
+| `--ocr-pages N` | how many leading pages to OCR (default: 2) |
+| `--no-year` | do not append the year to file names |
+| `--title-from-text` | build the title from the **whole** page text without special characters (title fragments are joined), instead of picking single candidate lines |
+| `--title-pages N` | how many leading pages to take for `--title-from-text` (default: 1) |
+| `--report CSV` | write a report: old name, new name, source, status |
+| `-v, --verbose` | show title candidates and warnings |
+| `-q, --quiet` | print only the summary |
+
+### AI options (vision LLM, opt-in)
+
+| Option | Description |
+|--------|-------------|
+| `--ai` | ask a vision LLM to read the cover; its answer outranks the heuristics |
+| `--ai-url URL` | OpenAI-compatible endpoint (default `https://api.openai.com/v1`; Ollama: `http://localhost:11434/v1`) |
+| `--ai-model MODEL` | model name (default `gpt-4o-mini`; Ollama: `moondream`, `llava`, `llama3.2-vision`) |
+| `--ai-key KEY` | API key (or env `TITLEMARK_AI_KEY`; not needed for local Ollama) |
+| `--ai-timeout SEC` | request timeout (default 60) |
+
+Environment variables: `TITLEMARK_AI_URL`, `TITLEMARK_AI_MODEL`, `TITLEMARK_AI_KEY`.
+
+The AI is used **only when `--ai` is passed**. Titlemark renders the first page
+to PNG, shows it to the model together with the heuristic candidates, and gets
+back strict JSON `{"title", "author", "year"}`. If the model is unreachable or
+answers oddly, the heuristic result is kept and a warning is printed.
+
+```bash
+# cloud (OpenAI, DeepSeek, GigaChat, YandexGPT, … — any compatible API)
+export TITLEMARK_AI_KEY=sk-...
+titlemark --ai book.pdf
+
+# local Ollama, fully offline
+titlemark --ai --ai-url http://localhost:11434/v1 --ai-model moondream book.pdf
+```
+
+## How the name is chosen
+
+By default the name follows the pattern **`Author - Title [year].ext`**
+(just `Title [year].ext` when no author is found). The pattern is
+customizable: `--naming-template "{author} - {title}"`, `"{title}-{year}"`,
+`"{year}_{title}"` — empty values are dropped together with their separators,
+and the file extension is always appended automatically.
+
+Sources are tried from most to least reliable:
+
+1. **File metadata** — Title/Author/date. Junk values (`Microsoft Word - …`,
+   `Layout 1`, `Pamyat_text 02.indd`, hashes, upload ids) are discarded;
+2. **Text layer of the leading pages** — lines are scored by casing
+   (ALL CAPS / Title Case), position on the page, length and punctuation.
+   Service lines (ISBN, UDC, running heads, URLs), publisher imprints
+   («Москва · Санкт-Петербург», «O'Reilly cities»), section headings
+   («Table of Contents», «Preface») and name-like lines are rejected;
+   subtitle lines are merged into the title;
+3. **OCR of the leading pages** — when there is no text layer (a scan) or
+   it is broken: mojibake from exotic font encodings, split words
+   («W ICKED COOL», «SHELL SCRIP T S»);
+4. **The original file name** — used when the other sources produced only a
+   fragment («ВЕСЬ» of «Весь Linux…»), a cipher («М. МЦНМО, 2016»), a broken
+   bibliographic line or a bad OCR guess. Names like `Author - Title`,
+   `Title (Author)` and `03_Title_by_Author` are parsed apart.
+
+Telling a short author name from a short title (both may be set in caps:
+`АРТУР ДУМЧЕВ` vs `DARK MATTER`) is done with a compact dictionary of common
+Russian/English first names and their transliterations
+(`titlemark/names.py`) — easy to extend.
+
+Name lines in the forms «Surname F. M.», «F. M. Surname», «Surname, Name»
+and «by Jane Smith» are recognised by pattern. ALL-CAPS names are normalised
+(`АРТУР ДУМЧЕВ` → `Артур Думчев`), and service words («And Unix Systems»)
+never count as a person's name.
+
+## Safety
+
+* **nothing is renamed by default** — the tool prints a plan first;
+* name collisions are resolved with ` (2)`, ` (3)` suffixes;
+* the file extension is preserved, forbidden characters become spaces;
+* names are capped at 200 **bytes** (the FS limit is 255 bytes per path
+  component, and Cyrillic takes 2 bytes per character), cut at a word
+  boundary with `…`;
+* the year is appended only when it was found in metadata or in the
+  original file name.
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+128 tests: title/author heuristics, text cleaning, mojibake detection,
+file-name building, file-name parsing, synthetic files for every supported
+format, and rename scenarios.
+
+## Project layout
+
+```
+titlemark/
+├── titlemark/
+│   ├── cli.py               # command line, plan output
+│   ├── renamer.py           # rename planning and execution
+│   ├── titlefinder.py       # heuristics: title and author from text
+│   ├── names.py             # name dictionary: "author" vs "title"
+│   ├── textclean.py         # string cleanup, mojibake detection
+│   ├── naming.py            # file-name building, limits, collisions
+│   ├── ocr.py               # OCR of leading pages (pdftoppm + tesseract)
+│   ├── signature.py         # format detection by signature (extensionless files)
+│   ├── ai.py                # vision LLM cover recognition (--ai, OpenAI-compatible)
+│   ├── models.py            # DocumentInfo, Source, TextQuality
+│   └── extractors/          # PDF, EPUB, FB2, MOBI, DJVU, DOCX
+├── tests/
+├── pyproject.toml
+├── README.md                # this file
+└── README.ru.md             # Russian documentation
+```
+
+## Author
+
+**Sergei Korneev (AI coded)** — version 1.1.0 (`titlemark --version`).

titlemark-1.2.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "titlemark"
+version = "1.2.0"
+description = "Titlemark — give every document its true name: \"Author - Title [year]\""
+readme = "README.md"
+authors = [{ name = "Sergei Korneev (AI coded)" }]
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = [
+    "rename", "filename", "title", "author", "metadata", "ocr",
+    "pdf", "epub", "fb2", "mobi", "djvu", "docx", "cli",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Utilities",
+]
+dependencies = []          # standard library + external tools only
+
+[project.urls]
+Homepage = "https://github.com/Sergei-Korneev/titlemark"
+Repository = "https://github.com/Sergei-Korneev/titlemark"
+Issues = "https://github.com/Sergei-Korneev/titlemark/issues"
+
+[project.scripts]
+titlemark = "titlemark.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["titlemark*"]

titlemark-1.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

titlemark-1.2.0/tests/test_ai.py

@@ -0,0 +1,141 @@
+"""Тесты ИИ-разбора обложки (--ai): сеть подменяется, без реальных запросов."""
+
+import json
+import tempfile
+import unittest
+import urllib.error
+from pathlib import Path
+from unittest import mock
+
+from titlemark.ai import (
+    AiConfig,
+    build_prompt,
+    enrich_with_ai,
+    parse_json_answer,
+)
+from titlemark.models import DocumentInfo, Source
+from titlemark.renamer import plan_rename
+
+AI_ANSWER = {"title": "A History of Modern Computing",
+             "author": "Paul E. Ceruzzi", "year": "2004"}
+
+
+def _fake_response(config, payload: dict) -> dict:
+    """Ответ эндпоинта /chat/completions."""
+    return {"choices": [{"message": {"content": json.dumps(AI_ANSWER, ensure_ascii=False)}}]}
+
+
+class TestParseAnswer(unittest.TestCase):
+    def test_plain_json(self):
+        self.assertEqual(parse_json_answer('{"title": "Книга"}'), {"title": "Книга"})
+
+    def test_markdown_fence(self):
+        text = '```json\n{"title": "Книга", "author": "Автор"}\n```'
+        self.assertEqual(parse_json_answer(text)["title"], "Книга")
+
+    def test_text_around_json(self):
+        text = 'Вот ответ:\n{"title": "Книга"}\nГотово.'
+        self.assertEqual(parse_json_answer(text), {"title": "Книга"})
+
+    def test_garbage(self):
+        self.assertEqual(parse_json_answer("не понял вопрос"), {})
+        self.assertEqual(parse_json_answer(""), {})
+
+
+class TestEnrichWithAi(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self._tmp.cleanup)
+        self.path = Path(self._tmp.name) / "00acaf02b9dfa6495f4842bd5de2a675"
+        self.path.write_bytes(b"%PDF-1.4 stub")
+        self.info = DocumentInfo(path=self.path, title="Черновик черновика")
+
+    def test_ai_overrides_heuristics(self):
+        with mock.patch("titlemark.ai._request", side_effect=_fake_response), \
+             mock.patch("titlemark.ai.render_cover", return_value=b"png-bytes"):
+            ok = enrich_with_ai(self.path, self.info, AiConfig(api_key="k"))
+        self.assertTrue(ok)
+        self.assertEqual(self.info.title, "A History of Modern Computing")
+        self.assertEqual(self.info.author, "Paul E. Ceruzzi")
+        self.assertEqual(self.info.year, "2004")
+        self.assertIs(self.info.title_source, Source.AI)
+
+    def test_cover_attached_as_image(self):
+        captured = {}
+
+        def fake_request(config, payload):
+            captured.update(payload)
+            return _fake_response(config, payload)
+
+        with mock.patch("titlemark.ai._request", side_effect=fake_request), \
+             mock.patch("titlemark.ai.render_cover", return_value=b"png-bytes"):
+            enrich_with_ai(self.path, self.info, AiConfig(api_key="k"))
+        content = captured["messages"][1]["content"]
+        self.assertIsInstance(content, list)
+        self.assertEqual(content[0]["type"], "image_url")
+        self.assertIn("base64", content[0]["image_url"]["url"])
+
+    def test_text_only_when_no_cover(self):
+        captured = {}
+
+        def fake_request(config, payload):
+            captured.update(payload)
+            return _fake_response(config, payload)
+
+        with mock.patch("titlemark.ai._request", side_effect=fake_request), \
+             mock.patch("titlemark.ai.render_cover", return_value=None):
+            enrich_with_ai(self.path, self.info, AiConfig(api_key="k"))
+        self.assertIsInstance(captured["messages"][1]["content"], str)
+        self.assertTrue(any("cover" in w for w in self.info.warnings))
+
+    def test_network_error_keeps_heuristics(self):
+        with mock.patch("titlemark.ai.render_cover", return_value=b"png"), \
+             mock.patch("titlemark.ai._request",
+                        side_effect=urllib.error.URLError("нет сети")):
+            ok = enrich_with_ai(self.path, self.info, AiConfig(api_key="k"))
+        self.assertFalse(ok)
+        self.assertEqual(self.info.title, "Черновик черновика")   # не тронуто
+        self.assertTrue(any("the AI did not respond" in w for w in self.info.warnings))
+
+    def test_prompt_contains_hints(self):
+        self.info.title_candidates = [("Кандидат один", 5.0)]
+        prompt = build_prompt(self.info)
+        self.assertIn("Черновик черновика", prompt)
+        self.assertIn("Кандидат один", prompt)
+
+
+class TestPlanWithAi(unittest.TestCase):
+    def test_plan_rename_uses_ai_title(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            p = Path(tmp) / "00acaf02b9dfa6495f4842bd5de2a675"
+            p.write_bytes(b"%PDF-1.4 stub")
+            with mock.patch("titlemark.ai._request", side_effect=_fake_response), \
+                 mock.patch("titlemark.ai.render_cover", return_value=b"png"):
+                plan = plan_rename(p, use_ocr=False, ai=AiConfig(api_key="k"))
+            self.assertEqual(plan.status, "ok")
+            self.assertEqual(
+                plan.new_name,
+                "Paul E. Ceruzzi - A History of Modern Computing [2004].pdf")
+
+
+class TestCliAi(unittest.TestCase):
+    def test_cloud_requires_key(self):
+        from titlemark.cli import main
+
+        with tempfile.NamedTemporaryFile(suffix=".pdf") as fh:
+            code = main(["--ai", fh.name])
+        self.assertEqual(code, 2)
+
+    def test_local_needs_no_key(self):
+        from titlemark.cli import main
+
+        with tempfile.NamedTemporaryFile(suffix=".pdf") as fh:
+            code = main(["--ai", "--ai-url", "http://localhost:11434/v1",
+                         "--no-ocr", fh.name])
+        # без ключа локальный запуск проходит валидацию (сеть в тесте не ходим:
+        # ИИ вернёт ошибку — это warning, не падение)
+        self.assertEqual(code, 0)
+
+
+if __name__ == "__main__":
+    unittest.main()