agent-wire-cli 0.2.1__py3-none-any.whl

agent_wire/channels/tier1_global/youtube.py

@@ -0,0 +1,223 @@
+"""YouTube: InnerTube metadata + in-memory transcript, chapters, top comments, search, channel feeds."""
+
+import re
+from urllib.parse import parse_qs, urlsplit
+
+from agent_wire.channels.base import (
+    Channel,
+    WireUnsupported,
+    assigned_json,
+    compact_count,
+    listing,
+    relative_ts,
+)
+from agent_wire.engine.waterfall import WireFetchError
+from agent_wire.media.subtitle_cleaner import parse_captions, parse_chapters, to_paragraphs
+from agent_wire.models import WireComment, WireSearchHit
+
+INNERTUBE = "https://www.youtube.com/youtubei/v1"
+ANDROID = {"clientName": "ANDROID", "clientVersion": "20.10.38", "androidSdkVersion": 30,
+           "hl": "en", "gl": "US"}  # fmt: skip
+ANDROID_UA = "com.google.android.youtube/20.10.38 (Linux; U; Android 11) gzip"
+WEB = {"clientName": "WEB", "clientVersion": "2.20250925.01.00", "hl": "en", "gl": "US"}
+MAX_COMMENTS = 40
+_ID = re.compile(r"^[\w-]{11}$")
+
+
+def video_id(url: str) -> str | None:
+    p = urlsplit(url)
+    host, segs = (p.hostname or ""), [s for s in p.path.split("/") if s]
+    if host.endswith("youtu.be") and segs:
+        cand = segs[0]
+    elif segs[:1] in (["shorts"], ["embed"], ["live"], ["v"]) and len(segs) > 1:
+        cand = segs[1]
+    else:
+        cand = parse_qs(p.query).get("v", [""])[0]
+    return cand if _ID.match(cand or "") else None
+
+
+def pick_track(tracks: list[dict], lang: str = "en") -> dict | None:
+    def rank(t):
+        manual = t.get("kind") != "asr"
+        same = t.get("languageCode", "").startswith(lang)
+        return (manual and same, same, manual)
+
+    return max(tracks, key=rank) if tracks else None
+
+
+def find_all(obj, key: str):
+    """Yield every value stored under `key` anywhere in a nested InnerTube response."""
+    if isinstance(obj, dict):
+        for k, v in obj.items():
+            if k == key:
+                yield v
+            yield from find_all(v, key)
+    elif isinstance(obj, list):
+        for v in obj:
+            yield from find_all(v, key)
+
+
+def _runs(obj) -> str:
+    if not obj:
+        return ""
+    return obj.get("simpleText") or "".join(r.get("text", "") for r in obj.get("runs", []))
+
+
+def parse_search(data: dict, limit: int) -> list[WireSearchHit]:
+    hits = []
+    for v in find_all(data, "videoRenderer"):
+        if not v.get("videoId"):
+            continue
+        hits.append(
+            WireSearchHit(
+                url=f"https://www.youtube.com/watch?v={v['videoId']}", title=_runs(v.get("title")),
+                snippet=" · ".join(x for x in (_runs(v.get("ownerText")), _runs(v.get("viewCountText")),
+                                               _runs(v.get("lengthText")), _runs(v.get("publishedTimeText"))) if x),
+                source="youtube", rank_score=float(compact_count(_runs(v.get("viewCountText")))),
+                timestamp=relative_ts(_runs(v.get("publishedTimeText"))), author=_runs(v.get("ownerText")),
+                engagement={"views": compact_count(_runs(v.get("viewCountText")))},
+            )
+        )  # fmt: skip
+        if len(hits) >= limit:
+            break
+    return hits
+
+
+def parse_lockups(data: dict, limit: int) -> list[dict]:
+    """Channel Videos tab (2025+ `lockupViewModel` layout) -> listing items."""
+    items = []
+    for lv in find_all(data, "lockupViewModel"):
+        meta = (lv.get("metadata") or {}).get("lockupMetadataViewModel") or {}
+        parts = [p.get("text", {}).get("content") for rows in find_all(meta, "metadataRows")
+                 for row in rows for p in row.get("metadataParts") or []]  # fmt: skip
+        if lv.get("contentId"):
+            items.append({"title": (meta.get("title") or {}).get("content"),
+                          "url": f"https://www.youtube.com/watch?v={lv['contentId']}", "meta": parts})  # fmt: skip
+        if len(items) >= limit:
+            break
+    return items
+
+
+def parse_comment_mutations(data: dict) -> list[WireComment]:
+    out = []
+    for p in find_all(data, "commentEntityPayload"):
+        props, author = p.get("properties", {}), p.get("author", {})
+        toolbar = p.get("toolbar", {})
+        out.append(
+            WireComment(
+                id=props.get("commentId", str(len(out))), body=props.get("content", {}).get("content", ""),
+                author_handle=(author.get("displayName") or "").lstrip("@") or None,
+                score=compact_count(toolbar.get("likeCountNotliked") or toolbar.get("likeCountA11y")),
+                is_op=bool(author.get("isCreator")),
+            )
+        )  # fmt: skip
+    return out[:MAX_COMMENTS]
+
+
+class YouTubeChannel(Channel):
+    name = "youtube"
+
+    async def _innertube(self, endpoint: str, payload: dict, client: dict = WEB):
+        headers = {"Content-Type": "application/json"}
+        if client is ANDROID:
+            headers["User-Agent"] = ANDROID_UA
+        data, f = await self.fetch_json(
+            f"{INNERTUBE}/{endpoint}?prettyPrint=false", method="POST",
+            json_body={"context": {"client": client}, **payload}, headers=headers,
+        )  # fmt: skip
+        return data, f
+
+    async def read(self, url, *, query=None, section=None, include_comments=True):
+        vid = video_id(url)
+        if not vid:
+            return await self.feed(url)
+        player, f = await self._innertube("player", {"videoId": vid}, ANDROID)
+        details = player.get("videoDetails") or {}
+        if not details:
+            reason = (player.get("playabilityStatus") or {}).get("reason", "unavailable")
+            raise WireUnsupported(f"youtube {vid}: {reason}")
+        desc = details.get("shortDescription", "")
+        chapters = parse_chapters(desc)
+        transcript = await self._transcript(player, chapters)
+        parts = [desc.strip()[:1500]]
+        parts.append(f"## Transcript\n{transcript}" if transcript else "_No captions available._")
+        comments = await self._comments(vid) if include_comments else []
+        micro = (player.get("microformat") or {}).get("playerMicroformatRenderer") or {}
+        return self.doc(
+            f, f"https://www.youtube.com/watch?v={vid}", title=details.get("title"),
+            author_handle=details.get("author"), body="\n\n".join(p for p in parts if p),
+            comments=comments,
+            metadata={"views": int(details.get("viewCount") or 0),
+                      "length": f"{int(details.get('lengthSeconds') or 0) // 60}m",
+                      "uploaded": micro.get("uploadDate") or micro.get("publishDate"),
+                      "chapters": len(chapters) or None},
+        )  # fmt: skip
+
+    async def _transcript(self, player: dict, chapters) -> str:
+        tracks = (
+            (player.get("captions") or {})
+            .get("playerCaptionsTracklistRenderer", {})
+            .get("captionTracks", [])
+        )
+        track = pick_track(tracks)
+        if not track:
+            return ""
+        base = re.sub(r"&fmt=[^&]*", "", track["baseUrl"])
+        try:
+            f = await self.fetch(f"{base}&fmt=json3", archive=False, browser=False)
+            segs = parse_captions(f.content) if f.content.strip() else []
+        except (WireFetchError, ValueError):
+            return ""
+        return to_paragraphs(segs, chapters)
+
+    async def _comments(self, vid: str) -> list[WireComment]:
+        try:
+            nxt, _ = await self._innertube("next", {"videoId": vid})
+            token = next(
+                (c["continuationCommand"]["token"]
+                 for sec in find_all(nxt, "itemSectionRenderer")
+                 if sec.get("sectionIdentifier") == "comment-item-section"
+                 for c in find_all(sec, "continuationEndpoint") if "continuationCommand" in c),
+                None,
+            )  # fmt: skip
+            if not token:
+                return []
+            page, _ = await self._innertube("next", {"continuation": token})
+            return parse_comment_mutations(page)
+        except (WireFetchError, ValueError, KeyError):
+            return []  # comments are a bonus; the transcript is the payload
+
+    async def search(self, query, *, limit=5, sort="relevance"):
+        data, _ = await self._innertube("search", {"query": query})
+        return parse_search(data, limit)
+
+    async def feed(self, target, *, sort="hot", limit=10):
+        t = target.strip()
+        channel_id = t if re.match(r"^UC[\w-]{22}$", t) else None
+        if not channel_id:
+            page_url = (
+                t
+                if t.startswith("http")
+                else f"https://www.youtube.com/{t if t.startswith('@') else '@' + t}"
+            )
+            f = await self.fetch(page_url, archive=False)
+            # canonical / externalId name the page's own channel; a bare "channelId" can be a recommendation
+            m = (re.search(r'<link rel="canonical" href="https://www\.youtube\.com/channel/(UC[\w-]{22})"', f.text)
+                 or re.search(r'"externalId":"(UC[\w-]{22})"', f.text))  # fmt: skip
+            if not m:
+                raise WireUnsupported(f"couldn't resolve YouTube channel for {target!r}")
+            channel_id = m[1]
+        rss = f"https://www.youtube.com/feeds/videos.xml?channel_id={channel_id}"
+        try:
+            return await self.ctx.channel("rss").feed(rss, limit=limit)
+        except WireFetchError:  # the RSS endpoint 500s intermittently; read the Videos tab instead
+            url = f"https://www.youtube.com/channel/{channel_id}/videos"
+            f = await self.fetch(url, archive=False)
+            data = assigned_json(f.text, "var ytInitialData") or {}
+            name = next(find_all(data, "channelMetadataRenderer"), {}).get("title") or channel_id
+            return self.doc(
+                f, url, title=f"{name} · videos", body=listing(parse_lockups(data, limit))
+            )
+
+
+CHANNEL = YouTubeChannel

