bible-lookup-helper

name

bible-lookup-helper

description

Bible reference lookups, full-text/topic/Strong's/Q&A search, and AI semantic search in Raamattu Nyt. Use for fetching verses by reference (Joh 3:16), building/modifying the SearchPage (7 tabs: jakeet/aiheet/Strong's/kysymykset/videot/muut/comparison), calling search RPCs (search_text, search_topics_with_aliases, search_verses_by_strongs, get_approved_ai_summary), classifying queries (verse vs topic vs Strong's vs free-text), anchor questions/AI summaries/topic synonyms, validating OSIS references, and choosing the right lookup pattern.

Bible Lookup Helper

Covers two related but distinct workflows:

• Lookup — fetch a specific verse / chapter / range when the reference is already known
• Search — surface results across verses, topics, Strong's, questions, and AI summaries when the user types a free-form query

When in doubt which one applies: a known reference (Joh 3:16) → lookup; a free-form query (rakkaus, armo ja totuus) → search. The search path itself classifies the query and picks the right backend.

Context Files (Read First)

For schema and API details, read from Docs/context/:

• Docs/context/db-schema-short.md - Bible schema tables
• Docs/context/supabase-map.md - RPC functions list

Learnings

Before debugging search RPC performance or behavior, skim references/learnings.md (terminology conventions + pointers to cross-cutting DB-perf entries in .claude/LEARNINGS.md).

Detailed Search Reference

For the full search architecture — 7 tabs, per-modality RPCs, query classification, AI-summary caching/feedback, anchor questions, recent additions — read references/search-system.md.

Read it when the task touches:

• The SearchPage UI or any *SearchSection.tsx component
• A search RPC that's not in the basic lookup list below
• AI semantic search, summary caching, or thumbs-up/down feedback
• Topic aliases / synonyms / translation
• Anchor questions or similar-questions sections
• Query classification logic (classifyQuery, isReference, intent routing)

Capabilities

• Generate correct RPC function calls for Bible lookups
• Validate OSIS reference formats
• Suggest optimal lookup patterns (verse vs chapter vs range vs search)
• Provide book name aliases and normalization
• Convert between different reference formats
• Route free-form queries to the right search RPC (verses / topics / Strong's / Q&A / AI)
• Reason about the AI-semantic-search flow end-to-end: cache key (normalizeQueryKey), ai_summary_feedback table, ai-semantic vs ai-search feature_key, quality circuit-breaker (thumbs_down ratio), and the verse-text rendering chain (AISemanticResults → fetchVerseTexts → mapFinnishToOsis → get_verses_by_ref)

When to delegate to other skills

This skill owns the SEARCH side of AI semantic search (cache, routing, rendering, feature_key selection at the call site). For deeper AI configuration, hand off to ai-prompt-manager:

Question / task	Skill
"Why is the AI summary card blank for <book> <ch>:<v>?"	This skill (verseTextService mapping)
"Cache miss when I expected a hit for <query>"	This skill (normalizeQueryKey, prefixed-key rule)
"Add a new AI feature key for X"	ai-prompt-manager (registration SQL pattern)
"Change which model runs ai_semantic_search"	ai-prompt-manager (ai_feature_bindings)
"Getting feature_locked / operation_not_found / 429"	ai-prompt-manager (quota + plan_feature_access)
"Edit the prompt template that generates summaries"	ai-prompt-manager (ai_prompt_versions)
"Build a new AI UI panel"	ai-prompt-manager (AIProcessingPanel/AIProgressBar/AIErrorBanner)

Usage Examples

Example 1: Generate RPC call for single verse

User: "How do I fetch John 3:16 in Finnish?" Assistant:

const { data } = await supabase.rpc('get_verse_by_ref', {
  p_ref_book: 'John',
  p_chapter: 3,
  p_verse: 16,
  p_version_code: 'finstlk201',
  p_language_code: 'fi'
});

Example 2: Generate RPC call for chapter

User: "Get all verses from Genesis chapter 1" Assistant:

const { data: verses } = await supabase.rpc('get_chapter_by_ref', {
  p_ref_book: 'Genesis',
  p_chapter: 1,
  p_version_code: 'finstlk201',
  p_language_code: 'fi'
});

Example 3: Validate reference format

User: "Is '1. Joh.4:8' a valid reference?" Assistant: Yes, this is valid. It follows the Finnish format for numbered books:

• Book: 1. Johannes (1 John)
• Chapter: 4
• Verse: 8

Alternative valid formats:

• 1 Joh.4:8 (without period after number)
• 1.Joh.4:8 (no space)
• 1 John 4:8 (English)

Example 4: Convert reference formats

User: "Convert 'Joh.3:16' to OSIS format" Assistant: OSIS format: John.3.16

Finnish formats accepted:

• Joh.3:16 (with colon)
• Joh.3.16 (with period)
• Johannes 3:16 (full name)

Available RPC Functions

Single Verse

get_verse_by_ref(p_ref_book, p_chapter, p_verse, p_version_code, p_language_code)
→ {osis, text_content, verse_id}

Full Chapter

get_chapter_by_ref(p_ref_book, p_chapter, p_version_code, p_language_code)
→ [{book_code, book_name, chapter_number, verse_number, osis, text_content, verse_id, version_code}]

Verse Range

get_verses_by_ref(p_ref_book, p_chapter, p_verses[], p_version_code, p_language_code)
→ Same as chapter but filtered

Verse Study (with Strong's)

get_verse_study_data(p_version_code, p_book_name, p_chapter, p_verse)
→ Full study data including KJV Strong's tags

Text Search

search_text(p_query, p_version_code, p_limit)
search_text_extended(p_query, p_version_code, p_limit)
→ [{book_name, chapter_number, verse_number, osis, text_content, verse_id}]

Supported Bible Versions

Code	Name	Language
finstlk201	Pyhä Raamattu (STLK 2017) - DEFAULT	Finnish
finpr_finn	Pyhä Raamattu (1933/1938)	Finnish
KJV	King James Version with Strong's	English

Book Name Aliases

The system recognizes multiple formats:

• Finnish: Joh, Johannes, Johanneksen evankeliumi
• English: John, Jn, Gospel of John
• Numbered books: 1. Joh, 1 Joh, 1Joh, 1 John
• Moses books: 1. Moos, 1 Moos, Gen, Genesis

Best Practices

1. Always use RPC functions - Never query tables directly
2. Default version - Use finstlk201 for Finnish content
3. Cache results - Use React Query to cache lookups
4. Preload - Load next chapter for better UX
5. Error handling - Check for empty results
6. OSIS format - Use for cross-version references

Performance Tips

• Single verse: ~20ms
• Full chapter: ~50ms
• Text search: ~100ms
• Use indexed fields for best performance
• Limit search results with p_limit parameter

Reference Format Patterns

Valid Formats

• Book.Chapter:Verse - e.g., Joh.3:16
• Book.Chapter.Verse - e.g., Joh.3.16
• Book Chapter:Verse - e.g., John 3:16
• Number. Book.Chapter:Verse - e.g., 1. Joh.4:8

Range Formats

• Book.Chapter:Verse-Verse - e.g., Joh.3:16-17
• Book.Chapter:Verse-Chapter:Verse - e.g., Joh.3:16-4:2

Related Documentation

• See Docs/03-API.md for complete API reference