inspect-ai 0.3.103__py3-none-any.whl → 0.3.105__py3-none-any.whl

inspect_ai/model/_providers/_anthropic_citations.py

@@ -0,0 +1,158 @@
+from anthropic.types import (
+    CitationCharLocation,
+    CitationCharLocationParam,
+    CitationContentBlockLocation,
+    CitationContentBlockLocationParam,
+    CitationPageLocation,
+    CitationPageLocationParam,
+    CitationsWebSearchResultLocation,
+    CitationWebSearchResultLocationParam,
+    TextCitation,
+    TextCitationParam,
+)
+
+from inspect_ai._util.citation import (
+    Citation,
+    DocumentCitation,
+    DocumentRange,
+    UrlCitation,
+)
+
+
+def to_inspect_citation(input: TextCitation) -> Citation:
+    match input:
+        case CitationsWebSearchResultLocation(
+            cited_text=cited_text,
+            title=title,
+            url=url,
+            encrypted_index=encrypted_index,
+        ):
+            # Sanitize a citation to work around https://github.com/anthropics/anthropic-sdk-python/issues/965.
+            return UrlCitation(
+                cited_text=cited_text,
+                title=title
+                if title is None or len(title) <= 255
+                else title[:254] + "…",
+                url=url,
+                internal={"encrypted_index": encrypted_index},
+            )
+
+        case CitationCharLocation(
+            cited_text=cited_text,
+            document_index=document_index,
+            document_title=title,
+            end_char_index=end_char_index,
+            start_char_index=start_char_index,
+        ):
+            return DocumentCitation(
+                cited_text=cited_text,
+                title=title,
+                range=DocumentRange(
+                    type="char", start_index=start_char_index, end_index=end_char_index
+                ),
+                internal={"document_index": document_index},
+            )
+
+        case CitationContentBlockLocation(
+            cited_text=cited_text,
+            document_index=document_index,
+            document_title=title,
+            end_block_index=end_block_index,
+            start_block_index=start_block_index,
+        ):
+            return DocumentCitation(
+                cited_text=cited_text,
+                title=title,
+                range=DocumentRange(
+                    type="block",
+                    start_index=start_block_index,
+                    end_index=end_block_index,
+                ),
+                internal={"document_index": document_index},
+            )
+
+        case CitationPageLocation(
+            cited_text=cited_text,
+            document_index=document_index,
+            document_title=title,
+            end_page_number=end_page_number,
+            start_page_number=start_page_number,
+        ):
+            return DocumentCitation(
+                cited_text=cited_text,
+                title=title,
+                range=DocumentRange(
+                    type="page",
+                    start_index=start_page_number - 1,
+                    end_index=end_page_number - 1,
+                ),
+                internal={"document_index": document_index},
+            )
+
+    assert False, f"Unexpected citation type: {input.type}"
+
+
+def to_anthropic_citation(input: Citation) -> TextCitationParam:
+    cited_text = input.cited_text
+    assert isinstance(cited_text, str), (
+        "anthropic citations must have a string cited_text"
+    )
+
+    match input:
+        case UrlCitation(title=title, url=url, internal=internal):
+            assert internal, "UrlCitation must have internal field"
+            encrypted_index = internal.get("encrypted_index", None)
+            assert isinstance(encrypted_index, str), (
+                "URL citations require encrypted_index in internal field"
+            )
+
+            return CitationWebSearchResultLocationParam(
+                type="web_search_result_location",
+                cited_text=cited_text,
+                title=title,
+                url=url,
+                encrypted_index=encrypted_index,
+            )
+
+        case DocumentCitation(title=title, range=range, internal=internal):
+            assert internal, "DocumentCharCitation must have internal field"
+            document_index = internal.get("document_index", None)
+            assert isinstance(document_index, int), (
+                "DocumentCharCitation require encrypted_index in internal field"
+            )
+            assert range, "DocumentCitation must have a range"
+
+            start_index = range.start_index
+            end_index = range.end_index
+
+            match range.type:
+                case "char":
+                    return CitationCharLocationParam(
+                        type="char_location",
+                        cited_text=cited_text,
+                        document_title=title,
+                        document_index=document_index,
+                        start_char_index=start_index,
+                        end_char_index=end_index,
+                    )
+                case "block":
+                    return CitationContentBlockLocationParam(
+                        type="content_block_location",
+                        cited_text=cited_text,
+                        document_title=title,
+                        document_index=document_index,
+                        start_block_index=start_index,
+                        end_block_index=end_index,
+                    )
+                case "page":
+                    return CitationPageLocationParam(
+                        type="page_location",
+                        cited_text=cited_text,
+                        document_title=title,
+                        document_index=document_index,
+                        start_page_number=start_index + 1,
+                        end_page_number=end_index + 1,
+                    )
+
+    # If we can't handle this citation type, raise an error
+    raise ValueError(f"Unsupported citation type: {input.type}")

