nedviga-cli 0.1.0__py3-none-any.whl

nedviga/sources_avito.py

@@ -0,0 +1,138 @@
+"""v0.5.13 (the task brief) Avito browser adapter (offline-first)."""
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+# v0.5.13.1 (замечание realtor live): капча Авито формулируется по-разному —
+# «Здравствуйте, робот» и «Доступ ограничен: проверка безопасности».
+BLOCK_MARKERS = ("Здравствуйте, робот", "Доступ ограничен", "проверка безопасности",
+                 "Are you a robot", "captcha")
+
+RATE_LIMIT_SECONDS = 60.0
+_last_goto: float = 0.0
+
+
+def _norm_num(s: str) -> float:
+    s = s.replace("\u00a0", "").replace(" ", "").replace(",", ".")
+    try:
+        return float(s)
+    except ValueError:
+        return 0.0
+
+
+def parse_livetext(text: str) -> list[dict]:
+    cards = []
+    for m in re.finditer(r"(\d)-к\.\s*квартира,\s*([\d,\.]+)\s*м²,\s*(\d+)/(\d+)\s*эт\.", text):
+        rooms = int(m.group(1))
+        area = _norm_num(m.group(2))
+        floor = int(m.group(3))
+        floors = int(m.group(4))
+        prefix = text[:m.start()]
+        price_matches = list(re.finditer(r"(\d[\d\s\u00a0]*)\s*₽", prefix))
+        price = 0
+        ppm2 = None
+        # identify total price (not "за м²")
+        total_pm = None
+        for pm in reversed(price_matches):
+            # v0.5.13 контроль: «за м²» ищем СРАЗУ после ₽, иначе следующая
+            # строка-перм² съедала и total-цену (15 990 000 ₽\n\n382 536 ₽ за м²
+            # — у обоих в 20-символьном хвосте было «за м²», price=0)
+            seg_after = text[pm.end():pm.end()+12]
+            if re.match(r"\s*за\s*м", seg_after):
+                if ppm2 is None:
+                    ppm2 = int(_norm_num(pm.group(1)))
+                continue
+            total_pm = pm
+            break
+        if total_pm is not None:
+            price = int(_norm_num(total_pm.group(1)))
+        # fallback ppm2 search
+        if ppm2 is None:
+            segment = text[total_pm.start() if total_pm else m.start():m.start()]
+            ppm = re.search(r"(\d[\d\s\u00a0]*)\s*₽\s*за\s*м²", segment)
+            if ppm:
+                ppm2 = int(_norm_num(ppm.group(1)))
+        rest = text[m.end():m.end() + 600]
+        lines = [ln.strip() for ln in rest.splitlines() if ln.strip()]
+        # контроль: продавец-строки не адрес
+        _SELLER_MARKS = ("Надёжный партнёр", "Надёжный продавец", "Документы проверены")
+        address = ""
+        for ln in lines:
+            if not any(s in ln for s in _SELLER_MARKS):
+                address = ln
+                break
+        metro = ""
+        for ln in lines:
+            if "мин." in ln:
+                metro = ln
+                break
+        seller_kind = "Надёжный партнёр" if "Надёжный партнёр" in rest else ""
+        # v0.5.15 контроль: стабильный id. Позиционный 'avito-<индекс>' ломал
+        # watch-идентичность при перестановке выдачи (digest врал new/removed).
+        import hashlib as _hl
+        lot = None
+        ml = re.search(r"Номер лота[:\s]*([\w\-]+)", rest)
+        if ml:
+            lot = ml.group(1)
+        cid = ("avito-" + lot) if lot else ("avito-" + _hl.sha1(
+            f"{price}|{address}|{area}|{floor}".encode("utf-8")).hexdigest()[:10])
+        card = {
+            "id": cid,
+            "source": "avito",
+            "url": None,
+            "title": f"{rooms}-к. квартира, {area} м²",
+            "pricing": {"price_total_rub": price, "price_per_m2_rub": ppm2},
+            "parameters": {"rooms": rooms, "area_total_m2": area, "floor": floor, "floors_total": floors},
+            "building": {"address_raw": address},
+            "geo": {"district": None},
+            "seller": {"seller_type": seller_kind},
+            "warnings": ["url_unavailable"],
+        }
+        cards.append(card)
+    return cards
+
+
+def _rate_limit_goto():
+    global _last_goto
+    now = time.time()
+    wait = RATE_LIMIT_SECONDS - (now - _last_goto)
+    if wait > 0:
+        time.sleep(wait)
+    _last_goto = time.time()
+
+
+def browser_search(catalog_url: str, max_n: int = 20) -> list[dict]:
+    proxy = os.environ.get("NEDVIGA_EGRESS_PROXY")
+    if not proxy:
+        raise RuntimeError("source_disabled")
+    try:
+        from camoufox.sync_api import Camoufox
+    except Exception as exc:
+        raise RuntimeError(f"source_disabled: {exc}")
+    _rate_limit_goto()
+    try:
+        with Camoufox(headless=True, humanize=True, proxy={"server": proxy}) as browser:
+            page = browser.new_page()
+            page.goto(catalog_url, timeout=60000)
+            page.wait_for_timeout(6000)
+            _txt = (page.evaluate("document.body.innerText") or "")
+            if any(m.lower() in _txt.lower() for m in BLOCK_MARKERS):
+                raise RuntimeError("source_blocked")
+            content = page.inner_text("body")
+            if "Здравствуйте, робот" in content or "/captcha" in page.url:
+                raise RuntimeError("source_blocked")
+            cards = parse_livetext(content)
+            return cards[:max_n]
+    except RuntimeError:
+        raise
+    except Exception as exc:
+        msg = str(exc).lower()
+        if "captcha" in msg or "робот" in msg:
+            raise RuntimeError("source_blocked")
+        raise RuntimeError(f"source_error: {exc}")

