mednotes-opencode 0.1.0

package/.opencode/mednotes/src/mednotes/domains/wiki/flows/enrich/workflow/inputs.py

@@ -0,0 +1,120 @@
+"""Input expansion and note path validation."""
+from __future__ import annotations
+
+import glob
+import re
+from pathlib import Path
+
+from mednotes.domains.wiki.flows.enrich.workflow.models import NoteResult
+
+_EXCLUDED_NOTE_DIR_NAMES = {
+    ".git",
+    ".hg",
+    ".obsidian",
+    ".svn",
+    ".venv",
+    "__pycache__",
+    "_attachments",
+    "anexos",
+    "attachments",
+    "build",
+    "dist",
+    "images",
+    "node_modules",
+    "venv",
+}
+_GLOB_CHARS_RE = re.compile(r"[*?\[]")
+
+
+def _has_glob(value: str) -> bool:
+    return bool(_GLOB_CHARS_RE.search(value))
+
+
+def _sort_key(path: Path) -> str:
+    return path.as_posix().casefold()
+
+
+def _note_key(path: Path) -> str:
+    try:
+        return str(path.resolve(strict=False))
+    except OSError:
+        return str(path.absolute())
+
+
+def _is_excluded_note_path(path: Path) -> bool:
+    return any(part.casefold() in _EXCLUDED_NOTE_DIR_NAMES for part in path.parts)
+
+
+def _markdown_files_in_dir(directory: Path) -> list[Path]:
+    files = []
+    for path in directory.rglob("*.md"):
+        try:
+            relative = path.relative_to(directory)
+        except ValueError:
+            relative = path
+        if _is_excluded_note_path(relative):
+            continue
+        if path.is_file():
+            files.append(path)
+    return sorted(files, key=_sort_key)
+
+
+def _resolve_note_inputs(inputs: list[Path]) -> tuple[list[Path], list[NoteResult]]:
+    notes: list[Path] = []
+    errors: list[NoteResult] = []
+    seen: set[str] = set()
+
+    def add_note(path: Path) -> None:
+        key = _note_key(path)
+        if key in seen:
+            return
+        seen.add(key)
+        notes.append(path)
+
+    def add_error(path: Path, message: str) -> None:
+        errors.append(NoteResult(note=path, code=2, status="failed", message=message))
+
+    for raw in inputs:
+        path = raw.expanduser()
+        raw_text = str(path)
+        if _has_glob(raw_text):
+            matches = sorted((Path(match) for match in glob.glob(raw_text, recursive=True)), key=_sort_key)
+            if not matches:
+                add_error(path, f"glob sem correspondências: {raw}")
+                continue
+            found: list[Path] = []
+            for match in matches:
+                if match.is_dir():
+                    found.extend(_markdown_files_in_dir(match))
+                elif match.is_file() and match.suffix.lower() == ".md":
+                    if not _is_excluded_note_path(match):
+                        found.append(match)
+            if not found:
+                add_error(path, f"glob não encontrou notas .md: {raw}")
+                continue
+            for note in sorted(found, key=_sort_key):
+                add_note(note)
+            continue
+
+        if path.is_dir():
+            found = _markdown_files_in_dir(path)
+            if not found:
+                add_error(path, f"diretório sem notas .md: {path}")
+                continue
+            for note in found:
+                add_note(note)
+            continue
+
+        add_note(path)
+
+    return notes, errors
+
+
+def _validate_note_path(note: Path) -> str | None:
+    if note.suffix.lower() != ".md":
+        return f"caminho não é uma nota .md: {note}"
+    if not note.exists():
+        return f"caminho não encontrado: {note}"
+    if not note.is_file():
+        return f"caminho não é arquivo: {note}"
+    return None

package/.opencode/mednotes/src/mednotes/domains/wiki/flows/enrich/workflow/models.py

