rslapp 1.0.0__py3-none-any.whl

rslapp/__init__.py

@@ -0,0 +1,4 @@
+"""RSL.app — Servidor MCP para revisão sistemática da literatura."""
+
+# D-001: Pacote principal em Python
+__version__ = "1.0.0"

rslapp/config.py

@@ -0,0 +1,77 @@
+"""Configuração local do servidor RSL.app a partir de variáveis de ambiente."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+DEFAULT_DATA_DIR_NAME = "RSL.app"
+DEFAULT_EXPORT_DIR_NAME = "exports"
+DEFAULT_CACHE_DAYS = 7
+
+
+# FR-07: Configuração do servidor e das chaves de API na máquina do usuário via variáveis de ambiente
+# NFR-02: Execução local (self-hosted), usando diretórios locais da máquina do usuário
+# NFR-03: O objeto de configuração guarda apenas se as chaves estão presentes (bool), nunca o valor delas
+@dataclass(frozen=True)
+class Config:
+    """Configuração imutável carregada do ambiente local."""
+
+    data_dir: Path
+    export_dir: Path
+    cache_days: int = DEFAULT_CACHE_DAYS
+    contact_email: str | None = field(default=None, repr=False)
+    openalex_key_configured: bool = False
+    semantic_scholar_key_configured: bool = False
+
+
+def _is_key_configured(env_var: str) -> bool:
+    """Verifica se uma chave de API está definida e não vazia sem reter seu valor (NFR-03)."""
+    raw = os.environ.get(env_var)
+    return bool(raw and raw.strip())
+
+
+def _parse_cache_days(raw_value: str | None) -> int:
+    """Valida e converte RSL_CACHE_DAYS para inteiro positivo."""
+    if raw_value is None:
+        return DEFAULT_CACHE_DAYS
+    try:
+        days = int(raw_value.strip())
+    except ValueError:
+        raise ValueError("RSL_CACHE_DAYS deve ser um inteiro positivo") from None
+    if days <= 0:
+        raise ValueError("RSL_CACHE_DAYS deve ser um inteiro positivo")
+    return days
+
+
+# FR-07: Leitura dinâmica da configuração a cada chamada, sem criar pastas nem reter chaves
+def load() -> Config:
+    """Lê as variáveis de ambiente e devolve a configuração atual."""
+    # NFR-02: Pastas locais padrão na conta do usuário
+    raw_data_dir = os.environ.get("RSL_DATA_DIR")
+    if raw_data_dir and raw_data_dir.strip():
+        data_dir = Path(raw_data_dir.strip()).expanduser()
+    else:
+        data_dir = Path.home() / DEFAULT_DATA_DIR_NAME
+
+    raw_export_dir = os.environ.get("RSL_EXPORT_DIR")
+    if raw_export_dir and raw_export_dir.strip():
+        export_dir = Path(raw_export_dir.strip()).expanduser()
+    else:
+        export_dir = data_dir / DEFAULT_EXPORT_DIR_NAME
+
+    cache_days = _parse_cache_days(os.environ.get("RSL_CACHE_DAYS"))
+
+    raw_email = os.environ.get("RSL_CONTACT_EMAIL")
+    contact_email = raw_email.strip() if raw_email and raw_email.strip() else None
+
+    # NFR-03: Apenas booleanos indicando presença das chaves são armazenados
+    return Config(
+        data_dir=data_dir,
+        export_dir=export_dir,
+        cache_days=cache_days,
+        contact_email=contact_email,
+        openalex_key_configured=_is_key_configured("OPENALEX_API_KEY"),
+        semantic_scholar_key_configured=_is_key_configured("SEMANTIC_SCHOLAR_API_KEY"),
+    )

rslapp/core/__init__.py

@@ -0,0 +1,16 @@
+"""Miolo (core) do RSL.app: modelos e erros independentes do protocolo MCP."""
+
+from __future__ import annotations
+
+from rslapp.core.errors import ERROR_CODES, ErrorCode, RSLError
+from rslapp.core.models import Affiliation, Author, SourceResult, Work
+
+__all__ = [
+    "ERROR_CODES",
+    "Affiliation",
+    "Author",
+    "ErrorCode",
+    "RSLError",
+    "SourceResult",
+    "Work",
+]

rslapp/core/dedup.py

@@ -0,0 +1,319 @@
+"""Deduplicação e junção de artigos acadêmicos entre múltiplas fontes."""
+
+from __future__ import annotations
+
+import unicodedata
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from rslapp.core.models import Author, Work
+
+# FR-04: Ordem canônica de prevalência de fontes acadêmicas
+SOURCE_PRECEDENCE: tuple[str, ...] = ("openalex", "crossref", "semantic_scholar")
+
+_DOI_PREFIXES: tuple[str, ...] = (
+    "https://doi.org/",
+    "http://doi.org/",
+    "https://dx.doi.org/",
+    "http://dx.doi.org/",
+    "doi:",
+)
+
+
+# FR-04: Normalização de DOI (minúsculo, sem prefixos URL ou 'doi:', sem barras finais)
+def normalize_doi(raw: str | None) -> str | None:
+    """Normaliza um DOI removendo prefixos conhecidos e espaços, em minúsculas."""
+    if not isinstance(raw, str):
+        return None
+    val = raw.strip().lower()
+    for prefix in _DOI_PREFIXES:
+        if val.startswith(prefix):
+            val = val[len(prefix) :].strip()
+    val = val.rstrip("/")
+    return val if val else None
+
+
+# FR-04: Normalização de título (minúsculas, sem acento, só letras e números, espaços simples)
+def normalize_title(title: str) -> str:
+    """Normaliza um título para chave de deduplicação quando não há DOI."""
+    if not isinstance(title, str):
+        return ""
+    decomposed = unicodedata.normalize("NFKD", title.lower())
+    without_accents = "".join(
+        ch for ch in decomposed if not unicodedata.combining(ch)
+    )
+    alnum_and_spaces = "".join(
+        ch for ch in without_accents if ch.isalnum() or ch.isspace()
+    )
+    return " ".join(alnum_and_spaces.split())
+
+
+def get_work_source(work: Work) -> str | None:
+    """Identifica o nome da fonte principal de um trabalho acadêmico."""
+    for src in SOURCE_PRECEDENCE:
+        if src in work.source_ids or src in work.citations:
+            return src
+    if work.source_ids:
+        return next(iter(work.source_ids.keys()))
+    if work.citations:
+        return next(iter(work.citations.keys()))
+    return None
+
+
+def _source_priority(work: Work) -> int:
+    src = get_work_source(work)
+    if src in SOURCE_PRECEDENCE:
+        return SOURCE_PRECEDENCE.index(src)
+    return len(SOURCE_PRECEDENCE)
+
+
+@dataclass
+class _WorkCluster:
+    works: list[Work] = field(default_factory=list)
+    dois: set[str] = field(default_factory=set)
+    title_years: set[tuple[str, int]] = field(default_factory=set)
+
+
+@dataclass
+class DedupResult:
+    """Resultado da deduplicação contendo trabalhos únicos e metadados de junção."""
+
+    works: list[Work]
+    merge: dict[str, Any]
+
+
+# FR-04, FR-14: Prevalência de campos na junção (OpenAlex > Crossref > Semantic Scholar)
+def _merge_cluster_works(cluster: _WorkCluster) -> Work:
+    ordered = sorted(cluster.works, key=_source_priority)
+
+    # Campos simples: primeiro valor não vazio na ordem de precedência
+    title = next((w.title for w in ordered if w.title and w.title.strip()), "")
+    doi = next((normalize_doi(w.doi) for w in ordered if normalize_doi(w.doi)), None)
+    year = next((w.year for w in ordered if isinstance(w.year, int)), None)
+    type_ = next((w.type for w in ordered if w.type and w.type.strip()), None)
+    venue = next((w.venue for w in ordered if w.venue and w.venue.strip()), None)
+    abstract = next((w.abstract for w in ordered if w.abstract and w.abstract.strip()), None)
+    references_count = next(
+        (w.references_count for w in ordered if isinstance(w.references_count, int)), None
+    )
+
+    # authors e keywords: primeira fonte que os tiver não vazios
+    authors_work = next((w for w in ordered if w.authors), None)
+    authors = [Author.from_dict(a.to_dict()) for a in authors_work.authors] if authors_work else []
+
+    keywords_work = next((w for w in ordered if w.keywords), None)
+    keywords = list(keywords_work.keywords) if keywords_work else []
+
+    # source_ids e citations: unem todas as fontes sem perda e sem somar citações (FR-14)
+    source_ids: dict[str, str] = {}
+    for w in ordered:
+        for src_name, src_id in w.source_ids.items():
+            if src_name not in source_ids:
+                source_ids[src_name] = src_id
+
+    citations: dict[str, int] = {}
+    for w in ordered:
+        for src_name, count in w.citations.items():
+            if src_name not in citations:
+                citations[src_name] = count
+
+    # references: união na ordem sem repetição, com ids da primeira fonte primeiro
+    references: list[str] = []
+    seen_refs: set[str] = set()
+    for w in ordered:
+        for ref in w.references:
+            if ref not in seen_refs:
+                seen_refs.add(ref)
+                references.append(ref)
+
+    return Work(
+        title=title,
+        doi=doi,
+        year=year,
+        type=type_,
+        venue=venue,
+        abstract=abstract,
+        keywords=keywords,
+        authors=authors,
+        references=references,
+        references_count=references_count,
+        citations=citations,
+        source_ids=source_ids,
+    )
+
+
+# FR-04: Contagem de divergências por campo em artigos presentes em mais de uma fonte
+def _compute_cluster_divergences(cluster: _WorkCluster) -> dict[str, bool]:
+    diverged = {"year": False, "title": False, "doi": False, "venue": False}
+    ordered = sorted(cluster.works, key=_source_priority)
+
+    # Agrupa o primeiro valor de cada fonte distinta
+    seen_sources: set[str] = set()
+    titles: list[str] = []
+    years: list[int] = []
+    dois: list[str] = []
+    venues: list[str] = []
+
+    for w in ordered:
+        src = get_work_source(w) or id(w)
+        if src in seen_sources:
+            continue
+        seen_sources.add(str(src))
+
+        t_norm = normalize_title(w.title)
+        if t_norm:
+            titles.append(t_norm)
+
+        if isinstance(w.year, int):
+            years.append(w.year)
+
+        d_norm = normalize_doi(w.doi)
+        if d_norm:
+            dois.append(d_norm)
+
+        if w.venue and w.venue.strip():
+            venues.append(w.venue.strip())
+
+    if len(set(titles)) > 1:
+        diverged["title"] = True
+    if len(set(years)) > 1:
+        diverged["year"] = True
+    if len(set(dois)) > 1:
+        diverged["doi"] = True
+    if len(set(venues)) > 1:
+        diverged["venue"] = True
+
+    return diverged
+
+
+# FR-04: Atualização de índices do grupo para junção transitiva
+def _reindex_cluster(
+    cluster: _WorkCluster,
+    by_doi: dict[str, _WorkCluster],
+    by_title_year: dict[tuple[str, int], list[_WorkCluster]],
+) -> None:
+    for w in cluster.works:
+        norm_d = normalize_doi(w.doi)
+        if norm_d is not None:
+            cluster.dois.add(norm_d)
+            by_doi[norm_d] = cluster
+
+        # FR-04: só o título com o ano do próprio registro entra no índice; ano ausente
+        # nunca é emprestado de outro membro (a regra é por par, e assim não depende da ordem)
+        norm_t = normalize_title(w.title)
+        if norm_t and isinstance(w.year, int):
+            ty = (norm_t, w.year)
+            cluster.title_years.add(ty)
+            cands = by_title_year.setdefault(ty, [])
+            if cluster not in cands:
+                cands.append(cluster)
+
+
+# FR-04: Fusão de grupo de origem no alvo com migração de referências e índices
+def _merge_clusters(
+    target: _WorkCluster,
+    source: _WorkCluster,
+    clusters: list[_WorkCluster],
+    by_doi: dict[str, _WorkCluster],
+    by_title_year: dict[tuple[str, int], list[_WorkCluster]],
+) -> None:
+    target.works.extend(source.works)
+    if source in clusters:
+        clusters.remove(source)
+    for ty in source.title_years:
+        if ty in by_title_year and source in by_title_year[ty]:
+            by_title_year[ty].remove(source)
+    for d in source.dois:
+        if by_doi.get(d) is source:
+            by_doi[d] = target
+    _reindex_cluster(target, by_doi, by_title_year)
+
+
+# FR-04, FR-14: Deduplicação transitiva com contagem de artigos juntados e divergências
+def deduplicate_works_with_merge(works: Sequence[Work]) -> DedupResult:
+    """Agrupa artigos duplicados por DOI ou (título normalizado + ano), gerando merge info."""
+    clusters: list[_WorkCluster] = []
+    by_doi: dict[str, _WorkCluster] = {}
+    by_title_year: dict[tuple[str, int], list[_WorkCluster]] = {}
+
+    for work in works:
+        norm_doi = normalize_doi(work.doi)
+        norm_title = normalize_title(work.title)
+        year = work.year if isinstance(work.year, int) else None
+
+        doi_cluster = by_doi.get(norm_doi) if norm_doi is not None else None
+
+        title_clusters: list[_WorkCluster] = []
+        if norm_title and year is not None:
+            for cand in by_title_year.get((norm_title, year), []):
+                if cand not in title_clusters:
+                    title_clusters.append(cand)
+
+        # Escolha do cluster alvo respeitando regras de DOI e junção transitiva:
+        # - Dois DOIs diferentes nunca se juntam (FR-04).
+        # - Se um registro casa com dois grupos diferentes (um pelo DOI, outro pelo título),
+        #   ele fica no grupo do DOI (FR-04).
+        target: _WorkCluster
+        if doi_cluster is not None:
+            target = doi_cluster
+        elif norm_doi is not None:
+            valid_cands = [c for c in title_clusters if not c.dois]
+            if valid_cands:
+                target = valid_cands[0]
+            else:
+                target = _WorkCluster()
+                clusters.append(target)
+        else:
+            if title_clusters:
+                doi_cands = [c for c in title_clusters if c.dois]
+                target = doi_cands[0] if doi_cands else title_clusters[0]
+            else:
+                target = _WorkCluster()
+                clusters.append(target)
+
+        # Funde transitivamente quaisquer candidatos por título que não tenham DOI conflitante
+        for cand in title_clusters:
+            if cand is not target and not cand.dois:
+                _merge_clusters(target, cand, clusters, by_doi, by_title_year)
+
+        target.works.append(work)
+        _reindex_cluster(target, by_doi, by_title_year)
+
+    merged_count = 0
+    divergence_counts: dict[str, int] = {"year": 0, "title": 0, "doi": 0, "venue": 0}
+    deduped_works: list[Work] = []
+
+    for cluster in clusters:
+        distinct_sources: set[str] = set()
+        for w in cluster.works:
+            src = get_work_source(w)
+            if src:
+                distinct_sources.add(src)
+
+        is_multi_source = len(distinct_sources) > 1 or (
+            not distinct_sources and len(cluster.works) > 1
+        )
+
+        if is_multi_source:
+            merged_count += 1
+            divs = _compute_cluster_divergences(cluster)
+            for field_name, had_div in divs.items():
+                if had_div:
+                    divergence_counts[field_name] += 1
+
+        deduped_works.append(_merge_cluster_works(cluster))
+
+    divergences_result = {k: v for k, v in divergence_counts.items() if v > 0}
+    merge_info: dict[str, Any] = {
+        "merged": merged_count,
+        "divergences": divergences_result,
+    }
+
+    return DedupResult(works=deduped_works, merge=merge_info)
+
+
+# FR-04: Interface simplificada de deduplicação preservando compatibilidade
+def deduplicate_works(works: Sequence[Work]) -> list[Work]:
+    """Remove duplicatas mantendo o primeiro registro pela ordem de precedência e agregando dados."""
+    return deduplicate_works_with_merge(works).works

rslapp/core/errors.py

@@ -0,0 +1,31 @@
+"""Erros do miolo do RSL.app segundo o contrato de interface."""
+
+from __future__ import annotations
+
+from typing import Literal, get_args
+
+# FR-06, D-002: Códigos de erro do contrato de interface (incluindo empty_list para lista sem artigos)
+ErrorCode = Literal[
+    "no_source_available",
+    "invalid_input",
+    "list_not_found",
+    "search_not_found",
+    "work_not_found",
+    "format_not_available",
+    "export_folder_not_writable",
+    "empty_list",
+]
+
+ERROR_CODES: frozenset[str] = frozenset(get_args(ErrorCode))
+
+
+# D-002: Códigos de erro estáveis do contrato, sem dependência do protocolo MCP no miolo
+class RSLError(Exception):
+    """Exceção de domínio do miolo que o servidor MCP converte na borda."""
+
+    def __init__(self, code: ErrorCode | str, message: str) -> None:
+        if code not in ERROR_CODES:
+            raise ValueError(f"Código de erro fora do contrato: {code!r}")
+        self.code: str = code
+        self.message: str = message
+        super().__init__(f"{code}: {message}")

rslapp/core/find.py

@@ -0,0 +1,213 @@
+"""Miolo de busca de artigo específico por título ou DOI, deduplicação e gravação."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Sequence
+from typing import Any
+
+from rslapp.core.dedup import deduplicate_works_with_merge, normalize_doi
+from rslapp.core.errors import RSLError
+from rslapp.core.models import SourceResult, Work
+from rslapp.core.search import _select_sources, _summarize_work
+from rslapp.sources.base import Source
+from rslapp.store import Store
+
+PAGE_SIZE = 25
+DEFAULT_MAX_RESULTS = 10
+MIN_MAX_RESULTS = 1
+MAX_MAX_RESULTS = 100
+
+__all__ = [
+    "DEFAULT_MAX_RESULTS",
+    "MAX_MAX_RESULTS",
+    "MIN_MAX_RESULTS",
+    "PAGE_SIZE",
+    "run_find",
+]
+
+
+# FR-02, D-002: Validação estrita de DOI (começa com 10., sem espaço, ?, #, % nem segmentos . ou ..)
+def _validate_and_normalize_doi(raw: Any) -> str:
+    if not isinstance(raw, str) or not raw.strip():
+        raise RSLError("invalid_input", "doi não pode ser vazio")
+    val = raw.strip()
+    norm = normalize_doi(val)
+    if not norm or not norm.startswith("10."):
+        raise RSLError("invalid_input", f"doi deve começar com '10.': {raw}")
+    if any(ch.isspace() for ch in norm):
+        raise RSLError("invalid_input", f"doi não pode conter espaços: {raw}")
+    if any(ch in "?#%" for ch in norm):
+        raise RSLError("invalid_input", f"doi contém caracteres inválidos: {raw}")
+    segments = norm.split("/")
+    if any(seg in (".", "..") for seg in segments):
+        raise RSLError("invalid_input", f"doi contém segmentos inválidos: {raw}")
+    return norm
+
+
+# FR-02, UC-02, D-002: Orquestração da busca de artigo específico por DOI ou título
+async def run_find(
+    store: Store,
+    sources: Sequence[Source],
+    *,
+    title: str | None = None,
+    doi: str | None = None,
+    request_summary: str = "",
+    max_results: int = DEFAULT_MAX_RESULTS,
+    source_names: Sequence[str] | None = None,
+    repeated_from: str | None = None,
+    kind: str = "work",
+) -> dict[str, Any]:
+    """Busca um artigo específico por título ou DOI nas fontes, deduplica e grava lista própria."""
+    if (title is None and doi is None) or (title is not None and doi is not None):
+        raise RSLError("invalid_input", "informe exatamente um entre title ou doi")
+
+    clean_doi: str | None = None
+    clean_title: str | None = None
+
+    if doi is not None:
+        clean_doi = _validate_and_normalize_doi(doi)
+    else:
+        assert title is not None
+        if not isinstance(title, str) or not title.strip():
+            raise RSLError("invalid_input", "title não pode ser vazio")
+        clean_title = title.strip()
+
+    if not isinstance(request_summary, str):
+        raise RSLError("invalid_input", "request_summary deve ser texto")
+
+    if (
+        not isinstance(max_results, int)
+        or isinstance(max_results, bool)
+        or max_results < MIN_MAX_RESULTS
+        or max_results > MAX_MAX_RESULTS
+    ):
+        raise RSLError(
+            "invalid_input",
+            f"max_results deve ser um inteiro entre {MIN_MAX_RESULTS} e {MAX_MAX_RESULTS}",
+        )
+
+    selected_sources = _select_sources(sources, source_names)
+
+    # FR-02: Execução por DOI via find_by_doi ou por título via search
+    if clean_doi is not None:
+        async def _fetch_by_doi(source: Source) -> tuple[SourceResult, bool, str | None]:
+            if not hasattr(source, "find_by_doi"):
+                return (
+                    SourceResult(
+                        name=source.name,
+                        status="not_supported",
+                        reason=f"não suportado por {source.name}",
+                        query=f"doi:{clean_doi}",
+                        found=None,
+                        fetched=0,
+                        works=[],
+                    ),
+                    False,
+                    None,
+                )
+            result = await source.find_by_doi(clean_doi)
+            return result, False, None
+
+        fetch_outcomes = await asyncio.gather(
+            *[_fetch_by_doi(src) for src in selected_sources]
+        )
+    else:
+        assert clean_title is not None
+
+        # NFR-06: Consulta o cache antes de chamar cada fonte e só grava no cache resultados ok
+        async def _fetch_by_title(source: Source) -> tuple[SourceResult, bool, str | None]:
+            c_query = source.cache_query(clean_title, max_results)
+            cached = store.get_cache(source.name, c_query)
+            if cached is not None:
+                return SourceResult.from_dict(cached["response"]), True, cached.get("fetched_at")
+            result = await source.search(clean_title, max_results)
+            if result.status == "ok":
+                store.set_cache(source.name, c_query, result.to_dict())
+            return result, False, None
+
+        fetch_outcomes = await asyncio.gather(
+            *[_fetch_by_title(src) for src in selected_sources]
+        )
+
+    source_entries: list[dict[str, Any]] = []
+    raw_works: list[Work] = []
+
+    for result, from_cache, fetched_at in fetch_outcomes:
+        raw_works.extend(result.works)
+        source_entries.append(
+            {
+                "name": result.name,
+                "query": result.query,
+                "status": result.status,
+                "reason": result.reason,
+                "found": result.found,
+                "fetched": result.fetched,
+                "from_cache": from_cache,
+                "fetched_at": fetched_at,
+            }
+        )
+
+    # D-002: Erro no_source_available quando todas as fontes estão sem chave
+    if all(entry["status"] == "missing_key" for entry in source_entries):
+        raise RSLError(
+            "no_source_available",
+            "nenhuma fonte pode responder; configure OPENALEX_API_KEY",
+        )
+
+    # FR-04, FR-14: Deduplicação e junção entre fontes com prevalência e contagem de divergências
+    dedup_result = deduplicate_works_with_merge(raw_works)
+    deduped_works = dedup_result.works
+    total = len(deduped_works)
+
+    # FR-08: Lista incompleta quando alguma fonte consultada não terminou em ok
+    list_status = (
+        "complete"
+        if all(entry["status"] == "ok" for entry in source_entries)
+        else "incomplete"
+    )
+
+    params: dict[str, Any] = {
+        "max_results": max_results,
+        "sources": [src.name for src in selected_sources],
+    }
+    if clean_doi is not None:
+        params["doi"] = clean_doi
+    else:
+        assert clean_title is not None
+        params["title"] = clean_title
+
+    # FR-02, FR-05, FR-09, FR-12: Gravação da busca e lista (vazia ou preenchida)
+    search_data: dict[str, Any] = {
+        "kind": kind,
+        "request_summary": request_summary,
+        "repeated_from": repeated_from,
+        "origin": None,
+        "params": params,
+        "merge": dedup_result.merge,
+        "sources": source_entries,
+    }
+    list_data: dict[str, Any] = {
+        "status": list_status,
+        "total": total,
+        "works": [work.to_dict() for work in deduped_works],
+    }
+    saved_search, saved_list = store.record_search(search_data, list_data)
+
+    first_page_works = [_summarize_work(w) for w in deduped_works[:PAGE_SIZE]]
+    next_page: int | None = 2 if total > PAGE_SIZE else None
+
+    result_dict: dict[str, Any] = {
+        "search_id": saved_search["id"],
+        "list_id": saved_list["id"],
+        "status": list_status,
+        "total": total,
+        "page": 1,
+        "next_page": next_page,
+        "sources": saved_search["sources"],
+        "works": first_page_works,
+    }
+    if repeated_from is not None:
+        result_dict["repeated_from"] = repeated_from
+
+    return result_dict