mednotes-opencode 0.1.0

package/.opencode/mednotes/src/mednotes/domains/wiki/capabilities/illustrate/core/insert.py

@@ -0,0 +1,227 @@
+r"""Etapa 5: inserção determinística de blocos de imagem em notas Markdown.
+
+Contrato:
+- ``insert_images(text, items)`` recebe o markdown completo (com ou sem
+  frontmatter) e uma lista de :class:`InsertedImage`. Para cada item:
+  localiza a seção alvo via ``section_path`` e insere o bloco
+  ``![[<filename>]]`` + caption no fim da seção. Em seguida aplica patch
+  aditivo no frontmatter (``images_enriched``, ``images_enriched_at``,
+  ``image_count``, ``image_sources``) sem reordenar nem mexer nas chaves
+  existentes (``chat_id``, ``url``, ``title``, ``exported_at``, ``model``,
+  ``source``, ``tags``).
+- ``items`` vazio → devolve ``text`` sem mudança alguma (sem patch).
+- Path ambíguo (mais de uma seção com o mesmo trilho): primeira ocorrência
+  vence. Limitação documentada — não há campo ``occurrence`` ainda.
+- Path inexistente: levanta :class:`SectionNotFound`.
+
+Suporta headings ATX (``#``..``######``) e setext (``===``/``---``
+underline). Linhas dentro de blocos de código fenced (``\`\`\``` ou
+``~~~``) são ignoradas para fins de detecção de headings.
+"""
+from __future__ import annotations
+
+import re
+from collections import Counter, defaultdict
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from mednotes.domains.wiki.capabilities.illustrate.core import frontmatter
+
+__all__ = ["InsertedImage", "SectionNotFound", "insert_images", "parse_sections"]
+
+
+@dataclass(frozen=True)
+class InsertedImage:
+    anchor_id: str
+    section_path: list[str]
+    image_filename: str
+    concept: str
+    source: str
+    source_url: str
+
+
+class SectionNotFound(LookupError):
+    """``section_path`` não casa com nenhuma seção da nota."""
+
+
+@dataclass
+class _Section:
+    start_line: int          # índice da linha do heading (0-based, em body)
+    end_line: int            # exclusivo: primeira linha da próxima seção de nível ≤
+    level: int
+    text: str
+    path: list[str] = field(default_factory=list)
+
+
+_ATX_RE = re.compile(r"^(#{1,6})[ \t]+(.*?)(?:[ \t]+#+)?[ \t]*$")
+_FENCE_RE = re.compile(r"^[ \t]*(```+|~~~+)")
+
+
+def _parse_headings(body: str) -> tuple[list[str], list[_Section]]:
+    """Devolve (lines_split, sections). ``lines_split`` é ``body.split('\\n')``
+    (preserva trailing-newline como elemento '' final, se houver)."""
+    lines = body.split("\n")
+    raw: list[tuple[int, int, str]] = []  # (line_idx, level, text)
+    in_fence = False
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        if _FENCE_RE.match(line):
+            in_fence = not in_fence
+            i += 1
+            continue
+        if in_fence:
+            i += 1
+            continue
+        m = _ATX_RE.match(line)
+        if m:
+            raw.append((i, len(m.group(1)), m.group(2).strip()))
+            i += 1
+            continue
+        # Setext: linha não-vazia seguida de '===+' (H1) ou '---+' (H2).
+        stripped = line.strip()
+        if stripped and i + 1 < len(lines):
+            nxt = lines[i + 1].strip()
+            if nxt and (set(nxt) == {"="} or set(nxt) == {"-"}):
+                level = 1 if nxt[0] == "=" else 2
+                raw.append((i, level, stripped))
+                i += 2
+                continue
+        i += 1
+
+    # Constrói paths via stack de (level, text).
+    sections: list[_Section] = []
+    stack: list[tuple[int, str]] = []
+    for line_idx, level, text in raw:
+        while stack and stack[-1][0] >= level:
+            stack.pop()
+        path = [t for _, t in stack] + [text]
+        stack.append((level, text))
+        sections.append(_Section(line_idx, -1, level, text, path))
+
+    # end_line: próxima seção de nível <= esta, ou len(lines).
+    for idx, sec in enumerate(sections):
+        end = len(lines)
+        for j in range(idx + 1, len(sections)):
+            if sections[j].level <= sec.level:
+                end = sections[j].start_line
+                break
+        sec.end_line = end
+
+    return lines, sections
+
+
+def _find_section(sections: list[_Section], path: list[str]) -> _Section:
+    for sec in sections:
+        if sec.path == path:
+            return sec
+    raise SectionNotFound(f"section_path não encontrado: {path!r}")
+
+
+def _block_for(item: InsertedImage) -> tuple[str, str]:
+    """(linha do embed, linha da caption)."""
+    embed = f"![[{item.image_filename}]]"
+    # Normaliza concept: strip whitespace e qualquer pontuação final repetida
+    # ('.', '!', '?'), evitando '..*' quando o agente passa um conceito que
+    # já termina em ponto.
+    concept = item.concept.strip().rstrip(".!?")
+    caption = (
+        f"*Figura: {concept}.* "
+        f"*Fonte: {item.source} — {item.source_url}*"
+    )
+    return embed, caption
+
+
+def _build_group(items: list[InsertedImage]) -> list[str]:
+    """Linhas a inserir para um grupo na mesma seção, com '' (linha em branco)
+    entre captions e nas bordas. As bordas podem ser podadas pelo caller."""
+    out: list[str] = []
+    for item in items:
+        out.append("")
+        embed, caption = _block_for(item)
+        out.append(embed)
+        out.append(caption)
+    out.append("")
+    return out
+
+
+def _insert_at(lines: list[str], idx: int, group: list[str]) -> list[str]:
+    """Insere ``group`` em ``lines`` na posição ``idx``, podando bordas em
+    branco redundantes pra evitar linhas vazias duplicadas."""
+    g = list(group)
+    if idx > 0 and lines[idx - 1] == "" and g and g[0] == "":
+        g.pop(0)
+    if idx < len(lines) and lines[idx] == "" and g and g[-1] == "":
+        g.pop()
+    return lines[:idx] + g + lines[idx:]
+
+
+def _build_patch(
+    items: list[InsertedImage], now: datetime
+) -> dict[str, object]:
+    counts = Counter(item.source for item in items)
+    sorted_sources = sorted(counts.items(), key=lambda kv: (-kv[1], kv[0]))
+    return {
+        "images_enriched": True,
+        "images_enriched_at": now,
+        "image_count": len(items),
+        "image_sources": [
+            {"source": s, "count": c} for s, c in sorted_sources
+        ],
+    }
+
+
+def parse_sections(text: str) -> list[dict[str, object]]:
+    """Wrapper público sobre o parser de headings, JSON-serializável.
+
+    Devolve uma lista de dicts ``{section_path, level, start_line, end_line,
+    text}``. ``start_line`` e ``end_line`` são índices 0-based em **body**
+    (após `frontmatter.read`); ``end_line`` é exclusivo.
+    """
+    _, body = frontmatter.read(text)
+    _, sections = _parse_headings(body)
+    return [
+        {
+            "section_path": list(s.path),
+            "level": s.level,
+            "text": s.text,
+            "start_line": s.start_line,
+            "end_line": s.end_line,
+        }
+        for s in sections
+    ]
+
+
+def insert_images(
+    text: str,
+    items: Iterable[InsertedImage],
+    *,
+    now: datetime | None = None,
+) -> str:
+    items_list = list(items)
+    if not items_list:
+        return text
+
+    meta, body = frontmatter.read(text)
+    lines, sections = _parse_headings(body)
+
+    # Agrupa items por seção alvo (ordem de items preservada dentro de cada grupo).
+    by_section: dict[int, list[InsertedImage]] = defaultdict(list)
+    for item in items_list:
+        sec = _find_section(sections, list(item.section_path))
+        by_section[sections.index(sec)].append(item)
+
+    # Insere de baixo pra cima pra não invalidar end_line.
+    for sec_idx in sorted(by_section.keys(), reverse=True):
+        sec = sections[sec_idx]
+        group = _build_group(by_section[sec_idx])
+        lines = _insert_at(lines, sec.end_line, group)
+
+    new_body = "\n".join(lines)
+
+    if now is None:
+        now = datetime.now(UTC)
+    patch = _build_patch(items_list, now)
+    new_meta = {**meta, **patch}
+    return frontmatter.write(new_meta, new_body)

