mednotes-opencode 0.1.0

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

@@ -0,0 +1,223 @@
+"""Cache SQLite único para o pipeline.
+
+Três tabelas:
+- ``anchors``: chave ``sha256(markdown_body)``, JSON da lista de âncoras
+  produzida na Etapa 1 (Gemini). Sem TTL — markdown idêntico → mesma saída.
+- ``candidates``: chave ``(source, query, visual_type)``, JSON da lista de
+  candidatas devolvida por um adapter na Etapa 2. TTL configurável (default
+  30d) porque APIs de fonte mudam.
+- ``images``: chave ``sha256`` do conteúdo binário. Mapeia para o filename
+  local. Permanente (asset baixado é asset baixado).
+
+API minimalista; só ``get_*`` / ``put_*`` por tabela. Sem migrations — o
+schema é idempotente via ``CREATE TABLE IF NOT EXISTS``.
+
+``Cache`` aceita ``clock`` injetável para tornar TTL testável sem manipular
+relógio do sistema. Suporta ``":memory:"`` para testes.
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from collections.abc import Callable
+from pathlib import Path
+
+from mednotes.domains.wiki.capabilities.illustrate.core.config import expand_path
+from mednotes.kernel.base import JsonArrayAdapter, JsonObject, JsonObjectAdapter
+
+__all__ = ["Cache"]
+
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS anchors (
+    note_sha   TEXT PRIMARY KEY,
+    payload    TEXT NOT NULL,
+    created_at REAL NOT NULL
+);
+CREATE TABLE IF NOT EXISTS candidates (
+    source      TEXT NOT NULL,
+    query       TEXT NOT NULL,
+    visual_type TEXT NOT NULL,
+    payload     TEXT NOT NULL,
+    created_at  REAL NOT NULL,
+    PRIMARY KEY (source, query, visual_type)
+);
+CREATE TABLE IF NOT EXISTS images (
+    sha        TEXT PRIMARY KEY,
+    filename   TEXT NOT NULL,
+    source     TEXT NOT NULL,
+    source_url TEXT NOT NULL,
+    width      INTEGER,
+    height     INTEGER,
+    bytes      INTEGER,
+    created_at REAL NOT NULL
+);
+CREATE TABLE IF NOT EXISTS url_index (
+    image_url  TEXT PRIMARY KEY,
+    sha        TEXT NOT NULL,
+    created_at REAL NOT NULL
+);
+"""
+
+
+def _json_object_list(payload: str) -> list[JsonObject]:
+    """Validate cached JSON arrays before returning them to workflow code."""
+
+    values = JsonArrayAdapter.validate_python(json.loads(payload))
+    return [JsonObjectAdapter.validate_python(item) for item in values]
+
+
+class Cache:
+    def __init__(
+        self,
+        path: str | Path,
+        *,
+        clock: Callable[[], float] = time.time,
+    ) -> None:
+        path_str = str(path)
+        if path_str == ":memory:":
+            self.path: str | Path = path_str
+        else:
+            resolved = expand_path(path_str)
+            resolved.parent.mkdir(parents=True, exist_ok=True)
+            self.path = resolved
+        self._conn = sqlite3.connect(str(self.path))
+        self._conn.executescript(_SCHEMA)
+        self._conn.commit()
+        self._clock = clock
+
+    def close(self) -> None:
+        self._conn.close()
+
+    def __enter__(self) -> Cache:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    # --- anchors -----------------------------------------------------
+
+    def get_anchors(self, note_sha: str) -> list[JsonObject] | None:
+        row = self._conn.execute(
+            "SELECT payload FROM anchors WHERE note_sha = ?", (note_sha,)
+        ).fetchone()
+        return _json_object_list(row[0]) if row else None
+
+    def put_anchors(self, note_sha: str, anchors: list[JsonObject]) -> None:
+        payload = JsonArrayAdapter.validate_python(anchors)
+        self._conn.execute(
+            "INSERT OR REPLACE INTO anchors(note_sha, payload, created_at) "
+            "VALUES (?, ?, ?)",
+            (note_sha, json.dumps(payload, ensure_ascii=False), self._clock()),
+        )
+        self._conn.commit()
+
+    # --- candidates (TTL) --------------------------------------------
+
+    def get_candidates(
+        self,
+        source: str,
+        query: str,
+        visual_type: str,
+        *,
+        ttl_days: int,
+    ) -> list[JsonObject] | None:
+        row = self._conn.execute(
+            "SELECT payload, created_at FROM candidates "
+            "WHERE source = ? AND query = ? AND visual_type = ?",
+            (source, query, visual_type),
+        ).fetchone()
+        if not row:
+            return None
+        payload, created_at = row
+        age_days = (self._clock() - created_at) / 86400.0
+        if age_days > ttl_days:
+            return None
+        return _json_object_list(payload)
+
+    def put_candidates(
+        self,
+        source: str,
+        query: str,
+        visual_type: str,
+        candidates: list[JsonObject],
+    ) -> None:
+        payload = JsonArrayAdapter.validate_python(candidates)
+        self._conn.execute(
+            "INSERT OR REPLACE INTO candidates"
+            "(source, query, visual_type, payload, created_at) "
+            "VALUES (?, ?, ?, ?, ?)",
+            (
+                source,
+                query,
+                visual_type,
+                json.dumps(payload, ensure_ascii=False),
+                self._clock(),
+            ),
+        )
+        self._conn.commit()
+
+    # --- images (permanente) -----------------------------------------
+
+    def get_image(self, sha: str) -> JsonObject | None:
+        row = self._conn.execute(
+            "SELECT filename, source, source_url, width, height, bytes "
+            "FROM images WHERE sha = ?",
+            (sha,),
+        ).fetchone()
+        if not row:
+            return None
+        return JsonObjectAdapter.validate_python({
+            "sha": sha,
+            "filename": row[0],
+            "source": row[1],
+            "source_url": row[2],
+            "width": row[3],
+            "height": row[4],
+            "bytes": row[5],
+        })
+
+    def put_image(
+        self,
+        sha: str,
+        *,
+        filename: str,
+        source: str,
+        source_url: str,
+        width: int | None = None,
+        height: int | None = None,
+        size_bytes: int | None = None,
+    ) -> None:
+        self._conn.execute(
+            "INSERT OR REPLACE INTO images"
+            "(sha, filename, source, source_url, width, height, bytes, created_at)"
+            " VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+            (
+                sha,
+                filename,
+                source,
+                source_url,
+                width,
+                height,
+                size_bytes,
+                self._clock(),
+            ),
+        )
+        self._conn.commit()
+
+    # --- url → sha lookup (evita re-baixar) -------------------------
+
+    def get_sha_for_url(self, image_url: str) -> str | None:
+        row = self._conn.execute(
+            "SELECT sha FROM url_index WHERE image_url = ?", (image_url,)
+        ).fetchone()
+        return row[0] if row else None
+
+    def put_url_index(self, image_url: str, sha: str) -> None:
+        self._conn.execute(
+            "INSERT OR REPLACE INTO url_index(image_url, sha, created_at) "
+            "VALUES (?, ?, ?)",
+            (image_url, sha, self._clock()),
+        )
+        self._conn.commit()

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

