Design Decision: Choosing llm_do() as the Function Name

[wu-changxing]

Date: 2024-01-29 (Updated 2024-01-30) | Status: Decided → Revised

Summary

We chose llm_do() over the shorter llm() because functions need verbs to be immediately understandable. While llm() is shorter, it reads as a noun and confused users about what action it performs.

The Problem with llm()

Initial user feedback revealed:

• llm reads as a noun, not a verb
• Functions should be actions
• Users were confused about what llm() does at a glance

Why llm_do() Won

1. Has a clear verb: "do" is the most versatile action word
2. Works for all use cases:

   answer = llm_do("What's 2+2?")  # Do the calculation
   invoice = llm_do(text, output=Invoice)  # Do the extraction
   translation = llm_do("Hello", system_prompt="Translate")  # Do the translation

3. Immediately clear: Users understand it's performing an action
4. Still short: Only 6 characters (vs 3 for llm())

Options We Considered

• llm() - Too noun-like, unclear action ❌
• llm_oneshot() - Too verbose (11 chars), enterprise Java feel ❌
• llm_ask() - Only works for questions ❌
• llm_go() - Too vague ("go where?") ❌
• llm_gen() - Implies generation only, not extraction ❌
• llm_call() - Could confuse with function calls ❌
• ask() - Natural but too informal for all use cases ❌
• llm_do() - Clear, versatile, professional ✅

Testing Against Real Use Cases

# Data Extraction
invoice = llm_do(invoice_text, output=Invoice)  # ✅ "Do the extraction"

# Analysis
analysis = llm_do(text, output=FeedbackAnalysis)  # ✅ "Do the analysis"

# Translation
translation = llm_do("Hello", system_prompt="Translate")  # ✅ "Do the translation"

llm_do() reads naturally across ALL use cases.

Lessons Learned

1. Functions need verbs: Even if shorter, noun-based function names confuse users
2. Versatility matters: The verb must work for ALL use cases, not just some
3. User feedback is crucial: The confusion with llm() only became clear through usage
4. "Do" is the ultimate verb: It's the most versatile action word in English

---

Read the full decision: docs/design-decisions/002-choosing-llm-function-name.md