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.

  1. 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’s README.md explains how to add a theme and draw its props. manage.py load_doodle_themes, which initialize_platform runs, loads the catalog and draws each theme’s artwork.

  2. 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_doodles does the same by hand, and asks the editor too with --editor.

  3. The api. GET /api/v1/doodles/today/?tz=<time zone> returns the doodle of the day as JSON, and GET /api/v1/doodles/artwork/<sha256>.svg its 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.

  4. 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 holidays package. 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_input Guardrail, 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.

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.regions maps a browser’s time zone to a region, and its local date.

  • smarter.apps.doodle.schedule decides the days on which a theme is due.

  • smarter.apps.doodle.artwork draws a theme’s props on the base scene.

  • smarter.apps.doodle.planner chooses each region’s doodle, a week ahead.

  • smarter.apps.doodle.tasks runs the planner daily, from Celery Beat.

  • smarter.apps.doodle.api.v1 serves 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.

Parameters:

tz (str | None) – An IANA time zone name, e.g. America/Mexico_City.

Returns:

The ISO 3166 country code, e.g. MX, or None for a time zone that belongs to no country, such as UTC, or to none in zone.tab, such as the alias US/Pacific.

Return type:

str | None

smarter.apps.doodle.regions.local_date(tz, now=None)[source]

Return the date in a time zone.

Parameters:
  • tz (str | None) – An IANA time zone name. An invalid name is UTC.

  • now (datetime | None) – The moment. Now, by default.

Returns:

The date in that time zone at that moment.

Return type:

date

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.

Parameters:

region (str) – The region.

Returns:

The ISO 3166 country codes whose time zones belong to the region, sorted. Empty for DoodleRegion.GLOBAL, which is no country’s.

Return type:

tuple[str, ...]

smarter.apps.doodle.regions.region_for_timezone(tz)[source]

Return the region of a time zone.

Parameters:

tz (str | None) – An IANA time zone name, e.g. Asia/Kolkata.

Returns:

The region, e.g. DoodleRegion.SOUTH_ASIA, or DoodleRegion.GLOBAL.

Return type:

DoodleRegion

smarter.apps.doodle.regions.theme_applies_to(regions, region)[source]

Whether a theme whose regions are these is shown in a region.

Parameters:
  • regions (list[str]) – The theme’s regions, or ["*"] for all of them.

  • region (str) – The region.

Returns:

True if the theme applies to the region.

Return type:

bool

smarter.apps.doodle.regions.valid_timezone(tz)[source]

Return the time zone of an IANA name, or None if the name isn’t one.

Parameters:

tz (str | None) – An IANA time zone name, e.g. Europe/Paris, from the browser.

Returns:

The time zone, or None.

Return type:

ZoneInfo | None

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, for days days.

  • nth_weekday: e.g. Ada Lovelace Day, the second Tuesday of October.

  • holiday: a holiday of a country, by name, from the holidays package, 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.

Parameters:

day (date) – The day.

Returns:

True if the theme is due.

Return type:

bool

start_dates(year)[source]

Return the dates on which the theme starts in a year.

Parameters:

year (int) – The year.

Returns:

The dates. Empty for never, or a date that the year doesn’t have (February 29).

Return type:

list[date]

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.

Parameters:
  • country (str) – The ISO 3166 country code, e.g. IN.

  • year (int) – The year.

Returns:

The English names of each date’s holidays, by ISO date, e.g. {"2026-11-08": ["Diwali"]}. Empty if the country isn’t supported, or the package doesn’t date that year.

Return type:

dict[str, list[str]]

smarter.apps.doodle.schedule.holiday_dates(country, name, year)[source]

Return the dates of a country’s holiday in a year.

Parameters:
  • country (str) – The ISO 3166 country code, e.g. IN.

  • name (str) – Text that the holiday’s English name contains, e.g. Diwali. Case doesn’t matter.

  • year (int) – The year.

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:

list[str]

smarter.apps.doodle.schedule.holidays_on(country, day)[source]

Return the holidays of a country on a day.

Parameters:
  • country (str) – The ISO 3166 country code, e.g. MX.

  • day (date) – The day.

Returns:

The holidays’ English names, e.g. ["Revolution Day"].

Return type:

list[str]

smarter.apps.doodle.schedule.nth_weekday(year, month, weekday, nth)[source]

Return the nth weekday of a month.

