graph-crawler 4.1.2__tar.gz → 4.1.4__tar.gz

{graph_crawler-4.1.2/graph_crawler.egg-info → graph_crawler-4.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graph-crawler
-Version: 4.1.2
+Version: 4.1.4
 Summary: Sync-First бібліотека для побудови графу веб-сайтів - просто як requests!
 Author: 0-EternalJunior-0
 Maintainer: 0-EternalJunior-0
@@ -38,6 +38,10 @@ Requires-Dist: aiofiles>=24.1.0
 Requires-Dist: aiosqlite>=0.20.0
 Requires-Dist: pybloom-live
 Requires-Dist: fastapi>=0.135.0
+Requires-Dist: tenacity>=9.0.0
+Requires-Dist: stop-words>=2018.7.23
+Requires-Dist: tiktoken>=0.13.0
+Requires-Dist: markdown-it-py>=4.0.0
 Provides-Extra: native
 Requires-Dist: cython>=3.0.0; extra == "native"
 Requires-Dist: mmh3>=5.0.0; extra == "native"

graph_crawler-4.1.4/docs/JS_REDIRECT_ANALYSIS.md

@@ -0,0 +1,184 @@
+# Аналіз: JS-редіректи й «втрата» адаптера між запитами
+
+> Контекст задачі від користувача: на прикладі сайту `4a-games.com.mt`
+> бібліотека сканувала сторінку вакансії як «головну», бо клієнтський JS на
+> ній через 2–3 секунди перенаправляв браузер на корінь сайту. Цього
+> бібліотека не помічала. Виявилось, що сайт використовує сервіс
+> `geotargetly-api-1.com` — гео-таргетер, який читає `window.location.href`
+> й `document.referrer`, асинхронно звертається до власного API і за
+> правилом редіректить через `location.href = ...`.
+
+## 1. Що помітив користувач
+
+* Відкриваєш у браузері `https://www.4a-games.com.mt/senior-technical-animator-new-ip`
+  напряму — через пару секунд клієнтський JS виконує
+  `window.location = "https://www.4a-games.com.mt/"`. Без правильного
+  `Referer` / cookies потрапити на сторінку вакансії неможливо.
+* Якщо відкрити `https://www.4a-games.com.mt/careers` та **колесом миші**
+  клікнути на посилання вакансії — у новій вкладці сторінка відкривається
+  й залишається. Це працює лише в **одному й тому самому браузері**, де
+  передались і `Referer`, і власні cookies.
+* Якщо скопіювати ту саму URL в інший браузер / іншу вкладку без переходу
+  через `/careers` — знов спрацьовує редірект.
+* Простий `GET`-запит через `requests` / `curl` показує повний HTML
+  вакансії — бо JS на сервері не виконується.
+
+Висновок: антипарсерний захист реалізований **на клієнті**, через JS,
+який перевіряє `document.referrer` / стан з `/careers` (cookies, history,
+sessionStorage) і у разі «холодного» переходу прибирає користувача на
+корінь сайту.
+
+## 2. Що з цим робить наша бібліотека сьогодні
+
+Перевіряв `graph_crawler/infrastructure/transport/playwright/driver.py`,
+гілка `main`, файли:
+
+* `PlaywrightDriver._fetch_async` — основний метод завантаження.
+* `PlaywrightDriver._create_context` — створює `BrowserContext`.
+* `PlaywrightDriver.fetch_many` — паралельне завантаження.
+
+Знайдені слабкі місця:
+
+| # | Проблема | Файл / місце | Наслідок |
+|---|----------|--------------|----------|
+| 1 | **На кожен `fetch()` створюється новий `BrowserContext`**: `pw_context = await self.browser.new_context(...)` | `driver.py:320` | Cookies, sessionStorage, історія навігації між URL-ами **повністю губляться**. Скрипт антибота вважає кожен запит «холодним». |
+| 2 | **`page.goto(url, wait_until=..., timeout=...)` НЕ передає `referer`** | `driver.py:477` | `document.referrer` у браузері порожній → JS вирішує, що користувач «прийшов з нізвідки», і редіректить. |
+| 3 | **Після `goto` ми не звіряємо `page.url` з оригінальним `url`**: одразу читаємо `await page.content()` | `driver.py:524` | Якщо JS уже встиг зробити `window.location = "/"` — ми збережемо HTML головної як HTML вакансії. Граф буде зіпсований. |
+| 4 | **`FetchResponse.final_url` і `redirect_chain` у Playwright-драйвері не заповнюються** (на відміну від `AsyncDriver` у `async_http/driver.py:303-304`). | `driver.py:574-580` | Подальші шари не мають можливості зрозуміти, що нас підмінили URL — навіть якщо вони перевіряють `is_redirect`. |
+| 5 | **Між `page.goto` й `page.content()` немає «settle» паузи** для виявлення JS-редіректу (`window.location`, `meta refresh`, `<script>`). | `driver.py:497-524` | Сторінка може ще «їхати» — ми зчитуємо HTML на льоту. |
+| 6 | `AsyncHTTPDriver` тримає одну `aiohttp.ClientSession` на драйвер → cookies зберігаються між URL-ами на одному домені. **АЛЕ** на goto/fetch не пробрасується `Referer`-заголовок із посилаючої сторінки. | `async_http/driver.py:294` | Для HTTP-режиму та сама проблема — `Referer`-захист не пройдемо. |
+
+## 3. Чому це важливо для графа
+
+`NodeScanner.scan_node`
+(`application/use_cases/crawling/node_scanner.py:147`) викликає
+`await self.driver.fetch(node.url)` без жодного контексту про те, **з якої
+сторінки** ми перейшли. У результаті:
+
+1. На `node` зі сторінки `/senior-...-new-ip` ми отримуємо HTML головної.
+2. На цій сторінці є посилання `/careers`, `/contact` тощо — ми ствердно
+   додаємо їх як дочірні до вакансії. Граф **жирніє хибними ребрами**.
+3. Якщо потім бібліотека повторно зайде на `/senior-...-new-ip` — знов
+   побачить ту саму «головну», тому що дедуплікатор за оригінальним `url`
+   дасть кеш.
+
+## 4. Як це працює всередині (короткий огляд)
+
+```
+NodeScanner.scan_node(node)
+        │
+        ▼
+PlaywrightDriver.fetch(url)
+        │
+        ├── _init_playwright()         // browser один раз на драйвер
+        ├── _create_context()          // нов. context, чисті cookies!
+        ├── pw_context.new_page()
+        ├── page.goto(url)             // referer ВІДСУТНІЙ
+        ├── await page.content()       // HTML «як є»
+        └── return FetchResponse(...)  // final_url=None завжди
+```
+
+## 5. Що ми пропонуємо змінити (мінімально-інвазивно)
+
+Усі правки сумісні зі старим API — нові аргументи опціональні.
+
+### 5.1. Опціональний `referer` для `fetch()`
+
+* `BaseDriver.fetch(self, url, *, referer: str | None = None)` — розширити
+  сигнатуру (без поломки існуючих імплементацій, бо вони можуть
+  проігнорувати).
+* У `PlaywrightDriver._fetch_async`: передати `referer` у
+  `page.goto(url, referer=referer, ...)`. Playwright офіційно підтримує
+  цей аргумент.
+* У `AsyncDriver.fetch`: додати `Referer` у `request_headers`, якщо
+  переданий.
+
+### 5.2. Persistent context per-domain у `PlaywrightDriver`
+
+* Нова опція в конфізі: `persistent_context_per_domain: bool = False`.
+* Якщо `True` — драйвер тримає кеш `dict[domain] -> BrowserContext` і
+  переюзає його. Cookies, sessionStorage, історія зберігаються →
+  крос-сторінкові переходи на одному домені імітують роботу справжнього
+  браузера.
+* Закриваються контексти у `close()`.
+
+### 5.3. Виявлення JS-редіректу: settle-затримка + перевірка `page.url`
+
+* Нова опція: `post_navigation_settle_ms: int = 0` (за замовч. 0, щоб
+  нічого не зламати в існуючих юзерах).
+* Якщо `> 0` — після `page.goto` (і `wait_for_selector`) робимо
+  `await asyncio.sleep(post_navigation_settle_ms / 1000)`.
+* Після цього порівнюємо `page.url` з оригінальним `url`. Якщо
+  відрізняються — заповнюємо `final_url` у `FetchResponse`, додатково лог
+  `WARNING` про JS-редірект.
+
+### 5.4. Заповнення `redirect_chain` і `final_url` у Playwright-режимі
+
+* Підписка `page.on("framenavigated", ...)` лише для **main frame**:
+  складаємо `redirect_chain` (без дублів) для подальшого аналізу.
+* `final_url = page.url` **після** `settle`-затримки (вже після можливих JS
+  редіректів) — це фінальна URL у браузерному сенсі.
+* Передаємо ці поля у
+  `FetchResponse(url=url, final_url=..., redirect_chain=...)`.
+
+### 5.5. Прокидання `referer` у `NodeScanner`
+
+* `Node` уже має `parent_id`. У `scan_node` шукати URL батька з графа (за
+  `parent_id`) і викликати `driver.fetch(node.url, referer=parent_url)`.
+* Для batch-сценарію (`fetch_many`) — додаємо опціональний паралельний
+  список `referrers: list[str | None] | None` й розкладаємо по
+  внутрішніх `fetch`. Якщо драйвер не підтримує — ігноруємо (зворотна
+  сумісність).
+
+### 5.6. Перевірка URL після сканування
+
+Як побажав користувач — «перевіряти не тільки на початку, а й у кінці
+сканування сторінки». Це 5.3 + 5.4: якщо `final_url != url`, можна:
+
+* пропустити node як «нерелевантний»;
+* або зберегти результат як `node.canonical_url = final_url`;
+* або повторно поставити в чергу новий URL для повноцінного сканування.
+
+Наразі обрано **м'який варіант**: фіксуємо `final_url` у `FetchResponse`,
+лог-warning, і дозволяємо вищому шару (graph_walker / node_scanner)
+прийняти рішення на основі прапора `is_redirect`. Це не змінює існуючу
+логіку графа для тих, хто `persistent_context` не вмикає.
+
+## 6. План тестів
+
+1. Юніт-тест `tests/test_playwright_referer.py`:
+   * мокаємо `playwright.async_api.async_playwright`;
+   * перевіряємо, що `page.goto` був викликаний саме з `referer=...`;
+   * перевіряємо, що `FetchResponse.final_url` заповнюється коли
+     mocked-page міняє `page.url` під час settle.
+
+2. Юніт-тест `tests/test_playwright_persistent_context.py`:
+   * mock browser → `new_context` має викликатися **один раз** для двох
+     послідовних `fetch()` на одному домені, коли
+     `persistent_context_per_domain=True`.
+
+3. Manual-тест `tests/manual_4a_games_test.py` — відтворює 4 сценарії: raw
+   HTTP, чистий Playwright, новий контекст-на-URL, контекст через
+   `/careers` + referer. Файл self-contained, можна запустити локально.
+
+## 7. Залишилось зовні зони (для майбутніх ітерацій)
+
+* `botasaurus_driver`, `undetected/*`, `cloudscraper_driver` — на них цей
+  самий референс не пробрасується. Якщо проект активно ними користується,
+  варто пройти тим же шаблоном.
+* Cookies SQLite-storage між запусками процесу: зараз `SessionManager`
+  уміє це для `requests`/`httpx`, але не для Playwright. Кандидат на
+  наступний PR — використати `BrowserContext.storage_state()` для
+  збереження/завантаження.
+
+## 8. Як перевірити вручну
+
+```bash
+# в кореневій папці job/
+python tests/manual_4a_games_test.py
+```
+
+У середовищі CI (без гео-Мальти) JS-редірект може не спрацювати — це
+нормально. Логіка `final_url != url` має лишитися **функціонально
+коректною** незалежно від того, чи редіректить сайт у цьому конкретному
+оточенні.

{graph_crawler-4.1.2 → graph_crawler-4.1.4}/docs/api/API.md

@@ -79,8 +79,9 @@ def crawl(
     max_depth: int = 3,
     max_pages: Optional[int] = 100,
     same_domain: bool = True,
+    allowed_domains: Optional[list[str]] = None,
     timeout: Optional[int] = None,
-    request_delay: float = 0.5,
+    request_delay: Optional[float] = None,
     follow_links: bool = True,
 
     # Компоненти
@@ -94,7 +95,6 @@ def crawl(
     node_class: Optional[type[Node]] = None,
     edge_class: Optional[type[Edge]] = None,
     url_rules: Optional[list[URLRule]] = None,
-    edge_rules: Optional[list[EdgeRule]] = None,
     edge_strategy: str = "all",
 
     # Callbacks
@@ -103,45 +103,64 @@ def crawl(
     on_error: Optional[Callable] = None,
     on_completed: Optional[Callable] = None,
 
+    # Low-memory режим
+    low_memory_mode: bool = False,
+    evict_threshold: int = 500,
+    eviction_storage_path: Optional[str] = None,
+
     # Distributed mode
     wrapper: Optional[dict] = None,
 ) -> Graph
 ```
 
-Синхронний краулінг веб-сайту - **простий як requests**.
+Синхронний краулінг веб-сайту. Працює як `requests` — функція приймає URL і повертає
+результат, не вимагаючи `async/await` або контекстних менеджерів.
 
-🆕 **NEW in v3.2.0:** Підтримка множинних точок входу (`seed_urls`) та продовження існуючого краулінгу (`base_graph`)!
+**Призначення:** одноразовий запуск краулінгу з простого Python-скрипта, CLI або
+notebook. Внутрішньо викликає `async_crawl()` через `asyncio.run` або через
+ThreadPoolExecutor (якщо вже працює event-loop, наприклад у Jupyter).
 
 **Параметри:**
 
-| Параметр          | Тип          | Default  | Опис                                                    |
-| ----------------- | ------------ | -------- | ------------------------------------------------------- |
-| `url`             | str          | None     | URL для початку краулінгу (якщо seed_urls не передано)  |
-| `seed_urls` 🆕    | list[str]    | None     | Список URL для початку краулінгу (множинні точки входу) |
-| `base_graph` 🆕   | Graph        | None     | Існуючий граф для продовження краулінгу (incremental)   |
-| `max_depth`       | int          | 3        | Максимальна глибина обходу                              |
-| `max_pages`       | int          | 100      | Максимальна кількість сторінок                          |
-| `same_domain`     | bool         | True     | Сканувати тільки поточний домен                         |
-| `timeout`         | int          | None     | Максимальний час в секундах                             |
-| `request_delay`   | float        | 0.5      | Затримка між запитами                                   |
-| `follow_links` 🆕 | bool         | True     | Переходити за посиланнями (False = тільки seed URLs)    |
-| `driver`          | str/IDriver  | "http"   | "http", "async", "playwright", "stealth"                |
-| `driver_config`   | dict         | None     | Конфігурація драйвера                                   |
-| `storage`         | str/IStorage | "memory" | "memory", "json", "sqlite", "postgresql"                |
-| `storage_config`  | dict         | None     | Конфігурація storage                                    |
-| `plugins`         | list         | default  | Список плагінів                                         |
-| `node_class`      | type         | Node     | Кастомний клас Node                                     |
-| `edge_class`      | type         | Edge     | Кастомний клас Edge                                     |
-| `url_rules`       | list         | None     | Список URLRule                                          |
-| `edge_rules` 🆕   | list         | None     | Список EdgeRule для контролю edges                      |
-| `edge_strategy`   | str          | "all"    | "all", "new_only", "max_in_degree", "deeper_only"       |
-| `on_progress`     | Callable     | None     | Callback для прогресу                                   |
-| `on_node_scanned` | Callable     | None     | Callback після сканування ноди                          |
-| `on_error`        | Callable     | None     | Callback для помилок                                    |
-| `on_completed`    | Callable     | None     | Callback після завершення                               |
-| `wrapper`         | dict         | None     | Конфіг distributed crawling                             |
-
-**Повертає:** `Graph`
+| Параметр                | Тип                | Default     | Опис                                                                                                                                                              |
+| ----------------------- | ------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `url`                   | str \| None        | None        | Початковий URL краулінгу. Обов'язковий, якщо не передано `seed_urls` або `base_graph`.                                                                            |
+| `seed_urls`             | list[str] \| None  | None        | Список початкових URL для багатоточкового старту. Якщо переданий разом з `url`, всі URL потрапляють до черги.                                                     |
+| `base_graph`            | Graph \| None      | None        | Готовий граф, з якого продовжується краулінг (інкрементальний режим). Усі його ноди вважаються відомими.                                                          |
+| `max_depth`             | int                | 3           | Максимальна глибина обходу від початкового URL. `0` — лише seed-ноди.                                                                                             |
+| `max_pages`             | int \| None        | 100         | Жорсткий ліміт кількості завантажених сторінок. `None` — без ліміту.                                                                                              |
+| `same_domain`           | bool               | True        | Якщо `True`, краулер не виходить за межі домену seed-URL. Ігнорується, якщо передано `allowed_domains`.                                                           |
+| `allowed_domains`       | list[str] \| None  | None        | Білий список доменів. Приймає прямі домени (`example.com`), вайлдкарди (`*.example.com`) або алiаси: `domain`, `subdomains`, `domain+subdomains`, `*` (будь-який). |
+| `timeout`               | int \| None        | None        | Максимальний час усього краулінгу в секундах. Після таймауту повертається частковий граф.                                                                         |
+| `request_delay`         | float \| None      | None        | Затримка (сек) між запитами до одного домену. `None` — використовується `DEFAULT_REQUEST_DELAY` з `shared.constants`.                                             |
+| `follow_links`          | bool               | True        | Якщо `False`, краулер обробляє лише seed URL без розкриття знайдених посилань.                                                                                    |
+| `driver`                | str \| IDriver     | "http"      | Транспорт для завантаження сторінок. Допустимі літерали: `http`, `async`, `playwright`, `stealth`. Можна передати власний інстанс `IDriver`.                      |
+| `driver_config`         | dict \| None       | None        | Параметри драйвера: `user_agent`, `headers`, `headless`, `browser_type`, `viewport_*`, `page_load_timeout` тощо. Див. розділ `DriverSettings`.                    |
+| `storage`               | str \| IStorage    | "memory"    | Backend для збереження графу: `memory`, `json`, `sqlite`, `postgresql`, `mongodb`. Або власний інстанс `IStorage`.                                                |
+| `storage_config`        | dict \| None       | None        | Параметри storage: `path`, `host`, `port`, `database`, `username`, `password`.                                                                                    |
+| `plugins`               | list \| None       | default set | Список `BaseNodePlugin` для extraction (metadata, links, text, structured data, NLP тощо). При `None` використовується дефолтний набір.                           |
+| `node_class`            | type[Node] \| None | None        | Підкласовий Node для додавання власних полів та методів обробки HTML.                                                                                             |
+| `edge_class`            | type[Edge] \| None | None        | Підкласовий Edge з власними атрибутами.                                                                                                                           |
+| `url_rules`             | list[Rule] \| None | None        | Список правил для priority/should\_scan/should\_follow\_links по regex-патернах URL.                                                                              |
+| `edge_strategy`         | str                | "all"       | Стратегія створення ребер: `all`, `new_only`, `max_in_degree`, `same_depth_only`, `deeper_only`, `first_encounter_only`.                                          |
+| `on_progress`           | Callable \| None   | None        | Колбек `fn(event_data)` для оновлень прогресу (виклик з пулу подій `PROGRESS_UPDATE`).                                                                            |
+| `on_node_scanned`       | Callable \| None   | None        | Колбек після завершення сканування кожної ноди.                                                                                                                   |
+| `on_error`              | Callable \| None   | None        | Колбек з payload помилки (URL, виняток, трасування).                                                                                                              |
+| `on_completed`          | Callable \| None   | None        | Колбек, що викликається один раз після завершення всього краулінгу.                                                                                               |
+| `low_memory_mode`       | bool               | False       | Увімкнення режиму обмеженого RAM. Виштовхує (`evict`) старі ноди на диск, тримаючи в пам'яті лише активне вікно.                                                  |
+| `evict_threshold`       | int                | 500         | Поріг кількості нод у пам'яті, після якого починається eviction. Діє лише з `low_memory_mode=True`.                                                               |
+| `eviction_storage_path` | str \| None        | None        | Шлях до директорії або файлу для evicted-нод. `None` — тимчасова директорія.                                                                                      |
+| `wrapper`               | dict \| None       | None        | Конфігурація розподіленого режиму (`broker`, `database`, `workers`). За наявності перемикає виконання на `distributed_crawl`.                                     |
+
+**Повертає:** `Graph` — повний граф сайту з нодами (`graph.nodes`) та ребрами
+(`graph.iter_edges()`). У випадку timeout повертається частковий граф.
+
+**Винятки:**
+
+- `ValueError` — якщо не передано жодного з `url`, `seed_urls`, `base_graph`,
+  або у distributed-режимі відсутній `url`.
+- `TimeoutError` — якщо краулінг не завершився у межах `timeout`.
+- `GraphCrawlerError` і підкласи — див. розділ **Exceptions**.
 
 **Приклади:**
 
@@ -198,13 +217,63 @@ graph = gc.crawl("https://example.com", wrapper=config)
 
 ```python
 async def async_crawl(
-    url: str,
+    url: Optional[str] = None,
     *,
-    # ... ті самі параметри що і crawl() (без wrapper)
+    seed_urls: Optional[list[str]] = None,
+    base_graph: Optional[Graph] = None,
+
+    # Основні параметри
+    max_depth: int = 3,
+    max_pages: Optional[int] = 100,
+    same_domain: bool = True,
+    allowed_domains: Optional[list[str]] = None,
+    timeout: Optional[int] = None,
+    request_delay: Optional[float] = None,
+    follow_links: bool = True,
+
+    # Компоненти
+    driver: Optional[str | IDriver] = None,
+    driver_config: Optional[dict] = None,
+    storage: Optional[str | IStorage] = None,
+    storage_config: Optional[dict] = None,
+    plugins: Optional[list[BaseNodePlugin]] = None,
+
+    # Кастомізація
+    node_class: Optional[type[Node]] = None,
+    edge_class: Optional[type[Edge]] = None,
+    url_rules: Optional[list[URLRule]] = None,
+    edge_strategy: str = "all",
+
+    # Callbacks
+    on_progress: Optional[Callable] = None,
+    on_node_scanned: Optional[Callable] = None,
+    on_error: Optional[Callable] = None,
+    on_completed: Optional[Callable] = None,
+
+    # Low-memory режим
+    low_memory_mode: bool = False,
+    evict_threshold: int = 500,
+    eviction_storage_path: Optional[str] = None,
+
+    # AI Agent integration
+    crawl_context: Optional[Any] = None,
+    control_channel: Optional[Any] = None,
 ) -> Graph
 ```
 
-Async версія crawl() для максимальної продуктивності.
+Асинхронна версія `crawl()`. Викликається з вже запущеного event-loop і дозволяє
+паралельний краулінг кількох сайтів через `asyncio.gather`. Підтримує всі параметри
+синхронної функції (крім `wrapper`, який наявний лише у `crawl()`), а також два
+додаткові параметри для інтеграції з AI-агентом.
+
+**Додаткові параметри (відсутні у `crawl()`):**
+
+| Параметр          | Тип        | Default | Опис                                                                                                                                                              |
+| ----------------- | ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `crawl_context`   | Any \| None | None    | Зовнішній контекст, що проброшується в плагіни та спайдер (зазвичай об'єкт `CrawlContext` з `ai/`). Дозволяє агенту читати/писати спільний стан під час краулінгу. |
+| `control_channel` | Any \| None | None    | Канал керування (наприклад `asyncio.Queue` або `ControlChannel`), через який зовнішній код може динамічно подавати команди: `pause`, `resume`, `stop`, `expand`.   |
+
+**Повертає:** `Graph` — побудований граф сайту.
 
 **Приклади:**
 
@@ -220,6 +289,25 @@ graphs = await asyncio.gather(
     gc.async_crawl("https://site1.com"),
     gc.async_crawl("https://site2.com"),
 )
+
+# Контрольований краулінг з AI-агентом
+from graph_crawler.ai import CrawlContext, ControlChannel
+
+ctx = CrawlContext()
+channel = ControlChannel()
+
+task = asyncio.create_task(
+    gc.async_crawl(
+        "https://example.com",
+        crawl_context=ctx,
+        control_channel=channel,
+    )
+)
+
+# Зупинити краулінг ззовні
+await channel.send("pause")
+await asyncio.sleep(5)
+await channel.send("resume")
 ```
 
 ---
@@ -238,13 +326,57 @@ def crawl_sitemap(
     storage: Optional[str | IStorage] = None,
     storage_config: Optional[dict] = None,
     wrapper: Optional[dict] = None,
+    url_rules: Optional[list[URLRule]] = None,
+    max_sitemaps: Optional[int] = None,
+    max_depth: Optional[int] = None,
     on_progress: Optional[Callable] = None,
     on_error: Optional[Callable] = None,
     on_completed: Optional[Callable] = None,
+    http_client: str = "requests",
+    browser_config: Optional[dict] = None,
 ) -> Graph
 ```
 
-Краулінг через sitemap.xml - парсить robots.txt → знаходить sitemap → обробляє всі URL.
+Краулінг через `sitemap.xml`. Алгоритм:
+
+1. Завантажує `<url>/robots.txt`, шукає директиви `Sitemap:`.
+2. Завантажує знайдені sitemap-файли (включно з sitemap-індексами).
+3. Рекурсивно проходить індекси, формуючи дерево.
+4. (Опційно) розкриває URL зі sitemap у ноди графу.
+
+Результат — `Graph`, де root-нода це `robots.txt`, далі sitemap-індекс(и),
+далі окремі sitemap, далі (опційно) кінцеві URL.
+
+**Параметри:**
+
+| Параметр         | Тип                | Default     | Опис                                                                                                                                              |
+| ---------------- | ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `url`            | str                | —           | Корінь сайту (наприклад `https://example.com`). Sitemap буде шукатися автоматично через `robots.txt` та стандартні шляхи (`/sitemap.xml`).        |
+| `max_urls`       | int \| None        | None        | Максимальна кількість URL зі sitemap, які потраплять у граф. `None` = без обмежень.                                                               |
+| `include_urls`   | bool               | True        | Якщо `False`, граф містить лише структуру sitemap-файлів без розгортання окремих URL — корисно для аналізу архітектури.                           |
+| `timeout`        | int \| None        | None        | Таймаут (сек) всього sitemap-краулінгу. При перевищенні повертається частковий граф.                                                              |
+| `driver`         | str \| IDriver     | "http"      | Транспорт для завантаження sitemap-файлів. Див. опис у `crawl()`.                                                                                 |
+| `driver_config`  | dict \| None       | None        | Налаштування драйвера.                                                                                                                            |
+| `storage`        | str \| IStorage    | "memory"    | Backend збереження графу.                                                                                                                         |
+| `storage_config` | dict \| None       | None        | Налаштування storage.                                                                                                                             |
+| `wrapper`        | dict \| None       | None        | Конфіг distributed sitemap-краулінгу. При наявності використовується `distributed_crawl_sitemap`.                                                 |
+| `url_rules`      | list[Rule] \| None | None        | Правила фільтрації/пріоритизації URL зі sitemap (regex + дії).                                                                                    |
+| `max_sitemaps`   | int \| None        | None        | Жорсткий ліміт кількості sitemap-файлів, які буде завантажено (захист від бомб з 10k sitemap-індексами).                                           |
+| `max_depth`      | int \| None        | None        | Максимальна глибина вкладеності sitemap-індексів. `None` — використовується default з `CrawlerConfig` (3).                                        |
+| `on_progress`    | Callable \| None   | None        | Колбек на події `PAGE_CRAWLED` (кожен завантажений sitemap або URL).                                                                              |
+| `on_error`       | Callable \| None   | None        | Колбек на помилки парсингу/мережі.                                                                                                                |
+| `on_completed`   | Callable \| None   | None        | Колбек на `SITEMAP_CRAWL_COMPLETED`.                                                                                                              |
+| `http_client`    | str                | "requests"  | Транспорт для завантаження XML: `requests` (синхронний, швидкий) або `browser` (через Playwright — для сайтів з Cloudflare/JS-захистом sitemap'у). |
+| `browser_config` | dict \| None       | None        | Налаштування браузера, якщо `http_client="browser"` (headless, user_agent, proxy тощо).                                                           |
+
+**Повертає:** `Graph` — структуроване дерево sitemap'у. Приклад:
+
+```
+robots.txt (root)
+└── sitemap_index.xml
+    ├── sitemap-posts.xml (URLs: 100)
+    └── sitemap-pages.xml (URLs: 50)
+```
 
 **Приклади:**
 
@@ -255,8 +387,45 @@ graph = gc.crawl_sitemap("https://example.com")
 # Тільки структура (без кінцевих URL)
 graph = gc.crawl_sitemap("https://example.com", include_urls=False)
 
-# З лімітом
-graph = gc.crawl_sitemap("https://example.com", max_urls=1000)
+# З лімітом і браузерним клієнтом для захищених сайтів
+graph = gc.crawl_sitemap(
+    "https://example.com",
+    max_urls=1000,
+    max_sitemaps=20,
+    http_client="browser",
+    browser_config={"headless": True},
+)
+```
+
+---
+
+## async_crawl_sitemap()
+
+```python
+async def async_crawl_sitemap(
+    url: str,
+    *,
+    max_urls: Optional[int] = None,
+    include_urls: bool = True,
+    timeout: Optional[int] = None,
+    driver: Optional[str | IDriver] = None,
+    driver_config: Optional[dict] = None,
+    storage: Optional[str | IStorage] = None,
+    storage_config: Optional[dict] = None,
+    url_rules: Optional[list[URLRule]] = None,
+    max_sitemaps: Optional[int] = None,
+    max_depth: Optional[int] = None,
+    on_progress: Optional[Callable] = None,
+    on_error: Optional[Callable] = None,
+    on_completed: Optional[Callable] = None,
+) -> Graph
+```
+
+Асинхронний аналог `crawl_sitemap()` для виклику з вже запущеного event-loop.
+Підтримує ті ж параметри (без `wrapper`, `http_client`, `browser_config`).
+
+```python
+graph = await gc.async_crawl_sitemap("https://example.com", max_urls=500)
 ```
 
 ---
@@ -1193,6 +1362,7 @@ from graph_crawler.extensions.plugins.node.structured_data import (
 
 ## Наступні кроки
 
+- [REST API Reference →](REST_API.md)
 - [Getting Started →](../getting-started/quickstart.md)
 - [Plugin System →](../extraction/plugins.md)
 - [Architecture →](../architecture/ARCHITECTURE_OVERVIEW.md)