@@ -0,0 +1,131 @@
+"""Carrega configuração local e persistente do Medical Notes Workbench."""
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from mednotes.platform.paths import (
+    default_config_path as _shared_default_config_path,
+)
+from mednotes.platform.paths import (
+    expand_path as _shared_expand_path,
+)
+from mednotes.platform.paths import (
+    find_config as _shared_find_config,
+)
+from mednotes.platform.paths import (
+    resolve_wiki_dir,
+)
+from mednotes.platform.paths import (
+    user_state_dir as _shared_user_state_dir,
+)
+
+_DEFAULTS: dict[str, Any] = {
+    "vault": {"path": "", "attachments_subdir": "attachments/medicina"},
+    "enrichment": {
+        "max_anchors_per_note": 5,
+        "max_image_dimension": 1600,
+        "webp_min_savings_pct": 30,
+        # Idioma preferido das figuras retornadas. Afeta:
+        #  - queries que o gemini gera (pt-br adiciona 1 query em PT)
+        #  - params do SerpAPI (hl/gl)
+        #  - regra de desempate no rerank (prefere figuras com texto no idioma)
+        # Valores: "pt-br", "en" (default), "any" (sem hl/gl).
+        "preferred_language": "en",
+    },
+    "sources": {
+        "enabled": [
+            "wikimedia",
+            "radiopaedia",
+            "nih_open_i",
+            "openstax",
+            "dermnet",
+            "teachmeanatomy",
+            "web_search",
+        ],
+        "top_k_per_source": 6,
+    },
+    # `[gemini]` é consumido pelo orquestrador (`scripts/enrich_notes.py`),
+    # não pelo toolbox em si. O enricher core não invoca LLM.
+    "gemini": {
+        "binary": "gemini",
+        "model_anchors": "gemini-2.5-pro",
+        "model_rerank": "gemini-2.5-pro",
+        "max_candidates_per_anchor": 12,
+        "timeout_seconds": 120,
+    },
+    "download": {
+        # User-Agent pra fetch de bytes em `download.py`.
+        # Default: UA browser-like (Chrome/macOS) — destrava osmosis,
+        # thehealthy.com, e similares com anti-bot básico. Wikimedia também
+        # aceita (qualquer browser legítimo passa). Trocar de volta pra UA
+        # identificável (`medical-notes-workbench/0.1 (...)`) é mais
+        # respeitoso mas perde fontes; veja config.example.toml.
+        "user_agent": (
+            "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+            "AppleWebKit/537.36 (KHTML, like Gecko) "
+            "Chrome/131.0.0.0 Safari/537.36"
+        ),
+    },
+    "cache": {
+        "path": "~/Documents/medical-notes-workbench/cache.db",
+        "candidates_ttl_days": 30,
+    },
+}
+
+
+def expand_path(p: str) -> Path:
+    return _shared_expand_path(p)
+
+
+def user_state_dir() -> Path:
+    """Diretório persistente para estado editável pelo usuário.
+
+    A extensão Gemini CLI é auto-updatable e pode recriar
+    ``~/.gemini/extensions/medical-notes-workbench``. Configuração, chaves,
+    cache e venv não devem depender desse diretório volátil.
+    """
+    return _shared_user_state_dir()
+
+
+def default_config_path() -> Path:
+    return user_state_dir() / "config.toml"
+
+
+def default_env_path() -> Path:
+    return user_state_dir() / ".env"
+
+
+def _deep_merge(base: dict[str, Any], over: dict[str, Any]) -> dict[str, Any]:
+    out = dict(base)
+    for k, v in over.items():
+        if isinstance(v, dict) and isinstance(out.get(k), dict):
+            out[k] = _deep_merge(out[k], v)
+        else:
+            out[k] = v
+    return out
+
+
+def find_config(start: Path | None = None) -> Path | None:
+    return _shared_find_config(start=start)
+
+
+def load(path: Path | None = None) -> dict[str, Any]:
+    if path is None:
+        path = find_config()
+    if path is None or not path.exists():
+        return dict(_DEFAULTS)
+    with path.open("rb") as f:
+        data = tomllib.load(f)
+    return _deep_merge(_DEFAULTS, data)
+
+
+def resolve_wiki_root(config_path: Path | None = None, *, start: Path | None = None) -> Path | None:
+    """Return canonical wiki root for workflows that can fall back from vault.path."""
+    resolution = resolve_wiki_dir(config=config_path, start=start or Path.cwd(), enable_gemini_probe=False)
+    return resolution.path if resolution.ok else None
+
+
+def wiki_memory_path() -> Path:
+    return _shared_default_config_path()

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

