src.dackar.RCA.ner.hybrid_ner.llm_disambiguator
===============================================

.. py:module:: src.dackar.RCA.ner.hybrid_ner.llm_disambiguator


Classes
-------

.. autoapisummary::

   src.dackar.RCA.ner.hybrid_ner.llm_disambiguator.LLMConfig
   src.dackar.RCA.ner.hybrid_ner.llm_disambiguator.LLMDisambiguator


Module Contents
---------------

.. py:class:: LLMConfig

   .. py:attribute:: use_cli
      :type:  bool
      :value: False



   .. py:attribute:: cli_binary
      :type:  str
      :value: 'ollama'



   .. py:attribute:: http_url
      :type:  str
      :value: 'http://localhost:11434/v1/chat/completions'



   .. py:attribute:: model
      :type:  str
      :value: 'ollama/gpt-oss:20B'



   .. py:attribute:: timeout
      :type:  int
      :value: 10



   .. py:attribute:: temperature
      :type:  float
      :value: 0.0



   .. py:attribute:: max_tokens
      :type:  int
      :value: 64



   .. py:attribute:: stop_sequences
      :type:  Optional[List[str]]
      :value: None



   .. py:attribute:: min_confidence
      :type:  float
      :value: 0.15



   .. py:attribute:: cache_ttl_seconds
      :type:  int
      :value: 3600



   .. py:attribute:: dry_run
      :type:  bool
      :value: False



   .. py:attribute:: uncertain_score_floor
      :type:  float
      :value: 0.4



   .. py:attribute:: uncertain_score_ceiling
      :type:  float
      :value: 0.65



   .. py:attribute:: high_conf_bypass_score
      :type:  float
      :value: 0.85



.. py:class:: LLMDisambiguator(schema, config = LLMConfig())

   .. py:attribute:: schema


   .. py:attribute:: config


   .. py:attribute:: _cache
      :type:  Dict[str, Dict[str, Any]]


   .. py:attribute:: llm_ok
      :value: True



   .. py:method:: should_call(c)

      Decide whether to invoke the LLM for this candidate span.

      Decision logic (in priority order):
      1. High-confidence gazetteer hit exists → bypass LLM entirely (trust deterministic match).
      2. No proposed labels at all → ask LLM (span has no evidence).
      3. All hypotheses lack a known schema group → ask LLM (labels are unrecognised).
      4. Multiple competing schema groups → ask LLM (genuine ambiguity).
      5. Best score in the uncertain confidence band → ask LLM (embed result is marginal).
      6. Best score below the floor → do NOT ask LLM (span is too weak; LLM would speculate).
      7. Best score above the ceiling → do NOT ask LLM (embed is confident enough).



   .. py:method:: _build_prompt(doc_text, c, candidate_labels)


   .. py:method:: _label_short(lbl)


   .. py:method:: _cache_key(c)


   .. py:method:: _extract_json_object(s)

      Some models occasionally wrap JSON with extra text.
      Try to recover the first {...} object.



   .. py:method:: disambiguate(doc_text, candidates)


   .. py:method:: _call_llm_for_candidate(doc_text, c)


   .. py:method:: _parse_llm_response(resp, c)


   .. py:method:: health_check()