Documentation
¶
Overview ¶
Package find is kb's retrieval judge (spec §10): code proposes candidates (frontmatter facet filters, BM25, concept expansion, optional vectors), the decision model judges whether each candidate answers the question, and code ranks the survivors and names the reason every other candidate was dropped. Facets reports the corpus atlas counts without any model call.
Index ¶
- Constants
- Variables
- func KindMatches(questionKind, genre string) bool
- func Rank(items []Judged, questionKind string, keep, window float64, limit int) ([]Hit, []Drop)
- func Score(pAnswers, specificity float64, kindMatch bool, depth float64) float64
- type Count
- type Drop
- type FacetReport
- type Hit
- type Judged
- type Query
- type Result
- type Vectors
Constants ¶
const ( // FacetNone buckets documents without a value for the facet. FacetNone = "(none)" // TopConcepts is the number of concepts listed by Facets. TopConcepts = 20 )
Facet bucket names.
const ( // BankID is the question bank asked by find. BankID = "find" // LexicalTopK is the number of BM25 candidates. LexicalTopK = 60 // VectorTopK is the number of optional vector candidates. VectorTopK = 30 // ConceptSeeds is how many top BM25 hits contribute their `concepts`. ConceptSeeds = 10 // BatchSize is the number of candidates judged per request. BatchSize = 20 // HeadChars bounds each candidate's head in the state. HeadChars = 400 // DefaultLimit is the default number of results. DefaultLimit = 10 )
Retrieval limits (spec §10).
const ( ReasonLowProbability = "low-probability" ReasonBelowWindow = "below-window" ReasonLimit = "limit" ReasonFilteredFacet = "filtered-facet" ReasonQuarantined = "quarantined" )
Drop reasons (spec §10 step 3). Undecided answers are reported as "undecided:<reason>".
const ( KindDefinition = "definition" KindHowTo = "how_to" KindComparison = "comparison" KindEvidence = "evidence_or_data" KindOpinion = "opinion" KindOther = "other" )
Question kinds of the find bank's question_kind choice.
Variables ¶
var KindGenres = map[string][]string{ KindDefinition: {"reference_docs", "article_or_essay"}, KindHowTo: {"tutorial_or_guide"}, KindComparison: {"article_or_essay", "paper"}, KindEvidence: {"paper", "dataset_or_benchmark"}, KindOpinion: {"opinion_or_discussion"}, }
KindGenres maps a question kind to the document genres that match it (kind_match = 1 in the rank formula). `other` matches nothing.
definition reference_docs, article_or_essay how_to tutorial_or_guide comparison article_or_essay, paper evidence_or_data paper, dataset_or_benchmark opinion opinion_or_discussion
Functions ¶
func KindMatches ¶
KindMatches reports whether a document genre matches a question kind (see KindGenres).
Types ¶
type Drop ¶
type Drop struct {
Path string `json:"path"`
Title string `json:"title"`
Reason string `json:"reason"`
PAnswers *float64 `json:"p_answers,omitempty"`
Rank *float64 `json:"rank,omitempty"`
}
Drop is one candidate that was not returned, with its named reason.
func Candidates ¶
Candidates proposes the documents to judge, by code only: facet filters first, then BM25 (title, aliases, summary, questions, entities, head) top 60, the articles named in `concepts` of the top 10 BM25 hits, and optional vector hits. Quarantined (`triage: quarantined`) and facet-filtered documents never consume a candidate slot; those that ranked among the BM25 hits are returned as drops with their reason.
type FacetReport ¶
type FacetReport struct {
Documents int `json:"documents"`
Sources int `json:"sources"`
Articles int `json:"articles"`
Quarantined int `json:"quarantined"`
Genre []Count `json:"genre"`
Relevance []Count `json:"relevance"`
// Depth buckets the 0–3 depth expectation by its integer part.
Depth []Count `json:"depth"`
Concepts []Count `json:"concepts"`
}
FacetReport is the corpus atlas of a topic (spec §8): document counts per facet value, computed from frontmatter only (no model call).
func Facets ¶
func Facets(docs []*corpus.Document) FacetReport
Facets counts genre, relevance, depth (buckets 0–3) and the top concepts over docs. Quarantined documents (`triage: quarantined`) are counted in Quarantined only.
type Hit ¶
type Hit struct {
Path string `json:"path"`
Title string `json:"title"`
Rank float64 `json:"rank"`
PAnswers float64 `json:"p_answers"`
Specificity float64 `json:"specificity"`
Kind string `json:"kind,omitempty"`
Concepts []string `json:"concepts,omitempty"`
Depth *float64 `json:"depth,omitempty"`
}
Hit is one kept document.
type Judged ¶
type Judged struct {
Doc *corpus.Document
// PAnswers is P(yes) of answers_{id}; valid when Decided.
PAnswers float64
// Specificity is the expected level (0–3) of specificity_{id}; 0 when
// undecided.
Specificity float64
Decided bool
// Reason is "undecided:<reason>" when not Decided.
Reason string
}
Judged is a candidate with its answers.
type Query ¶
type Query struct {
Text string
Limit int
// Facet filters, applied to frontmatter before any model call.
Kind string
Concept string
Relevance string
MinDepth float64
Explain bool
// Vectors is the optional vector candidate source (nil = off).
Vectors Vectors `json:"-"`
}
Query is one find request.
type Result ¶
type Result struct {
Question string `json:"question"`
QuestionKind string `json:"question_kind,omitempty"`
Candidates int `json:"candidates"`
Hits []Hit `json:"results"`
// Dropped lists every candidate not returned (filled only with Explain).
Dropped []Drop `json:"dropped,omitempty"`
// Decided counts judged candidates whose answers_{id} was decided.
Decided int `json:"decided"`
// Undecided lists, sorted, the judged candidates whose answers_{id} was
// undecided (timeout, budget, invalid receipt): never a "no".
Undecided []string `json:"undecided"`
}
Result is the answer to one query.
Source Files