Doodle React Component
@smarter/doodle is the left panel of the web console’s sign-in pages: the logo, the
doodle of the day, and the project’s name and description. The doodle is a small, flat
illustration of a Smarter LLMClient’s chat window, with the plugin, guardrail, vectorstore and
secret that it uses, and its manifest. On days worth celebrating, the illustration is decorated
for the day: lanterns for the Lunar New Year, diyas for Diwali, a menorah for Hanukkah, gears for
Ada Lovelace Day, fireworks for Canada Day. On other days it is the plain scene.
The single-page console, @smarter/console, imports the component and shows it beside its
sign-in, sign-up and password reset forms. It passes the doodle api’s url, the plain scene’s url and
the platform’s branding from the console’s session, GET /api/web/session/, whose
signIn.doodle reports the enable_doodle switch. The panel’s styles are the package’s own,
in App.css. On a phone, the panel shows only the logo.
Visitors in different regions can see different doodles on the same day. The browser sends its
time zone, e.g. Asia/Kolkata, which gives the visitor’s local date, so a holiday starts at local
midnight, and, through the time zone database, the country and the region. No IP address is
looked up, and nothing about the visitor is stored. The regions are global, us, ca,
mx, latam, europe, africa, middle-east, south-asia, east-asia,
southeast-asia and oceania.
How it works
The Django app smarter.apps.doodle does the work, and the React app only shows the result.
The theme catalog. Each theme is a YAML file in
smarter/apps/doodle/data/themes/: what it celebrates, its caption and link, the regions that see it, its priority, its schedule, and an SVG of its props, the decorations that are drawn on the base scene. A schedule is a fixed date (Pi Day, March 14), the nth weekday of a month (Ada Lovelace Day, the second Tuesday of October), or a country’s holiday by name, which the holidays package dates, including the moving ones such as Diwali, Eid al-Fitr and Thanksgiving. The catalog’sREADME.mdexplains how to add a theme and draw its props.manage.py load_doodle_themes, whichinitialize_platformruns, loads the catalog and draws each theme’s artwork.The planner. A Celery Beat task,
plan_doodles, chooses the doodle of every region for the next seven days, so that a week of content is always ready, then asks the Smarter Doodle Editor about each new day (below). For each day and region, the due theme of the highest priority wins, and a region’s own theme wins over one of every region. When nothing is due, the plain default wins.manage.py plan_doodlesdoes the same by hand, and asks the editor too with--editor.The api.
GET /api/v1/doodles/today/?tz=<time zone>returns the doodle of the day as JSON, andGET /api/v1/doodles/artwork/<sha256>.svgits artwork. Both are public, because the page shows the doodle before anyone signs in. An artwork’s url is its content’s hash, so a browser caches it for a year. Both are internal to the sign-in page, and not part of the api contract.The app. The page shows the plain scene at once, from the static files, and the app replaces it with the doodle of the day when it arrives. It shows the artwork with
<img>, in which an SVG can run no scripts and load nothing, and the caption, e.g. Happy Diwali!, below it, linked to a page about the day. Without JavaScript, or if the api fails, the page keeps the plain scene.
A superuser can override a day’s doodle in the Django admin, under Doodles: choose another theme, and neither the planner nor the editor changes that day again. The list’s actions approve or reject doodles, and its Preview the week button shows every region’s doodle of every planned day as a grid, with its caption, whether a Smarter AI application chose or drew it, and why, and an Approve and a Reject button on each. A change shows within ten minutes, the time that a day’s doodle is cached.
The Smarter Doodle Editor and Artist
The doodle is itself a Smarter AI application. Two staff-only LLMClients of the Smarter account,
from the example manifests, choose and draw
it, and the platform’s own code prompts them in-process, as their owner, with
prompt_in_process(): through the same provider handler
as the chat api, without an api key or an http request, so their system prompts, guardrails,
budgets and chat history apply as they would to anyone’s prompt. An Orchestrator’s steps are
prompted the same way.
smarter_doodle_editor chooses each region’s doodle of each new day. The planner prompts it once a day, with JSON: for each region, the catalog themes that are due, and the region’s other holidays that day, from the
holidayspackage. It answers with JSON: for each region, a catalog theme, one of the holidays, or the plain scene. The day before, it looks at the day once more, with what each region is reading about too (Trends, below), and may choose a trend. Its guardrails strip a code fence from its answer, and check it with OpenAI’s moderation model.smarter_doodle_artist draws a holiday that the editor chose and the catalog has no theme for. It answers with the SVG of the decorations, and its guardrail removes scripts.
The editor can’t invent a topic, and nothing it says is trusted. The platform
(smarter.apps.doodle.editor) checks every choice again:
A choice must be one of the region’s candidates, and a holiday only when the region has no catalog theme that day.
A holiday about mourning, war, politics, a monarchy or a single religion’s holy day is never a candidate, and the editor’s caption and subject for the artist may not be about one either. The match uses the plugin selectors’ language matching: plurals, typos and WordNet synonyms, e.g. bereavement for mourning.
The category, the caption’s length and the alt text are checked, and the caption’s link must be a Wikipedia article. A trend’s link is always its own article’s.
Last, the
upbeat_occasion_inputGuardrail, a small LLM judge from the example manifests, must find the occasion plainly fun and upbeat. Word lists can’t tell a solemn anniversary or sad news from a festival; a judge of tone can, and moderation models, which look for harm, don’t. Without the Guardrail, or when it fails, nothing is drawn.
The artist’s SVG goes through an allowlist sanitizer (smarter.apps.doodle.sanitize): only
the shapes of a flat drawing, no text, images, links, scripts, ids or url(), and css that only
animates its own classes. A drawn doodle is proposed: visitors see the calendar’s choice until a
superuser approves it, unless enable_doodle_auto_approve is on.
Each prompt of the editor is recorded, under Doodle Editor Runs in the admin: what it was asked, what it answered, and which of its choices were refused. A day is asked once, or until it has failed three times, after which the calendar’s choice stays. On a platform without the example manifests, the calendar alone chooses.
Trends
Holidays are planned a week ahead; what people care about, e.g. a World Cup, isn’t. So the editor
looks at today and tomorrow once more, while the enable_doodle_trends switch is on, and is told
what each region is reading about, from Wikipedia (smarter.apps.doodle.trends):
Wikimedia publishes the most viewed articles of each language edition every day, an official, free and anonymous signal. Each region stands for its languages’ editions, e.g. Spanish and Portuguese for Latin America.
Each article is judged by its Wikidata item’s English label and description, whatever its edition’s language, with one Wikidata request per edition. An article about a person (years of life, or an occupation in its description), a date, or with a blocked word is left out, and its description must name an occasion (a tournament, a festival, an eclipse, a launch…): an allowlist, since a blocklist can’t keep up with the news.
A trend is chosen only when the region has no catalog theme that day, and it is always drawn, so it waits for a superuser’s approval, unless auto-approve is on. A doodle that the artist drew for a region is kept on the second look.
When a Smarter AI application chose or drew the day’s doodle, the panel says so, in place of the project’s description: Chosen by a Smarter AI application, or Drawn by a Smarter AI application, with a Learn how link to An LLM Editor and an SVG Artist, the blog post that walks through how the doodle is chosen and drawn. The case study The Smarter Doodle: Celebrating Special Days, Without an Artist or an Arbiter explains the design’s choices, with real decisions of the editor.
Waffle switches
enable_doodle: shows the doodle of the day. Inactive, the sign-in pages show the logo, the project’s name and its description, without the doodle.enable_doodle_regional: chooses the doodle by the visitor’s region. Inactive, everyone sees the global doodle.enable_doodle_animation: animates the doodles, e.g. a flickering flame. Inactive, every doodle is a still image. Visitors who ask their system for reduced motion always get still images.enable_doodle_caption: shows the caption below a themed doodle.enable_doodle_llm_editor: lets the Smarter Doodle Editor choose the doodles of each new day. Inactive, the calendar alone chooses.enable_doodle_llm_artwork: lets the editor choose a holiday that the catalog has no theme for, which the Smarter Doodle Artist draws.enable_doodle_trends: tells the editor what each region is reading about, on its second look at today and tomorrow.enable_doodle_auto_approve: shows a drawn doodle without a superuser’s approval. It is the only one that is inactive by default.enable_doodle_ai_credit: shows the credit of a Smarter AI application below its doodle.log_doodle: logs the app’s info and debug messages.
All but enable_doodle_auto_approve are active by default.
Technical Reference
The Doodle: the sign-in page’s illustration of the day.
The web console’s sign-in page shows a small, colorful illustration of a Smarter LLMClient and the resources around it. On days worth celebrating, such as a holiday, a day of recognition or a moment in computing history, the illustration is decorated for the day. Visitors in different regions can see different doodles on the same day, according to their time zone.
smarter.apps.doodle.regionsmaps a browser’s time zone to a region, and its local date.smarter.apps.doodle.scheduledecides the days on which a theme is due.smarter.apps.doodle.artworkdraws a theme’s props on the base scene.smarter.apps.doodle.plannerchooses each region’s doodle, a week ahead.smarter.apps.doodle.tasksruns the planner daily, from Celery Beat.smarter.apps.doodle.api.v1serves the doodle of the day, and its artwork.
The regions of the doodle, and how a browser’s time zone maps to one.
A browser sends its IANA time zone (Intl.DateTimeFormat().resolvedOptions().timeZone), e.g.
America/Vancouver. The time zone gives the visitor’s local date, so that a holiday starts at
local midnight, and, through the tz database’s zone.tab, the country, which gives the region.
No IP address is looked up, and nothing is stored.
The regions are coarse on purpose: each one is a doodle to plan every day.
- smarter.apps.doodle.regions.ALL_REGIONS = '*'
In a theme’s
regions, every region.
- class smarter.apps.doodle.regions.DoodleRegion(*values)[source]
A region that sees its own doodle.
- smarter.apps.doodle.regions.country_for_timezone(tz)[source]
Return the country of a time zone.
- smarter.apps.doodle.regions.local_date(tz, now=None)[source]
Return the date in a time zone.
- smarter.apps.doodle.regions.region_countries(region: str) tuple[str, ...][source]
Return the countries of a region, by their time zones.
It is a pure function of the tz database, which the editor asks again for every region of every day, so its answers are kept for the life of the process.
- smarter.apps.doodle.regions.region_for_timezone(tz)[source]
Return the region of a time zone.
- smarter.apps.doodle.regions.theme_applies_to(regions, region)[source]
Whether a theme whose
regionsare these is shown in a region.
- smarter.apps.doodle.regions.valid_timezone(tz)[source]
Return the time zone of an IANA name, or
Noneif the name isn’t one.
The schedule of a doodle theme: on which days it is due.
A theme’s schedule is one of:
fixed: the same day every year, e.g. Pi Day on March 14, fordaysdays.nth_weekday: e.g. Ada Lovelace Day, the second Tuesday of October.holiday: a holiday of a country, by name, from theholidayspackage, which knows the moving ones: Diwali, the Lunar New Year, Eid al-Fitr, Hanukkah, Thanksgiving, …never: the evergreen default theme, which the planner chooses when nothing else is due.
- class smarter.apps.doodle.schedule.DoodleSchedule(**data)[source]
When a doodle theme is due.
See
smarter.apps.doodle.schedule.- check_fields_of_kind()[source]
Check that the schedule has the fields that its kind needs.
- Return type:
DoodleSchedule- Returns:
The schedule.
- Raises:
ValueError – If a field that the kind needs is missing.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- occurs_on(day)[source]
Whether the theme is due on a day.
A theme that lasts several days, e.g. from December 24, may have started the year before.
- smarter.apps.doodle.schedule.country_holidays(country, year)[source]
Return a country’s holidays in a year, by date.
Every category of the country’s holidays is included (public, optional, school, …), because some holidays that a doodle celebrates aren’t public ones, e.g. Hanukkah in Israel. The weekdays that replace a holiday on a weekend, “(observed)”, are left out: they aren’t the holiday.
- smarter.apps.doodle.schedule.holiday_dates(country, name, year)[source]
Return the dates of a country’s holiday in a year.
- Parameters:
- Returns:
The dates, as ISO strings, e.g.
["2026-11-08"]. Empty if the country isn’t supported, or has no such holiday that year.- Return type:
- smarter.apps.doodle.schedule.holidays_on(country, day)[source]
Return the holidays of a country on a day.
- smarter.apps.doodle.schedule.nth_weekday(year, month, weekday, nth)[source]
Return the nth weekday of a month.
- Parameters:
- Returns:
The date, e.g. the second Tuesday of October 2026 is 2026-10-13.
- Return type:
- Raises:
ValueError – If the month has no such weekday, e.g. a fifth Monday.
The artwork of a doodle: a theme’s props, drawn on the base scene.
The base scene, static/doodle/base.svg, is a Smarter LLMClient’s chat window and the resources
around it: a plugin, a guardrail, a vectorstore, a secret and its manifest. It has an empty group,
<g id="doodle-props"/>, and a theme’s props, an SVG of the same viewBox, are moved into
it. The props decorate the scene: lanterns in the sky, a pumpkin on the ground, a hat on the chat
window. They are drawn around the scene, not over it.
The browser shows the result with <img>, in which an SVG can’t run scripts or load anything.
- smarter.apps.doodle.artwork.compose_svg(props_svg, title)[source]
Draw a theme’s props on the base scene.
- smarter.apps.doodle.artwork.parse_svg(svg)[source]
Parse an SVG document, safely.
- smarter.apps.doodle.artwork.read_base_scene()[source]
Read the base scene.
- Returns:
The base scene’s SVG.
- Return type:
- smarter.apps.doodle.artwork.still_svg(svg)[source]
Return a doodle’s SVG without its animations.
- smarter.apps.doodle.artwork.svg_sha256(svg)[source]
Return the hash of an SVG, which names its artwork.
The theme catalog: data/themes/<slug>.yaml, and the props of each, <slug>.svg.
manage.py load_doodle_themes, which initialize_platform runs, calls load_themes()
to keep the DoodleTheme table in step with the files. A
theme’s artwork is composed again each time, so that a change to the base scene reaches every
theme. See data/themes/README.md for the file format.
- class smarter.apps.doodle.themes.DoodleThemeSpec(**data)[source]
A theme’s file,
data/themes/<slug>.yaml.- classmethod check_link_url(link_url)[source]
Check that the link is https.
- Parameters:
link_url (
str) – The link.- Return type:
- Returns:
The link.
- Raises:
ValueError – If it isn’t empty or https.
- classmethod check_regions(regions)[source]
Check that each region is a
DoodleRegion, or*.- Parameters:
- Return type:
- Returns:
The regions.
- Raises:
ValueError – If one isn’t a region.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- smarter.apps.doodle.themes.load_themes(folder='/Users/mcdaniel/Desktop/gh/smarter-sh/smarter/smarter/smarter/apps/doodle/data/themes')[source]
Load every theme of the catalog, and deactivate the themes whose files were removed.
A removed theme is deactivated, not deleted, so that the past doodles that show it keep it.
- smarter.apps.doodle.themes.read_theme(path)[source]
Read a theme’s file and its props.
- Parameters:
path (
str) – The theme’s.yamlfile.- Returns:
The theme, and its props’ SVG, empty if it has none.
- Return type:
- Raises:
pydantic.ValidationError – If the file isn’t a valid theme.
ValueError – If the slug isn’t the file’s name, or the props file named doesn’t exist.
- smarter.apps.doodle.themes.save_theme(spec, props_svg)[source]
Create or update a theme from its file.
- Parameters:
spec (
DoodleThemeSpec) – The theme.props_svg (
str) – Its props.
- Returns:
The theme.
- Return type:
DoodleTheme- Raises:
SmarterValueError – If the props aren’t a valid SVG of the base scene’s viewBox.
- smarter.apps.doodle.themes.theme_files(folder='/Users/mcdaniel/Desktop/gh/smarter-sh/smarter/smarter/smarter/apps/doodle/data/themes')[source]
Return the catalog’s theme files.
The planner: it chooses the doodle of each day in each region, a week ahead.
For a day and a region, every active theme that is due and applies to the region is a candidate. The candidate of the highest priority wins; at equal priority, a theme of the region’s own wins over one of every region, then the slug decides, so that the choice is the same on every run. When nothing is due, the default theme wins.
A doodle that a person chose in the admin (source human), or that the Smarter Doodle Editor
chose (source llm, see smarter.apps.doodle.editor), is never replanned.
- smarter.apps.doodle.planner.candidates(day, region, due=None)[source]
Return the themes that are due on a day in a region, best first.
- smarter.apps.doodle.planner.catalog()[source]
Return the active themes of the catalog, without the default theme.
The planner reads them once for all the days and regions it plans.
- Returns:
The themes.
- Return type:
list[DoodleTheme]
- smarter.apps.doodle.planner.due_on(day, themes=None)[source]
Return the themes that are due on a day, in any region.
- smarter.apps.doodle.planner.plan_doodle(day, region, due=None)[source]
Plan the doodle of a day in a region.
- smarter.apps.doodle.planner.plan_doodles(days=7, today=None)[source]
Plan the doodles of every region,
daysdays ahead, and purge the old ones.
- smarter.apps.doodle.planner.planning_window(days=7, today=None)[source]
Return the days to plan.
The window starts the day before today in UTC, which is still today west of UTC, and ends
daysdays after, which is already the day after east of UTC.
- smarter.apps.doodle.planner.purge(today=None, retention_days=30)[source]
Delete the doodles and editor runs older than the retention period, and the drawn themes and.
artworks that nothing uses.
Models of the doodle app.
DoodleArtworkis an SVG, stored once and named by its hash, so that its url never changes and a browser may cache it forever.DoodleThemeis a theme of the catalog,data/themes/: when it is due, where, its caption and its artwork.manage.py load_doodle_themeskeeps the table in step with the files.Doodleis the planned doodle of one day in one region, which the planner writes a week ahead, and which a superuser can override in the admin.
- class smarter.apps.doodle.models.Doodle(*args, **kwargs)[source]
The doodle of one day in one region.
- Parameters:
id (Unknown) – Primary key: ID
created_at (Unknown) – Created at
updated_at (Unknown) – Updated at
date (Unknown) – Date. The local date on which it is shown.
region (Unknown) – Region
status (Unknown) – Status
source (Unknown) – Source
title (Unknown) – Title. What it celebrates, e.g. Diwali.
caption (Unknown) – Caption
alt_text (Unknown) – Alt text
link_url (Unknown) – Link url
reason (Unknown) – Reason. Why it was chosen.
Relationship fields:
- Parameters:
theme (Unknown) – Theme (related name:
doodles)artwork (Unknown) – Artwork (related name:
doodles)
- exception DoesNotExist
- exception MultipleObjectsReturned
- exception NotUpdated
- property ai_credit: Literal['', 'chosen', 'drawn']
What a Smarter AI application did for the doodle, for the credit below it.
- Returns:
drawnif the Smarter Doodle Artist drew its artwork,chosenif the Smarter Doodle Editor chose its catalog theme, or an empty string. Never for the plain default.- Return type:
DoodleAiCredit
- created_at
-
Created at
Timestamp indicating when the model instance was created.
This field is automatically set to the current date and time when the instance is first created. It is indexed in the database for efficient querying.
- Type:
Type
- id: int
-
Primary key: ID
The row’s primary key, which Django adds to every concrete model. Declared, without a value, only so that type checkers know it: Django ignores a bare annotation.
- Type:
Type
- classmethod shown(date, region)[source]
Return the approved doodle of a day in a region.
- updated_at
-
Updated at
Timestamp indicating when the model instance was last updated.
This field is automatically updated to the current date and time whenever the instance is saved. It is indexed in the database for efficient querying.
- Type:
Type
- class smarter.apps.doodle.models.DoodleArtwork(*args, **kwargs)[source]
An SVG of a doodle, named by its content’s SHA-256.
- Parameters:
id (Unknown) – Primary key: ID
created_at (Unknown) – Created at
updated_at (Unknown) – Updated at
sha256 (Unknown) – Sha256. The SHA-256 of the SVG, in hex.
svg (Unknown) – Svg. The SVG.
Reverse relationships:
- Parameters:
themes (Unknown) – All themes of this Doodle Artwork (related name of
artwork)doodles (Unknown) – All doodles of this Doodle Artwork (related name of
artwork)
- exception DoesNotExist
- exception MultipleObjectsReturned
- exception NotUpdated
- created_at
-
Created at
Timestamp indicating when the model instance was created.
This field is automatically set to the current date and time when the instance is first created. It is indexed in the database for efficient querying.
- Type:
Type
- classmethod for_svg(svg)[source]
Return the artwork of an SVG, stored once.
- Parameters:
svg (
str) – The SVG.- Returns:
The artwork, existing or new.
- Return type:
DoodleArtwork
- id: int
-
Primary key: ID
The row’s primary key, which Django adds to every concrete model. Declared, without a value, only so that type checkers know it: Django ignores a bare annotation.
- Type:
Type
- updated_at
-
Updated at
Timestamp indicating when the model instance was last updated.
This field is automatically updated to the current date and time whenever the instance is saved. It is indexed in the database for efficient querying.
- Type:
Type
- class smarter.apps.doodle.models.DoodleCategory(*values)[source]
What a theme celebrates.
The planner’s guardrails accept only these categories.
- class smarter.apps.doodle.models.DoodleEditorRun(*args, **kwargs)[source]
A prompt of the Smarter Doodle Editor for one day: what it was asked, and what it answered.
The planner asks the editor once for each day, a week ahead, and once more, with trends, the day before. A day whose run succeeded isn’t asked again, and a day whose runs failed
EDITOR_MAX_ATTEMPTStimes is left to the calendar.- Parameters:
id (Unknown) – Primary key: ID
created_at (Unknown) – Created at
updated_at (Unknown) – Updated at
date (Unknown) – Date. The day that the editor chose the doodles of.
status (Unknown) – Status
request (Unknown) – Request. The prompt: the day’s candidates, in each region.
response (Unknown) – Response. The editor’s answer.
error (Unknown) – Error. Why the run failed.
with_trends (Unknown) – With trends. Whether the editor was told what each region is reading about.
- exception DoesNotExist
- exception MultipleObjectsReturned
- exception NotUpdated
- created_at
-
Created at
Timestamp indicating when the model instance was created.
This field is automatically set to the current date and time when the instance is first created. It is indexed in the database for efficient querying.
- Type:
Type
- id: int
-
Primary key: ID
The row’s primary key, which Django adds to every concrete model. Declared, without a value, only so that type checkers know it: Django ignores a bare annotation.
- Type:
Type
- updated_at
-
Updated at
Timestamp indicating when the model instance was last updated.
This field is automatically updated to the current date and time whenever the instance is saved. It is indexed in the database for efficient querying.
- Type:
Type
- class smarter.apps.doodle.models.DoodleEditorRunStatus(*values)[source]
How a run of the Smarter Doodle Editor ended.
- class smarter.apps.doodle.models.DoodleSource(*values)[source]
Who chose a planned doodle.
- class smarter.apps.doodle.models.DoodleStatus(*values)[source]
Whether a planned doodle may be shown.
- class smarter.apps.doodle.models.DoodleTheme(*args, **kwargs)[source]
A theme of the catalog.
See
data/themes/README.md.- Parameters:
id (Unknown) – Primary key: ID
created_at (Unknown) – Created at
updated_at (Unknown) – Updated at
slug (Unknown) – Slug. The theme’s name, and its file’s.
name (Unknown) – Name. What the theme celebrates, e.g. Diwali.
category (Unknown) – Category
caption (Unknown) – Caption. e.g. Happy Diwali!
alt_text (Unknown) – Alt text. The artwork’s description, for screen readers.
link_url (Unknown) – Link url. Where the caption links to.
priority (Unknown) – Priority. When several themes are due, the one of the highest priority wins.
regions (Unknown) – Regions. The regions that see it, or [“*”] for all of them.
schedule (Unknown) – Schedule. When it is due. See DoodleSchedule.
props_svg (Unknown) – Props svg. The props, drawn on the base scene.
is_active (Unknown) – Is active. Whether the planner may choose it.
is_generated (Unknown) – Is generated. Whether the Smarter Doodle Artist drew it, for one day, rather than the catalog’s file.
Relationship fields:
- Parameters:
artwork (Unknown) – Artwork. The props on the base scene. (related name:
themes)
Reverse relationships:
- Parameters:
doodles (Unknown) – All doodles of this Doodle Theme (related name of
theme)
- exception DoesNotExist
- exception MultipleObjectsReturned
- exception NotUpdated
- created_at
-
Created at
Timestamp indicating when the model instance was created.
This field is automatically set to the current date and time when the instance is first created. It is indexed in the database for efficient querying.
- Type:
Type
- property doodle_schedule: DoodleSchedule
The theme’s schedule.
- Returns:
The schedule, validated.
- Return type:
DoodleSchedule
- id: int
-
Primary key: ID
The row’s primary key, which Django adds to every concrete model. Declared, without a value, only so that type checkers know it: Django ignores a bare annotation.
- Type:
Type
- updated_at
-
Updated at
Timestamp indicating when the model instance was last updated.
This field is automatically updated to the current date and time whenever the instance is saved. It is indexed in the database for efficient querying.
- Type:
Type
The Smarter Doodle Editor and Artist: two LLMClients that choose and draw the doodle of the day.
After the calendar has planned a day (smarter.apps.doodle.planner), the planner asks the
editor, the staff-only LLMClient smarter_doodle_editor of the Smarter account, to choose each
region’s doodle of that day. The editor may only choose among what it is given:
the region’s catalog themes that are due, whose artwork exists and was reviewed;
the region’s observances: its other holidays that day, from the
holidayspackage, which have no artwork yet. When it chooses one, the artist,smarter_doodle_artist, draws it;the region’s trends: what it is reading about on Wikipedia (
smarter.apps.doodle.trends), on the editor’s second look at today and tomorrow. The artist draws them too;the default: the plain scene.
Its answer is checked again here, whatever its system prompt says: a choice must be one of the
region’s candidates; an observance or a trend must not be about mourning, war, politics or a
religion’s holy day (BLOCKED_WORDS), its category, caption and link must be fit to show, and
the upbeat_occasion_input Guardrail, a small LLM, must judge it fun and upbeat
(tone_check()). A choice that
fails is ignored, and the calendar’s doodle stays. A drawn doodle is proposed, and a superuser
approves it in the admin, unless the enable_doodle_auto_approve switch is on.
Both LLMClients are prompted in-process, as their owner, with
smarter.apps.llmclient.prompting.prompt_in_process(): their system prompts, guardrails and
budgets apply, as they would to a person’s prompt. Every editor prompt is recorded as a
DoodleEditorRun. A day is asked
once, or until it has failed EDITOR_MAX_ATTEMPTS times.
- smarter.apps.doodle.editor.BLOCKED_WORDS = ('mourning', 'memorial', 'remembrance', 'martyr', 'massacre', 'genocide', 'victims', 'tragedy', 'disaster', 'war', 'armistice', 'death', 'funeral', 'election', 'referendum', 'party', 'president', 'king', 'queen', 'prophet', 'saint', 'holy', 'lent', 'good friday', 'ashura', 'religious', 'christian', 'church', 'feast day', 'accident', 'collision', 'crash', 'derailment', 'killed', 'attack', 'shooting', 'bombing', 'explosion', 'murder', 'crime', 'terrorism', 'earthquake', 'flood', 'hurricane', 'wildfire', 'epidemic', 'pandemic', 'scandal', 'protest', 'riot', 'trial')
mourning, war, politics, and a single.
religion’s holy days. The catalog may still celebrate religious holidays that it chose, and drew, with care, e.g. Diwali or Christmas. See
has_blocked_word()for how a text matches one.( 'mourning', 'memorial', 'remembrance', 'martyr', 'massacre', 'genocide', 'victims', 'tragedy', 'disaster', 'war', 'armistice', 'death', 'funeral', 'election', 'referendum', 'party', 'president', 'king', 'queen', 'prophet', 'saint', 'holy', 'lent', 'good friday', 'ashura', 'religious', 'christian', 'church', 'feast day', 'accident', 'collision', 'crash', 'derailment', 'killed', 'attack', 'shooting', 'bombing', 'explosion', 'murder', 'crime', 'terrorism', 'earthquake', 'flood', 'hurricane', 'wildfire', 'epidemic', 'pandemic', 'scandal', 'protest', 'riot', 'trial', )
- Type:
Words of a holiday that a doodle never celebrates on its own
- class smarter.apps.doodle.editor.DoodleEditorAnswer(**data)[source]
The editor’s answer.
- model_config = {'extra': 'ignore'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.doodle.editor.DoodleEditorDecision(**data)[source]
The editor’s choice for one region.
Extra fields are ignored: an LLM adds some.
- model_config = {'extra': 'ignore'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.doodle.editor.DoodleEditorRequest(**data)[source]
The editor’s prompt: the day’s candidates, in each region.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- smarter.apps.doodle.editor.check_decision(decision, request)[source]
Check a decision against the request and the guardrails.
- smarter.apps.doodle.editor.edit_day(day)[source]
Ask the editor to choose the doodles of a day, and apply its choices.
- smarter.apps.doodle.editor.edit_days(days)[source]
Ask the editor about each day that needs it, while the
enable_doodle_llm_editorswitch is on.
- smarter.apps.doodle.editor.editor_request(day, regions, artwork_allowed, with_trends=False)[source]
Build the editor’s prompt for a day.
- Parameters:
- Returns:
The request.
- Return type:
DoodleEditorRequest
- smarter.apps.doodle.editor.observances(day, region)[source]
Return a region’s holidays on a day, without those that a doodle never celebrates.
- smarter.apps.doodle.editor.parse_answer(text)[source]
Parse the editor’s answer.
Trend signals for the Smarter Doodle Editor: what each region is reading about.
The Wikimedia Foundation publishes, every day, the most viewed articles of each language edition
of Wikipedia (the pageviews api).
During a World Cup, the football articles lead the Spanish, Portuguese and French editions, so the
editions that a region reads (REGION_PROJECTS) are a regional signal of what people are
paying attention to. It is free, official and anonymous.
Trends are the riskiest candidates of the editor: most of what people read about is a person, a death, a crime or the news. So a trend reaches the editor only if:
it is an article, not the main page or a special page;
it has a Wikidata item, whose English label and description it is judged by, whatever the edition’s language (one
wbgetentitiesrequest for all of an edition’s top articles);its title, English label and English description have none of the editor’s
BLOCKED_WORDS, by the same language matching;its description isn’t a person’s: no years of life, e.g.
(1950–2026), and none ofPERSON_WORDS, e.g.actororfootballer. A doodle never draws a person;its description names an occasion, one of
OCCASION_WORDS, e.g.tournament,festivaloreclipse: an allowlist, since a blocklist can’t keep up with the news.
The editor may choose a trend only when the region has no catalog theme that day, and the artist always draws it, so a trend’s doodle awaits a superuser’s approval unless auto-approve is on.
The day’s top articles are those of the day before, or, until the api has published it, a few hours after midnight UTC, of the day before that.
Try it yourself
Three commands, with curl and jq, show what this module does, for Canada, in English. They
are a simplified version of it: step 3 checks a short list of occasion words, not every filter above.
Ask Wikipedia which 25 articles were read the most yesterday, and save their titles:
curl -s "https://wikimedia.org/api/rest_v1/metrics/pageviews/top/en.wikipedia.org/all-access/2026/11/03" | jq -r '[.items[0].articles[:25][].article | gsub("_"; " ")] | join("|")' > titles.txt
Ask Wikidata, Wikipedia’s sister site, what each of those articles is about, in one short English sentence, e.g. FIFA World Cup: international association football competition:
curl -s -G "https://www.wikidata.org/w/api.php" --data-urlencode "action=wbgetentities" --data-urlencode "sites=enwiki" --data-urlencode "titles=$(cat titles.txt)" --data-urlencode "props=labels|descriptions" --data-urlencode "languages=en" --data-urlencode "format=json" > articles.json
Keep only the articles about an occasion worth a doodle, e.g. a festival or a tournament, and write them up as the request that the doodle editor, an LLMClient, receives:
jq '{date: "2026-11-04", artwork_allowed: true, regions: [{region: "ca", name: "Canada", catalog: [], observances: [.entities[] | select(.descriptions.en.value // "" | test("festival|tournament|championship|cup|season|holiday|eclipse"; "i")) | {id: ("CA:" + .id), name: .labels.en.value, countries: ["CA"]}]}]}' articles.json
which prints, e.g.:
{ "date": "2026-11-04", "artwork_allowed": true, "regions": [ { "region": "ca", "name": "Canada", "catalog": [], "observances": [ { "id": "CA:Q139761349", "name": "Dancing with the Stars (American TV series) season 35", "countries": ["CA"] } ] } ] }
- class smarter.apps.doodle.trends.DoodleTrend(**data)[source]
A trending article of a region, as the editor is told about it.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- smarter.apps.doodle.trends.REGION_PROJECTS: dict[str, tuple[str, ...]] = {DoodleRegion.AFRICA: ('fr.wikipedia.org', 'sw.wikipedia.org'), DoodleRegion.CA: ('en.wikipedia.org', 'fr.wikipedia.org'), DoodleRegion.EAST_ASIA: ('ja.wikipedia.org', 'ko.wikipedia.org', 'zh.wikipedia.org'), DoodleRegion.EUROPE: ('de.wikipedia.org', 'fr.wikipedia.org', 'it.wikipedia.org', 'pl.wikipedia.org'), DoodleRegion.GLOBAL: ('en.wikipedia.org',), DoodleRegion.LATAM: ('es.wikipedia.org', 'pt.wikipedia.org'), DoodleRegion.MIDDLE_EAST: ('ar.wikipedia.org', 'tr.wikipedia.org'), DoodleRegion.MX: ('es.wikipedia.org',), DoodleRegion.OCEANIA: ('en.wikipedia.org',), DoodleRegion.SOUTH_ASIA: ('hi.wikipedia.org', 'bn.wikipedia.org'), DoodleRegion.SOUTHEAST_ASIA: ('id.wikipedia.org', 'vi.wikipedia.org', 'th.wikipedia.org'), DoodleRegion.US: ('en.wikipedia.org',)}
The Wikipedia editions whose readers stand for each region.
English is read everywhere, so it stands only for the regions where it is the first language; elsewhere the region’s own languages do, e.g. Spanish and Portuguese for Latin America.
{ DoodleRegion.AFRICA: ('fr.wikipedia.org', 'sw.wikipedia.org'), DoodleRegion.CA: ('en.wikipedia.org', 'fr.wikipedia.org'), DoodleRegion.EAST_ASIA: ( 'ja.wikipedia.org', 'ko.wikipedia.org', 'zh.wikipedia.org', ), DoodleRegion.EUROPE: ( 'de.wikipedia.org', 'fr.wikipedia.org', 'it.wikipedia.org', 'pl.wikipedia.org', ), DoodleRegion.GLOBAL: ('en.wikipedia.org', ), DoodleRegion.LATAM: ('es.wikipedia.org', 'pt.wikipedia.org'), DoodleRegion.MIDDLE_EAST: ('ar.wikipedia.org', 'tr.wikipedia.org'), DoodleRegion.MX: ('es.wikipedia.org', ), DoodleRegion.OCEANIA: ('en.wikipedia.org', ), DoodleRegion.SOUTH_ASIA: ('hi.wikipedia.org', 'bn.wikipedia.org'), DoodleRegion.SOUTHEAST_ASIA: ( 'id.wikipedia.org', 'vi.wikipedia.org', 'th.wikipedia.org', ), DoodleRegion.US: ('en.wikipedia.org', ), }
- smarter.apps.doodle.trends.article_entities(project, titles)[source]
Return the English label, English description and url of articles, from their Wikidata items.
- Parameters:
- Returns:
Each title’s English label, English description and article url. A title without a Wikidata item, or without an English description, is left out.
- Return type:
- Raises:
SafeHttpError – If the api fails. A failure isn’t cached.
- smarter.apps.doodle.trends.is_a_person(description: str) bool[source]
Whether an article’s description says that it is about a person.
It is a pure function of its text, which the regions that share an edition ask about again, so its answers are kept for the life of the process.
- smarter.apps.doodle.trends.is_an_occasion(description: str) bool[source]
Whether an article’s description says that it is an occasion that a doodle may celebrate.
- smarter.apps.doodle.trends.region_trends(region, day, refuse)[source]
Return the trends of a region that a doodle may celebrate.
- smarter.apps.doodle.trends.top_articles(project, day)[source]
Return the most viewed articles of a Wikipedia edition on a day.
- Parameters:
- Returns:
Each article’s title and views, most viewed first, at most
TOP_ARTICLES_SCANNED, without pages that aren’t articles.- Return type:
- Raises:
SafeHttpError – If the api fails. A failure isn’t cached.
The sanitizer of the SVG that the Smarter Doodle Artist draws.
The artist is an LLM, so its SVG is untrusted, whatever its system prompt says. The sign-in page
shows it with <img>, which runs no scripts and loads nothing, and the artwork’s url is served
with a sandboxing Content-Security-Policy; this module is the third layer. It keeps only what a
flat, decorative drawing needs, by allowlist:
elements:
svg,g,path,rect,circle,ellipse,line,polyline,polygonandstyle. Anything else, e.g.script,foreignObject,image,a,use,textor an SMILanimate, is removed with its children.attributes: geometry, paint,
transformandclass. Everyon*handler,href,styleandidis removed, and a value that containsurl(,javascript:ordata:.styles: one
<style>of css rules and keyframes, without@import,url(,expressionor markup, whose class and keyframe names start with the theme’s prefix.
The result must still be an SVG of the base scene’s viewBox with something left to draw.
- smarter.apps.doodle.sanitize.extract_svg(text)[source]
Return the SVG in an LLM’s answer, without the prose or code fence around it.
- smarter.apps.doodle.sanitize.sanitize_svg(svg, prefix)[source]
Return a generated SVG, with only what a decorative drawing needs.
- Parameters:
- Returns:
The sanitized SVG, ready for
compose_svg().- Return type:
- Raises:
SmarterValueError – If it is too long, not an SVG of the base scene’s
viewBox, has too many elements, or has nothing left to draw.
Prompt an LLMClient from the platform’s own code, through its chat api.
Some of the platform’s features are Smarter AI applications themselves: the sign-in page’s doodle
(smarter.apps.doodle.editor) is chosen and drawn by LLMClients, an Orchestrator’s run
(smarter.apps.orchestrator.runtime) prompts its harness LLMClients, and manage.py
verify_stackademy checks that the Stackademy LLMClients work. There are two ways to prompt one.
In-process, through the provider’s handler that the chat api calls, as the LLMClient’s owner: its system prompt, plugins, guardrails, budgets and chat history all apply, as they would to a person’s prompt, without an api key or an http request. The doodle and the orchestrator do this.
new_session()creates aPromptsession of an LLMClient, owned by its owner.send_message()sends one message in a session, which keeps the conversation.prompt_in_process()sends one message in a new session.
Through the chat api, as any client does, which tests the api itself. verify_stackademy
does this.
single_use_api_key()creates an api key of the LLMClient’s owner, and deletes it afterwards.prompt_llmclient()sends one prompt in a new session, and returns the prompt’s result.
Either way, assistant_text() returns the LLM’s answer, and extract_json_object() the
JSON object in it, for an LLMClient that is asked to answer in JSON.
- smarter.apps.llmclient.prompting.PLATFORM_IP_ADDRESS = '127.0.0.1'
no browser opened it.
- Type:
The ip address of a session that the platform’s own code opens
- exception smarter.apps.llmclient.prompting.SmarterLLMClientPromptError(message='')[source]
A prompt to an LLMClient failed, or its response wasn’t a valid prompt response.
- smarter.apps.llmclient.prompting.assistant_text(result)[source]
Return the LLM’s answer: the text of the last assistant message that has any.
- Parameters:
result (
PromptChatApiPromptResult) – A prompt’s result.- Returns:
The answer, or
Noneif the LLM gave none.- Return type:
- smarter.apps.llmclient.prompting.extract_json_object(text)[source]
Return the JSON object in an LLM’s answer, e.g.
{"harness": "stackademy_hr_assistant"}.The answer should be only the object, but a model may wrap it in prose or a code block, so the text from its first
{to its last}is parsed.
- smarter.apps.llmclient.prompting.new_session(llmclient, url, user_agent)[source]
Create a
Promptsession of an LLMClient, owned by the LLMClient’s owner.
- smarter.apps.llmclient.prompting.prompt_in_process(llmclient, message, url, user_agent)[source]
Send one user message to an LLMClient, in a new session, in-process, as the LLMClient’s owner.
- Parameters:
- Returns:
The prompt’s result.
- Return type:
- Raises:
SmarterLLMClientPromptError – If the prompt failed.
- smarter.apps.llmclient.prompting.prompt_llmclient(llmclient, token_key, prompt)[source]
Send a prompt to an LLMClient, in a new session, through its chat api.
The prompt is sent in-process, as a client of version 2 of the chat contract would send it.
- Parameters:
- Returns:
The prompt’s result: the messages that it added, the completion, the tools.
- Return type:
- Raises:
SmarterLLMClientPromptError – If a request fails, or the response isn’t a prompt response.
- smarter.apps.llmclient.prompting.send_message(session, message, acting=None)[source]
Send one user message to a session’s LLMClient, in-process, as the LLMClient’s owner.
It calls the provider’s handler that the chat api calls, so the LLMClient’s system prompt, plugins, guardrails, budgets and chat history apply. A session that is sent several messages keeps its conversation.
Any failure raises
SmarterLLMClientPromptError. An unexpected exception’s message isn’t kept, only its class: it may quote the LLM provider.- Parameters:
- Returns:
The prompt’s result: the messages that it added, the completion, the tools.
- Return type:
- Raises:
SmarterLLMClientPromptError – If the prompt failed.
- smarter.apps.llmclient.prompting.single_use_api_key(user_profile, name)[source]
Create an api key of a user, and delete it when the block ends, whether or not it raised.
- Parameters:
user_profile (
UserProfile) – The key’s user, who must be staff, usually the LLMClient’s owner.name (
str) – The key’s name, in snake_case, e.g. the command or task that uses it.
- Returns:
The key, for an
Authorization: Token <key>header.- Return type:
Cached reads of the doodle app’s rows.
doodle_of_the_day(): the doodle of a day in a region, forGET /api/v1/doodles/today/.artwork_svg(): an artwork’s SVG, forGET /api/v1/doodles/artwork/<sha256>.svg.
A doodle is cached for DOODLE_CACHE_TIMEOUT seconds, so a
change in the admin, e.g. an approval, shows within ten minutes. An artwork never changes: its name is its hash.
- smarter.apps.doodle.caching.artwork_svg(sha256)[source]
Return the SVG of an artwork.
- smarter.apps.doodle.caching.artwork_url(sha256)[source]
Return the url of an artwork.
- smarter.apps.doodle.caching.doodle_of_the_day(day, region)[source]
Return the doodle of a day in a region.
The region’s approved doodle; else, e.g. while a drawn doodle awaits approval, or before the planner has run, the calendar’s choice for the region, made now; else, when the catalog isn’t loaded, the base scene from the static files.
The views of the doodle api, /api/v1/doodles/.
Both are public, because the sign-in page shows the doodle before anyone signs in. Neither reads
or writes anything of the visitor’s: the time zone that the browser sends picks the region and the
local date, and is not stored. Their reads are cached in smarter.apps.doodle.caching.
today/?tz=<IANA time zone>:DoodleTodayView, the doodle of the day, as JSON.artwork/<sha256>.svg:DoodleArtworkView, an artwork, cached forever by browsers.
- class smarter.apps.doodle.api.v1.views.DoodleArtworkView(**kwargs)[source]
An artwork of a doodle,
image/svg+xml.Its url names its content’s hash, so browsers may cache it forever. With
?still=1, it has no animations.
- class smarter.apps.doodle.api.v1.views.DoodleTodayView(**kwargs)[source]
The doodle of the day, for the sign-in page.
GETwith the query parametertz, the browser’s IANA time zone, e.g.Asia/Kolkata. It picks the visitor’s region and local date. Without it, or while theenable_doodle_regionalswitch is off, the doodle is the global one.- get(request, *args, **kwargs)[source]
Return the doodle of the day.
- Parameters:
request (
Request) – The request.- Returns:
A
DoodleApiResponse.- Return type:
Response
The response of the doodle of the day, GET /api/v1/doodles/today/.
The sign-in page’s React app, @smarter/doodle, reads it. Its fields are camelCase.
- class smarter.apps.doodle.contract.models.DoodleApiResponse(**data)[source]
The response of
GET /api/v1/doodles/today/: the doodle, and how to show it.- classmethod from_doodle(doodle, animated, show_caption, show_ai_credit=True)[source]
Build the response from a planned doodle and the switches.
- Parameters:
- Returns:
The response.
- Return type:
DoodleApiResponse
- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.doodle.contract.models.DoodleOfTheDay(**data)[source]
The doodle of a day in a region, as it is planned, before the switches apply.
- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
Celery tasks for the doodle app.
plan_doodles()plans the doodles of every region a week ahead, from the calendar, asks the Smarter Doodle Editor about each new day (smarter.apps.doodle.editor), and deletes the old ones. Celery Beat runs it every six hours.