Artifacts

An artifact is a thing the assistant made that lives beside the chat instead of inside it: a study guide, a handout, a practice quiz, a deck of flashcards, a slide deck to present, all of them things the person will keep and come back to. It opens in the conversation panel the moment the model starts writing it and fills in as the model writes, keeps every version, can be edited by hand, renamed, restored, printed, exported and reopened from a library, and never gets pasted back into the reply. This doc covers the chassis and its four kinds, document, quiz, flashcards and slides; the follow-ups at the end list what later items add. The agent loop and its tool registry are in agent-retrieval.md; the typed API framework the routes use is in spa-and-api-framework.md.

The models

apps/main_app/models/artifacts.py holds four rows, plus the export row under "Export" below.

Artifact is the identity: a UUID id, the owner (SET_NULL, for the same reason Conversation.user is - chat data outlives the person), the conversation and origin_message it came from, the kind, the live title, and archived_at. ArtifactVersion is one immutable snapshot: number (1-based, unique per artifact), source (assistant, restore or person), restored_from_number, the title at the time, the content JSON, the sources the version drew on, a change_summary, the assistant message that made it, and created_by. ArtifactDraft is the owner's edit in progress, one per artifact (OneToOneField): the title and content being typed, the base_version the edit started from, and a revision counting the saves since; its modified timestamp is what the idle rule reads. ArtifactRender is the drawn pages of one version, one per version (OneToOneField): the status (queued, running, ready, failed), the page_count once there are pages, an error_message when there are not, created_at, the queued_at the deadline counts from, and finished_at.

Versions are append-only and a restore is a new version copied from an older one, so the current version is the highest number and there is no current_version column. A check constraint pins that a restore names its origin and nothing else does; another pins kind and source to their enums.

Reads go through Artifact.objects.owned_by(principal), which takes an EndUser and nothing else, so an anonymous caller is a type error rather than an empty result. ArtifactService (services/artifacts/service.py) is the only writer: create, add_version, restore, rename, archive, link_to_message, and the draft operations under "Drafts" below. Every write to an existing artifact takes a row lock on it (select_for_update through owned()), and every write audits itself (below).

The kind contract

