Browse

async def browse_document(
    self,
    reference_code: str,
    pages: str,
    highlight_term: str | None = None,
    max_pages: int = 20,
    research_context: str | None = None,
    session_id: str | None = None,
) -> BrowseResult:
    """Browse specific pages of a document.

    Retrieves full transcribed content for specified pages of a document,
    with optional term highlighting. Supports various page specifications
    including ranges (1-5), lists (1,3,5), and combinations.

    Args:
        reference_code: Document identifier (e.g., 'SE/RA/730128/730128.006').
        pages: Page specification (e.g., '1-3,5,7-9' or 'all').
        highlight_term: Optional term to highlight in the returned text.
        max_pages: Maximum number of pages to retrieve.
        research_context: User's research goal (recorded as span attribute for telemetry).

    Returns:
        BrowseResult containing page contexts, document metadata,
        and persistent identifiers. Returns empty contexts if document
        not found or no valid pages.
    """
    with _tracer.start_as_current_span(
        "BrowseOperations.browse_document",
        attributes={
            "browse.reference_code": reference_code,
            "browse.pages_requested": pages,
            **({"browse.research_context": research_context} if research_context else {}),
            **({"mcp.session.id": session_id} if session_id else {}),
        },
    ) as span:
        try:
            # Fetch OAI-PMH metadata once and derive manifest ID from it
            oai_metadata = await self.oai_client.get_metadata(reference_code)
            manifest_id = self.oai_client.manifest_id_from_metadata(oai_metadata)

            if not manifest_id:
                # No manifest = non-digitised material
                # Return metadata but no page contexts
                span.set_attribute("browse.pages_returned", 0)
                _browse_counter.add(1, {"browse.status": "success"})
                _pages_histogram.record(0)
                return BrowseResult(
                    contexts=[],
                    reference_code=reference_code,
                    pages_requested=pages,
                    oai_metadata=oai_metadata,
                )

            page_contexts = await self._fetch_page_contexts(manifest_id, pages, max_pages, reference_code, highlight_term)

            # Count empty pages (blank but digitised)
            empty_count = sum(1 for ctx in page_contexts if not ctx.full_text)
            if empty_count:
                _empty_pages_counter.add(empty_count)

            span.set_attribute("browse.pages_returned", len(page_contexts))
            _browse_counter.add(1, {"browse.status": "success"})
            _pages_histogram.record(len(page_contexts))
            return BrowseResult(
                contexts=page_contexts,
                reference_code=reference_code,
                pages_requested=pages,
                manifest_id=manifest_id,
                oai_metadata=oai_metadata,
            )
        except Exception as e:
            span.set_status(StatusCode.ERROR, str(e))
            span.record_exception(e)
            _browse_counter.add(1, {"browse.status": "error"})
            raise

async def fetch_content(self, alto_url: str, timeout: int = 10) -> TextLayer | None:
    """
    Fetch and parse an ALTO XML file into a structured TextLayer.

    This method performs the complete workflow: fetches the XML document, parses it,
    and returns a TextLayer with line-level data (polygons, confidence, ids),
    handling multiple ALTO namespace versions automatically.

    Args:
        alto_url: Direct URL to the ALTO XML document.
        timeout: Request timeout in seconds (default: 10).

    Returns:
        TextLayer with line-level data and full_text,
        TextLayer with empty full_text if ALTO exists but has no text (blank page),
        or None if fetching/parsing fails (404, network error, etc.).

    Example:
        >>> layer = await client.fetch_content("https://sok.riksarkivet.se/dokument/alto/SE_RA_123.xml")
        >>> layer.full_text
        'Anno 1676 den 15 Januarii förekom för Rätten...'
    """
    with _tracer.start_as_current_span("ALTOClient.fetch_content", attributes={"alto.url": alto_url}) as span:
        headers = {"Accept": "application/xml, text/xml, */*"}
        raw = await self.http_client.get_content(alto_url, timeout=timeout, headers=headers)
        if not raw:
            span.set_attribute("alto.result", "not_found")
            _fetch_counter.add(1, {"alto.result": "not_found"})
            return None

        xml_content = raw.decode("utf-8") if isinstance(raw, bytes) else raw

        try:
            text_layer = detect_and_parse(xml_content)
        except Exception as e:
            logger.warning("Failed to parse ALTO XML from %s: %s", alto_url, e)
            span.set_status(StatusCode.ERROR, f"XML parse error: {e}")
            span.record_exception(e)
            span.set_attribute("alto.result", "parse_error")
            _fetch_counter.add(1, {"alto.result": "parse_error"})
            return None

        result_type = "success" if text_layer.full_text else "empty"
        span.set_attribute("alto.result", result_type)
        span.set_attribute("alto.text_length", len(text_layer.full_text))
        _fetch_counter.add(1, {"alto.result": result_type})
        return text_layer

