Punti di estensione

La pluggabilità di RAGSpine non è un registro di plugin — è semplice tipizzazione strutturale. Ogni dipendenza esterna è un Protocol Python; il core dipende dall'astrazione, mai da un SDK di terze parti. Aggiungere un provider, un vector store, un reranker o un motore OCR richiede un solo nuovo file, e ogni SDK pesante viene importato in modo lazy, così il core si importa senza problemi e funziona completamente offline con il MockProvider deterministico.

Le interfacce

Interfacce attuali per recupero e flussi di lavoro

Chunker.chunk(text, meta, *, max_chars, overlap_chars) -> list[Chunk] è responsabile della strategia di chunking. make_chunker supporta le implementazioni deterministica predefinita, layout, parent-child, sentence-window, laws, QA, book e semantica, oltre al gruppo di entry point ragspine.chunkers. Le implementazioni devono preservare doc_id e source_locator; i dati di gerarchia/finestra sono additivi, non un sostituto della tracciabilità.

LibraryRouter seleziona uno o più ID RoutableLibrary. MultiIndexRetriever invoca in modo indipendente i NarrativeRetriever selezionati e ne fonde i risultati con RRF; in caso di errore del router si ricade su tutte le librerie. FilterExtractor può proporre predicati sui metadati, ma i filtri restano operazioni di restrizione validate.

TemplateMatcher riceve riferimenti di catalogo contenenti metadati di corrispondenza, non prompt dei flussi di lavoro né credenziali. I matcher integrati lessicale e ONNX restituiscono candidati classificati; la policy di scaffolding applica la soglia di punteggio/margine e valida il template selezionato. Un matcher personalizzato non acquisisce autorità di scrittura su file o di esecuzione.

LLMProvider

Di proprietà di corespine e riesportato da src/ragspine/agent/llm_provider.py — l'unico metodo pilotato dal ciclo di tool-use dell'agente. Parla il formato chat-completions di OpenAI (un solo metodo chat). AnthropicProvider importa in modo lazy l'SDK anthropic e mappa il formato sull'API Anthropic; MockProvider non richiede né chiave né rete.

EmbeddingBackend

src/ragspine/retrieval/lexical/retrieval.py — il punto di dependency injection per il canale vettoriale. Il valore predefinito è none (BM25 puro); iniettatelo per aggiungere un canale vettoriale.

ListwiseJudge

src/ragspine/retrieval/rerank/listwise_rerank.py — l'interfaccia opzionale del reranker listwise basato su LLM. L'implementazione reale è Claude (tramite build_listwise_prompt / parse_listwise_response); i test usano un fake deterministico. In sua assenza si ricade sull'ordine RRF.

OcrBackend

src/ragspine/extraction/extractors/pdf_scanned_extractor.py — l'interfaccia OCR/VLM per i PDF scansionati. Il backend reale (PaddleOCR) gira su Ubuntu + GPU; i test di logica usano un fake così il flusso render → map → threshold → review è completamente testabile su una macchina senza GPU.

NarrativeRetriever

src/ragspine/agent/agent.py — l'implementazione di recupero narrativo iniettata in answer_question. Duck-typed; se omessa, il percorso narrativo degrada in modo onesto.

TaskQueue

src/ragspine/service/tasks/task_queue.py — la coda di job asincrona. RQQueue (RQ + Redis) per la produzione, FakeQueue (sincrona inline) per i test. rq / redis vengono importati in modo lazy solo all'interno di RQQueue.

SourceConnector

src/ragspine/ingestion/source/connector.py — l'interfaccia delle sorgenti di knowledge base. Un connettore produce documenti grezzi da qualunque posto in cui risieda la vostra KB; il FilesystemConnector predefinito non richiede alcun extra, mentre i connettori HTTP / Notion importano in modo lazy httpx dietro l'extra [connectors].

Le implementazioni integrate si registrano per nome in una tabella a livello di modulo; i connettori di terze parti vengono scoperti tramite il gruppo di entry point ragspine.source_connectors (in caso di conflitto vincono i nomi integrati). Selezionatene uno con la factory make_source_connector(spec=None, **kwargs) o con la variabile d'ambiente RAGSPINE_SOURCE_CONNECTOR (none / None → None):

RelationExtractor

src/ragspine/graph/extractor.py — lo slot opzionale per le relazioni narrative consumato da build_relation_graph(..., relation_extractor=None). Con il None predefinito, il grafo di base è identico byte per byte (nessun arco aggiuntivo). Vedere ADR 0015.

Selezionate tramite make_relation_extractor(spec=None, *, provider=None, profile=None, **kwargs) o RAGSPINE_RELATION_EXTRACTOR (none → None; deterministic / rule / cooccurrence → il predefinito deterministico; llm / on → l'estrattore LLM, che degrada onestamente a None quando nessun provider è disponibile).

Implementare un Protocol e iniettarlo

Poiché le interfacce sono strutturali, implementate il metodo (o i metodi) e passate l'istanza — nessuna registrazione, nessuna classe base. Ecco un LLMProvider basato su OpenAI, fondato sulla vera firma di chat e sul formato ChatCompletion (le dataclass provengono da corespine e sono riesportate da ragspine.agent.llm_provider):

from typing import Any

from openai import OpenAI  # lazy: only your file imports the SDK
from corespine import ChatCompletion, Choice, ResponseMessage, Usage


class OpenAIProvider:
    """A custom LLMProvider — no subclassing, just the chat method."""

    def __init__(self, model: str = "gpt-4o") -> None:
        self._client = OpenAI()
        self._model = model

    def chat(
        self,
        messages: list[dict[str, Any]],
        *,
        tools: list[dict[str, Any]] | None = None,
    ) -> ChatCompletion:
        # The messages are already in the OpenAI chat-completions shape, so they pass
        # through; the SDK response is the same shape, so the mapping back is direct.
        resp = self._client.chat.completions.create(
            model=self._model,
            messages=messages,
            tools=tools or [],  # adapt / omit as needed
        )
        choice = resp.choices[0]
        message = ResponseMessage(role="assistant", content=choice.message.content)
        u = resp.usage
        usage = (
            Usage(
                prompt_tokens=u.prompt_tokens,
                completion_tokens=u.completion_tokens,
                total_tokens=u.total_tokens,
            )
            if u is not None
            else None
        )
        return ChatCompletion(
            choices=(Choice(index=0, message=message, finish_reason=choice.finish_reason or "stop"),),
            usage=usage,
            model=resp.model,
            id=resp.id,
        )

Iniettatelo esattamente dove andrebbe MockProvider:

from ragspine.agent.agent import answer_question
from ragspine.storage.fact_store import SqliteFactStore
from my_openai_provider import OpenAIProvider

store = SqliteFactStore("data/fact_metric.db")
store.init_schema()
result = answer_question("...", store, OpenAIProvider())