Skip to content

Index

groundlens.providers

LLM provider wrappers with built-in groundlens scoring.

Each provider wraps a third-party LLM SDK and automatically evaluates every response for hallucination risk using SGI (when context is provided) or DGI (context-free).

Classes

BaseLLMProvider

Bases: Protocol

Protocol defining the interface all groundlens providers implement.

Providers wrap third-party LLM SDKs and automatically attach a GroundlensScore to every response, enabling inline hallucination detection without changing application code.

Example

def use_provider(provider: BaseLLMProvider) -> None: ... resp = provider.complete("Summarize this.", context="Source text.") ... if resp.groundlens_score and resp.groundlens_score.flagged: ... print("Review recommended!")

Functions
complete(prompt: str, context: str | None = None) -> LLMResponse

Generate a completion for the given prompt.

Parameters:

Name Type Description Default
prompt str

The user prompt or instruction.

 required
context str | None

Optional source document for grounded evaluation. When provided, SGI scoring is used; otherwise DGI.

 None

Returns:

Type Description
LLMResponse

LLMResponse with generated text and groundlens score.
Source code in src/groundlens/providers/_base.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def complete(
    self,
    prompt: str,
    context: str | None = None,
) -> LLMResponse:
    """Generate a completion for the given prompt.

    Args:
        prompt: The user prompt or instruction.
        context: Optional source document for grounded evaluation.
            When provided, SGI scoring is used; otherwise DGI.

    Returns:
        LLMResponse with generated text and groundlens score.
    """
    ...
chat(messages: list[dict[str, str]], context: str | None = None) -> LLMResponse

Generate a chat completion from a message history.

Parameters:

Name Type Description Default
messages list[dict[str, str]]

List of message dicts with role and content keys.

 required
context str | None

Optional source document for grounded evaluation. When provided, SGI scoring is used; otherwise DGI.

 None

Returns:

Type Description
LLMResponse

LLMResponse with generated text and groundlens score.
Source code in src/groundlens/providers/_base.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
def chat(
    self,
    messages: list[dict[str, str]],
    context: str | None = None,
) -> LLMResponse:
    """Generate a chat completion from a message history.

    Args:
        messages: List of message dicts with ``role`` and ``content`` keys.
        context: Optional source document for grounded evaluation.
            When provided, SGI scoring is used; otherwise DGI.

    Returns:
        LLMResponse with generated text and groundlens score.
    """
    ...

LLMResponse(text: str, model: str, usage: dict[str, Any] = dict(), groundlens_score: GroundlensScore | None = None) dataclass

Unified response container for all LLM provider calls.

Attributes:

Name Type Description
text str

The generated text content from the LLM.
model str

The model identifier used for generation.
usage dict[str, Any]

Provider-specific usage metadata (tokens, cost, etc.).
groundlens_score GroundlensScore | None

Optional groundlens evaluation result attached after hallucination scoring.
Example

resp = LLMResponse(text="Hello!", model="gpt-4o", usage={}) resp.groundlens_score is None True