package/.opencode/mednotes/src/mednotes/domains/wiki/capabilities/illustrate/core/local_import.py

@@ -0,0 +1,54 @@
+"""Local image staging/commit helpers for reviewed PDF crops."""
+from __future__ import annotations
+
+import hashlib
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from PIL import Image
+
+
+@dataclass(frozen=True)
+class StagedImage:
+    path: Path
+    sha256: str
+    filename: str
+
+
+@dataclass(frozen=True)
+class ImportedImage:
+    path: Path
+    filename: str
+    sha256: str
+
+
+def stage_crop(crop_path: Path, *, app_home: Path) -> StagedImage:
+    crop_path = crop_path.expanduser().resolve(strict=True)
+    with Image.open(crop_path) as image:
+        image.verify()
+    sha = _sha256_file(crop_path)
+    staging = app_home / "staging"
+    staging.mkdir(parents=True, exist_ok=True)
+    suffix = crop_path.suffix.lower() if crop_path.suffix else ".png"
+    filename = f"{sha[:16]}{suffix}"
+    target = staging / filename
+    if not target.exists():
+        shutil.copy2(crop_path, target)
+    return StagedImage(path=target, sha256=sha, filename=filename)
+
+
+def commit_staged_image(staged: StagedImage, *, attachments_dir: Path) -> ImportedImage:
+    attachments_dir.mkdir(parents=True, exist_ok=True)
+    target = attachments_dir / staged.filename
+    if not target.exists():
+        shutil.copy2(staged.path, target)
+    return ImportedImage(path=target, filename=target.name, sha256=staged.sha256)
+
+
+def _sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()

