hyf

Context-aware query service for Radroots
git clone https://radroots.dev/git/hyf.git
Log | Files | Refs | README | LICENSE

explain_result.mojo (4236B)

      1 from std.collections import List
      2 
      3 from json import Value, loads
      4 
      5 from hyf_core.capabilities.query_analysis import (
      6     analyze_query_text,
      7     build_deterministic_meta,
      8     query_signal_tags,
      9     serialize_extracted_filters,
     10     string_array_value,
     11 )
     12 from hyf_core.capabilities.ranking_support import (
     13     ExplainResultRequest,
     14     evaluate_candidate,
     15     parse_explain_result_request,
     16 )
     17 from hyf_core.errors import (
     18     CapabilityResult,
     19     failed_capability,
     20     invalid_input_error,
     21     successful_capability,
     22 )
     23 from hyf_core.provenance import ProvenanceSourceRef
     24 from hyf_core.request_context import RequestContext
     25 
     26 
     27 def _join_reason_summary(reasons: List[String]) -> String:
     28     if len(reasons) == 0:
     29         return "no strong ranking signals were detected"
     30 
     31     if len(reasons) == 1:
     32         return String(reasons[0])
     33 
     34     var summary = String()
     35     for index in range(len(reasons)):
     36         if index > 0:
     37             if index == len(reasons) - 1:
     38                 summary += " and "
     39             else:
     40                 summary += ", "
     41         summary += String(reasons[index])
     42     return summary^
     43 
     44 
     45 def _build_output(
     46     result_id: String,
     47     score: Int,
     48     reasons: List[String],
     49     matched_terms: List[String],
     50     ranking_hints: List[String],
     51     extracted_filters: Value,
     52     delivery_alignment: String,
     53     distance_band: String,
     54     freshness_band: String,
     55     scope_match: Bool,
     56 ) raises -> Value:
     57     var output = loads("{}")
     58     output.set("result_id", Value(String(result_id)))
     59     output.set(
     60         "explanation_kind",
     61         Value("deterministic"),
     62     )
     63     output.set(
     64         "summary",
     65         Value(
     66             "Result "
     67             + result_id
     68             + " was ranked using deterministic heuristic signals: "
     69             + _join_reason_summary(reasons)
     70             + "."
     71         ),
     72     )
     73     output.set("score", Value(score))
     74     output.set("reasons", string_array_value(reasons))
     75     output.set("matched_terms", string_array_value(matched_terms))
     76     output.set("ranking_hints", string_array_value(ranking_hints))
     77     output.set("extracted_filters", extracted_filters)
     78 
     79     var assessment = loads("{}")
     80     assessment.set("delivery_alignment", Value(String(delivery_alignment)))
     81     assessment.set("distance_band", Value(String(distance_band)))
     82     assessment.set("freshness_band", Value(String(freshness_band)))
     83     assessment.set("scope_match", Value(scope_match))
     84     output.set("signal_assessment", assessment)
     85     return output^
     86 
     87 
     88 def execute_explain_result(
     89     input: Value, context: RequestContext
     90 ) raises -> CapabilityResult:
     91     try:
     92         var request: ExplainResultRequest = parse_explain_result_request(input)
     93         var analysis = analyze_query_text(request.query_text, context)
     94         var evaluation = evaluate_candidate(
     95             request.candidate, analysis, context
     96         )
     97 
     98         var signal_tags = query_signal_tags(analysis)
     99         for reason in evaluation.reasons:
    100             signal_tags.append("reason:" + String(reason))
    101 
    102         var source_refs = List[ProvenanceSourceRef]()
    103         source_refs.append(
    104             ProvenanceSourceRef(
    105                 source_kind="candidate",
    106                 source_ref="explain_result:candidate",
    107             )
    108         )
    109 
    110         return successful_capability(
    111             _build_output(
    112                 result_id=evaluation.candidate.id,
    113                 score=evaluation.score,
    114                 reasons=evaluation.reasons,
    115                 matched_terms=evaluation.matched_terms,
    116                 ranking_hints=analysis.ranking_hints,
    117                 extracted_filters=serialize_extracted_filters(
    118                     analysis.extracted_filters
    119                 ),
    120                 delivery_alignment=evaluation.delivery_alignment,
    121                 distance_band=evaluation.distance_band,
    122                 freshness_band=evaluation.freshness_band,
    123                 scope_match=evaluation.scope_match,
    124             ),
    125             meta=build_deterministic_meta(
    126                 context=context,
    127                 capability_name="explain_result",
    128                 signal_tags=signal_tags,
    129                 extra_source_refs=source_refs^,
    130             ),
    131         )
    132     except e:
    133         return failed_capability(invalid_input_error(String(e)))