Agent

Il dominio agent (src/ragspine/agent/) è l'orchestratore di RAGSpine. La docstring del suo modulo riassume il flusso di cui è responsabile:

意图解析 → 澄清网关 → 安全门 → 三路分流 → tool-use 循环 → 合成回答

(parsing dell'intento → gateway di chiarimento → gate di sicurezza → instradamento a tre percorsi → ciclo tool-use → risposta sintetizzata)

Ha esattamente un unico punto di ingresso pubblico — answer_question — ed è dove risiede la protezione di prevenzione delle risposte inventate. Vedi Prevenzione delle risposte inventate per il concetto e Doppio canale per il modello di instradamento.

Struttura

intent — parsing a quattro slot

intent.py analizza una domanda grezza in una dataclass ParsedIntent dietro il Protocol IntentParser. Il RuleIntentParser predefinito non usa alcun LLM, è guidato dalla configurazione e delega alla funzione a livello di modulo parse_intent(question, reference_date=None).

ParsedIntent trasporta anche route, raw_question, gli slot multivalore metrics / entities / periods (per i compositi elencati esplicitamente) e external_entity. Costanti di instradamento: ROUTE_STRUCTURED = "structured", ROUTE_NARRATIVE = "narrative", ROUTE_COMPOSITE = "composite". Una metrica riconosciuta più un indizio narrativo instrada verso composite; un indizio numerico instrada verso structured; altrimenti narrative.

intent — il gateway di chiarimento

clarify_scope(intent, reference_date=None) -> ClarificationResult viene eseguito prima di qualsiasi canale. Le sue quattro modalità:

L'asimmetria è deliberata: una metrica mancante chiede prima (con narrowing_options = le metriche supportate), mentre un'entità o un periodo mancante viene risposto con assunzioni esplicitate — usando come predefinito l'entità principale (profile.home_entity_code) e l'ultimo anno fiscale completo (("FY", str(ref.year - 1))), esponendo entrambi in un assumption_note, e offrendo un restringimento con un solo clic. Il rifiuto per fuori ambito viene verificato per primo, prima del ritorno anticipato narrativo e del controllo della metrica, chiamando il gate di sicurezza su intent.raw_question — che deliberatamente non si fida di intent.external_entity.

Campi di ClarificationResult: mode, assumed_slots, assumption_note, narrowing_options, question.

security_gate — deterministico, mai sostituibile

security_gate.py ospita SecurityGate(external_entities, home_company_name). È deterministico, non chiama alcun LLM e non incorpora alcuna azienda hardcoded — l'elenco dei concorrenti e il nome dell'entità principale provengono dal DomainProfile.

• detect(text) -> SecurityScreen — rilevamento degli alias esterni/dei concorrenti con corrispondenza più lunga. Effettua la corrispondenza su una vista privata degli spazi bianchi (così "竞 安" non può eluderla) e maschera una corrispondenza con spazi di uguale lunghezza in modo che non rimanga alcuna sottostringa esposta (gestendo la collisione documentata di 中国 → ACME_CN).
• screen(*, raw_question, metric) -> SecurityVerdict — rideriva l'ambito solo dalla domanda grezza. In caso di corrispondenza con un concorrente restituisce SECURITY_REFUSE_OUT_OF_SCOPE (= "out_of_scope_entity", deliberatamente uguale a CLARIFY_OUT_OF_SCOPE_ENTITY) con un messaggio di rifiuto e un'opzione di restringimento "chiedi invece di home_company_name"; altrimenti SECURITY_ALLOW.

query_tools — lo stato triplo di query_metric

query_tools.py definisce l'unica primitiva del canale strutturato che produce fatti, lo strumento di function-calling query_metric. execute_query_metric(store, metric, entity, period, channel="TOTAL") normalizza ogni parametro attraverso il glossario, interroga lo store fact_metric e restituisce esattamente uno tra tre stati — mai una supposizione:

Gli schemi degli strumenti sono derivati dal profilo (build_query_metric_tool_anthropic / build_query_metric_tool_openai, più costanti precostruite), quindi gli esempi di entità provengono dal profilo attivo — mai da un'azienda hardcoded.

llm_provider — la giunzione sostituibile

A partire dalla 0.3.0, il Protocol LLMProvider è di proprietà del core condiviso di famiglia corespine e viene riesportato da ragspine.agent.llm_provider. Parla il formato chat-completions di OpenAI — un unico metodo chat:

from corespine import ChatCompletion  # re-exported via ragspine.agent.llm_provider


class LLMProvider(Protocol):
    def chat(
        self,
        messages: list[dict[str, Any]],
        *,
        tools: list[dict[str, Any]] | None = None,
    ) -> ChatCompletion: ...

messages è la cronologia in formato OpenAI (ciascuno {"role", "content", ...}); il prompt di sistema è semplicemente la prima voce {"role": "system", ...} anziché un argomento separato. Un ChatCompletion trasporta choices: tuple[Choice, ...] (ogni Choice incapsula un ResponseMessage con content e opzionalmente tool_calls), oltre a usage, model e id — la busta chat-completions standard, tutte dataclass frozen da corespine.

DEFAULT_ANTHROPIC_MODEL = "claude-opus-4-8". Non c'è ancora alcun OpenAIProvider di chat incluso — solo una giunzione documentata (lo schema degli strumenti OpenAI è già precostruito in query_tools.py, e l'extra [llm] include openai per il backend degli embedding). ProviderError (una sottoclasse di corespine.CorespineError) incapsula solo gli errori di rete/API/timeout — gli errori di programma si propagano.

