The one-sentence API design test

A newspaper with six writers#

Think of a newspaper that hires six good freelance writers. Each files a strong piece. Put the six pieces on one page, though, and they spell the same word three ways, use two date formats, and call the same politician by different titles. None of the writers is wrong; the paper never gave them its style guide.

An API is a page every user reads. The framework’s existing code is its house style, whether or not anyone wrote it down, and every proposal is a freelancer’s piece. The critic’s job is the editor’s: check each piece against the style guide, and where there isn’t one, write it.

The one-sentence test#

Take every public name a new user has to learn. Write one sentence that explains each. Then imagine saying it to a colleague: if they’d naturally ask a follow-up question, the concept fails.

Some of the names in the six proposals, with the sentence each one got:

The follow-up is the question your users will otherwise answer for themselves, by guessing, and not all of them will guess the same way.

One name, three meanings#

AgentSession is the one I’d remember, because each proposal’s use of it made sense on that proposal’s own terms. In the snippets below, ep is the app’s endpoint, its connection to the people on the other end of the call: audio arrives on ep.audio_in and leaves on ep.audio_out, and >> chains steps into the pipeline. One proposal put AgentSession in the pipeline like a step:

python↩ WrapCopy

1
agent = AgentSession(model=..., tools=[...])
2
pipeline = Pipeline(...)
3
ep.audio_in >> agent >> ep.audio_out
4
Session(pipeline).run()

Another kept it inside a new app base class, where it runs the conversation from outside the pipeline:

python↩ WrapCopy

1
class OutboundAgent(VoiceAgent):
2
    ...
3

4
    def on_call_started(self, endpoint):
5
        self.agent_session.say("Hi! ...")

And its name suggests a third thing: a kind of Session. Asking for one sentence forces you to pick. The critic picked “step”. If it sits in the >> chain, it is one, so name it like one: RealtimeModel, “a single step that handles the whole voice conversation”, which passes.

python↩ WrapCopy

1
ep.audio_in >> RealtimeModel(model=..., tools=[...]) >> ep.audio_out

When a name fails, work down this chart and stop at the first yes:

Splitting a name, or picking one meaning

The bottom two boxes of the chart look alike and aren’t. A name that needs two sentences within one design is doing two jobs, and should be split into two names, one sentence each. A name that different designs use differently, like AgentSession, has one job per design, so splitting doesn’t help: pick one meaning, and a name to match.

Where the sentences come from: the house style#

A sentence is only “one sentence” relative to what the reader already knows, and for an existing API that’s the rules its current code follows. Writing them down makes that explicit. The critic read the framework’s existing example apps and listed what they had in common. Most have the same shape. Here’s the core of one, an app that mixes the audio of everyone in a call:

1
import os
2

3
pipeline = Pipeline("multiparty")
4
ep = Endpoint.webrtc(signaling_url=os.environ["SIGNALING_URL"])
5
ep.audio_in >> OpusDecoder() >> AudioMixer() >> OpusEncoder() >> ep.audio_out
6
Session(pipeline, ...).run()

Read it top to bottom: name a pipeline, open an endpoint with its address from the environment, chain three steps between the audio coming in and going out (decode the compressed audio, mix it, compress it again), and run it. And the rules it follows, the house style:

• An app starts with Session(...).run(), or, for an app written as a class, by subclassing the framework’s one app class and calling run().
• Steps are connected with >> and created inside the chain, not assigned to a variable first.
• Steps are named for what they do, with no suffix (AudioMixer, not AudioMixerNode).
• The simple case has no lifecycle callbacks, methods the framework calls at moments like “the call started”.
• Configuration comes from the environment, or from the app’s manifest, its settings file.
• Imports come from a few known modules.
• The simple case doesn’t need async.

None of these rules is right in general; plenty of good frameworks are async from the first line. They fit this framework because its users already know them. A proposal that breaks one asks users to learn a second way to do something they can already do.

The VoiceAgent snippet above breaks at least two of them: a second app class, and a lifecycle callback (on_call_started) just to say hello. The critic’s rewrite moved the greeting into the language-model step’s configuration instead, LLM(greeting="Hi! ..."). The same rules settle the first two rows of the opening figure. Two names for one job fail the test together, because the follow-up is “what’s the difference?”, and the naming rule says which way to go: the Node versions lose their suffix, and each job keeps one short name, STT and LLM in the rewrite.

Make the rules countable#

Rules still invite a debate about whether something “feels consistent”, so the critic turned them into checks, the newspaper’s style checker:

The targets came from the framework’s own small examples, so treat them as starting points for yours. Anyone reading a proposal can check it against them.

The scaling proposal, checked#

To run many sessions at once, one per phone call, the worker proposal turned the app into an async function that a Worker starts once for each session. This is the shape, from the reconstruction in the demo folder:

python↩ WrapCopy

1
async def entrypoint(ctx: JobContext):
2
    call = ctx.metadata
3
    pipeline = ctx.pipeline
4
    ...  # the endpoint and the steps, configured from call
5
    ctx.add_shutdown_callback(lambda: print(f"Call {call['call_id']} ended"))
6
    await ctx.session.run_until_complete()
7

8