async def get_collection(self, pid: str, timeout: int = 30) -> IIIFCollection | None:
    """Get IIIF collection with typed model.

    Args:
        pid: Persistent identifier for the collection.
        timeout: Request timeout in seconds.

    Returns:
        Parsed collection with manifests, or None on fetch failure.
    """
    with _tracer.start_as_current_span("IIIFClient.get_collection", attributes={"iiif.pid": pid}) as span:
        url = f"{COLLECTION_API_BASE_URL}/{pid}"
        data = await self._fetch_json(url, timeout)
        if not data:
            span.set_attribute("iiif.result", "not_found")
            return None

        manifests = self._parse_manifests(data.get("items", []))
        span.set_attribute("iiif.manifests_found", len(manifests))

        return IIIFCollection(
            id=data.get("id", pid),
            label=self._extract_iiif_label(data.get("label")),
            manifests=manifests,
        )

async def extract_manifest_id(self, identifier: str) -> str | None:
    """Extract PID from a record for IIIF access."""
    with _tracer.start_as_current_span("OAIPMHClient.extract_manifest_id", attributes={"oai.identifier": identifier}) as span:
        try:
            metadata = await self.get_metadata(identifier)
            return self.manifest_id_from_metadata(metadata)
        except Exception as e:
            logger.warning("Failed to extract manifest ID for %s: %s", identifier, e)
            span.set_status(StatusCode.ERROR, str(e))
            span.record_exception(e)
            return None

async def get_metadata(self, identifier: str) -> OAIPMHMetadata | None:
    """Get record metadata as typed OAIPMHMetadata model.

    Fetches the OAI-PMH GetRecord response for the given identifier and
    parses the EAD metadata into a structured model.

    Args:
        identifier: Record identifier (e.g., "SE/RA/310187/1").

    Returns:
        Parsed metadata, or None on fetch/parse failure.
    """
    with _tracer.start_as_current_span("OAIPMHClient.get_metadata", attributes={"oai.identifier": identifier}) as span:
        try:
            params: dict[str, str | int] = {"verb": "GetRecord", "identifier": identifier, "metadataPrefix": "oai_ape_ead"}
            xml_root = await self._make_request(params)
            record = self._extract_record(xml_root)

            header_id, datestamp = self._parse_header(record)
            metadata = self._parse_ead_metadata(record, header_id or identifier, datestamp)

            _fetch_counter.add(1, {"oai_pmh.result": "success"})
            return metadata
        except Exception as e:
            logger.warning("Failed to get OAI-PMH metadata for %s: %s", identifier, e)
            span.set_status(StatusCode.ERROR, str(e))
            span.record_exception(e)
            _fetch_counter.add(1, {"oai_pmh.result": "error"})
            return None

def manifest_id_from_metadata(self, metadata: OAIPMHMetadata | None) -> str | None:
    """Extract manifest ID from already-fetched metadata (no HTTP call)."""
    if metadata and metadata.nad_link:
        return self._extract_manifest_id_from_nad_link(metadata.nad_link)
    return None