@@ -0,0 +1,224 @@
+"""Etapa 4 (numeração nova): fetch + validate + resize + dedupe.
+
+Contrato:
+- Recebe URL, ``vault_dir`` e parâmetros de redimensionamento/encoding.
+- Baixa via ``httpx``, valida o conteúdo via ``Pillow.Image.open`` (magic
+  number — proteção contra Google/Bing servir HTML quando o asset some).
+- Redimensiona se ``max(width, height) > max_dim`` (LANCZOS).
+- Decide encoding final: tenta WebP; mantém WebP se a economia for ≥
+  ``webp_min_savings_pct``%, senão preserva o formato original
+  (PNG/JPEG; GIF vira PNG single-frame; SVG não é suportado).
+- SHA-256 sobre os **bytes finais** (após resize/recode), pra dedupe correta.
+- Idempotência por dois níveis:
+  1. ``cache.get_sha_for_url(url)``: se conhecemos a URL, recuperamos o SHA
+     sem ir à rede.
+  2. ``cache.get_image(sha)`` + arquivo existe: reusa.
+
+Erros:
+- :class:`DownloadError` para falhas HTTP, conteúdo não-imagem, formato não
+  suportado.
+"""
+from __future__ import annotations
+
+import hashlib
+import io
+from pathlib import Path
+from typing import Any
+
+import httpx
+from PIL import Image, UnidentifiedImageError
+
+from mednotes.domains.wiki.capabilities.illustrate.core.cache import Cache
+
+__all__ = ["DownloadError", "download"]
+
+
+class DownloadError(RuntimeError):
+    """Falha no download/validação/encoding de uma imagem."""
+
+
+_SUPPORTED_FORMATS = {"PNG", "JPEG", "WEBP", "GIF"}
+_FORMAT_TO_EXT = {"PNG": "png", "JPEG": "jpg", "WEBP": "webp", "GIF": "gif"}
+
+# Wikimedia (e outros) rejeitam UAs genéricos como `python-httpx/X.Y` com 403.
+_DEFAULT_USER_AGENT = (
+    "medical-notes-workbench/0.1 (personal study; "
+    "https://github.com/augustocaruso/medical-notes-workbench)"
+)
+
+
+def download(
+    url: str,
+    *,
+    vault_dir: Path,
+    max_dim: int = 1600,
+    webp_min_savings_pct: int = 30,
+    cache: Cache | None = None,
+    client: httpx.Client | None = None,
+    source: str = "unknown",
+    source_url: str | None = None,
+    user_agent: str | None = None,
+) -> dict[str, Any]:
+    """Baixa, valida, normaliza e indexa uma imagem.
+
+    Devolve ``{sha, filename, path, width, height, bytes, source, source_url, cached}``.
+    ``cached=True`` quando a imagem já estava conhecida (por URL ou SHA) e o
+    arquivo no vault existe — nesse caso não houve fetch nem reescrita.
+    """
+    # 1) URL cache hit → evita HTTP inteiramente.
+    if cache is not None:
+        sha_known = cache.get_sha_for_url(url)
+        if sha_known:
+            existing = cache.get_image(sha_known)
+            if existing:
+                path = vault_dir / existing["filename"]
+                if path.exists():
+                    return _hit_dict(existing, path, source_url=source_url or url)
+
+    # 2) Fetch.
+    own = client is None
+    request_headers = _browser_like_headers(
+        user_agent=user_agent or _DEFAULT_USER_AGENT,
+        referer=source_url,
+    )
+    if own:
+        client = httpx.Client(
+            timeout=30.0,
+            follow_redirects=True,
+        )
+    try:
+        try:
+            resp = client.get(url, headers=request_headers)
+            resp.raise_for_status()
+        except httpx.HTTPError as e:
+            raise DownloadError(f"falha HTTP em {url}: {e}") from e
+        raw = resp.content
+    finally:
+        if own:
+            client.close()
+
+    # 3) Valida (magic number via Pillow).
+    try:
+        img = Image.open(io.BytesIO(raw))
+        img.load()
+    except (UnidentifiedImageError, OSError) as e:
+        raise DownloadError(f"conteúdo de {url} não é imagem válida: {e}") from e
+
+    fmt = (img.format or "").upper()
+    if fmt not in _SUPPORTED_FORMATS:
+        raise DownloadError(f"formato {fmt!r} não suportado ({url})")
+
+    # 4) Resize.
+    if max(img.size) > max_dim:
+        img.thumbnail((max_dim, max_dim), Image.Resampling.LANCZOS)
+
+    # 5) Decide encoding final.
+    final_bytes, final_fmt = _encode(
+        img, original_fmt=fmt, webp_min_savings_pct=webp_min_savings_pct
+    )
+    sha = hashlib.sha256(final_bytes).hexdigest()
+    ext = _FORMAT_TO_EXT[final_fmt]
+    filename = f"{sha[:12]}.{ext}"
+    out_path = vault_dir / filename
+
+    # 6) SHA cache hit → arquivo já existe (ou existia em outro lugar).
+    if cache is not None:
+        existing = cache.get_image(sha)
+        if existing and (vault_dir / existing["filename"]).exists():
+            cache.put_url_index(url, sha)
+            return _hit_dict(existing, vault_dir / existing["filename"], source_url=source_url or url)
+
+    # 7) Grava + indexa.
+    vault_dir.mkdir(parents=True, exist_ok=True)
+    if not out_path.exists():
+        out_path.write_bytes(final_bytes)
+
+    width, height = img.size
+    size_bytes = len(final_bytes)
+
+    if cache is not None:
+        cache.put_image(
+            sha,
+            filename=filename,
+            source=source,
+            source_url=source_url or url,
+            width=width,
+            height=height,
+            size_bytes=size_bytes,
+        )
+        cache.put_url_index(url, sha)
+
+    return {
+        "sha": sha,
+        "filename": filename,
+        "path": str(out_path),
+        "width": width,
+        "height": height,
+        "bytes": size_bytes,
+        "source": source,
+        "source_url": source_url or url,
+        "cached": False,
+    }
+
+
+# --- helpers --------------------------------------------------------
+
+
+def _hit_dict(existing: dict[str, Any], path: Path, *, source_url: str) -> dict[str, Any]:
+    return {
+        "sha": existing["sha"],
+        "filename": existing["filename"],
+        "path": str(path),
+        "width": existing.get("width"),
+        "height": existing.get("height"),
+        "bytes": existing.get("bytes"),
+        "source": existing.get("source"),
+        "source_url": existing.get("source_url") or source_url,
+        "cached": True,
+    }
+
+
+def _browser_like_headers(*, user_agent: str, referer: str | None) -> dict[str, str]:
+    headers = {
+        "User-Agent": user_agent,
+        "Accept": "image/avif,image/webp,image/apng,image/svg+xml,image/*,*/*;q=0.8",
+        "Accept-Language": "en-US,en;q=0.9,pt-BR;q=0.8,pt;q=0.7",
+    }
+    if referer:
+        headers["Referer"] = referer
+    return headers
+
+
+def _encode(
+    img: Image.Image, *, original_fmt: str, webp_min_savings_pct: int
+) -> tuple[bytes, str]:
+    if original_fmt == "WEBP":
+        return _encode_as(img, "WEBP"), "WEBP"
+
+    target_fmt = "PNG" if original_fmt == "GIF" else original_fmt
+    orig_bytes = _encode_as(img, target_fmt)
+    webp_bytes = _encode_as(img, "WEBP")
+
+    if not orig_bytes:
+        return webp_bytes, "WEBP"
+
+    savings_pct = (len(orig_bytes) - len(webp_bytes)) / len(orig_bytes) * 100
+    if savings_pct >= webp_min_savings_pct:
+        return webp_bytes, "WEBP"
+    return orig_bytes, target_fmt
+
+
+def _encode_as(img: Image.Image, fmt: str) -> bytes:
+    out = io.BytesIO()
+    save_img = img
+    if fmt == "JPEG" and img.mode in ("RGBA", "P", "LA"):
+        save_img = img.convert("RGB")
+    if fmt == "WEBP":
+        save_img.save(out, "WEBP", quality=88, method=6)
+    elif fmt == "JPEG":
+        save_img.save(out, "JPEG", quality=88, optimize=True)
+    elif fmt == "PNG":
+        save_img.save(out, "PNG", optimize=True)
+    else:  # pragma: no cover
+        raise ValueError(f"formato de saída não suportado: {fmt}")
+    return out.getvalue()

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