nedviga/sources_domclick.py

@@ -0,0 +1,122 @@
+"""v0.5.14 F-15b: Domclid browser-адаптер. innerText-парсинг (Angular-рендер, карточных
+атрибутов нет — решётка текста с пустыми строками; lesson avito v0.5.13: парсер по тексту).
+Контакты не извлекаются никогда; «Показать телефон» — маркер отсечения поля.
+url: ссылки /offer/ в DOM не появлялись — url=None честно, id = хеш карточки.
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import time
+from datetime import datetime, timezone
+
+RATE_LIMIT_SECONDS = 60
+_BLOCK_MARKERS = ("Доступ ограничен", "проверка безопасности", "Здравствуйте, робот",
+                  "Are you a robot", "captcha")
+_last_goto = [0.0]
+
+
+def _rate_limit_goto() -> None:
+    wait = RATE_LIMIT_SECONDS - (time.time() - _last_goto[0])
+    if _last_goto[0] and wait > 0:
+        time.sleep(wait)
+    _last_goto[0] = time.time()
+
+
+def _num(s: str) -> float | None:
+    s = s.replace("\u00a0", "").replace(" ", "").replace(",", ".")
+    m = re.match(r"^(\d+(?:\.\d+)?)(?:м²|этаж|эт)?", s)
+    return float(m.group(1)) if m else None
+
+
+def parse_domclick_text(text: str) -> list[dict]:
+    """Карточка начинается с общей цены 'N ₽' отдельной строкой; дальше перм²/ипотека/
+    статусы; параметры 'N-комн. квартира', площадь 'S м²', этаж 'F/E эт.', ЖК, адрес."""
+    lines = [ln.strip() for ln in text.splitlines()]
+    lines = [ln for ln in lines if ln]
+    cards = []
+    for i, ln in enumerate(lines):
+        m = re.fullmatch(r"(\d[\d\s\u00a0]{4,12})\s*₽", ln)
+        if not m:
+            continue
+        # следующая содержательная строка — ₽/м² или сразу ипотека/параметры
+        ppm2 = None
+        j = i + 1
+        if j < len(lines) and re.match(r"\d[\d\s\u00a0]*\s*₽/м²", lines[j]):
+            ppm2 = _num(lines[j].split("₽")[0])
+            j += 1
+        # окна карточки: до следующей цены или <=18 строк
+        window = lines[j:j + 18]
+        rooms = area = floor = floors = None
+        complex_name = address = None
+        is_new = False
+        for k, w in enumerate(window):
+            mr = re.match(r"(\d+)-комн\.\s*(квартира|студия)", w)
+            if mr and rooms is None:
+                rooms = int(mr.group(1))
+                if "студия" in mr.group(2):
+                    rooms = 0
+            ma = re.match(r"([\d.,]+)\s*м²$", w)
+            if ma and area is None:
+                area = _num(ma.group(1))
+            mf = re.match(r"(\d+)/(\d+)\s*эт\.?", w)
+            if mf and floor is None:
+                floor, floors = int(mf.group(1)), int(mf.group(2))
+            if w.startswith("ЖК") and complex_name is None:
+                complex_name = w[:80]
+            if w.startswith("Новостройка"):
+                is_new = True
+            if "Россия," in w and address is None:
+                address = w[:120]
+            # отсечение: следующая цена раньше параметров = стоп-окно прерываем позже
+        if rooms is None or area is None:
+            continue  # не карточка (мелкие цены/ипотека без структуры)
+        price = _num(m.group(1))
+        if not price or price < 1_000_000:
+            continue
+        cid = "dc-" + hashlib.sha1(f"{price}|{address}|{area}".encode()).hexdigest()[:10]
+        cards.append({
+            "id": cid, "source": "domclick", "url": None,
+            "title": (complex_name or address or f"{rooms}-комн. {area} м²")[:100],
+            "pricing": {"price_total_rub": int(price),
+                        "price_per_m2_rub": int(ppm2) if ppm2 else None},
+            "parameters": {"rooms": rooms, "area_total_m2": area,
+                           "floor": floor, "floors_total": floors},
+            "building": {"address_raw": address or "", "complex": complex_name,
+                         "is_new_build": is_new},
+            "status_flags": {"rosreestr_checked": any("Росреестр" in w for w in window[:10])},
+        })
+    # дедуп по id
+    seen = set()
+    out = []
+    for c in cards:
+        if c["id"] not in seen:
+            seen.add(c["id"])
+            out.append(c)
+    return out
+
+
+def browser_search_domclick(catalog_url: str, max_n: int = 20) -> list[dict]:
+    proxy = (os.environ.get("NEDVIGA_EGRESS_PROXY") or "").strip()
+    if not proxy:
+        raise RuntimeError("source_disabled")
+    try:
+        from camoufox.sync_api import Camoufox
+    except Exception as exc:
+        raise RuntimeError(f"source_disabled: {exc}")
+    _rate_limit_goto()
+    with Camoufox(headless=True, humanize=True, geoip=True,
+                  proxy={"server": proxy}) as browser:
+        page = browser.new_page()
+        page.goto(catalog_url, wait_until="domcontentloaded", timeout=50000)
+        page.wait_for_timeout(8000)
+        for _ in range(3):
+            page.evaluate("window.scrollTo(0, document.body.scrollHeight)")
+            page.wait_for_timeout(3000)
+        txt = page.evaluate("document.body.innerText") or ""
+    low = txt.lower()
+    if any(m.lower() in low for m in _BLOCK_MARKERS):
+        raise RuntimeError("source_blocked")
+    cards = parse_domclick_text(txt)
+    return cards[:max_n]

nedviga/stale.py

@@ -0,0 +1,83 @@
+"""v0.5.3 (the task brief) stale detection."""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+from . import pipeline
+from .dedup import _listing, _candidate, signature
+from .models import ListingCard
+
+
+def _age_days(ts: Any) -> Optional[int]:
+    if not ts:
+        return None
+    try:
+        dt = datetime.fromisoformat(str(ts).replace("Z", "+00:00"))
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return (datetime.now(timezone.utc) - dt).days
+    except ValueError:
+        return None
+
+
+def _last_seen(card_id: str) -> Optional[str]:
+    try:
+        conn = pipeline._connect()
+        row = conn.execute("SELECT MAX(snapshot_at) as last_seen FROM watch_snapshots WHERE card_id=?", (card_id,)).fetchone()
+        conn.close()
+        return row["last_seen"] if row else None
+    except Exception:
+        return None
+
+
+def detect_stale(cards, max_age_days: int = 14, verify_live: bool = False) -> list[dict[str, Any]]:
+    lst = [_listing(c) for c in cards]
+    # signatures for relist detection
+    sig_map: dict[Any, list[ListingCard]] = {}
+    for c in lst:
+        sig_map.setdefault(signature(c), []).append(c)
+
+    results = []
+    for c in lst:
+        age = _age_days(_last_seen(c.id))
+        status = None
+        reason = None
+        # relisted: another card same signature different id
+        same_sig = [x for x in sig_map.get(signature(c), []) if x.id != c.id]
+        if same_sig:
+            status = "relisted"
+            reason = "подпись совпадает с " + ", ".join(x.id for x in same_sig)
+        elif age is not None and age > max_age_days:
+            status = "stale_suspect"
+            reason = f"последняя видимость {age} дн назад (порог {max_age_days})"
+        else:
+            # no last_seen data: stale suspect if no snapshot
+            if _last_seen(c.id) is None:
+                status = "stale_suspect"
+                reason = "нет подтверждённой видимости в watch_snapshots"
+            else:
+                status = "fresh"
+                reason = "актуально"
+
+        if status in {"stale_suspect"} and verify_live:
+            try:
+                from .cian_live import get_card
+                get_card(c.id)
+            except Exception as exc:
+                msg = str(exc).lower()
+                if "404" in msg or "not found" in msg or "removed" in msg:
+                    status = "confirmed_gone"
+                    reason = "live-check: объект недоступен (404)"
+
+        results.append({"card_id": c.id, "status": status, "reason": reason})
+    return results
+
+
+def render_text(results) -> str:
+    lines = []
+    for r in results:
+        lines.append(f"{r['card_id']}: {r['status']} — {r['reason']}")
+    return "\n".join(lines)

nedviga/textsearch.py

@@ -0,0 +1,141 @@
+"""v0.5.4 (the task brief) local full-text search (FTS5)."""
+from __future__ import annotations
+
+import hashlib
+import html as _html
+import json
+import os
+import sqlite3
+from pathlib import Path
+from typing import Any, Optional
+
+from .models import ListingCard
+
+
+class TextSearchError(Exception):
+    pass
+
+
+def db_path() -> Path:
+    base = Path(os.environ.get("NEDVIGA_STATE_DIR", str(Path.home() / ".local" / "share" / "nedviga")))
+    base.mkdir(parents=True, exist_ok=True)
+    return base / "text_index.sqlite"
+
+
+def _sha_file(path: str) -> str:
+    return hashlib.sha256(Path(path).read_bytes()).hexdigest()
+
+
+def _connect(db=None):
+    p = db or db_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(p), timeout=30.0)
+    conn.row_factory = sqlite3.Row
+    # check FTS5
+    try:
+        conn.execute("CREATE VIRTUAL TABLE IF NOT EXISTS _fts5_check USING fts5(x)")
+        conn.execute("DROP TABLE IF EXISTS _fts5_check")
+    except sqlite3.OperationalError as exc:
+        conn.close()
+        raise TextSearchError("fts5_unavailable: " + str(exc))
+    conn.execute("""CREATE TABLE IF NOT EXISTS indexed_files (
+        sha TEXT PRIMARY KEY, path TEXT, indexed_at TEXT)""")
+    conn.execute("""CREATE TABLE IF NOT EXISTS documents (
+        card_id TEXT PRIMARY KEY, title TEXT, description TEXT, note TEXT, sha TEXT)""")
+    conn.execute("""CREATE VIRTUAL TABLE IF NOT EXISTS docs_fts USING fts5(card_id, title, description, note)""")
+    conn.commit()
+    return conn
+
+
+def _load_cards(path: str):
+    raw = json.loads(Path(path).read_text(encoding="utf-8"))
+    if isinstance(raw, dict):
+        if "cards" in raw and isinstance(raw["cards"], list):
+            raw = raw["cards"]
+        elif "data" in raw:
+            d = raw["data"]
+            raw = d if isinstance(d, list) else ([d] if isinstance(d, dict) else [])
+        else:
+            raw = [raw]
+    if not isinstance(raw, list):
+        raw = [raw]
+    out = []
+    for x in raw:
+        if isinstance(x, dict):
+            try:
+                out.append(ListingCard(**x))
+            except Exception:
+                # minimal
+                out.append(x)
+        elif isinstance(x, ListingCard):
+            out.append(x)
+    return out
+
+
+def index_file(path: str, db=None) -> dict:
+    sha = _sha_file(path)
+    conn = _connect(db)
+    try:
+        row = conn.execute("SELECT 1 FROM indexed_files WHERE sha=?", (sha,)).fetchone()
+        if row:
+            return {"ok": True, "idempotent": True, "sha": sha}
+        cards = _load_cards(path)
+        for c in cards:
+            if isinstance(c, ListingCard):
+                card_id = c.id
+                title = c.title or ""
+                desc = c.description_text or ""
+                note = ""
+            else:
+                card_id = c.get("id", "")
+                title = c.get("title", "") or ""
+                desc = c.get("description_text", "") or ""
+                note = c.get("note", "") or ""
+            conn.execute("INSERT OR REPLACE INTO documents (card_id,title,description,note,sha) VALUES (?,?,?,?,?)",
+                         (card_id, title, desc, note, sha))
+            conn.execute("INSERT INTO docs_fts (card_id,title,description,note) VALUES (?,?,?,?)",
+                         (card_id, title, desc, note))
+        conn.execute("INSERT INTO indexed_files (sha,path,indexed_at) VALUES (?,?,?)",
+                     (sha, path, __import__("datetime").datetime.now(__import__("datetime").timezone.utc).isoformat()))
+        conn.commit()
+        return {"ok": True, "idempotent": False, "sha": sha, "indexed": len(cards)}
+    except TextSearchError:
+        raise
+    except Exception as exc:
+        raise TextSearchError(str(exc))
+    finally:
+        conn.close()
+
+
+def query(q: str, project: Optional[str] = None, db=None) -> list[dict]:
+    conn = _connect(db)
+    try:
+        # v0.5.4 контроль качества: FTS5 unicode61 не понимает русскую морфологию
+        # («доверенности» != «доверенность», узакон* не ловит «узаконим»).
+        # LIKE по подстроке = предсказуемое поведение для локального корпуса;
+        # хвостовая * трактуется как префикс-поиск.
+        term = q.strip().rstrip("*").strip()
+        if len(term) < 2:
+            raise TextSearchError("query_too_short")
+        like = "%" + term.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_") + "%"
+        rows = conn.execute(
+            "SELECT card_id, title, description, note FROM documents"
+            " WHERE title LIKE ? ESCAPE '\\' OR description LIKE ? ESCAPE '\\' OR note LIKE ? ESCAPE '\\'"
+            " ORDER BY card_id", (like, like, like)).fetchall()
+    except sqlite3.OperationalError as exc:
+        conn.close()
+        raise TextSearchError("fts5_unavailable: " + str(exc))
+    results = []
+    for r in rows:
+        # context fragment from description
+        hay = (r["description"] or "") or (r["title"] or "") or (r["note"] or "")
+        pos = hay.lower().find(term.lower())
+        start = max(0, pos - 40) if pos >= 0 else 0
+        frag = ("…" if start else "") + hay[start:start + 120]
+        results.append({
+            "card_id": r["card_id"],
+            "title": _html.escape(r["title"] or ""),
+            "fragment": _html.escape(frag),
+        })
+    conn.close()
+    return results

nedviga/tour.py

@@ -0,0 +1,180 @@
+"""v0.5.1 (the task brief) tour routing."""
+from __future__ import annotations
+
+import json
+import math
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any, Optional
+
+from .models import ListingCard
+from . import pipeline
+
+
+def _load_cards(path: Optional[str] = None, project: Optional[str] = None) -> list[ListingCard]:
+    cards: list[ListingCard] = []
+    if project:
+        from .projects import project_cards
+        for cid in project_cards(project):
+            cards.append(ListingCard(id=cid, source="cian", url=""))
+    if path:
+        raw = json.loads(Path(path).read_text(encoding="utf-8"))
+        if isinstance(raw, dict):
+            if "cards" in raw and isinstance(raw["cards"], list):
+                raw = raw["cards"]
+            elif "data" in raw:
+                d = raw["data"]
+                raw = d if isinstance(d, list) else ([d] if isinstance(d, dict) else [])
+            else:
+                raw = [raw]
+        if not isinstance(raw, list):
+            raw = [raw]
+        for x in raw:
+            if isinstance(x, dict):
+                cards.append(ListingCard(**x))
+            elif isinstance(x, ListingCard):
+                cards.append(x)
+    return cards
+
+
+def _coords(c: ListingCard):
+    g = c.geo
+    if g and g.lat is not None and g.lon is not None:
+        return (g.lat, g.lon)
+    return None
+
+
+def _haversine(a, b):
+    R = 6371000.0
+    phi1 = math.radians(a[0]); phi2 = math.radians(b[0])
+    dphi = math.radians(b[0]-a[0]); dl = math.radians(b[1]-a[1])
+    x = math.sin(dphi/2)**2 + math.cos(phi1)*math.cos(phi2)*math.sin(dl/2)**2
+    return 2*R*math.asin(math.sqrt(x))
+
+
+def _pair_distance(a: ListingCard, b: ListingCard):
+    ca = _coords(a); cb = _coords(b)
+    if ca is None or cb is None:
+        return None, True  # unknown -> straight estimate
+    # try graph
+    try:
+        from . import graph as _g
+        r = _g.route(ca[0], ca[1], cb[0], cb[1])
+        if r is not None:
+            meters, provider = r
+            return float(meters), False
+    except Exception:
+        pass
+    return _haversine(ca, cb), True
+
+
+def _allowed_ids(all_flag: bool):
+    if all_flag:
+        return None
+    try:
+        items = pipeline.list_items()
+    except Exception:
+        return None
+    allowed = set()
+    for it in items:
+        if it.get("status") in {"shortlist", "call_planned"}:
+            allowed.add(it.get("card_id"))
+    return allowed if allowed else None
+
+
+def _filter(cards, all_flag):
+    allowed = _allowed_ids(all_flag)
+    if allowed is None or all_flag:
+        return cards
+    return [c for c in cards if c.id in allowed]
+
+
+def _order(cards):
+    if len(cards) <= 1:
+        return list(cards)
+    # deterministic start: sorted by id
+    remaining = sorted(cards, key=lambda c: c.id)
+    # greedy nearest neighbor from first
+    route = [remaining.pop(0)]
+    while remaining:
+        last = route[-1]
+        # choose nearest by distance; tie-break by id
+        best = min(remaining, key=lambda c: (_pair_distance(last, c)[0] if _pair_distance(last, c)[0] is not None else float("inf"), c.id))
+        remaining.remove(best)
+        route.append(best)
+    # 2-opt
+    def total(r):
+        s = 0.0
+        for i in range(len(r)-1):
+            d, _ = _pair_distance(r[i], r[i+1])
+            s += d if d is not None else 0.0
+        return s
+    improved = True
+    # limit iterations for determinism
+    iters = 0
+    while improved and iters < 100:
+        improved = False
+        iters += 1
+        for i in range(1, len(route)-1):
+            for j in range(i+1, len(route)):
+                new = route[:i] + list(reversed(route[i:j+1])) + route[j+1:]
+                if total(new) + 1e-9 < total(route):
+                    route = new
+                    improved = True
+    return route
+
+
+def build_tour(cards, slot_min=45, start_time="10:00", all_flag=False):
+    cards = _filter(cards, all_flag)
+    cards = cards[:6]
+    ordered = _order(cards)
+    slots = []
+    t = datetime.strptime(start_time, "%H:%M")
+    warnings = []
+    for c in ordered:
+        ca = None
+        if len(slots) > 0:
+            prev = ordered[len(slots)-1]
+            dist, straight = _pair_distance(prev, c)
+            if dist is None:
+                warnings.append(f"между {prev.id} и {c.id} — координаты неизвестны, близость не гарантирована")
+            elif straight:
+                warnings.append(f"между {prev.id} и {c.id} — только по прямой {dist/1000:.1f} км, реальная поездка дольше — проверьте маршрутом")
+        slots.append({"time": t.strftime("%H:%M"), "card": c})
+        t = t + timedelta(minutes=slot_min)
+    return {"slots": slots, "warnings": warnings, "count": len(slots)}
+
+
+def render_text(tour, fmt="telegram"):
+    slots = tour["slots"]
+    warnings = tour["warnings"]
+    lines = []
+    for s in slots:
+        c = s["card"]
+        district = c.geo.district if c.geo else ""
+        metro = ""
+        if c.geo and c.geo.cian_claimed_metro:
+            metro = c.geo.cian_claimed_metro.station or ""
+        loc = f"{district}, {metro}".strip(", ")
+        lines.append(f"{s['time']} {c.title or c.id} ({loc})")
+    if warnings:
+        lines.append("")
+        for w in warnings:
+            lines.append(f"⚠ {w}")
+    # build timeline with arrows
+    timeline = " → ".join(f"{s['time']} {s['card'].title or s['card'].id}" for s in slots)
+    if fmt == "md":
+        out = ["# Маршрут показов", "", timeline, ""]
+        for s in slots:
+            c = s["card"]
+            out.append(f"- {s['time']} {c.title or c.id}")
+        if warnings:
+            out.append("")
+            for w in warnings:
+                out.append(f"- ⚠ {w}")
+        return "\n".join(out)
+    # telegram compact
+    out = [timeline]
+    for w in warnings:
+        out.append(f"⚠ {w}")
+    return "\n".join(out)