mednotes-opencode 0.1.0

package/.opencode/mednotes/src/mednotes/domains/wiki/contracts/workflow_outcomes.py

@@ -0,0 +1,121 @@
+"""Typed workflow outcome facade for Wiki domain callers.
+
+This module deliberately does not reconstruct decisions from legacy
+`status`/`blocked_reason` fields. A caller that wants a `WorkflowDecision` must
+provide the typed `decision_summary` or a typed `human_decision_packet`; otherwise
+the boundary fails closed and the emitting workflow must be fixed at the source.
+"""
+from __future__ import annotations
+
+from pydantic import Field, StrictStr
+from pydantic import ValidationError as PydanticValidationError
+
+from mednotes.kernel.base import ContractModel, JsonObject
+from mednotes.kernel.workflow import (
+    AutomationKind,
+    DecisionEvidence,
+    DecisionKind,
+    HumanDecisionOption,
+    HumanDecisionPacket,
+    RejectedAutomation,
+    WorkflowAutomationKind,
+    WorkflowDecision,
+    WorkflowDecisionKind,
+    WorkflowDecisionSummary,
+    WorkflowOutcomeError,
+    attach_human_decision_packet,
+)
+
+__all__ = [
+    "AutomationKind",
+    "DecisionEvidence",
+    "DecisionKind",
+    "HumanDecisionOption",
+    "HumanDecisionPacket",
+    "RejectedAutomation",
+    "WorkflowAutomationKind",
+    "WorkflowDecision",
+    "WorkflowDecisionKind",
+    "WorkflowOutcomeError",
+    "attach_human_decision_packet",
+    "decision_payload_from_decision",
+    "decision_from_payload",
+]
+
+
+class _WorkflowDecisionSourcePayload(ContractModel):
+    """Typed subset used to recover an already-declared decision from JSON."""
+
+    decision_summary: WorkflowDecisionSummary | None = None
+    human_decision_packet: HumanDecisionPacket | None = None
+    next_action: StrictStr = ""
+    required_inputs: list[StrictStr] = Field(default_factory=list)
+
+
+def decision_from_payload(payload: JsonObject) -> WorkflowDecision:
+    """Validate a typed decision already present in an operational payload."""
+    try:
+        return _decision_from_payload(_decision_source_payload(payload))
+    except PydanticValidationError as exc:
+        raise WorkflowOutcomeError(f"invalid workflow decision payload: {exc}") from exc
+
+
+def _decision_source_payload(payload: JsonObject) -> _WorkflowDecisionSourcePayload:
+    raw: dict[str, object] = {}
+    for key in ("decision_summary", "human_decision_packet", "next_action", "required_inputs"):
+        if key in payload:
+            raw[key] = payload[key]
+    return _WorkflowDecisionSourcePayload.model_validate(raw)
+
+
+def _decision_from_payload(source: _WorkflowDecisionSourcePayload) -> WorkflowDecision:
+    packet = source.human_decision_packet
+    summary = source.decision_summary or (packet.decision_summary if packet is not None else None)
+    if summary is None:
+        raise WorkflowOutcomeError("decision_summary is required; legacy status fields cannot create decisions")
+
+    next_action = source.next_action or (packet.resume_action if packet is not None else "")
+    # Ask-human packets carry the closed option set and recommended option.
+    # Reconstructing an intermediate WorkflowDecision without those fields would
+    # trip the contract before the packet data is folded back in.
+    if packet is not None:
+        return WorkflowDecision(
+            kind=summary.kind,
+            phase=summary.phase,
+            reason_code=summary.reason_code,
+            public_summary=summary.public_summary,
+            developer_summary=summary.developer_summary,
+            evidence=summary.evidence,
+            rejected_automations=packet.rejected_automations,
+            next_action=next_action,
+            required_inputs=list(source.required_inputs),
+            human_decision_kind=packet.kind,
+            resume_action=packet.resume_action,
+            recommended_option_id=packet.recommended_option_id,
+            options=packet.options,
+        )
+    return WorkflowDecision(
+        kind=summary.kind,
+        phase=summary.phase,
+        reason_code=summary.reason_code,
+        public_summary=summary.public_summary,
+        developer_summary=summary.developer_summary,
+        evidence=summary.evidence,
+        rejected_automations=summary.rejected_automations,
+        next_action=next_action,
+        required_inputs=list(source.required_inputs),
+    )
+
+
+def decision_payload_from_decision(decision: WorkflowDecision) -> JsonObject:
+    """Project a typed decision summary without manufacturing workflow state."""
+
+    payload: JsonObject = {
+        "decision_summary": decision.decision_summary(),
+        "next_action": decision.next_action,
+        "required_inputs": list(decision.required_inputs),
+        "human_decision_required": decision.kind == WorkflowDecisionKind.ASK_HUMAN,
+    }
+    if decision.kind == WorkflowDecisionKind.ASK_HUMAN:
+        payload["human_decision_packet"] = decision.to_human_decision_packet()
+    return payload

