[Artifacts] Implement resolve_embeds() engine — replace {{artifact:ID}} markers with rendered HTML previews done coding:8 reasoning:7

Goal

Implement a resolve_embeds() function that replaces {{artifact:ID}} markers in analysis reports and hypothesis descriptions with rich, interactive HTML previews of artifacts (notebooks, 3D protein structures, pathway diagrams, etc.).

Context

Quest 17 (Rich Artifacts) is highest priority. Analyses and hypotheses can reference artifacts (Jupyter notebooks, protein structures, pathway diagrams), but currently these are just links. We need inline rendered previews for better user experience.

Current State

• Artifacts exist in artifacts table with types: notebook, protein_structure, pathway_diagram, etc.
• Analysis reports and hypothesis descriptions contain markdown text
• No inline preview system exists in post_process.py
• api.py already has a sophisticated _resolve_embeds / _render_artifact_embed_html for API endpoints, but post_process.py (which generates HTML reports via generate_report()) has no such function

Implementation

1. Create resolve_embeds() function

Location: post_process.py (before the Quality Gates section)

_EMBED_PATTERN = re.compile(r'\{\{artifact:([a-zA-Z0-9_-]+)\}\}')

def _render_artifact_embed_html(artifact_id: str, db) -> str:
    """Render HTML for one artifact embed marker."""
    # Queries artifacts table, returns typed HTML for each artifact type
    ...

def resolve_embeds(text: str) -> str:
    """Replace all {{artifact:ID}} markers with rendered HTML previews."""
    if not text:
        return text
    db = get_db()
    try:
        def replace_embed(match):
            artifact_id = match.group(1).strip()
            return _render_artifact_embed_html(artifact_id, db)
        result = _EMBED_PATTERN.sub(replace_embed, text)
    finally:
        db.close()
    return result

2. Supported Artifact Types

• hypothesis: Rich hypothesis card with score badge and link
• figure: SVG inline or image with caption
• protein_design: Protein design card with mutations, stability, binding affinity
• model: Model card with framework, parameters, metrics
• tabular_dataset / dataset: Data table preview (first 10 rows) or source card
• notebook: Notebook card with link to full view
• generic fallback: Generic artifact card for unknown types

3. Integration in generate_report()

In the hypothesis description handling within generate_report():

desc_full = html_unescape.unescape(h[3])
# Resolve artifact embeds if description contains markers; otherwise truncate
if "{{artifact:" in desc_full:
    desc_html = resolve_embeds(desc_full)
else:
    desc_html = desc_full[:200] + ("..." if len(desc_full) > 200 else "")

This preserves existing behavior (200-char truncation) for descriptions without artifact markers, and renders full descriptions with embedded artifacts when markers are present.

Acceptance Criteria

Dependencies

• Artifacts table exists with artifact IDs and types
• get_db_write() from database module available in post_process.py

Dependents

• Quest 16 (Demo Showcase) — needs rich artifacts for impressive demos
• Other artifact-related tasks in Quest 17

Work Log

2026-04-03 - Original attempt (orphan commit fe6e3e7f0)

• Implemented resolve_embeds() in post_process.py
• Integrated into generate_report()
• Commit was never merged to main (ORPHAN_BRANCH)

2026-04-13 - Current implementation

Changes:

Verification:

• python3 -m py_compile post_process.py — ✅ passes

• Add /artifacts/{id}/preview endpoint to api.py for notebook rendering
• Test with real artifact markers in production data