@@ -0,0 +1,34 @@
+"""Shared models and constants for the image enrichment workflow."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from mednotes.domains.wiki.capabilities.illustrate.sources import ImageCandidate
+
+
+class GeminiError(RuntimeError):
+    pass
+
+
+_DEFAULT_GEMINI_TIMEOUT_SECONDS = 120
+_EXIT_SOURCE_QUOTA = 9
+
+
+@dataclass
+class CandidateReport:
+    candidates: list[ImageCandidate]
+    counts_by_source: dict[str, int]
+    failed_queries: list[tuple[str, str, str]]
+    capped: bool = False
+
+
+@dataclass
+class NoteResult:
+    note: Path
+    code: int
+    status: str
+    inserted_count: int = 0
+    sources_count: dict[str, int] = field(default_factory=dict)
+    message: str = ""
+    quality_report: dict[str, object] | None = None

package/.opencode/mednotes/src/mednotes/domains/wiki/flows/enrich/workflow/parsing.py

@@ -0,0 +1,48 @@
+"""JSON response parsing for Gemini outputs."""
+from __future__ import annotations
+
+import json
+import re
+
+_JSON_FENCE_RE = re.compile(r"```(?:json)?\s*(.+?)\s*```", re.DOTALL)
+
+
+def _strip_fences(s: str) -> str:
+    m = _JSON_FENCE_RE.search(s)
+    return m.group(1) if m else s.strip()
+
+
+def parse_anchors_json(raw: str) -> list[dict]:
+    cleaned = _strip_fences(raw)
+    data = json.loads(cleaned)
+    if not isinstance(data, list):
+        raise ValueError(f"esperava lista de âncoras, recebi {type(data).__name__}")
+    out = []
+    for i, a in enumerate(data):
+        for k in ("section_path", "concept", "visual_type", "search_queries"):
+            if k not in a:
+                raise ValueError(f"âncora #{i} sem chave obrigatória {k!r}")
+        a.setdefault("anchor_id", f"a{i+1}")
+        out.append(a)
+    return out
+
+
+def parse_rerank_json(raw: str) -> dict:
+    cleaned = _strip_fences(raw)
+    data = json.loads(cleaned)
+    if "chosen_index" not in data:
+        raise ValueError("rerank sem chave 'chosen_index'")
+    if "minimum_quality_met" not in data:
+        data["minimum_quality_met"] = data.get("chosen_index") is not None
+    candidates = data.get("candidates", [])
+    if candidates is None:
+        candidates = []
+    if not isinstance(candidates, list):
+        raise ValueError("rerank candidates precisa ser lista")
+    for item in candidates:
+        if not isinstance(item, dict):
+            raise ValueError("cada item de candidates precisa ser objeto")
+        if "index" not in item:
+            raise ValueError("candidate rubric sem index")
+    data["candidates"] = candidates
+    return data

package/.opencode/mednotes/src/mednotes/domains/wiki/flows/enrich/workflow/prompts.py

@@ -0,0 +1,216 @@
+"""Prompt templates and builders for image enrichment."""
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+
+from mednotes.domains.wiki.capabilities.illustrate.sources import ImageCandidate
+
+_ANCHORS_PROMPT_TEMPLATE = """Você é um curador de imagens médicas para uma nota de estudo de alto rigor.
+
+CONTEXTO DE QUALIDADE:
+- O usuário estuda medicina em português do Brasil e quer material útil para prova/residência e revisão clínica.
+- A imagem deve parecer material didático confiável: foto clínica real, lâmina, radiologia, anatomia, gráfico ou esquema técnico. Não escolha imagem decorativa, caricatura, meme, stock genérico ou desenho infantil.
+- Priorize precisão visual sobre quantidade. Uma figura errada ensina errado.
+
+Leia a NOTA abaixo e devolva até {max_anchors} ÂNCORAS — pontos onde uma figura tornaria o aprendizado mais eficiente.
+
+REGRAS DE SELEÇÃO (importantes):
+
+1. **Prefira seções-folha (sem subseções)** sobre seções com filhos. Se uma seção tem subseções listadas em SECTIONS, escolha a subseção em vez do pai — a inserção vai pro fim do trilho escolhido, e seções com filhos têm o "fim" depois das subseções (posicionamento ruim).
+
+2. **Cada visual_type bem específico**:
+   - `diagram`: esquema/fluxograma técnico de mecanismo molecular, fisiopatologia ou via metabólica
+   - `anatomy`: anatomia macro realista (órgão, sistema, corte, peça ou atlas)
+   - `histology`: lâmina histológica/microscopia com coloração, imunofluorescência ou achado anatomopatológico
+   - `radiology`: imagem radiológica real (RX, TC, RM, US), com modalidade/achado quando possível
+   - `chart`: gráfico/curva clinicamente interpretável (dose-resposta, sobrevida, ECG, algoritmo)
+   - `photo`: foto clínica real (lesão, sinal semiológico, exame físico), não ilustração genérica
+
+3. **Conceito curto e visual**: o que a figura PRECISA MOSTRAR, não o que a seção fala em geral. Ex: "binding do ISRS ao SERT bloqueando recaptação", não "mecanismo dos ISRS". Termine SEM ponto final.
+
+4. **Queries — siga a regra de IDIOMA abaixo**:
+{language_guidance}
+
+5. **Use operadores de busca quando isso aumentar precisão.** Para `web_search`, inclua em pelo menos uma query termos acadêmicos em inglês e, quando fizer sentido, operadores `site:` apontando fontes confiáveis:
+   - histology/photo/mecanismo: `site:nih.gov`, `site:ncbi.nlm.nih.gov`, `site:nejm.org`, `site:dermnetnz.org`
+   - radiology: `site:radiopaedia.org`, `site:acr.org`, `site:rsna.org`
+   - anatomy/diagram: `site:openstax.org`, `site:teachmeanatomy.info`, `site:kenhub.com`
+   Não force `site:` se isso piorar a query; use como "virtual adapter" apenas quando o domínio combina com o tipo visual.
+
+6. **Não force âncoras fracas.** Se uma seção é puramente lista de fármacos ou texto sem imagem natural, pule. Melhor 2 âncoras boas que 5 medíocres. Mas também não seja tímido — uma nota didática quase sempre tem >=1 ponto que se beneficia.
+
+Devolva APENAS um JSON válido (sem ```fences), no formato:
+[{{"section_path": [...], "concept": "...", "visual_type": "...", "search_queries": ["...", "..."], "anchor_id": "a1"}}]
+
+Lista vazia `[]` se realmente nenhum ponto pede figura.
+
+SECTIONS (paths e níveis — note quais têm filhos):
+{sections_json}
+
+NOTA:
+{note_text}
+"""
+
+
+_LANGUAGE_GUIDANCE = {
+    "pt-br": (
+        "   Gere 3-5 queries: pelo menos **1 em português** (termos médicos canônicos PT-BR, "
+        "ex.: \"mecanismo de ação ISRS SERT sinapse\") e **1-2 em inglês** "
+        "(ex.: \"SSRI mechanism action SERT\"). Inclua termos de prova/achado quando existirem "
+        "(ex.: marcador, sinal, modalidade, coloração, classificação). Variar as duas línguas "
+        "amplia a chance de achar figura com legenda em PT (preferida) sem perder o material em EN."
+    ),
+    "en": (
+        "   Gere 3-5 queries em **inglês**, médicas, canônicas e específicas. "
+        "Inclua marcador, sinal, modalidade, coloração ou classificação quando existirem. "
+        "Ex.: [\"SSRI mechanism action SERT\", \"selective serotonin reuptake inhibitor binding\"]."
+    ),
+    "any": (
+        "   Gere 3-5 queries em **inglês**, médicas, canônicas e específicas (cobertura máxima). "
+        "Inclua marcador, sinal, modalidade, coloração ou classificação quando existirem. "
+        "Ex.: [\"SSRI mechanism action SERT\", \"selective serotonin reuptake inhibitor binding\"]."
+    ),
+}
+
+
+_LANGUAGE_RERANK_HINT = {
+    "pt-br": (
+        "\n6. **PREFERÊNCIA DE IDIOMA**: quando 2+ candidatas tiverem qualidade equivalente, "
+        "prefira figura com texto em **português** ou **sem texto**. Figura em inglês é "
+        "aceitável se claramente superior nos outros critérios."
+    ),
+    "en": "",
+    "any": "",
+}
+
+
+_RERANK_PROMPT_TEMPLATE = """Você é um curador EXIGENTE de imagens médicas. Para a ÂNCORA abaixo, escolha a melhor candidata olhando as miniaturas anexadas — OU recuse todas se nenhuma é boa.
+
+PADRÃO DE QUALIDADE:
+- Pense como alguém selecionando material para revisão clínica/prova de residência.
+- Prefira imagem tecnicamente precisa, real ou acadêmica, com fonte rastreável.
+- Não premie imagem bonita se ela for genérica, antiga sem valor didático atual, decorativa ou apenas vagamente relacionada.
+
+ÂNCORA:
+- Conceito (o que a figura precisa mostrar): {concept}
+- Tipo visual desejado: {visual_type}
+- Queries usadas: {queries}
+
+CANDIDATAS (índice 0-based, miniatura inline via @arquivo):
+{candidates_block}
+
+REGRAS DE DECISÃO:
+
+1. **Match temático ESTRITO.** A figura tem que mostrar exatamente o conceito. Se mostra um tópico vizinho (mesmo que mesma molécula/órgão), NÃO É MATCH. Ex: conceito "ISRS bloqueando SERT" — uma figura de "MDMA causando efflux via SERT" é vizinha mas NÃO é match. Devolva `null`.
+
+2. **Tipo visual tem que bater.** Se pediram `diagram`, uma foto de medicamento não serve. Se pediram `radiology`, um esquema desenhado não serve.
+
+3. **Qualidade visual mínima**: legível, sem watermark, sem texto em idioma absurdo, sem mistura de figuras desconexas no mesmo arquivo.
+
+4. **Filtro de confiabilidade e atualidade.** Recuse imagem histórica/obsoleta quando o objetivo for conduta, achado radiológico moderno, classificação atual ou foto clínica contemporânea. Aceite imagem antiga só se ela for claramente anatomia/histologia clássica e ainda didática.
+
+5. **Recusar é melhor que escolher meia-certo.** Uma figura ruim na nota é pior que nenhuma figura — quem estuda fica confuso. Em dúvida, escolha `null`.
+
+6. **Justifique em UMA frase concreta** apontando elemento da figura (ex: "mostra exatamente SSRI ligando ao SERT bloqueando 5HT", ou "a figura é sobre MDMA causando efflux, não bloqueio por ISRS — vizinho mas off-topic").
+
+7. **Rubrica estruturada obrigatória.** Avalie cada candidata com notas 0-5:
+   - `topic_match`: mostra exatamente o conceito?
+   - `visual_type_match`: bate com o tipo visual pedido?
+   - `clinical_reliability`: parece fonte médica/acadêmica confiável?
+   - `legibility`: dá para estudar pela imagem?
+   - `source_traceability`: há página/fonte rastreável?
+   - `obsolete_or_decorative_risk`: risco de ser obsoleta, decorativa, stock, clipart ou off-topic.
+
+Só use `"minimum_quality_met": true` quando a candidata escolhida tiver match temático estrito, tipo visual correto, legibilidade suficiente e fonte rastreável. Se qualquer eixo essencial falhar, use `chosen_index: null`.
+
+Devolva APENAS um JSON válido (sem ```fences), neste formato:
+{{
+  "chosen_index": <int ou null>,
+  "minimum_quality_met": <true ou false>,
+  "reason": "<uma frase concreta>",
+  "candidates": [
+    {{
+      "index": <int>,
+      "topic_match": <0-5>,
+      "visual_type_match": <0-5>,
+      "clinical_reliability": <0-5>,
+      "legibility": <0-5>,
+      "source_traceability": <0-5>,
+      "obsolete_or_decorative_risk": <0-5>,
+      "decision": "accept|reject"
+    }}
+  ]
+}}
+"""
+
+
+def build_anchors_prompt(
+    note_text: str,
+    sections: list[dict],
+    *,
+    max_anchors: int,
+    preferred_language: str = "any",
+) -> str:
+    # Anota `has_children`: True se a próxima seção é descendente (level maior).
+    annotated = []
+    for i, s in enumerate(sections):
+        has_children = (
+            i + 1 < len(sections) and sections[i + 1]["level"] > s["level"]
+        )
+        annotated.append(
+            {
+                "section_path": s["section_path"],
+                "level": s["level"],
+                "has_children": has_children,
+            }
+        )
+    guidance = _LANGUAGE_GUIDANCE.get(preferred_language.lower(), _LANGUAGE_GUIDANCE["any"])
+    return _ANCHORS_PROMPT_TEMPLATE.format(
+        max_anchors=max_anchors,
+        language_guidance=guidance,
+        sections_json=json.dumps(annotated, ensure_ascii=False, indent=2),
+        note_text=note_text,
+    )
+
+
+def build_rerank_prompt(
+    anchor: dict,
+    candidates: list[ImageCandidate],
+    *,
+    thumb_basenames: Sequence[str | None] | None = None,
+    preferred_language: str = "any",
+) -> str:
+    """``thumb_basenames[i]`` é o nome do arquivo do thumb de ``candidates[i]``,
+    referenciável via ``@<basename>`` quando o caller passar a pasta dos thumbs
+    em ``--include-directories``. ``None`` na posição = thumb falhou; ainda
+    listamos a candidata como texto pra preservar o índice."""
+    if thumb_basenames is None:
+        thumb_basenames = [None] * len(candidates)
+    lines = []
+    for i, (c, tb) in enumerate(zip(candidates, thumb_basenames, strict=False)):
+        thumb_ref = f"@{tb}" if tb else "(thumb indisponível)"
+        lines.append(
+            f"  [{i}] {thumb_ref}\n"
+            f"      title={c.title!r} | source={c.source} | "
+            f"profile={c.source_profile or '-'} | domain={c.page_domain or '-'} | "
+            f"trust={c.trust_score if c.trust_score is not None else '-'} | "
+            f"size={c.width}x{c.height} | license={c.license}\n"
+            f"      quality_hints: {', '.join(c.quality_hints) if c.quality_hints else '-'}\n"
+            f"      description: {c.description}\n"
+            f"      url: {c.image_url}"
+        )
+    base = _RERANK_PROMPT_TEMPLATE.format(
+        concept=anchor["concept"],
+        visual_type=anchor["visual_type"],
+        queries=", ".join(anchor.get("search_queries", [])),
+        candidates_block="\n".join(lines),
+    )
+    hint = _LANGUAGE_RERANK_HINT.get(preferred_language.lower(), "")
+    if hint:
+        # Insere a regra extra antes da instrução final de "Devolva APENAS um JSON".
+        base = base.replace(
+            "Devolva APENAS um JSON",
+            hint + "\n\nDevolva APENAS um JSON",
+        )
+    return base

package/.opencode/mednotes/src/mednotes/domains/wiki/flows/enrich/workflow/quality.py

@@ -0,0 +1,54 @@
+"""Deterministic quality helpers for image candidate selection."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mednotes.domains.wiki.capabilities.illustrate.sources import ImageCandidate
+
+DECORATIVE_MARKERS = ("stock", "icon", "clipart", "vector", "wallpaper", "logo")
+
+
+@dataclass(frozen=True)
+class CandidateQuality:
+    candidate: ImageCandidate
+    score: float
+    flags: tuple[str, ...]
+
+
+def assess_candidate(visual_type: str, candidate: ImageCandidate) -> CandidateQuality:
+    flags: list[str] = []
+    width = candidate.width or 0
+    height = candidate.height or 0
+    trust = candidate.trust_score if candidate.trust_score is not None else 0.50
+    resolution_score = min(max(min(width, height) / 1200, 0.0), 1.0)
+    text = f"{candidate.title} {candidate.description}".lower()
+
+    if min(width, height) and min(width, height) < 600:
+        flags.append("low_resolution")
+    if any(marker in text for marker in DECORATIVE_MARKERS):
+        flags.append("possibly_decorative")
+    if (
+        visual_type == "radiology"
+        and candidate.source not in {"radiopaedia", "nih_open_i", "web_search"}
+    ):
+        flags.append("weak_radiology_source")
+
+    penalty = 0.15 * len(flags)
+    score = max(0.0, min(1.0, (0.65 * trust) + (0.35 * resolution_score) - penalty))
+    return CandidateQuality(candidate=candidate, score=round(score, 4), flags=tuple(flags))
+
+
+def rank_candidates_for_rerank(
+    visual_type: str,
+    candidates: list[ImageCandidate],
+) -> list[ImageCandidate]:
+    assessed = [assess_candidate(visual_type, item) for item in candidates]
+    assessed.sort(
+        key=lambda item: (
+            -item.score,
+            item.candidate.source,
+            item.candidate.title.lower(),
+            item.candidate.image_url,
+        )
+    )
+    return [item.candidate for item in assessed]

package/.opencode/mednotes/src/mednotes/domains/wiki/flows/enrich/workflow/reporting.py

@@ -0,0 +1,24 @@
+"""Local reporting helpers for image-enrichment quality decisions."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from mednotes.kernel.base import JsonObject, JsonObjectAdapter
+
+
+def write_quality_report(path: Path, payload: JsonObject) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    validated = JsonObjectAdapter.validate_python(payload)
+    path.write_text(
+        json.dumps(validated, ensure_ascii=False, indent=2) + "\n",
+        encoding="utf-8",
+    )
+
+
+def note_report(path: Path, status: str, anchors: list[JsonObject]) -> JsonObject:
+    return {
+        "path": str(path),
+        "status": status,
+        "anchors": anchors,
+    }