agent_wire/channels/tier2_pro/archive_bypass.py

@@ -0,0 +1,66 @@
+"""Wayback Machine and Archive.today: read snapshots, list a URL's capture history."""
+
+import re
+from urllib.parse import quote, urlsplit
+
+from agent_wire.channels.base import Channel, WireUnsupported, listing
+from agent_wire.channels.tier1_global.web import extract_article
+from agent_wire.engine.waterfall import wayback_snapshot
+from agent_wire.models import WireSearchHit
+
+_WAYBACK = re.compile(r"^/web/(\d{1,14})(?:[a-z_]{2,3}_)?/(.+)$")
+
+
+def raw_wayback(url: str) -> str:
+    """Wayback page URL -> the `id_` form, which serves the original bytes without the toolbar."""
+    m = _WAYBACK.match(
+        urlsplit(url).path + (f"?{urlsplit(url).query}" if urlsplit(url).query else "")
+    )
+    return f"https://web.archive.org/web/{m[1]}id_/{m[2]}" if m else url
+
+
+def parse_cdx(rows: list) -> list[dict]:
+    if not rows:
+        return []
+    header, *data = rows
+    return [dict(zip(header, r, strict=False)) for r in data]
+
+
+class ArchiveChannel(Channel):
+    name = "archive"
+
+    async def read(self, url, *, query=None, section=None, include_comments=True):
+        host = urlsplit(url).hostname or ""
+        if host == "web.archive.org":
+            target = raw_wayback(url)
+        elif host in ("archive.ph", "archive.today", "archive.is"):
+            target = url
+        else:  # any other URL: read its newest Wayback snapshot
+            target = await wayback_snapshot(self.ctx.pool, url)
+            if not target:
+                raise WireUnsupported(f"no Wayback snapshot of {url}")
+        f = await self.fetch(target, archive=False)
+        body, info = extract_article(f.text)
+        return self.doc(f, url, title=info["title"], author_handle=info["author"], body=body,
+                        metadata={"snapshot": target})  # fmt: skip
+
+    async def search(self, query, *, limit=5, sort="relevance"):
+        """Capture history of a URL (newest first)."""
+        if "." not in query:
+            raise WireUnsupported("archive search takes a URL and lists its Wayback captures")
+        data, _ = await self.fetch_json(
+            f"https://web.archive.org/cdx/search/cdx?url={quote(query)}&output=json&limit=-{limit}"
+            "&fl=timestamp,original,statuscode&filter=statuscode:200"
+        )
+        caps = list(reversed(parse_cdx(data)))
+        return [WireSearchHit(url=f"https://web.archive.org/web/{c['timestamp']}/{c['original']}",
+                              title=f"{c['original']} @ {c['timestamp'][:8]}", snippet=f"HTTP {c.get('statuscode')}",
+                              source="wayback") for c in caps[:limit]]  # fmt: skip
+
+    async def feed(self, target, *, sort="hot", limit=10):
+        hits = await self.search(target, limit=limit)
+        return self.doc(None, target, title=f"Wayback captures of {target}",
+                        body=listing([{"title": h.title, "url": h.url} for h in hits]))  # fmt: skip
+
+
+CHANNEL = ArchiveChannel

