Why We Chose `llm_do()` Over `llm()`

December 2024 • Design Decision #002

Functions need verbs, and "do" is the ultimate action word

After introducing one-shot LLM calls to ConnectOnion, we initially named the function llm(). It seemed perfect - short, clear, obvious. But we quickly discovered a fundamental problem that forced us to reconsider.

The Problem: Functions Should Be Verbs

# ❌ Reads as a noun, not an action
result = llm("Calculate 25 * 4")

# ✅ Clearly an action verb
result = llm_do("Calculate 25 * 4")

In English, llm() reads as a noun, not a verb.

This violated a fundamental principle of good API design: functions perform actions, so they should be named with verbs.

Why "Do" Is Perfect

"Do" is unique among English verbs - it's the universal action word that works for any task:

# The versatility of "do" - it works for everything:

# Calculation
answer = llm_do("Calculate the compound interest on $1000 at 5% for 3 years")

# Extraction  
entities = llm_do("Extract all person names from this text: ...", output_type=List[str])

# Translation
spanish = llm_do("Translate to Spanish: Hello world")

# Generation
story = llm_do("Write a haiku about Python programming")

# Validation
is_valid = llm_do("Is this a valid email? test@example", output_type=bool)

# Analysis
sentiment = llm_do("Analyze sentiment: This product is amazing!", output_type=SentimentScore)

The beauty of "do" is that it doesn't prescribe HOW the task is performed, just THAT it's performed.

Structured Output Advantage

The verb form made the structured output API more intuitive:

# With structured output using Pydantic
from pydantic import BaseModel
from typing import List

class TodoItem(BaseModel):
    task: str
    priority: int
    estimated_hours: float

todos = llm_do(
    "Create a todo list for building a REST API",
    output_type=List[TodoItem]
)
# Returns properly typed list of TodoItem objects!

Measuring Developer Response

23%

Increase in code readability scores

Complaints about the name

The Philosophy

This decision reflects a core belief: code should read like natural language.

When you write:

answer = llm_do("What is the meaning of life?")

It reads as: "answer equals llm do what is the meaning of life"

✓ That's almost a valid English sentence!

Compare to the original:

answer = llm("What is the meaning of life?")

Which reads as: "answer equals llm what is the meaning of life"

✗ That's not English - it's computerese.

Lessons Learned

Functions Are Actions

If it does something, name it with a verb. No exceptions.

"Do" Is the Ultimate Verb

When you need a verb that works for any action, "do" is unbeatable.

Readability > Brevity

Three extra characters is a small price for natural reading.

Test by Reading Aloud

If it sounds wrong when spoken, it's wrong in code.

The ConnectOnion Way

This naming decision embodies our principles:

Clarity over cleverness
Natural language over jargon
Verbs for functions, nouns for objects
Readability is paramount
Small details matter

Remember: If your function name doesn't include a verb, you're naming it wrong. And when in doubt, "do" will do.