package/.opencode/mednotes/src/mednotes/domains/wiki/contracts/workflow_receipts.py

@@ -0,0 +1,100 @@
+"""Receipt builder for workflow outcomes."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from pydantic import ValidationError as PydanticValidationError
+
+from mednotes.domains.wiki.contracts.workflow_outcomes import WorkflowDecision
+from mednotes.kernel.base import JsonObject
+from mednotes.kernel.workflow import (
+    HumanDecisionPacket,
+    VersionControlSafety,
+    WorkflowArtifact,
+    WorkflowPhaseOutcome,
+    WorkflowPhaseReceipt,
+    WorkflowReceiptPayload,
+    WorkflowRollback,
+)
+
+
+class WorkflowReceiptError(ValueError):
+    """Raised when a workflow receipt violates the common contract."""
+
+
+@dataclass
+class WorkflowReceiptBuilder:
+    schema: str
+    workflow: str
+    run_id: str
+    phase_outcomes: list[WorkflowPhaseOutcome] = field(default_factory=list)
+    phase_receipts: dict[str, WorkflowPhaseReceipt] = field(default_factory=dict)
+    artifacts: list[WorkflowArtifact] = field(default_factory=list)
+    changed_files: list[str] = field(default_factory=list)
+    rollback: WorkflowRollback | None = None
+    no_resource_mutation: bool = False
+
+    def add_phase(self, phase: str, *, decision: WorkflowDecision) -> None:
+        human_packet = (
+            HumanDecisionPacket.model_validate(decision.to_human_decision_packet())
+            if decision.kind == "ask_human"
+            else None
+        )
+        self.phase_outcomes.append(
+            WorkflowPhaseOutcome(
+                phase=phase,
+                decision_summary=decision.decision_summary(),
+                human_decision_packet=human_packet,
+            )
+        )
+
+    def add_phase_receipt(self, phase: str, receipt_path: str, *, status: str = "") -> None:
+        self.phase_receipts[phase] = WorkflowPhaseReceipt(receipt_path=receipt_path, status=status)
+
+    def add_artifact(self, kind: str, path: str) -> None:
+        self.artifacts.append(WorkflowArtifact(kind=kind, path=path))
+
+    def add_mutation_summary(self, *, changed_paths: list[str]) -> None:
+        self.changed_files.extend(changed_paths)
+
+    def add_rollback(self, strategy: str, value: str) -> None:
+        self.rollback = WorkflowRollback(strategy=strategy, value=value)
+
+    def finalize(self, *, status: str, next_action: str = "") -> JsonObject:
+        if status in {"blocked", "failed", "completed_with_warnings", "completed_with_link_blockers"} and not next_action:
+            raise WorkflowReceiptError(f"{status} receipt requires next_action")
+        mutated = bool(self.changed_files)
+        if mutated and not self.rollback and not self.no_resource_mutation:
+            raise WorkflowReceiptError("mutated receipt requires rollback or no_resource_mutation")
+        try:
+            phase_outcomes = [WorkflowPhaseOutcome.model_validate(item) for item in self.phase_outcomes]
+            phase_receipts = {
+                phase: WorkflowPhaseReceipt.model_validate(receipt) for phase, receipt in self.phase_receipts.items()
+            }
+            artifacts = [WorkflowArtifact.model_validate(item) for item in self.artifacts]
+            rollback = WorkflowRollback.model_validate(self.rollback) if self.rollback else None
+            human_packets = [outcome.human_decision_packet for outcome in phase_outcomes if outcome.human_decision_packet]
+            receipt = WorkflowReceiptPayload(
+                schema=self.schema,
+                workflow=self.workflow,
+                run_id=self.run_id,
+                status=status,  # type: ignore[arg-type]
+                mutated=mutated,
+                next_action=next_action,
+                human_decision_required=bool(human_packets),
+                human_decision_packet=human_packets[0] if human_packets else None,
+                phase_outcomes=phase_outcomes,
+                phase_receipts=phase_receipts,
+                artifacts=artifacts,
+                changed_files=list(self.changed_files),
+                rollback=rollback,
+                version_control_safety=VersionControlSafety(
+                    no_resource_mutation=self.no_resource_mutation,
+                    rollback_declared=bool(self.rollback),
+                ),
+            )
+        except PydanticValidationError as exc:
+            raise WorkflowReceiptError(f"invalid receipt payload: {exc}") from exc
+        payload = receipt.to_payload()
+        payload["rollback"] = payload["rollback"] or {}
+        return payload

package/.opencode/mednotes/src/mednotes/domains/wiki/flows/__init__.py

@@ -0,0 +1 @@
+"""flows."""

package/.opencode/mednotes/src/mednotes/domains/wiki/flows/enrich/__init__.py

@@ -0,0 +1 @@
+"""enrich — o workflow público /mednotes:enrich (flow)."""

package/.opencode/mednotes/src/mednotes/domains/wiki/flows/enrich/__main__.py

@@ -0,0 +1,4 @@
+from mednotes.domains.wiki.flows.enrich.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.opencode/mednotes/src/mednotes/domains/wiki/flows/enrich/cli.py

@@ -0,0 +1,275 @@
+"""CLI do enricher — toolbox de subcomandos.
+
+Cada subcomando faz **uma** coisa e devolve **JSON na stdout** (consumível por
+agente). Erros vão pra stderr com exit code != 0.
+
+Subcomandos:
+- ``sections <nota.md>``: lista headings da nota com ``section_path``, ``level``,
+  ``start_line``, ``end_line``.
+- ``search <source> --query <q> [--visual-type T] [--top-k N]``: busca candidatas
+  via adapter (``wikimedia`` ou ``web_search``).
+- ``insert <nota.md> --section P --image F --concept C --source S --source-url U``:
+  insere bloco no fim da seção e atualiza frontmatter aditivamente. ``--section``
+  é repetível pra paths nested (ex: ``--section "🤖 Gemini" --section Mecanismo``).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Callable
+from dataclasses import asdict, is_dataclass
+from pathlib import Path
+from typing import Protocol
+
+from mednotes.domains.wiki.capabilities.illustrate.core import frontmatter, insert
+from mednotes.domains.wiki.capabilities.illustrate.core.cache import Cache
+from mednotes.domains.wiki.capabilities.illustrate.core.config import expand_path, resolve_wiki_root, wiki_memory_path
+from mednotes.domains.wiki.capabilities.illustrate.core.config import load as load_config
+from mednotes.domains.wiki.capabilities.illustrate.core.download import DownloadError
+from mednotes.domains.wiki.capabilities.illustrate.core.download import download as download_image
+from mednotes.domains.wiki.capabilities.illustrate.sources import ImageCandidate, web_search, wikimedia
+from mednotes.kernel.base import JsonObject, JsonObjectAdapter, JsonValue
+
+
+class _ImageSearchSource(Protocol):
+    """Minimal adapter contract for image candidate sources exposed by this CLI."""
+
+    def search(self, query: str, visual_type: str, *, top_k: int = 4) -> list[ImageCandidate]: ...
+
+
+_SOURCE_REGISTRY: dict[str, _ImageSearchSource] = {
+    wikimedia.NAME: wikimedia,
+    web_search.NAME: web_search,
+}
+
+
+def _emit(obj: object) -> None:
+    """Serializa ``obj`` como JSON na stdout. ``ensure_ascii=False`` pra
+    preservar acentos e emojis nas mensagens."""
+    json.dump(obj, sys.stdout, ensure_ascii=False, indent=2, default=_json_default)
+    sys.stdout.write("\n")
+
+
+def _json_default(o: object) -> JsonValue:
+    # Datetimes (frontmatter) e dataclasses (ImageCandidate).
+    if hasattr(o, "isoformat"):
+        return str(o.isoformat())  # type: ignore[attr-defined]
+    if is_dataclass(o) and not isinstance(o, type):
+        return JsonObjectAdapter.validate_python(asdict(o))
+    raise TypeError(f"sem serializador pra {type(o).__name__}")
+
+
+def _guard_note_write(note: Path, *, command: str) -> int | None:
+    from mednotes.platform.vault_guard import VaultGuardError, require_vault_guard
+    try:
+        require_vault_guard(note, workflow="/mednotes:enrich", command=command)
+    except VaultGuardError as exc:
+        _emit(exc.to_payload())
+        return int(exc.exit_code)
+    return None
+
+
+# --- subcomandos -----------------------------------------------------
+
+
+def cmd_sections(args: argparse.Namespace) -> int:
+    text = args.note.read_text(encoding="utf-8")
+    _emit(insert.parse_sections(text))
+    return 0
+
+
+def cmd_search(args: argparse.Namespace) -> int:
+    source = _SOURCE_REGISTRY.get(args.source)
+    if source is None:
+        print(
+            f"erro: source desconhecida: {args.source!r}. "
+            f"disponíveis: {', '.join(sorted(_SOURCE_REGISTRY))}",
+            file=sys.stderr,
+        )
+        return 2
+    candidates = source.search(args.query, args.visual_type, top_k=args.top_k)
+    _emit([_candidate_to_dict(c) for c in candidates])
+    return 0
+
+
+def cmd_download(args: argparse.Namespace) -> int:
+    cfg = load_config(args.config)
+    vault = _resolve_vault(args, cfg)
+    if vault is None:
+        print(
+            "erro: vault_dir não definido. Passe --vault ou configure "
+            "[vault].path em config.toml ou [paths].wiki_dir em "
+            f"{wiki_memory_path()}.",
+            file=sys.stderr,
+        )
+        return 4
+    cache_path = expand_path(cfg["cache"]["path"])
+    try:
+        with Cache(cache_path) as cache:
+            out = download_image(
+                args.url,
+                vault_dir=vault,
+                cache=cache,
+                max_dim=args.max_dim or cfg["enrichment"]["max_image_dimension"],
+                webp_min_savings_pct=cfg["enrichment"]["webp_min_savings_pct"],
+                source=args.source,
+                source_url=args.source_url,
+                user_agent=cfg["download"]["user_agent"],
+            )
+    except DownloadError as e:
+        print(f"erro: {e}", file=sys.stderr)
+        return 5
+    _emit(out)
+    return 0
+
+
+def _resolve_vault(args: argparse.Namespace, cfg: dict) -> Path | None:
+    if args.vault:
+        return args.vault
+    base = cfg["vault"].get("path") or ""
+    if not base:
+        wiki_root = resolve_wiki_root(args.config)
+        if wiki_root:
+            return wiki_root / cfg["vault"].get("attachments_subdir", "")
+        return None
+    return expand_path(base) / cfg["vault"].get("attachments_subdir", "")
+
+
+def cmd_insert(args: argparse.Namespace) -> int:
+    blocked = _guard_note_write(args.note, command="enricher insert")
+    if blocked is not None:
+        return blocked
+    text = args.note.read_text(encoding="utf-8")
+    item = insert.InsertedImage(
+        anchor_id=args.anchor_id or "manual",
+        section_path=args.section,
+        image_filename=args.image,
+        concept=args.concept,
+        source=args.source,
+        source_url=args.source_url,
+    )
+    try:
+        new_text = insert.insert_images(text, [item])
+    except insert.SectionNotFound as e:
+        print(f"erro: {e}", file=sys.stderr)
+        return 3
+    args.note.write_text(new_text, encoding="utf-8")
+    meta, _ = frontmatter.read(new_text)
+    _emit(
+        {
+            "note": str(args.note),
+            "inserted": 1,
+            "image_count": meta.get("image_count"),
+            "image_sources": meta.get("image_sources"),
+            "images_enriched_at": meta.get("images_enriched_at"),
+        }
+    )
+    return 0
+
+
+def _candidate_to_dict(c: ImageCandidate) -> JsonObject:
+    return JsonObjectAdapter.validate_python(asdict(c))
+
+
+# --- parser ---------------------------------------------------------
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="enricher",
+        description=(
+            "Toolbox de primitivas para enriquecer notas médicas com imagens. "
+            "Cada subcomando devolve JSON na stdout."
+        ),
+    )
+    p.add_argument(
+        "--config",
+        type=Path,
+        default=None,
+        help=(
+            "config.toml (default: busca na árvore acima do CWD e depois em "
+            "~/.mednotes/config.toml)"
+        ),
+    )
+
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s_sections = sub.add_parser("sections", help="Lista headings da nota.")
+    s_sections.add_argument("note", type=Path, help="Caminho da nota .md")
+    s_sections.set_defaults(func=cmd_sections)
+
+    s_search = sub.add_parser("search", help="Busca candidatas em uma source.")
+    s_search.add_argument(
+        "source",
+        choices=sorted(_SOURCE_REGISTRY),
+        help="Nome do adapter de fonte.",
+    )
+    s_search.add_argument("--query", required=True, help="Termo de busca.")
+    s_search.add_argument(
+        "--visual-type",
+        default="diagram",
+        help="Tipo visual desejado (diagram, histology, radiology...). "
+        "Aceito por uniformidade entre adapters.",
+    )
+    s_search.add_argument("--top-k", type=int, default=4, help="Máximo de candidatas.")
+    s_search.set_defaults(func=cmd_search)
+
+    s_download = sub.add_parser(
+        "download",
+        help="Baixa imagem, valida, redimensiona, dedupe SHA, indexa no cache.",
+    )
+    s_download.add_argument("url", help="URL direta da imagem.")
+    s_download.add_argument(
+        "--vault",
+        type=Path,
+        default=None,
+        help=(
+            "Diretório destino. Default: <[vault].path>/<[vault].attachments_subdir>; "
+            "fallback: <config.toml [paths].wiki_dir>/<[vault].attachments_subdir>."
+        ),
+    )
+    s_download.add_argument(
+        "--max-dim",
+        type=int,
+        default=None,
+        help="Maior lado em px. Default: [enrichment].max_image_dimension.",
+    )
+    s_download.add_argument(
+        "--source",
+        default="unknown",
+        help="Identificador da fonte (vai para o cache).",
+    )
+    s_download.add_argument(
+        "--source-url",
+        default=None,
+        help="URL canônica da página descritiva (rastreabilidade).",
+    )
+    s_download.set_defaults(func=cmd_download)
+
+    s_insert = sub.add_parser(
+        "insert",
+        help="Insere bloco de imagem em uma seção da nota e atualiza frontmatter.",
+    )
+    s_insert.add_argument("note", type=Path, help="Caminho da nota .md (modificada in-place).")
+    s_insert.add_argument(
+        "--section",
+        action="append",
+        required=True,
+        help="Heading-trail. Repetível: --section H1 --section H2 (do topo pra folha).",
+    )
+    s_insert.add_argument("--image", required=True, help="Filename do attachment já baixado.")
+    s_insert.add_argument("--concept", required=True, help="Conceito da figura (vai no caption).")
+    s_insert.add_argument("--source", required=True, help="Identificador da fonte (ex: wikimedia).")
+    s_insert.add_argument("--source-url", required=True, help="URL canônica da fonte.")
+    s_insert.add_argument("--anchor-id", default=None, help="Opcional, default 'manual'.")
+    s_insert.set_defaults(func=cmd_insert)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    func: Callable[[argparse.Namespace], int] = args.func
+    return func(args)

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

@@ -0,0 +1,2 @@
+"""Image enrichment workflow internals."""
+from __future__ import annotations