"""
Models of the doodle app.
- :class:`DoodleArtwork` is an SVG, stored once and named by its hash, so that its url never
changes and a browser may cache it forever.
- :class:`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.
- :class:`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.
"""
from typing import Optional
from django.db import models
from smarter.lib.django.models import TimestampedModel
from .artwork import svg_sha256
from .const import DEFAULT_THEME_SLUG, DoodleAiCredit
from .regions import DoodleRegion
from .schedule import DoodleSchedule
[docs]
class DoodleArtwork(TimestampedModel):
"""An SVG of a doodle, named by its content's SHA-256."""
sha256 = models.CharField(max_length=64, unique=True, help_text="The SHA-256 of the SVG, in hex.")
svg = models.TextField(help_text="The SVG.")
# pylint: disable=C0115
class Meta:
verbose_name = "Doodle Artwork"
verbose_name_plural = "Doodle Artworks"
def __str__(self) -> str:
sha256 = str(self.sha256)
return sha256[:12]
[docs]
@classmethod
def for_svg(cls, svg: str) -> "DoodleArtwork":
"""
Return the artwork of an SVG, stored once.
:param svg: The SVG.
:returns: The artwork, existing or new.
:rtype: DoodleArtwork
"""
sha256 = svg_sha256(svg)
artwork, _ = cls.objects.get_or_create(sha256=sha256, defaults={"svg": svg})
return artwork
[docs]
class DoodleCategory(models.TextChoices):
"""What a theme celebrates.
The planner's guardrails accept only these categories.
"""
EVERGREEN = "evergreen", "Evergreen"
CELEBRATION = "celebration", "Celebration"
NATIONAL = "national", "National day"
OBSERVANCE = "observance", "Day of recognition"
SCIENCE = "science", "Science and computing"
CULTURE = "culture", "Culture"
SEASON = "season", "Season"
SPORT = "sport", "Sport"
[docs]
class DoodleTheme(TimestampedModel):
"""A theme of the catalog.
See ``data/themes/README.md``.
"""
slug = models.SlugField(max_length=64, unique=True, help_text="The theme's name, and its file's.")
name = models.CharField(max_length=128, help_text="What the theme celebrates, e.g. Diwali.")
category = models.CharField(max_length=32, choices=DoodleCategory.choices)
caption = models.CharField(max_length=128, blank=True, default="", help_text="e.g. Happy Diwali!")
alt_text = models.CharField(max_length=255, help_text="The artwork's description, for screen readers.")
link_url = models.URLField(blank=True, default="", help_text="Where the caption links to.")
priority = models.PositiveSmallIntegerField(
default=50, help_text="When several themes are due, the one of the highest priority wins."
)
regions = models.JSONField(default=list, help_text='The regions that see it, or ["*"] for all of them.')
schedule = models.JSONField(default=dict, help_text="When it is due. See DoodleSchedule.")
props_svg = models.TextField(blank=True, default="", help_text="The props, drawn on the base scene.")
artwork = models.ForeignKey(
DoodleArtwork, on_delete=models.PROTECT, related_name="themes", help_text="The props on the base scene."
)
is_active = models.BooleanField(default=True, help_text="Whether the planner may choose it.")
is_generated = models.BooleanField(
default=False,
help_text="Whether the Smarter Doodle Artist drew it, for one day, rather than the catalog's file.",
)
# pylint: disable=C0115
class Meta:
verbose_name = "Doodle Theme"
verbose_name_plural = "Doodle Themes"
ordering = ["slug"]
def __str__(self) -> str:
return str(self.slug)
@property
def doodle_schedule(self) -> DoodleSchedule:
"""
The theme's schedule.
:returns: The schedule, validated.
:rtype: DoodleSchedule
"""
return DoodleSchedule.model_validate(self.schedule)
[docs]
class DoodleStatus(models.TextChoices):
"""Whether a planned doodle may be shown."""
APPROVED = "approved", "Approved"
PROPOSED = "proposed", "Proposed, awaiting approval"
REJECTED = "rejected", "Rejected"
[docs]
class DoodleSource(models.TextChoices):
"""Who chose a planned doodle."""
CALENDAR = "calendar", "The calendar"
DEFAULT = "default", "The default, nothing was due"
HUMAN = "human", "A person, in the admin"
LLM = "llm", "The Smarter Doodle Editor, an LLMClient"
[docs]
class Doodle(TimestampedModel):
"""The doodle of one day in one region."""
date = models.DateField(help_text="The local date on which it is shown.")
region = models.CharField(max_length=32, choices=DoodleRegion.choices)
theme = models.ForeignKey(DoodleTheme, on_delete=models.CASCADE, related_name="doodles")
artwork = models.ForeignKey(DoodleArtwork, on_delete=models.PROTECT, related_name="doodles")
status = models.CharField(max_length=16, choices=DoodleStatus.choices, default=DoodleStatus.APPROVED)
source = models.CharField(max_length=16, choices=DoodleSource.choices, default=DoodleSource.CALENDAR)
title = models.CharField(max_length=128, help_text="What it celebrates, e.g. Diwali.")
caption = models.CharField(max_length=128, blank=True, default="")
alt_text = models.CharField(max_length=255)
link_url = models.URLField(blank=True, default="")
reason = models.TextField(blank=True, default="", help_text="Why it was chosen.")
# pylint: disable=C0115
class Meta:
verbose_name = "Doodle"
verbose_name_plural = "Doodles"
ordering = ["-date", "region"]
constraints = [models.UniqueConstraint(fields=["date", "region"], name="doodle_unique_date_region")]
def __str__(self) -> str:
return f"{self.date} {self.region} {self.theme}"
@property
def ai_credit(self) -> DoodleAiCredit:
"""
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.
:rtype: DoodleAiCredit
"""
if self.source != DoodleSource.LLM:
return ""
theme = self.theme
if theme.is_generated:
return "drawn"
if theme.slug == DEFAULT_THEME_SLUG:
return ""
return "chosen"
[docs]
@classmethod
def shown(cls, date, region: str) -> Optional["Doodle"]:
"""
Return the approved doodle of a day in a region.
:param date: The local date.
:param region: The region.
:returns: The doodle, or ``None`` if none is planned and approved.
:rtype: Optional[Doodle]
"""
doodles = cls.objects.filter(date=date, region=region, status=DoodleStatus.APPROVED)
doodles = doodles.select_related("theme", "artwork")
# the doodle of the day names its artwork by hash: the SVG text is served on its own.
doodles = doodles.defer("theme__props_svg", "artwork__svg")
doodle = doodles.first()
return doodle
[docs]
class DoodleEditorRunStatus(models.TextChoices):
"""How a run of the Smarter Doodle Editor ended."""
SUCCEEDED = "succeeded", "Succeeded"
FAILED = "failed", "Failed"
[docs]
class DoodleEditorRun(TimestampedModel):
"""
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
:data:`~smarter.apps.doodle.const.EDITOR_MAX_ATTEMPTS` times is left to the calendar.
"""
date = models.DateField(help_text="The day that the editor chose the doodles of.")
status = models.CharField(max_length=16, choices=DoodleEditorRunStatus.choices)
request = models.JSONField(default=dict, help_text="The prompt: the day's candidates, in each region.")
response = models.TextField(blank=True, default="", help_text="The editor's answer.")
error = models.TextField(blank=True, default="", help_text="Why the run failed.")
with_trends = models.BooleanField(
default=False, help_text="Whether the editor was told what each region is reading about."
)
# pylint: disable=C0115
class Meta:
verbose_name = "Doodle Editor Run"
verbose_name_plural = "Doodle Editor Runs"
ordering = ["-created_at"]
indexes = [models.Index(fields=["date", "status"])]
def __str__(self) -> str:
return f"{self.date} {self.status}"
__all__ = [
"Doodle",
"DoodleEditorRun",
"DoodleEditorRunStatus",
"DoodleArtwork",
"DoodleCategory",
"DoodleSource",
"DoodleStatus",
"DoodleTheme",
]