Designing the System for and Around AI

I set three rules everything else in the toolkit had to follow:

• Just-in-time — introduce AI help when it's needed, not all at once.
• Personalized — use onboarding, learned preferences, and context to tailor what surfaces.
• Fluid, not siloed — a contextual insight can open into a conversation, and a conversation can kick off agentic work.

Goal: give every downstream decision — what pattern to use, when to speak up, how much to explain — a shared filter to run through.

I mapped the real system architecture behind the AI experience:

• Client's GraphQL mutation → AppSync → async Lambda pipeline → a pydantic-ai agent calling tools (OpenSearch, food-queries, menu lookups) → results written to DynamoDB while the client polls.
• Async by necessity — AppSync enforces a 30-second timeout, but our workflows average 22 seconds and can take up to 5 minutes.
• Benchmarked real performance — 22.4s average response time; 90–216 seconds at p90–p99.
• Flagged scalability concerns, like sequential tool calls that needed optimizing.

Goal: give engineering and design a shared, accurate picture of what's actually happening under the hood, not just the polished UI on top.

I defined a personality spec so the AI's voice would be consistent everywhere it shows up.

• Six traits — reliable, direct, proactive, honest, respectful, practical.
• Framed for the team as “the best employee our clients have ever had” — no fluff, no unfounded claims.
• Respectful means the AI informs and recommends rather than dictates, since the user brings context and judgment the AI doesn't have.
• Practical means it's built for commercial kitchens, where data always has gaps and conditions change fast.

Goal: make sure every AI surface — regardless of which engineer or designer built it — sounds like the same person.

I mapped a decision tree for choosing the right AI interaction pattern — not just defaulting to chat.

• Contextual / embedded — anticipates what a user needs based on where they are; auto-populates, or reveals with a single tap.
• Conversational — reserved for when confidence is low or intent varies too widely to guess.
• Three questions decide it: is this relevant right now, is it valuable enough to just show automatically, and if not, does it belong in a conversation the user starts themselves.

Goal: stop every new AI feature from defaulting to a chat window, and instead match the interaction model to how confident we actually are and how urgent the insight is.

I defined the rules for when the AI should step back rather than push forward.

• Step back when: the task is outside its capability, the user is frustrated, the decision is high-stakes, or it's failed the same request repeatedly.
• Escalation signals: sentiment detection, repeated regeneration or negative feedback, an explicit ask from the user.
• Hard boundaries: defined capability limits, policy-based refusals, data it won't touch.
• Refusals explain why, without over-explaining.

Goal: make sure confidence never outruns judgment, and that people always know where the AI's authority actually ends.

I co-own this section — how we test whether the AI is actually working, not just whether it ships.

• Building a structured eval suite on our existing Logfire tracing, using pydantic-evals.
• Output consistency — run identical inputs twice, diff the results to catch non-determinism.
• Tool call accuracy — does the model call the right tool with the right parameters.
• Data interpretation accuracy — catches things like bad unit conversions or filtering logic.
• LLM-as-judge — rates open-ended chat responses against a rubric tied to the personality spec.

Sequenced cheapest to most expensive — deterministic checks first, LLM-as-judge last, since it's the most subjective and effort-intensive.

Goal: catch regressions before a client does, and give every new workflow a baseline before it ships.