agent_wire/channels/tier2_pro/arxiv_papers.py

@@ -0,0 +1,220 @@
+"""arXiv: full paper as Markdown (arxiv.org/html, ar5iv), abstract fallback, Semantic Scholar stats."""
+
+import asyncio
+import re
+import xml.etree.ElementTree as ET
+from datetime import UTC
+from urllib.parse import quote, urlsplit
+
+from curl_cffi.requests.exceptions import RequestException
+
+from agent_wire.channels.base import Channel, WireUnsupported, listing, ts
+from agent_wire.channels.tier1_global.web import extract_article
+from agent_wire.compression.anchor_slicer import slice_section
+from agent_wire.engine.waterfall import WireFetchError
+from agent_wire.models import WireSearchHit
+
+API = "https://export.arxiv.org/api/query"
+EXPORT_BUDGET_S = 8  # past this OpenAlex / the arxiv.org search page answer faster
+OPENALEX = "https://api.openalex.org/works"
+OPENALEX_ARXIV = "S4306400194"  # OpenAlex source id of arXiv
+
+
+def _abstract(inverted: dict | None) -> str:
+    """OpenAlex ships abstracts as {word: [positions]}."""
+    pos = sorted((i, w) for w, idx in (inverted or {}).items() for i in idx)
+    return " ".join(w for _, w in pos)
+
+
+def openalex_hit(w: dict) -> WireSearchHit | None:
+    url = next((loc.get("landing_page_url") for loc in w.get("locations") or []
+                if "arxiv.org/abs/" in (loc.get("landing_page_url") or "")), None)  # fmt: skip
+    if not url:
+        return None
+    authors = [(a.get("author") or {}).get("display_name") for a in w.get("authorships") or []]
+    when = ts(w.get("publication_date"))  # a bare date parses naive
+    return WireSearchHit(
+        url=url.replace("http://", "https://"), title=w.get("title") or "", source="arxiv",
+        snippet=_abstract(w.get("abstract_inverted_index"))[:300],
+        timestamp=when.replace(tzinfo=UTC) if when and when.tzinfo is None else when,
+        author=", ".join(a for a in authors[:3] if a) or None,
+        engagement={"citations": w.get("cited_by_count") or 0},
+    )  # fmt: skip
+
+
+_SUBMITTED = re.compile(r"Submitted\s+(\d{1,2})\s+([A-Za-z]+),?\s+(\d{4})")
+
+
+def _words(node) -> str:
+    return " ".join(node.text(separator=" ").split()) if node else ""
+
+
+def parse_search_html(html: str) -> list[WireSearchHit]:
+    """arxiv.org/search results (used when the export API times out)."""
+    from datetime import UTC, datetime
+
+    from selectolax.lexbor import LexborHTMLParser
+
+    hits = []
+    for li in LexborHTMLParser(html).css("li.arxiv-result"):
+        a = li.css_first("p.list-title a")
+        if not a or not (href := a.attributes.get("href")):
+            continue
+        when = None
+        if m := _SUBMITTED.search(_words(li.css_first("p.is-size-7"))):
+            try:
+                when = datetime.strptime(f"{m[1]} {m[2]} {m[3]}", "%d %B %Y").replace(tzinfo=UTC)
+            except ValueError:
+                when = None
+        hits.append(WireSearchHit(
+            url=href, title=_words(li.css_first("p.title")), source="arxiv", timestamp=when,
+            snippet=_words(li.css_first("span.abstract-full")).removesuffix("△ Less").strip()[:300],
+            author=", ".join(_words(x) for x in li.css("p.authors a")[:3]),
+        ))  # fmt: skip
+    return hits
+
+
+S2 = "https://api.semanticscholar.org/graph/v1/paper/arXiv:{}?fields=title,year,venue,citationCount,tldr"
+_ID = re.compile(r"(\d{4}\.\d{4,5}(?:v\d+)?|[a-z\-]+(?:\.[A-Z]{2})?/\d{7}(?:v\d+)?)")
+_ATOM = "{http://www.w3.org/2005/Atom}"
+
+
+def arxiv_id(url: str) -> str | None:
+    path = urlsplit(url).path
+    m = _ID.search(path.removesuffix(".pdf"))
+    return m[1] if m else None
+
+
+def parse_atom(content: bytes) -> list[dict]:
+    root = ET.fromstring(content)
+    out = []
+    for e in root.findall(f"{_ATOM}entry"):
+        link = e.findtext(f"{_ATOM}id") or ""
+        out.append({
+            "id": link.rsplit("/abs/", 1)[-1],
+            "title": " ".join((e.findtext(f"{_ATOM}title") or "").split()),
+            "summary": " ".join((e.findtext(f"{_ATOM}summary") or "").split()),
+            "authors": [a.findtext(f"{_ATOM}name") for a in e.findall(f"{_ATOM}author")],
+            "published": ts(e.findtext(f"{_ATOM}published")),
+            "url": link,
+            "categories": [c.get("term") for c in e.findall(f"{_ATOM}category")],
+        })  # fmt: skip
+    return out
+
+
+class ArxivChannel(Channel):
+    name = "arxiv"
+
+    async def _citations(self, pid: str) -> dict:
+        try:
+            data, _ = await self.fetch_json(S2.format(pid.split("v")[0]))
+        except (WireFetchError, RequestException, ValueError):
+            return {}
+        tldr = (data.get("tldr") or {}).get("text")
+        return {"citations": data.get("citationCount"), "venue": data.get("venue") or None,
+                "tldr": tldr}  # fmt: skip
+
+    async def read(self, url, *, query=None, section=None, include_comments=True):
+        pid = arxiv_id(url)
+        if not pid:
+            raise WireUnsupported("arxiv: expected an /abs/, /pdf/ or /html/ paper URL")
+        abs_data, abs_f = await self.fetch_json_atom(pid)
+        meta = await self._citations(pid)
+        try:  # full text: arXiv's own HTML render, ar5iv as mirror
+            f = await self.fetch(f"https://arxiv.org/html/{pid}", archive=False, browser=False,
+                                 mirrors=[f"https://ar5iv.labs.arxiv.org/html/{pid}"])  # fmt: skip
+            body, _ = extract_article(f.text)
+        except WireFetchError:
+            f, body = abs_f, ""
+        if not body.strip() and abs_data:
+            body = f"## Abstract\n{abs_data['summary']}\n\n_Full text not available as HTML; abstract only._"
+        if section:
+            body = slice_section(body, section) or body
+        if meta.get("tldr"):
+            body = f"TL;DR: {meta['tldr']}\n\n{body}"
+        return self.doc(
+            f, f"https://arxiv.org/abs/{pid}", title=abs_data.get("title") if abs_data else pid,
+            author_handle=", ".join(abs_data.get("authors", [])[:6]) if abs_data else None,
+            timestamp=abs_data.get("published") if abs_data else None, body=body,
+            metadata={"arxiv": pid, "categories": ", ".join(abs_data.get("categories", [])[:4]) if abs_data else None,
+                      "citations": meta.get("citations"), "venue": meta.get("venue")},
+        )  # fmt: skip
+
+    async def fetch_json_atom(self, pid: str):
+        f = await self.fetch(f"{API}?id_list={pid}", archive=False, browser=False)
+        entries = parse_atom(f.content)
+        return (entries[0] if entries else {}), f
+
+    async def _query(self, q: str, limit: int, by_date: bool):
+        sort = "submittedDate" if by_date else "relevance"
+        f = await self.fetch(f"{API}?search_query={quote(q)}&max_results={limit}&sortBy={sort}&sortOrder=descending",
+                             archive=False, browser=False)  # fmt: skip
+        return parse_atom(f.content), f
+
+    async def search(self, query, *, limit=5, sort="relevance"):
+        try:
+            entries, _ = await asyncio.wait_for(
+                self._query(f"all:{query}", limit, sort in ("new", "date", "recent")),
+                EXPORT_BUDGET_S,
+            )
+        except (WireFetchError, TimeoutError, ET.ParseError):  # export.arxiv.org stalls / 429s
+            by_date = sort in ("new", "date", "recent")
+            for fallback in (self._openalex_search, self._html_search):
+                try:
+                    if hits := await fallback(query, limit, by_date):
+                        return hits
+                except (WireFetchError, RequestException, ValueError, KeyError, TypeError):
+                    continue
+            return await self._s2_search(query, limit)
+        return [WireSearchHit(url=e["url"], title=e["title"], snippet=e["summary"][:300], source="arxiv",
+                              timestamp=e["published"], author=", ".join(a for a in e["authors"][:3] if a))
+                for e in entries]  # fmt: skip
+
+    async def _openalex_search(self, query: str, limit: int, by_date: bool) -> list[WireSearchHit]:
+        order = "publication_date:desc" if by_date else "relevance_score:desc"
+        data, _ = await self.fetch_json(
+            f"{OPENALEX}?search={quote(query)}&filter=locations.source.id:{OPENALEX_ARXIV}"
+            f"&sort={order}&per_page={limit}&select=title,publication_date,authorships,locations,"
+            "cited_by_count,abstract_inverted_index"
+        )
+        return [h for h in map(openalex_hit, data.get("results") or []) if h][:limit]
+
+    async def _html_search(self, query: str, limit: int, by_date: bool) -> list[WireSearchHit]:
+        order = "&order=-announced_date_first" if by_date else ""
+        f = await self.fetch(f"https://arxiv.org/search/?query={quote(query)}&searchtype=all"
+                             f"&size=25{order}", archive=False, browser=False)  # fmt: skip
+        return parse_search_html(f.text)[:limit]
+
+    async def _s2_search(self, query: str, limit: int) -> list[WireSearchHit]:
+        data, _ = await self.fetch_json(
+            f"https://api.semanticscholar.org/graph/v1/paper/search?query={quote(query)}&limit={limit}"
+            "&fields=title,abstract,externalIds,year,citationCount"
+        )
+        hits = []
+        for p in data.get("data", []):
+            ax = (p.get("externalIds") or {}).get("ArXiv")
+            url = (
+                f"https://arxiv.org/abs/{ax}"
+                if ax
+                else f"https://www.semanticscholar.org/paper/{p['paperId']}"
+            )
+            hits.append(WireSearchHit(url=url, title=p.get("title") or "", source="semanticscholar",
+                                      snippet=f"{p.get('year')} · {p.get('citationCount')} citations · "
+                                              f"{(p.get('abstract') or '')[:240]}"))  # fmt: skip
+        return hits
+
+    async def feed(self, target, *, sort="hot", limit=10):
+        cat = target.strip().removeprefix("arxiv:")
+        entries, f = await self._query(f"cat:{cat}", limit, True)
+        items = [{"title": e["title"], "url": e["url"], "meta": [", ".join(e["authors"][:3]),
+                  e["published"].date().isoformat() if e["published"] else None],
+                  "snippet": e["summary"]} for e in entries]  # fmt: skip
+        return self.doc(
+            f,
+            f"https://arxiv.org/list/{cat}/recent",
+            title=f"arXiv {cat} · newest",
+            body=listing(items),
+        )
+
+
+CHANNEL = ArxivChannel

