SDK Reference

​

Twenty essential SDK methods

​

Bonus methods

​

OpenRouter models

​

Battle-tested prompt patterns

​

1. Intent router (JSON classification)

Classify this user input. Return ONLY valid JSON, nothing else.
{"intent": "weather|timer|music|chat", "confidence": 0.0-1.0}
User: {user_input}

​

2. Persona system prompt (voice character)

You are Marcus, a brutally honest venture capitalist. You speak in short,
punchy sentences. 2-4 sentences max. No markdown, no lists. This is spoken
aloud, not a blog post. Never say "as a VC" or "in my experience".

​

3. Audio analysis — Pass 1 (general)

You are an expert audio analyst. Listen carefully to this recording and
provide a detailed analysis. Describe: what type of sound, environment,
acoustic characteristics (rhythm, pitch, texture, layers), and anything
unusual. Do NOT address the user. Write as pure third-person analysis.

​

4. Audio analysis — Pass 2 (specific with context)

Here is a general analysis already completed:
{general_analysis}

Now answer this specific question about the audio: "{user_question}"
Be precise. Use timestamps and specific details where possible.

​

5. Conversational response (with history)

You are [persona] in conversation about [topic].
--- ANALYSIS ---
{analysis}
--- CONVERSATION ---
{chat_history}

The user just said: "{user_input}"
Respond in 1-3 sentences, spoken aloud. Don't repeat yourself.

​

6. LLM-driven time parser (alarm pattern)

You are an alarm time parser. Current: {now_iso}, Timezone: {tz_name}
If day/date missing, respond: QUESTION:at what day?
If time missing, respond: QUESTION:at what time?
When complete, return ONLY valid JSON:
{"target_iso": "...", "human_time": "...", "timezone": "..."}

​

7. Grocery list extractor

Extract a grocery list from this transcript. Organize by section
(produce, dairy, meat, pantry). Deduplicate and clean up.

Transcript: {transcript}
Grocery List:

​

8. Restart vs continue intent detection

A user is in a conversation about a sound they played. Determine if
they want to listen to a NEW sound (restart) or are asking about the
current sound (continue).

User said: "{user_input}"
Return ONLY valid JSON: {"intent": "restart or continue", "confidence": 0.0}

​

9. Contextual voice assistant

You are a concise voice assistant for [domain] management.
USER: {name} | LOCATION: {city} | TIME: {current_time}

Rules: Keep responses to 2-4 sentences max. Be conversational.
Never say "as an AI" or "I don't have feelings".

​

10. Farewell / exit summary

The conversation is ending. Here's the full history:
{history}

Give a 1-2 sentence parting thought. If the idea improved during the
conversation, acknowledge it. If not, give one last honest nudge.

​

Architecture patterns

​

Ability categories

​

File structure

​

main.py vs background.py

​

Core patterns

​

The loop template (multi-turn conversation)

while True:
    user_input = await self.capability_worker.user_response()
    if any(word in user_input.lower() for word in EXIT_WORDS):
        break
    response = self.capability_worker.text_to_text_response(user_input)
    await self.capability_worker.speak(response)

self.capability_worker.resume_normal_flow()

​

The two-pass analysis pattern

• Pass 1: fire-and-forget via session_tasks.create(asyncio.to_thread(run_general))
• Talk to user while Pass 1 runs (hides 10–15s of latency)
• Pass 2: inject Pass 1 results as context, answer the specific question
• Each follow-up turn fires a background re-analysis, enriching future turns

​

The rolling window pattern (ambient audio)

• 10-second window, 3-second refresh cadence
• API call fires as background task, poll loop never waits
• Responses arrive asynchronously and log themselves

​

The coordination pattern (main.py + background.py)

• main.py: parse user input, write to JSON file, resume_normal_flow()
• background.py: poll file every 15–30 seconds, check conditions, act
• Use delete + write for JSON files — append corrupts JSON
• Call send_interrupt_signal() before speaking from a daemon

​

The pending state pattern (multi-step collection)

self.pending_create = {"waiting_for": "title"}
# Next turn: user gives title → update to {"title": "X", "waiting_for": "time"}
# Next turn: user gives time → all info collected, execute action

​

Sandbox rules

• Never write register_capability() by hand — always use the platform tag
• No import os, no import json at the top level outside the register block
• No raw open() — use play_from_audio_file() for audio, the file storage API for data
• No signal module — even in docstrings or comments, the scanner catches it
• Always call resume_normal_flow() on every exit path in main.py
• Use session_tasks.sleep() and session_tasks.create() — not raw asyncio
• Wrap all blocking HTTP calls in asyncio.to_thread()
• No print() — use editor_logging_handler
• Blocked imports: redis, connection_manager, user_config, exec(), eval(), pickle

​

Voice UX best practices

• Keep speak() to 1–2 sentences. This is voice, not text
• Fill the silence: say “One sec” before any API call over 1 second
• Read your speak() strings out loud before shipping
• Handle messy voice input: use the LLM to extract clean data from noisy transcription
• Offer exit at every loop iteration: check for “done”, “stop”, “quit”, etc.
• Use run_confirmation_loop() before destructive actions (send, delete, cancel)
• Idle detection: 1 empty response = keep going, 2 in a row = offer to leave
• Namespace your filenames: smarthub_prefs.json not data.json
• JSON persistence: always delete + write (append corrupts JSON)
• API calls: always set timeout=10, wrap in try/except, speak errors to user