inspect_ai/model/_providers/_google_citations.py

@@ -0,0 +1,100 @@
+from typing import Sequence
+
+from google.genai.types import (
+    Candidate,
+    GroundingChunk,
+    GroundingSupport,
+    Segment,
+)
+
+from inspect_ai._util.citation import Citation, UrlCitation
+
+
+def get_candidate_citations(candidate: Candidate) -> list[Citation]:
+    """Extract citations from Google AI candidate grounding metadata.
+
+    Understanding Google API Grounding Citations: `GroundingChunk`'s, `GroundingSupport`, and `Segment`'s
+
+    1. Grounding Chunks (`GroundingChunk`)
+       What they are: The raw source material that the AI retrieved to support its response.
+       Structure:
+         - Web (`GroundingChunkWeb`): Content from web searches
+           - domain: The website domain
+           - title: Page title
+           - uri: Web page URL
+       Think of chunks as: The library books or web pages that contain the information.
+
+    2. Segments (`Segment`)
+       What they are: Specific portions of the AI's generated response text.
+       Structure:
+         - start_index & end_index: Byte positions in the response text
+         - text: The actual text from the response that this segment represents
+       Think of segments as: Specific sentences or paragraphs in the AI's response that need citations.
+
+    3. Grounding Support (`GroundingSupport`)
+       What they are: The bridge that connects segments of the AI's response to the chunks that support them.
+       Structure:
+         - grounding_chunk_indices: Array of integers pointing to specific chunks (e.g., [1,3,4] means chunks 1, 3, and 4 support this claim)
+         - segment: Which part of the response this support applies to
+       Think of support as: The footnotes that say "this claim in my response is backed up by these specific sources."
+
+    Args:
+        candidate: The Google AI candidate response containing grounding metadata
+
+    Returns:
+        A list of `Citation` objects linking response segments to their web sources.
+        Currently only handles `GroundingChunkWeb` sources.
+    """
+    return (
+        []
+        if (
+            not candidate.content
+            or not candidate.content.parts
+            or not (metadata := candidate.grounding_metadata)
+            or not (chunks := metadata.grounding_chunks)
+            or not (supports := metadata.grounding_supports)
+        )
+        else [
+            citation
+            for support in supports
+            for citation in _citations_from_support(support, chunks)
+        ]
+    )
+
+
+def _create_citation_from_chunk_and_segment(
+    chunk: GroundingChunk, segment: Segment
+) -> UrlCitation | None:
+    """Create a citation from a chunk and segment, returning None if chunk is not web-based."""
+    return (
+        UrlCitation(
+            url=chunk.web.uri,
+            title=chunk.web.title,
+            cited_text=(
+                (segment.start_index or 0, segment.end_index)
+                if segment.end_index is not None
+                else None
+            ),
+        )
+        if (chunk.web and chunk.web.uri)
+        else None
+    )
+
+
+def _citations_from_support(
+    support: GroundingSupport, chunks: Sequence[GroundingChunk]
+) -> list[Citation]:
+    return (
+        []
+        if support.segment is None or support.grounding_chunk_indices is None
+        else [
+            citation
+            for chunk_index in support.grounding_chunk_indices
+            if chunk_index < len(chunks)
+            if (
+                citation := _create_citation_from_chunk_and_segment(
+                    chunks[chunk_index], support.segment
+                )
+            )
+        ]
+    )