agent_wire/channels/tier2_pro/devto.py

@@ -0,0 +1,114 @@
+"""DEV Community (dev.to public API, no key): developer write-ups by tag, with reactions."""
+
+import re
+from datetime import UTC, datetime
+from urllib.parse import quote, urlsplit
+
+from agent_wire.channels.base import Channel, WireUnsupported, html_to_markdown, listing, ts
+from agent_wire.engine.waterfall import WireFetchError
+from agent_wire.models import WireComment, WireSearchHit
+
+API = "https://dev.to/api"
+
+
+_STOP = frozenset({"the", "a", "an", "and", "or", "of", "for", "to", "in", "on", "with", "vs",
+                   "versus", "what", "is", "are", "how", "why", "best", "new"})  # fmt: skip
+
+
+def tag_of(text: str) -> str:
+    """dev.to tags are single lower-case alphanumeric words; use the longest topic word."""
+    return tag_candidates(text)[-1]
+
+
+def tag_candidates(text: str) -> list[str]:
+    """Most to least specific: acronym ('model context protocol' -> mcp), joined words, longest word."""
+    words = [w for w in re.findall(r"[a-z0-9]+", text.lower()) if w not in _STOP]
+    if not words:
+        raise WireUnsupported("devto: give a topic word, e.g. 'rust' or 'webdev'")
+    out = []
+    if 2 < len(words) < 6:
+        out.append("".join(w[0] for w in words))
+    if len(words) > 1 and len(joined := "".join(words)) <= 30:
+        out.append(joined)
+    out.append(max(words, key=len))
+    return list(dict.fromkeys(out))
+
+
+def article_hit(a: dict) -> WireSearchHit:
+    return WireSearchHit(
+        url=a.get("url") or "", title=a.get("title") or "", snippet=a.get("description") or "",
+        source="devto", rank_score=float(a.get("public_reactions_count") or 0),
+        timestamp=ts(a.get("published_at")), author=(a.get("user") or {}).get("username"),
+        engagement={"likes": a.get("public_reactions_count") or 0,
+                    "comments": a.get("comments_count") or 0},
+    )  # fmt: skip
+
+
+def _tags(a: dict) -> str | None:
+    """The list endpoint sends tag_list as a list, the article endpoint as 'a, b' (and tags as a list)."""
+    raw = a.get("tag_list") or a.get("tags")
+    return ", ".join(raw) if isinstance(raw, list) else raw or None
+
+
+def _comments(items: list, depth: int = 0) -> list[WireComment]:
+    return [WireComment(id=c.get("id_code") or str(i), body=html_to_markdown(c.get("body_html") or ""),
+                        author_handle=(c.get("user") or {}).get("username"),
+                        timestamp=ts(c.get("created_at")), depth=depth,
+                        replies=_comments(c.get("children") or [], depth + 1))
+            for i, c in enumerate(items)]  # fmt: skip
+
+
+class DevToChannel(Channel):
+    name = "devto"
+
+    async def search(self, query, *, limit=5, sort="relevance", since=None):
+        days = 30 if since is None else max(1, (datetime.now(UTC) - since).days)
+        words = {w for w in re.findall(r"[a-z0-9]+", query.lower()) if w not in _STOP}
+        tags = tag_candidates(query)
+        for tag in tags:
+            last = tag == tags[-1]
+            try:
+                data, _ = await self.fetch_json(
+                    f"{API}/articles?tag={quote(tag)}&top={days}&per_page={limit}"
+                )
+            except (WireFetchError, ValueError):
+                if last:
+                    raise
+                continue
+            text = set(re.findall(r"[a-z0-9]+", " ".join(
+                f"{a.get('title')} {a.get('description')}" for a in data).lower()))  # fmt: skip
+            # a guessed tag must bring on-topic articles; the last (plain word) tag is taken as is
+            if last or (data and (tag in text or len(words & text) > 1)):
+                return [article_hit(a) for a in data[:limit]]
+        return []
+
+    async def feed(self, target, *, sort="hot", limit=10):
+        tag = tag_of(target)
+        data, f = await self.fetch_json(f"{API}/articles?tag={quote(tag)}&top=7&per_page={limit}")
+        items = [{"title": h.title, "url": h.url, "snippet": h.snippet,
+                  "meta": [f"♥{h.engagement['likes']}", f"{h.engagement['comments']} comments", h.author]}
+                 for h in map(article_hit, data)]  # fmt: skip
+        return self.doc(
+            f, f"https://dev.to/t/{tag}/top/week", title=f"dev.to · #{tag}", body=listing(items)
+        )
+
+    async def read(self, url, *, query=None, section=None, include_comments=True):
+        parts = [p for p in urlsplit(url).path.split("/") if p]
+        if parts[:1] == ["t"] and len(parts) >= 2:  # /t/<tag>[/top/week]: the tag's feed
+            return await self.feed(parts[1])
+        if len(parts) != 2:
+            return await self.ctx.channel("web").read(url, query=query, section=section)
+        a, f = await self.fetch_json(f"{API}/articles/{parts[0]}/{parts[1]}")
+        comments = []
+        if include_comments and a.get("id"):
+            raw, _ = await self.fetch_json(f"{API}/comments?a_id={a['id']}")
+            comments = _comments(raw)
+        return self.doc(
+            f, url, title=a.get("title"), author_handle=(a.get("user") or {}).get("username"),
+            timestamp=ts(a.get("published_at")), score=a.get("public_reactions_count"),
+            body=a.get("body_markdown") or html_to_markdown(a.get("body_html") or ""),
+            comments=comments, metadata={"tags": _tags(a), "comments": a.get("comments_count")},
+        )  # fmt: skip
+
+
+CHANNEL = DevToChannel