config: expose public pipeline_signature() helper

[henryle97]

Context

Consumers that implement content-hash-based dedup (e.g. "same bytes + same pipeline → same doc, skip re-ingest") need a stable signature of the pipeline configuration to use as a cache key alongside the content hash.

llm-agent reconstructs this manually from RagSettings (parser, chunker, embedding, enrichment, etc.) — see app/core/rag/config.py::pipeline_signature and docs/rag/architecture.md §11 ("Content-hash idempotency" pattern). Whenever xrag adds a new pipeline knob (e.g. a new parser option), every consumer's signature drifts silently and dedup either over-collides or under-collides.

This is a contract that belongs in the library, not in each consumer.

Why this matters for production

• Dedup correctness depends on the signature reflecting every knob that affects chunk content. Drift = wrong-doc-returned bugs that are very hard to detect.
• Multiple consumers (current and future) recomputing the same logic = N copies that fall out of sync.
• Tests for dedup behaviour belong with the producer of the signature.

Proposed shape

A pure helper:

from xrag import compute_pipeline_signature

sig = compute_pipeline_signature(
    parser=\"unstructured:fast\",
    chunker=\"section_table\",
    embedding=\"openai:text-embedding-3-small\",
    enrichment=(\"auto_keywords\", \"auto_questions\"),
    # ... whatever knobs affect chunk content
)
# sig: str — stable hex digest, opaque to caller

Or, taking a constructed client / settings object:

sig = client.pipeline_signature()        # if it makes sense to live on Xrag
sig = compute_pipeline_signature(settings)  # standalone fn

Either works; standalone fn is more testable.

Stable means: same inputs → same output, across versions, until an input would actually change chunk bytes. New knobs that affect chunk content MUST be added to the signature input set in the same release that adds them.

Acceptance

• Public compute_pipeline_signature(...) exported from xrag.__init__.
• Documented set of knobs that participate in the signature.
• Versioning policy: signature format is stable across patch + minor releases; major bump allowed to reset.
• Unit test: knob change → signature change; same knobs → same signature.
• Migration note: consumers can replace their hand-rolled signature with this helper in a single line.

[henryle97]

Accepted, small standalone PR. Even with one consumer today, this is a future-correctness landmine: every consumer that re-derives the signature locally will silently drift the moment xrag adds a new pipeline knob, and the resulting dedup bugs ("same bytes return different doc") are very hard to detect.

Implementation note: the function itself is ~20 lines. The hard part is the governance commitment buried in the body —

"New knobs that affect chunk content MUST be added to the signature input set in the same release that adds them."

That should land as a CONTRIBUTING.md / CLAUDE.md rule in the same PR, not just a docstring. Otherwise the contract decays.

Will pair this with a unit test asserting (a) same inputs → same digest, (b) any covered-knob change → digest change, (c) uncovered metadata changes do not change the digest. Versioning policy: stable across patch + minor; major bump may reset.