package/.opencode/mednotes/src/mednotes/domains/wiki/capabilities/illustrate/sources/__init__.py

@@ -0,0 +1,42 @@
+"""Adapters de fontes de imagem.
+
+Cada adapter expõe:
+- ``NAME``: identificador curto (``"wikimedia"``, ``"openstax"``, ...).
+- ``search(query, visual_type, *, top_k=4, client=None) -> list[ImageCandidate]``.
+
+Falha comum de um adapter não derruba os outros — a etapa de busca chama todos
+e ignora exceções individuais. Exceções fatais, como cota paga esgotada, devem
+parar o orquestrador para evitar que o lote continue batendo na API.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+class SourceQuotaExceeded(RuntimeError):
+    """Erro fatal quando uma fonte paga bloqueia busca por cota/limite."""
+
+    def __init__(self, source: str, message: str):
+        super().__init__(message)
+        self.source = source
+
+
+@dataclass(frozen=True)
+class ImageCandidate:
+    source: str               # ex: "wikimedia"
+    source_url: str           # URL da página descritiva (rastreabilidade)
+    image_url: str            # URL para download direto
+    title: str
+    description: str
+    width: int | None
+    height: int | None
+    license: str | None    # informativo (uso pessoal/fair use)
+    score: float | None    # relevância da fonte, opcional
+    thumbnail_url: str | None = None  # fallback/proxy quando o original bloqueia
+    source_profile: str | None = None
+    page_domain: str | None = None
+    quality_hints: tuple[str, ...] = ()
+    trust_score: float | None = None
+
+
+__all__ = ["ImageCandidate", "SourceQuotaExceeded"]

package/.opencode/mednotes/src/mednotes/domains/wiki/capabilities/illustrate/sources/web_profiles.py

@@ -0,0 +1,99 @@
+"""Trusted web-profile image sources built on top of web_search."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+
+from mednotes.domains.wiki.capabilities.illustrate.sources import ImageCandidate, web_search
+
+
+@dataclass(frozen=True)
+class WebProfile:
+    name: str
+    domains: tuple[str, ...]
+    visual_types: tuple[str, ...]
+    trust_score: float
+
+
+PROFILES: dict[str, WebProfile] = {
+    "radiopaedia": WebProfile(
+        name="radiopaedia",
+        domains=("radiopaedia.org",),
+        visual_types=("radiology",),
+        trust_score=0.95,
+    ),
+    "nih_open_i": WebProfile(
+        name="nih_open_i",
+        domains=("nih.gov", "ncbi.nlm.nih.gov"),
+        visual_types=("diagram", "histology", "radiology", "photo", "chart"),
+        trust_score=0.90,
+    ),
+    "openstax": WebProfile(
+        name="openstax",
+        domains=("openstax.org",),
+        visual_types=("anatomy", "diagram", "chart"),
+        trust_score=0.85,
+    ),
+    "dermnet": WebProfile(
+        name="dermnet",
+        domains=("dermnetnz.org",),
+        visual_types=("photo",),
+        trust_score=0.88,
+    ),
+    "teachmeanatomy": WebProfile(
+        name="teachmeanatomy",
+        domains=("teachmeanatomy.info",),
+        visual_types=("anatomy",),
+        trust_score=0.82,
+    ),
+}
+
+
+def search_profile(
+    profile_name: str,
+    query: str,
+    visual_type: str,
+    *,
+    top_k: int = 4,
+    client: httpx.Client | None = None,
+    language: str | None = None,
+) -> list[ImageCandidate]:
+    profile = PROFILES[profile_name]
+    if visual_type not in profile.visual_types:
+        return []
+    out: list[ImageCandidate] = []
+    per_domain = max(1, top_k // len(profile.domains))
+    for domain in profile.domains:
+        out.extend(
+            web_search.search(
+                query,
+                visual_type,
+                top_k=per_domain,
+                client=client,
+                language=language,
+                site_filter=domain,
+                source_label=profile.name,
+            )
+        )
+    return [_with_profile_hints(item, profile) for item in out[:top_k]]
+
+
+def _with_profile_hints(candidate: ImageCandidate, profile: WebProfile) -> ImageCandidate:
+    hints = tuple(dict.fromkeys([*candidate.quality_hints, "trusted_web_profile"]))
+    return ImageCandidate(
+        source=candidate.source,
+        source_url=candidate.source_url,
+        image_url=candidate.image_url,
+        title=candidate.title,
+        description=candidate.description,
+        width=candidate.width,
+        height=candidate.height,
+        license=candidate.license,
+        score=candidate.score,
+        thumbnail_url=candidate.thumbnail_url,
+        source_profile=profile.name,
+        page_domain=candidate.page_domain,
+        quality_hints=hints,
+        trust_score=profile.trust_score,
+    )

package/.opencode/mednotes/src/mednotes/domains/wiki/capabilities/illustrate/sources/web_search.py

@@ -0,0 +1,203 @@
+"""Adapter de busca web genérica via SerpAPI (engine ``google_images``).
+
+Pra cobrir o que Wikimedia/fontes médicas curadas não têm. Pago — usuário
+guarda a chave no keyring do sistema ou usa env como fallback técnico. Sem a
+chave, ``search`` devolve ``[]`` silenciosamente. Cota/limite esgotado levanta
+``SourceQuotaExceeded`` para o orquestrador parar o lote e avisar o usuário.
+"""
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+from pydantic import ValidationError as PydanticValidationError
+
+from mednotes.domains.wiki.capabilities.illustrate.sources import ImageCandidate, SourceQuotaExceeded
+from mednotes.platform.paths import find_config
+from mednotes.platform.secrets import resolve_secret
+from mednotes.platform.user_config import SecretConfig, load_user_config
+
+NAME = "web_search"
+
+_ENDPOINT = "https://serpapi.com/search.json"
+_QUOTA_STATUS_CODES = {402, 429}
+_QUOTA_MARKERS = (
+    "quota",
+    "exceeded",
+    "exhaust",
+    "run out",
+    "monthly search",
+    "searches per month",
+    "credits",
+    "rate limit",
+    "too many requests",
+)
+_LANGUAGE_TO_GOOGLE_PARAMS = {
+    "pt-br": {"hl": "pt-br", "gl": "br"},
+    "en": {"hl": "en", "gl": "us"},
+}
+
+
+def _serpapi_secret_config() -> SecretConfig:
+    try:
+        return load_user_config(find_config(start=Path.cwd())).secrets.serpapi
+    except (OSError, tomllib.TOMLDecodeError, PydanticValidationError):
+        return SecretConfig()
+
+
+def _serpapi_key(explicit: str | None = None) -> str | None:
+    if explicit:
+        return explicit
+    result = resolve_secret("serpapi", _serpapi_secret_config())
+    return result.value if result.status == "available" else None
+
+
+def search(
+    query: str,
+    visual_type: str,
+    *,
+    top_k: int = 4,
+    client: httpx.Client | None = None,
+    api_key: str | None = None,
+    language: str | None = None,
+    site_filter: str | None = None,
+    source_label: str | None = None,
+) -> list[ImageCandidate]:
+    """Busca imagens via SerpAPI (Google Images).
+
+    Sem chave via keyring/env e sem ``api_key`` explícito, devolve ``[]``.
+    ``visual_type`` é aceito por uniformidade com outros adapters mas não
+    é mapeado em facets do SerpAPI.
+
+    ``language`` é mapeado para os params ``hl`` (UI language) e ``gl``
+    (geolocation) do Google Images. Aceita ``"pt-br"`` e ``"en"``;
+    qualquer outro valor (inclusive ``"any"`` e ``None``) → sem param.
+    """
+    key = _serpapi_key(api_key)
+    if not key:
+        return []
+
+    search_query = _query_with_site_filter(query, site_filter)
+    params: dict[str, str] = {
+        "engine": "google_images",
+        "q": search_query,
+        "api_key": key,
+        "num": str(max(top_k * 2, top_k)),
+    }
+    lang_params = _LANGUAGE_TO_GOOGLE_PARAMS.get((language or "").lower())
+    if lang_params:
+        params.update(lang_params)
+
+    owns_client = client is None
+    if owns_client:
+        client = httpx.Client(timeout=15.0)
+    try:
+        resp = client.get(_ENDPOINT, params=params)
+        error_message = _response_error_message(resp)
+        if _is_quota_error(resp.status_code, error_message):
+            raise SourceQuotaExceeded(
+                NAME,
+                f"SerpAPI bloqueou a busca por cota/limite: "
+                f"{error_message or f'HTTP {resp.status_code}'}",
+            )
+        resp.raise_for_status()
+        data = resp.json()
+        api_error = _api_error_message(data)
+        if _is_quota_error(resp.status_code, api_error):
+            raise SourceQuotaExceeded(
+                NAME,
+                f"SerpAPI bloqueou a busca por cota/limite: {api_error}",
+            )
+    finally:
+        if owns_client:
+            client.close()
+
+    return _parse(data, top_k=top_k, source_label=source_label)
+
+
+def _query_with_site_filter(query: str, site_filter: str | None) -> str:
+    if not site_filter:
+        return query
+    prefix = f"site:{site_filter}"
+    if query.strip().lower().startswith(prefix.lower()):
+        return query
+    return f"{prefix} {query}"
+
+
+def _domain(url: str) -> str | None:
+    host = urlparse(url).netloc.lower()
+    if host.startswith("www."):
+        host = host[4:]
+    return host or None
+
+
+def _response_error_message(resp: httpx.Response) -> str:
+    try:
+        data = resp.json()
+    except ValueError:
+        return resp.text.strip()
+    return _api_error_message(data)
+
+
+def _api_error_message(data: Any) -> str:
+    if not isinstance(data, dict):
+        return ""
+    for key in ("error", "message"):
+        value = data.get(key)
+        if value:
+            return str(value)
+    errors = data.get("errors")
+    if isinstance(errors, list):
+        return "; ".join(str(item) for item in errors if item)
+    if errors:
+        return str(errors)
+    return ""
+
+
+def _is_quota_error(status_code: int, message: str) -> bool:
+    lowered = (message or "").lower()
+    if status_code in _QUOTA_STATUS_CODES:
+        return True
+    return bool(lowered and any(marker in lowered for marker in _QUOTA_MARKERS))
+
+
+def _parse(
+    data: dict[str, Any],
+    *,
+    top_k: int,
+    source_label: str | None = None,
+) -> list[ImageCandidate]:
+    results = data.get("images_results") or []
+    out: list[ImageCandidate] = []
+    label = source_label or NAME
+    for r in results:
+        thumbnail_url = r.get("thumbnail")
+        image_url = r.get("original") or thumbnail_url
+        if not image_url:
+            continue
+        # `link` é a página onde a imagem aparece; `source` é o domínio.
+        source_url = r.get("link") or image_url
+        title = r.get("title", "") or ""
+        description = r.get("snippet") or r.get("source") or title
+        out.append(
+            ImageCandidate(
+                source=label,
+                source_url=source_url,
+                image_url=image_url,
+                title=title,
+                description=description,
+                width=r.get("original_width"),
+                height=r.get("original_height"),
+                license=None,  # SerpAPI não devolve licença
+                score=None,
+                thumbnail_url=thumbnail_url,
+                source_profile=source_label,
+                page_domain=_domain(source_url),
+            )
+        )
+        if len(out) >= top_k:
+            break
+    return out