agent — l'orchestratore e il ciclo tool-use

answer_question è l'unico ingresso pubblico:

def answer_question(
    question: str,
    store: FactStore,
    provider: LLMProvider,
    *,
    reference_date: date | None = None,
    narrative_retriever: NarrativeRetriever | None = None,
    intent_parser: IntentParser | None = None,
    decomposer: QueryDecomposer | None = None,
    history: Sequence[HistoryTurn] | None = None,
) -> AgentResult: ...

HistoryTurn è tuple[str, str]. La cronologia è solo contesto di generazione: viene inserita dopo il messaggio di sistema e prima della domanda corrente, ma non entra mai nel parsing deterministico dell'intento, nella verifica di sicurezza, nella query di recupero, né nell'elenco delle evidenze/fonti. Solo assistant viene trattato come ruolo assistant; i ruoli sconosciuti vengono normalizzati a user. Di conseguenza, il testo della conversazione precedente non può autorizzare una query su un concorrente né diventare una citazione. Vedi ADR 0017.

Il suo flusso: assegna un id di richiesta → costruisce un contesto di trace rispettoso della privacy → analizza l'intento (predefinito RuleIntentParser) → clarify_scope. Poi effettua ritorni anticipati in ordine rigoroso:

Il ciclo degli strumenti (_run_tool_loop) è limitato a MAX_TOOL_ITERATIONS = 5: chiama provider.chat(messages, tools=tools), esegue le eventuali chiamate allo strumento query_metric, reimmette i risultati come messaggio user e si ferma quando il modello non restituisce alcuna chiamata a strumenti. In caso di ProviderError degrada a un testo fisso e privo di numeri anziché inventare.

answer_question restituisce un AgentResult:

La protezione di prevenzione delle risposte inventate

La protezione "riscrivi in not-found indipendentemente dall'output del modello" risiede in _structured_answer. Partiziona i risultati degli strumenti per stato ed è deliberatamente per singolo percorso:

• Found → la risposta viene sintetizzata deterministicamente dal valore del fatto; la prosa del modello viene scartata (il test di regressione test_found_path_discards_fabricated_extra_number fissa questo comportamento).
• Nessun found, alcuni not_found → un rifiuto onesto ("查不到 … 不提供任何推测数字").
• Solo unrecognized_param → indica il parametro problematico.
• Zero risultati di strumenti (il modello ha risposto senza chiamare lo strumento) → il testo del modello viene restituito integralmente.

Il percorso multi-sotto-task (_multi_subtask_answer) non chiama mai l'LLM; il percorso narrativo (_run_narrative) si fida della prosa del modello ma aggiunge forzatamente qualsiasi documento sorgente citato che il modello ha omesso di nominare. Il flag di trace fabrication_guard_triggered è true quando esistono risultati di strumenti ma nessuno è found — cioè la protezione ha riscritto in un rifiuto.

Esempio

from ragspine.agent.agent import answer_question
from ragspine.agent.llm_provider import MockProvider
from ragspine.storage.fact_store import SqliteFactStore

store = SqliteFactStore("data/fact_metric.db"); store.init_schema()
result = answer_question("中国内地FY2024的REVENUE是多少", store, MockProvider())
print(result.answer)   # deterministic value, or an honest "not found"
print(result.sources)  # [{'doc': ..., 'locator': ...}]

Vedi anche