9
if __name__ == "__main__":
10
    worker = Worker(
11
        WorkerOptions(
12
            entrypoint_fnc=entrypoint,
13
            max_concurrent=5,
14
            name="voice-agent",
15
        )
16
    )
17
    worker.run()

entrypoint is the app now, and it gets everything about its session from ctx. Worker(WorkerOptions(...)) starts it once per session, up to five at a time. Against the checks, it fails three of the six just to scale:

Check	The worker proposal
New names	3: Worker, WorkerOptions, JobContext
async	async def entrypoint, and an await
Configuration	a config object, WorkerOptions

(Its shutdown callback is registered, not a method the user overrides, so it passes the lifecycle check as written. And lines don’t separate the two designs: the reconstruction is 34 lines, and the critic’s own app, rewrites/voice_agent.py, is 31, both over the target of 15 for this fuller app.)

The critic’s alternative left the app file as it was:

python↩ WrapCopy

1
pipeline = Pipeline("voice-agent")
2
...  # the steps, with per-call details read from os.environ
3
Session(pipeline).run()

and put the concurrency in the manifest:

toml↩ WrapCopy

1
...
2
[app.worker]
3
max_concurrent = 5

There’s still a worker in the critic’s sketch; the difference is who runs it. Deployment tooling reads the manifest, wraps the same app file in the worker, and passes each session’s details in, so the app author never imports Worker or JobContext. That tooling is part of the design, not something that exists yet. And if the details arrive as environment variables, each session needs its own process, because a process has one set of environment variables, which not every workload can afford. Either way, the app code doesn’t change, only the two lines of manifest above.

Where the borrowed names came from#

The worker proposal took Worker, WorkerOptions(entrypoint_fnc=...) and JobContext from LiveKit Agents, LiveKit’s open-source agent framework and one of the projects I’d pointed the agents at. All three appear in its 1.0 releases, as does AgentSession, which three of the other proposals used. (LiveKit has since replaced Worker with AgentServer.) The proposal chose Worker because it “aligns with industry terminology from LiveKit, Celery, Temporal”. They’re good names in LiveKit, whose programming model is built around them. Next to Pipeline, >> and Session, they became a second programming model.

That’s the six freelancers again: each wrote in the style of the papers it had read before. I’d watch for this in any agent-written proposal. Each agent fits its design to the prior art it has read, and none of them checks the others, so give them your rules before the prior art.

Try it on your API#

1. List every public name a new user has to learn, and write one sentence for each. Mark the ones that invite a question. On an existing API, you can start here.
2. Write down the house style. Take two or three apps or examples you already have, and list the rules they share. Before you invite proposals, from people or agents, hand these over.
3. Turn the rules into checks someone can count, taking the targets from your smallest real app.

And lint or run the sample code, which none of these checks replaces. One proposal defined its tools as plain functions and still reached for self:

1
@tool
2
async def end_call() -> str:
3
    """End the current call."""
4
    await self.session.hangup()
5
    return "Call ended"

Python doesn’t run a function’s body until the tool actually runs, so a module like this loads without complaint and fails with a NameError the first time the model calls the tool. pyflakes, a linter, flags it without running anything:

proposals/voice_agent.py:3:1: 'mf_all.Session' imported but unused
proposals/voice_agent.py:3:1: 'mf_all.AgentSession' imported but unused
proposals/voice_agent.py:12:11: undefined name 'self'
proposals/voice_agent.py:19:11: undefined name 'self'

The last two lines are the bug, once in each of the proposal’s two tools; the first two are unused imports. Running the samples wasn’t an option anyway: every one shown here imported from mf_all, a package the agents made up, so only reading or linting could catch it.

The demo#

The one-sentence-api/ folder has generic reconstructions of the voice-agent and worker proposals, the critic’s rewrites, and mf, a tiny stand-in framework that prints the pipeline and fakes one model turn, so the rewrite runs. It isn’t a media stack.

cd mainlog-code/one-sentence-api
python3 -m venv .venv && .venv/bin/pip install pyflakes==3.4.0
.venv/bin/python -m pyflakes proposals/voice_agent.py     # the undefined self, without running anything
.venv/bin/python -c "import sys, asyncio; sys.path.insert(0, 'proposals'); import tool_as_proposed; asyncio.run(tool_as_proposed.transfer_call('+15550100'))"
SIP_TRUNK=my-trunk CALLEE=+15551234567 PYTHONPATH=. .venv/bin/python rewrites/voice_agent.py
.venv/bin/python count_lines.py proposals/worker.py rewrites/voice_agent.py

The second command imports the proposal’s tool happily, then fails with NameError: name 'self' is not defined when it’s called. The third runs the critic’s rewrite against the stand-in:

[session] graph: sip.audio_in >> VAD >> STT >> LLM >> TTS >> sip.audio_out
[agent] says: Hi! This is a reminder about your appointment tomorrow.
[endpoint] transferring call to +15550100
[agent] tool result: Transferred to +15550100

The six proposals were sensible designs for their own corners of the framework. They clashed because I hadn’t given the agents a written definition of what fits, so each one brought its own from the prior art it had read. Write the house style down first, and the one-sentence test has something to measure against.