Parameters:
  • year (int) – The year.

  • month (int) – The month, 1 to 12.

  • weekday (int) – The weekday, 0 (Monday) to 6 (Sunday).

  • nth (int) – 1 to 5, or -1 for the last one.

Returns:

The date, e.g. the second Tuesday of October 2026 is 2026-10-13.

Return type:

date

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.

Parameters:
  • props_svg (str) – The props, an SVG of the base scene’s viewBox. Empty for none.

  • title (str) – The image’s accessible title, e.g. the theme’s alt text.

Returns:

The doodle’s SVG.

Return type:

str

Raises:

SmarterValueError – If the props, or the base scene, aren’t valid.

smarter.apps.doodle.artwork.parse_svg(svg)[source]

Parse an SVG document, safely.

Parameters:

svg (str) – The document.

Returns:

Its root element.

Return type:

Element

Raises:

SmarterValueError – If it isn’t well-formed XML, or its root isn’t an <svg> of the base scene’s viewBox.

smarter.apps.doodle.artwork.read_base_scene()[source]

Read the base scene.

Returns:

The base scene’s SVG.

Return type:

str

smarter.apps.doodle.artwork.still_svg(svg)[source]

Return a doodle’s SVG without its animations.

Parameters:

svg (str) – The doodle’s SVG.

Returns:

The same SVG, with a last style that stops every animation.

Return type:

str

smarter.apps.doodle.artwork.svg_sha256(svg)[source]

Return the hash of an SVG, which names its artwork.

Parameters:

svg (str) – The SVG.

Returns:

Its SHA-256, in hex.

Return type:

str

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:

str

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:

regions (list[str]) – The theme’s regions.

Return type:

list[str]

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.

Parameters:

folder (str) – The catalog’s folder.

Returns:

The themes loaded.

Return type:

list[DoodleTheme]

Raises:
  • pydantic.ValidationError – If a file isn’t a valid theme. No theme is changed then.

  • SmarterValueError – If a theme’s props aren’t a valid SVG. No theme is changed then.

smarter.apps.doodle.themes.read_theme(path)[source]

Read a theme’s file and its props.

Parameters:

path (str) – The theme’s .yaml file.

Returns:

The theme, and its props’ SVG, empty if it has none.

Return type:

tuple[DoodleThemeSpec, str]

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.

Parameters:

folder (str) – The catalog’s folder.

Returns:

The paths of the .yaml files, sorted.

Return type:

list[str]

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.

Parameters:
  • day (date) – The local date.

  • region (str) – The region.

  • due (list[DoodleTheme] | None) – The themes due on the day, from due_on(), when the caller asks about several regions. Found now, by default.

Returns:

The themes, without the default theme.

Return type:

list[DoodleTheme]

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.

Parameters:
  • day (date) – The local date.

  • themes (list[DoodleTheme] | None) – The catalog, from catalog(). Read now, by default.

Returns:

The themes whose schedule occurs on the day.

Return type:

list[DoodleTheme]

smarter.apps.doodle.planner.plan_doodle(day, region, due=None)[source]

Plan the doodle of a day in a region.

Parameters:
  • day (date) – The local date.

  • region (str) – The region.

  • due (list[DoodleTheme] | None) – The themes due on the day, from due_on(). Found now, by default.

Returns:

The doodle, or None if the catalog isn’t loaded.

Return type:

Doodle | None

smarter.apps.doodle.planner.plan_doodles(days=7, today=None)[source]

Plan the doodles of every region, days days ahead, and purge the old ones.

Parameters:
  • days (int) – How many days ahead to plan.

  • today (date | None) – Today, in UTC. Now, by default.

Returns:

The number of doodles planned.

Return type:

int

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 days days after, which is already the day after east of UTC.

Parameters:
  • days (int) – How many days ahead to plan.

  • today (date | None) – Today, in UTC. Now, by default.

Returns:

The days.

Return type:

list[date]

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.

Parameters:
  • today (date | None) – Today, in UTC. Now, by default.

  • retention_days (int) – How many days of past doodles to keep.

Returns:

The number of doodles deleted.

Return type:

int

Models of the doodle app.

  • DoodleArtwork is an SVG, stored once and named by its hash, so that its url never changes and a browser may cache it forever.

  • DoodleTheme is a theme of the catalog, data/themes/: when it is due, where, its caption and its artwork. manage.py load_doodle_themes keeps the table in step with the files.

  • Doodle is 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:

drawn if the Smarter Doodle Artist drew its artwork, chosen if the Smarter Doodle Editor chose its catalog theme, or an empty string. Never for the plain default.

Return type:

DoodleAiCredit

created_at

DateTimeField

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

BigAutoField

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.

Parameters:
  • date – The local date.

  • region (str) – The region.

Returns:

The doodle, or None if none is planned and approved.

Return type:

Doodle | None

updated_at

DateTimeField

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

DateTimeField

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

BigAutoField

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

DateTimeField

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_ATTEMPTS times 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

DateTimeField

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

BigAutoField

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

DateTimeField

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

DateTimeField

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

BigAutoField

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

DateTimeField

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 holidays package, 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].

region(region)[source]

Return the candidates of a region.

Parameters:

region (str) – The region.

Returns:

Its candidates, or None if the request doesn’t have it.

Return type:

DoodleEditorRegion | None

smarter.apps.doodle.editor.check_decision(decision, request)[source]

Check a decision against the request and the guardrails.

Parameters:
  • decision (DoodleEditorDecision) – A region’s decision.

  • request (DoodleEditorRequest) – The request it answers.

Returns:

Why the decision is refused, or None if it is fine.

Return type:

str | None

smarter.apps.doodle.editor.edit_day(day)[source]

Ask the editor to choose the doodles of a day, and apply its choices.

Parameters:

day (date) – The day, which the calendar has planned.

Returns:

The run, or None if the editor doesn’t exist on this platform.

Return type:

DoodleEditorRun | None

smarter.apps.doodle.editor.edit_days(days)[source]

Ask the editor about each day that needs it, while the enable_doodle_llm_editor switch is on.

Parameters:

days (list[date]) – The planned days.

Returns:

The number of days that the editor was asked about.

Return type:

int

smarter.apps.doodle.editor.editor_request(day, regions, artwork_allowed, with_trends=False)[source]

Build the editor’s prompt for a day.

Parameters:
  • day (date) – The day.

  • regions (list[str]) – The regions to choose for.

  • artwork_allowed (bool) – Whether the editor may choose a holiday that the artist must draw.

  • with_trends (bool) – Whether to tell the editor what each region is reading about, which the artist must draw too. See smarter.apps.doodle.trends.

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.

Parameters:
  • day (date) – The day.

  • region (str) – The region.

Returns:

At most MAX_OBSERVANCES_PER_REGION holidays, each with the region’s countries that observe it.

Return type:

list[DoodleEditorObservance]

smarter.apps.doodle.editor.parse_answer(text)[source]

Parse the editor’s answer.

Parameters:

text (str | None) – The answer, which should be one JSON object, perhaps in a code fence.

Returns:

The decisions.

Return type:

DoodleEditorAnswer

Raises:

SmarterValueError – If it isn’t a valid 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 wbgetentities request 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 of PERSON_WORDS, e.g. actor or footballer. A doodle never draws a person;

  • its description names an occasion, one of OCCASION_WORDS, e.g. tournament, festival or eclipse: 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.

  1. 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
    
  2. 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
    
  3. 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:
  • project (str) – The edition, e.g. es.wikipedia.org.

  • titles (tuple[str, ...]) – The articles’ titles, with underscores, at most 50.

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:

dict[str, tuple[str, str, str]]

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.

Parameters:

description (str) – e.g. American actor (born 1956).

Returns:

True if it has years of life, or one of PERSON_WORDS.

Return type:

bool

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.

Parameters:

description (str) – e.g. international association football tournament.

Returns:

True if it has one of OCCASION_WORDS, as whole words.

Return type:

bool

smarter.apps.doodle.trends.region_trends(region, day, refuse)[source]

Return the trends of a region that a doodle may celebrate.

Parameters:
  • region (str) – The region.

  • day (date) – The day of the doodle.

  • refuse – A function that says whether a text has a blocked word, e.g. has_blocked_word().

Returns:

At most MAX_TRENDS_PER_REGION trends, most viewed first. Empty if the api fails.

Return type:

list[DoodleTrend]

smarter.apps.doodle.trends.top_articles(project, day)[source]

Return the most viewed articles of a Wikipedia edition on a day.

Parameters:
  • project (str) – The edition, e.g. es.wikipedia.org.

  • day (str) – The day, as an ISO date.

Returns:

Each article’s title and views, most viewed first, at most TOP_ARTICLES_SCANNED, without pages that aren’t articles.

Return type:

list[tuple[str, int]]

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, polygon and style. Anything else, e.g. script, foreignObject, image, a, use, text or an SMIL animate, is removed with its children.

  • attributes: geometry, paint, transform and class. Every on* handler, href, style and id is removed, and a value that contains url(, javascript: or data:.

  • styles: one <style> of css rules and keyframes, without @import, url(, expression or 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.

Parameters:

text (str) – The answer.

Returns:

The text from the first <svg to the last </svg>.

Return type:

str

Raises:

SmarterValueError – If the answer has no SVG.

smarter.apps.doodle.sanitize.sanitize_svg(svg, prefix)[source]

Return a generated SVG, with only what a decorative drawing needs.

Parameters:
  • svg (str) – The SVG that the artist answered with.

  • prefix (str) – The theme’s prefix, two letters, which its css names must start with.

Returns:

The sanitized SVG, ready for compose_svg().

Return type:

str

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 a Prompt session 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 None if the LLM gave none.

Return type:

str | None

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.

Parameters:

text (str | None) – The answer.

Returns:

The object, or None if there is none.

Return type:

dict[str, Any] | None

smarter.apps.llmclient.prompting.new_session(llmclient, url, user_agent)[source]

Create a Prompt session of an LLMClient, owned by the LLMClient’s owner.

Parameters:
  • llmclient (LLMClient) – The LLMClient.

  • url (str) – Where the session comes from, e.g. the api url of an Orchestrator’s run.

  • user_agent (str) – Which feature of the platform opened it, e.g. smarter-orchestrator.

Returns:

The session.

Return type:

Prompt

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:
  • llmclient (LLMClient) – The LLMClient.

  • message (str) – The user message.

  • url (str) – Where the session comes from. See new_session().

  • user_agent (str) – Which feature of the platform prompts. See new_session().

Returns:

The prompt’s result.

Return type:

PromptChatApiPromptResult

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:
  • llmclient (LLMClient) – The LLMClient.

  • token_key (str) – An api key of a user who may prompt it.

  • prompt (str) – The user message.

Returns:

The prompt’s result: the messages that it added, the completion, the tools.

Return type:

PromptChatApiPromptResult

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:
  • session (Prompt) – The session, from new_session().

  • message (str) – The user message.

  • acting (User | None) – The user on whose behalf the platform prompts, whom MCP servers learn of, or None for nobody in particular.

Returns:

The prompt’s result: the messages that it added, the completion, the tools.

Return type:

PromptChatApiPromptResult

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:

Iterator[str]

Cached reads of the doodle app’s rows.

  • doodle_of_the_day(): the doodle of a day in a region, for GET /api/v1/doodles/today/.

  • artwork_svg(): an artwork’s SVG, for GET /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.

Parameters:

sha256 (str) – The artwork’s hash.

Returns:

Its SVG.

Return type:

str

Raises:

NotFound – If there is no such artwork. The failure isn’t cached.

smarter.apps.doodle.caching.artwork_url(sha256)[source]

Return the url of an artwork.

Parameters:

sha256 (str) – The artwork’s hash.

Returns:

Its path, e.g. /api/v1/doodles/artwork/<sha256>.svg.

Return type:

str

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.

Parameters:
  • day (str) – The local date, as an ISO string.

  • region (str) – The region.

Returns:

The doodle of the day.

Return type:

DoodleOfTheDay

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.

get(request, sha256, *args, **kwargs)[source]

Return the artwork.

Parameters:
  • request (Request) – The request.

  • sha256 (str) – The artwork’s hash.

Returns:

The SVG.

Return type:

HttpResponse

Raises:

NotFound – If there is no such artwork.

class smarter.apps.doodle.api.v1.views.DoodleTodayView(**kwargs)[source]

The doodle of the day, for the sign-in page.

GET with the query parameter tz, the browser’s IANA time zone, e.g. Asia/Kolkata. It picks the visitor’s region and local date. Without it, or while the enable_doodle_regional switch 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:
  • doodle (DoodleOfTheDay) – The doodle of the day.

  • animated (bool) – Whether the artwork may be animated.

  • show_caption (bool) – Whether the caption may be shown.

  • show_ai_credit (bool) – Whether the credit of a Smarter AI application may be shown.

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.