@@ -0,0 +1,59 @@
+"""Leitura e escrita aditiva do frontmatter YAML de notas Markdown.
+
+Contrato:
+- O frontmatter, quando presente, começa em ``---\\n`` na primeira linha e
+  termina no próximo ``---\\n``.
+- ``read(text)`` retorna ``(meta_dict, body)``. Sem frontmatter -> ``({}, text)``.
+- ``write(meta, body)`` reemite o frontmatter sempre, com ``meta == {}``
+  o frontmatter é omitido.
+- ``update(text, patch)`` aplica patch aditivamente sobre o frontmatter
+  existente sem mexer em chaves que não estão no patch e sem reordenar
+  agressivamente as chaves originais.
+
+Não usa nenhum hack contra os campos de origem do export
+(``chat_id``, ``url``, ``title``, ``exported_at``, ``model``, ``source``,
+``tags``); o caller é responsável por não passar essas chaves no patch.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import yaml
+
+_FENCE = "---"
+
+
+def read(text: str) -> tuple[dict[str, Any], str]:
+    if not text.startswith(_FENCE + "\n") and not text.startswith(_FENCE + "\r\n"):
+        return {}, text
+    after_first = text.split("\n", 1)[1]
+    end_idx = after_first.find("\n" + _FENCE + "\n")
+    if end_idx == -1:
+        end_idx_crlf = after_first.find("\n" + _FENCE + "\r\n")
+        if end_idx_crlf == -1:
+            return {}, text
+        end_idx = end_idx_crlf
+    yaml_block = after_first[:end_idx]
+    rest = after_first[end_idx + len("\n" + _FENCE + "\n") :]
+    meta = yaml.safe_load(yaml_block) or {}
+    if not isinstance(meta, dict):
+        return {}, text
+    return meta, rest
+
+
+def write(meta: dict[str, Any], body: str) -> str:
+    if not meta:
+        return body
+    yaml_block = yaml.safe_dump(
+        meta,
+        sort_keys=False,
+        allow_unicode=True,
+        default_flow_style=False,
+    ).rstrip("\n")
+    return f"{_FENCE}\n{yaml_block}\n{_FENCE}\n{body}"
+
+
+def update(text: str, patch: dict[str, Any]) -> str:
+    meta, body = read(text)
+    merged = {**meta, **patch}
+    return write(merged, body)