Skip to content

ask()

ask 

ask(question: str, docs: str | Path | Sequence[str | Path], *, preset: str = 'hybrid_balanced', output_html: str | Path | None = None, output_html_title: str | None = None, **preset_kwargs: Any) -> 'Answer'

Single-shot ingest + query + answer.

Parameters

question: Natural-language query. docs: Path or list of paths to document files (PDFs, etc.). preset: Named preset from :mod:verifiable_rag.presets. Default "hybrid_balanced" — Cohere retrieval + Dual NLI + constrained Haiku generator. See verifiable_rag.presets for alternatives. output_html: Optional path. If given, the audit-trail HTML report is written to that path alongside returning the Answer. output_html_title: Optional title for the HTML report. Default "verifiable-rag report". **preset_kwargs: Extra kwargs forwarded to the preset factory (e.g. generator_model, index_dir).

Returns

Answer The pipeline's full Answer — text via answer.text, audit trail via answer.verification_results / answer.retrieved_chunks, HTML report via answer.to_html().

Examples

Simplest::

import verifiable_rag
answer = verifiable_rag.ask("What did the authors find?", docs="paper.pdf")
print(answer.text)

With an HTML audit report::

verifiable_rag.ask(
    "What did the authors find?",
    docs="paper.pdf",
    output_html="report.html",
)

Switching presets::

answer = verifiable_rag.ask(
    "What did the authors find?",
    docs=["a.pdf", "b.pdf"],
    preset="hybrid_strict",
)
Source code in src/verifiable_rag/_ask.py 
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
def ask(
    question: str,
    docs: str | Path | Sequence[str | Path],
    *,
    preset: str = "hybrid_balanced",
    output_html: str | Path | None = None,
    output_html_title: str | None = None,
    **preset_kwargs: Any,
) -> "Answer":
    """Single-shot ingest + query + answer.

    Parameters
    ----------
    question:
        Natural-language query.
    docs:
        Path or list of paths to document files (PDFs, etc.).
    preset:
        Named preset from :mod:`verifiable_rag.presets`. Default
        ``"hybrid_balanced"`` — Cohere retrieval + Dual NLI + constrained
        Haiku generator. See ``verifiable_rag.presets`` for alternatives.
    output_html:
        Optional path. If given, the audit-trail HTML report is written
        to that path alongside returning the Answer.
    output_html_title:
        Optional title for the HTML report. Default ``"verifiable-rag report"``.
    **preset_kwargs:
        Extra kwargs forwarded to the preset factory (e.g.
        ``generator_model``, ``index_dir``).

    Returns
    -------
    Answer
        The pipeline's full Answer — text via ``answer.text``, audit
        trail via ``answer.verification_results`` /
        ``answer.retrieved_chunks``, HTML report via
        ``answer.to_html()``.

    Examples
    --------
    Simplest::

        import verifiable_rag
        answer = verifiable_rag.ask("What did the authors find?", docs="paper.pdf")
        print(answer.text)

    With an HTML audit report::

        verifiable_rag.ask(
            "What did the authors find?",
            docs="paper.pdf",
            output_html="report.html",
        )

    Switching presets::

        answer = verifiable_rag.ask(
            "What did the authors find?",
            docs=["a.pdf", "b.pdf"],
            preset="hybrid_strict",
        )
    """
    if preset not in _VALID_PRESETS:
        raise ValueError(
            f"Unknown preset {preset!r}; choose from {list(_VALID_PRESETS)}"
        )
    from verifiable_rag import presets

    preset_fn = getattr(presets, preset)
    pipeline = preset_fn(**preset_kwargs)

    doc_paths: list[Path] = (
        [Path(docs)]
        if isinstance(docs, (str, Path))
        else [Path(p) for p in docs]
    )
    for p in doc_paths:
        pipeline.ingest(p)

    answer = pipeline.ask(question)

    if output_html is not None:
        title = output_html_title or "verifiable-rag report"
        Path(output_html).write_text(answer.to_html(title=title))

    return answer