ai_explainer: The AI Rosetta Stone: Inside Chroma's Curriculum for the API Engineer

How a vector database company built a side-by-side translation guide to expose the stateless, messy reality of working with OpenAI, Anthropic, and Google.

7 min read • View on GitHub • More from chroma-core

A close-up of three different mechanical keys being filed down to fit into the exact same brass master cylinder lock, representing the convergence of AI APIs. — Despite superficial syntax differences, major AI providers are converging on identical messaging paradigms.

Key Takeaways

The concept of an AI chat session is a user interface illusion masking completely stateless, amnesiac backend functions.
Industry leaders are converging on a standard messages array format, but subtle syntax friction remains across providers.
Raw AI output requires aggressive regex sanitization before it can safely reach production application layers.

The Illusion of Chat

The dominant narrative around artificial intelligence focuses on emergent reasoning and massive parameter counts. The reality for frontend and backend developers is far more mundane. Under the hood, large language models are completely amnesiac functions. The concept of a continuous conversation is a user interface illusion.

Manual state management inflates API payloads rapidly over the course of a single conversation.

A Curriculum for the API Engineer

To bridge this gap, the team behind the vector database Chroma built ai_explainer. Rather than an abstract framework, it serves as a side-by-side comparative curriculum implemented in Jupyter notebooks. It forces traditional software engineers to confront the specific paradigms of stateless APIs directly.

Our goal with AI Explainer is to bridge the gap between black-box models and human understanding, empowering developers to build safer and more reliable AI systems.

Jeff Huber, Co-founder, Chroma · Introducing AI Explainer

The Great Message Convergence

The repository maps identical tasks across OpenAI, Anthropic, and Google Gemini. This exposes a clear industry trend. Providers are abandoning custom completion strings in favor of a standardized array of message objects. However, the exact syntax for passing system instructions remains a frustrating hurdle.

Provider	System Prompt Syntax
OpenAI	{"role": "system", "content": "..."}
Anthropic	system="..." (top-level parameter)
Google Gemini	GenerativeModel(..., system_instruction="...")

The Janitorial Reality of AI

Extraction tasks in the repository reveal the unglamorous side of AI engineering. Models frequently hallucinate formatting or inject conversational filler. Consequently, the most critical tool in the AI developer's kit is standard string manipulation.

A heavy industrial printing press spitting out a sheet of paper, while a robotic arm uses a push-broom to sweep scattered metal shavings off the page. — Unpredictable generative outputs require rigorous post-processing before reaching the application layer.

import re

# Standard sanitization found across the repo
clean_output = re.sub(r'\s+', ' ', raw_llm_response).strip()

Why a Database Company Teaches State

It might seem unusual for an infrastructure company to publish a basic API curriculum. The motive is deeply strategic. Chroma sells vector databases, which provide persistent memory for AI applications. By teaching developers that models are inherently amnesiac, they highlight the exact pain point their core product solves.