services/artifacts/kinds/ has one module per kind and one dictionary entry each. A kind supplies the Pydantic model that shapes ArtifactVersion.content, a to_html renderer, and a prompt projection; CONTENT_MODELS maps ArtifactKind to the model. Every model carries kind as a required literal, and ArtifactContent is the discriminated union over the five, so the tool schema, the OpenAPI document and the generated TypeScript all narrow on kind. The stored JSON keeps no kind: dump_artifact_content is the one writer and leaves it out, and parse_artifact_content(kind, raw) injects the row's kind column, so the column stays the one stored home of the fact, a payload whose own kind differs from the row's is refused by name, and no row is rewritten when a kind is added. ArtifactContentInvalid names the fields that failed and never the value: a body is too large and too personal to echo into a log. Every model mixes in HiddenTextRepr so its repr never carries text, which is one of the three measures that keep an artifact out of a Sentry event (test_artifact_sentry.py; the others are the repr=False fields on the loop's tool-call dataclasses and the DraftSaveRequest repr).

document (kinds/document.py) is DocumentBody, one body_html string capped at DOCUMENT_BODY_MAX_CHARS. Its validator strips [S#] citation markers and runs the body through services/html_sanitize.py, the Python home of the assistant-HTML allowlist that the SPA's sanitize.ts mirrors; test_artifact_sanitizer.py pins the two allowlists equal. Every HTML field of the other two kinds goes through the same clean_html_field (kinds/_fields.py).

quiz (kinds/quiz.py) is QuizBody: optional instructions HTML and one to fifty questions, each a union on type of multiple_choice (two to eight options, exactly one correct), multiple_select (two to eight options, at least one correct), true_false (answer) and short_answer (answer_text, self-graded when taken). Every question has a stem, points from 1 to 100, and optional explanation, hint and source_ref; to_html(content, answer_key=) is the print form with or without the key marked.

flashcards (kinds/flashcards.py) is FlashcardsBody: one to two hundred cards of front and back HTML, up to ten tags of forty characters, an optional hint and source_ref; fronts must be distinct by their case-folded plain text, so a deck never asks the same thing twice. to_tab_separated(content, title, target=) writes the Anki file (header lines #separator:tab, #html:true, #deck:<title>, #tags column:3, then front, back and space-joined tags per row) or the Quizlet file (plain text, one tab per row, no tags).

slides (kinds/slides.py) is SlidesBody: a theme chosen from six designed palettes (midnight, parchment, laboratory, slate, meadow, ink), and two to forty slides, each a union on layout. A title slide has an eyebrow, title and subtitle and is the first slide and only the first; a section slide is a divider of title and subtitle; a bullets slide has a title, subtitle and one to six bullets; a two_column slide has a left and a right, each a heading and its bullets; a closing slide has a title, subtitle and up to three takeaways. A title or bullets slide may carry one aside, a union on kind of a code card, a callout or a quote. Bullets take the same inline allowlist the other kinds take; every other field is plain text, and every slide carries plain-text speaker notes. The model picks the theme and the layouts; it never picks a colour or a font.

to_html is the handout the Word, HTML and Google Doc exports carry, one section per slide with its notes under it. The PowerPoint file is a different thing entirely: exports/pptx.py draws every slide itself on a blank layout, and the deck's PDF is Impress's conversion of that file rather than of the handout, so the PDF is the slides and carries no notes. The panel reads the deck as the drawn pages of that same file, which is "The drawn pages" below.

A question's or a card's source_ref is one source key, file:<id> or web:<url>, the form citations.source_key produces; the model writes a turn's [S#] ref there and the tool rewrites it to the key before the save, and a [S#] ref in stored content is a validation error. artifact_prompt_text is what the model reads back as the active artifact: a document's HTML, or every other kind's compact JSON with kind included, because update_artifact takes the whole content back and a projection would hide the answers, hints, points, types, refs, speaker notes the model would otherwise have to reinvent.

The caps per kind are module constants (QUIZ_MAX_QUESTIONS, STEM_MAX_CHARS, FLASHCARDS_MAX_CARDS, FLASHCARD_SIDE_MAX_CHARS, SLIDES_MAX and the rest), and the SPA's form editors carry the same numbers so a person is told before the server would refuse. Adding a kind is a new module with its kind literal, a member on ArtifactKind and the union, one entry in CONTENT_MODELS, a case in artifact_to_html and artifact_prompt_text, a delta shape in events.py and its counting arm in artifact_stream.py, and a migration that widens the kind check constraint, since the enum is pinned in the database as well as in the code. It is also a line in the prompt's kind rule, the same line at the end of both tool descriptions, the list of kinds on load_artifact_tools, and the catalog blurb in artifact_context.py, or the model has the kind and no idea when to reach for it. On the SPA it is a case in ArtifactBody and ArtifactEditor, an entry in KIND_LABELS, KIND_TRAITS, KIND_ICONS and EMPTY_BY_KIND, and a fixture in test/artifactFixtures.ts; assertNever and the Record<ArtifactKind, ...> types turn every one of those into a compile error until it is written.

The tools and the loop

services/agent/tools/artifacts.py holds create_artifact(title, content, source_refs?, change_summary?) and update_artifact(artifact_id, content, change_summary, title?, source_refs?), and neither of them is in the registry. A change_summary describes what the artifact covers or what changed and never counts its questions, cards or slides, because the counter on the artifact is the one source of that number, and both field descriptions tell the model so. Each one carries the whole four-kind content union in its argument schema, which is what the token table below counts, and both would ride on every model call of every turn if they were registered. What the registry holds behind the cc_artifacts switch is load_artifact_tools (services/agent/tools/load_artifact_tools_tool.py), a bootstrap tool with no arguments, the same progressive disclosure the connector actions use (connectors-philosophy.md section 9).

load_artifact_tools sets AgentState.artifact_tools_loaded and returns one line: the two tools are available in the next response, and their descriptions say how to write one. How to write an artifact is not in that result, because the two tool descriptions and the field descriptions on their schemas already hold every one of those rules, and the model reads them the moment it has the tools. rebuild_tools_with_loaded_extensions (services/agent/tool_wiring.py) runs at the start of every iteration and, when the flag is set, appends both tools built with the principal, state.conversation_id and the run state, so the model can call either of them from its next response to the end of the turn. That append sits above the early return the rebuild takes when no connector is loaded, which is what most turns do. The rebuild is also the only place a bound artifact tool comes from: conversation_id and run_state are required keyword arguments of _ArtifactToolBase, so a tool that would save into no conversation and resolve no source_refs is a type error rather than a quiet half-write.

A call to create_artifact or update_artifact before the loader has run is a call to a tool the iteration does not carry, and three things answer it. not_found_error (services/agent/tool_execution.py) tells the model that create_artifact is not loaded, that load_artifact_tools comes first and that it can call create_artifact in its next response, so it has a route back. It says that only when the loader is one of the iteration's own tools: a turn without the cc_artifacts flag carries neither the pair nor the loader, so an artifact name there keeps the plain Tool '<name>' not found every other missing name gets, rather than being sent after a tool that is not there either. absent_tool_display_args beside it is what the span and the ToolCallEvent show for that call, {"argument_names": [...]} and none of the values, because a tool that is not there vets nothing and an artifact body must never reach a span or Sentry's frame locals. The loop's panel branch reads ctx.state.artifact_tools_loaded as well, so such a call opens no panel and the person sees the narration alone rather than a card that fails.

create_default_registry(principal, artifacts=True) adds load_artifact_tools and nothing else; the flag is a capability switch the chat service derives from cc_artifacts, not part of the identity. The guest registry never has it. The registry's exact-set test in tests/test_agent_core.py pins both the plain set and that one-tool difference.

Both artifact tools are identity-bound (they hold the principal) and run the ArtifactService write under sync_to_async. The kind is the content.kind literal, not a separate argument, and each description ends with the one-line kind rule (questions to practise are a quiz, things to memorise are flashcards, a talk to give is slides, everything to keep and reread is a document); update_artifact refuses a content whose kind differs from the row's, naming both. source_refs carries the turn's [S#] refs; the tool resolves them, together with every question's and card's source_ref, against the run's citation registry into Source rows stored on the version, rewrites the per-item refs to their source keys, and reports any ref it could not resolve in the result text. A successful call returns ArtifactSaved under ToolResult.metadata["artifact"], which is how the loop learns an artifact was made without reading the body.

Three things in the loop (services/agent/agent_core.py) are artifact-specific. On the first ToolCallDelta of an artifact tool call, and only once the turn has loaded the tools, the loop emits ArtifactStartEvent (tool call id, step, tool name) once per call, before the arguments have finished streaming, so the panel opens on a skeleton seconds before the row exists. While the arguments stream, the loop appends each fragment to ArtifactArgumentBuffers (services/agent/artifact_stream.py) and emits ArtifactDeltaEvent whenever the partial parse has something new: the title once it has closed, then a DocumentDelta of the body characters that arrived, a QuizDelta counting the questions whose stem has closed, a FlashcardsDelta counting the cards whose front has, or a SlidesDelta counting the slides whose title has. Each counted field closes before the rest of its item, so a count names the item the model is writing rather than the last one finished. A revision's deltas carry the artifact's current title until the model streams one of its own, read from the title map build_artifact_context built for the turn, because update_artifact streams title after the body and may omit it altogether. The reader parses with jiter in partial mode, so a fragment that leaves a string open still yields the text inside it; a buffer that does not parse yields nothing rather than an error, and the buffer is dropped when the call completes. When the call's arguments complete, the loop emits ArtifactSavingEvent (tool call id, step) for every call it announced, so the panel can say the writing is over while the tool validates the content and writes the version. When the tool result carries metadata["artifact"] the loop emits ArtifactEndEvent (tool call id, artifact id, kind, title, version, change summary). A failed call emits no end event; the client closes the skeleton on the failed tool_result. None of the four - start, delta, saving, end - is persisted: the saved version is the record.

The body never reaches a span, a log, or the ToolCallEvent: the tools' display_args replaces content with content_chars, the llm_output span event carries the same view of each pending call, and the executor stamps campuscore.artifact.id, .kind and .version on the tool span after the save (services/observability/attributes.py). narrate in services/agent/tool_narration.py labels the trace rows: the loader reads "Getting ready to write" and then "Ready to write", and an artifact call reads "Drafting "