adapter.py

"""A tiny self-contained pipeline used by the docs, the examples, and the test suite."""

CORPUS: dict[str, str] = {
    "doc-001": "The X100 laptop ships with a 24 month warranty starting on the purchase date.",
    "doc-002": "Support tickets receive a first reply within one business day.",
    "doc-003": "The X100 battery lasts up to 12 hours of continuous video playback.",
    "doc-004": "Returns are accepted within 30 days when the device is undamaged.",
    "doc-005": "Firmware updates are released quarterly and install automatically.",
}


def _tokens(text: str) -> set[str]:
    cleaned = "".join(c.lower() if c.isalnum() else " " for c in text)
    return {token for token in cleaned.split() if len(token) > 2}


class MinimalAdapter:
    name = "minimal-python"
    supports_retrieval = True
    supports_answer = True

    def retrieve(self, question: str, k: int) -> list[dict[str, object]]:
        query = _tokens(question)
        ranked = sorted(
            CORPUS.items(),
            key=lambda item: len(query & _tokens(item[1])),
            reverse=True,
        )
        return [
            {"id": doc_id, "text": text, "score": float(len(query & _tokens(text)))}
            for doc_id, text in ranked[:k]
        ]

    def answer(self, question: str) -> dict[str, object]:
        chunks = self.retrieve(question, 3)
        top = chunks[0]
        return {
            "answer_text": str(top["text"]),
            "citations": [{"chunk_id": str(top["id"])}],
            "retrieved_chunks": chunks,
        }


def build() -> MinimalAdapter:
    return MinimalAdapter()