Artifacts & Spreadsheets

Artifacts are versioned outputs created by the assistant during chat (HTML, code, text, and spreadsheets).

Version Continuity

When a create tool is called with a file name that already exists in the same chat, BoxedAI now continues that artifact as a new version (v2, v3, ...), instead of creating a duplicate artifact row.

This applies consistently across:

• generic artifacts (create_artifact)
• visualizations (create_visualization)
• spreadsheets (create_spreadsheet)

Why the Artifact Abstractions Exist

BoxedAI now uses two core abstraction layers for artifacts:

1. Kind Registry

   • Classifies artifacts by kind (text, html, visualization, spreadsheet)
   • Handles kind resolution from file name, MIME type, and visual metadata

2. Content Adapter Registry

   • Applies per-kind content normalization for storage
   • Applies per-kind decoding/summarization when content is read back

These layers allow adding new artifact formats without rewriting core create/edit/read flows.

Spreadsheet Generation (.xlsx)

The model does not produce raw XLSX bytes.

Instead, it calls a spreadsheet capability with structured sheet data:

• workbook name
• sheets
• rows/cells
• optional style/layout rules (styles, merges, column widths, row heights, freeze panes)

The backend then:

1. Builds a real XLSX workbook programmatically
2. Serializes it to base64
3. Stores a structured spreadsheet envelope as artifact content

This avoids brittle “raw binary in prompt” behavior and keeps spreadsheet generation deterministic.

Spreadsheet Envelope

Spreadsheet artifact content uses:

• format: boxedai.spreadsheet.v1
• name: workbook filename
• sheets: normalized sheet data
• xlsx_base64: generated workbook payload

The UI can preview table data and download the generated .xlsx file directly.

Complex Spreadsheet Styling

create_spreadsheet supports advanced formatting through structured metadata per sheet:

• styles: apply style objects to A1 ranges (font, fill, border, alignment, number format, etc.)
• merges: merge ranges like A1:C1
• column_widths: set width for one column or a span
• row_heights: set explicit row heights
• freeze_pane: configure frozen/split panes and selection

This keeps styling deterministic and editable while still avoiding raw binary generation in prompts.

Encryption Behavior

If organization encryption is enabled, artifact content (including spreadsheet envelope) is encrypted using the same artifact encryption flow as other artifacts.

Extending Artifact Types

To add another binary-friendly artifact type in the future:

1. Add a new kind to the kind registry
2. Add a content adapter
3. Add a command/tool that produces a structured envelope and generated payload
4. Add frontend preview/export behavior