AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
"""HTTP surface for the Executive Artifacts section.
A unified view over the two places the Executive stores deliverables — no
new table, the underlying rows stay canonical:
1. `draft_artifact` output, written to the alerts table
(`source='artifact'`) in any registered format (Markdown, HTML, Word,
Excel, or a link into a connected app — `orchestrator/artifact_formats.py`),
2. completed workflow runs, whose Markdown lives in
`workflow_runs.artifact`.
Both sources are merged, sorted newest-first, and addressed by a composite
id `"{kind}:{native_id}"` (`alert:<int>` / `run:<hex>`). Lookup, archive and
delete go through `orchestrator/artifact_records.py`, which the Executive's
`list_artifacts` / `get_artifact` tools share.
Archive is a reversible soft-hide (a nullable `archived_at` column on each
backing table); delete is a permanent hard-delete of the underlying row.
The default list shows only active artifacts; `?archived=true` shows only
archived ones. Every route refuses non-artifact alert ids — these routes
must not become general alert/run readers or mutators.
Every route answers for the signed-in caller (`chat._resolve_caller_person_id`)
and sees only what they may (`artifact_records` module docstring): their own
drafts and runs, and the team's scheduled ones. Anyone else's answers 404, as
a missing one does.
Downloads are always served as attachments with `nosniff` and a sandbox CSP,
so an HTML artifact never renders on the app's origin (the UI shows it in a
sandboxed iframe instead).
Endpoints:
- GET /artifacts Unified list (summaries, no bodies)
- GET /artifacts/{composite_id} One artifact with its displayable body
- GET /artifacts/{composite_id}/download The file (optionally ?as=<format>)
- POST /artifacts/{composite_id}/archive Soft-hide (reversible)
- POST /artifacts/{composite_id}/restore Un-archive
- DELETE /artifacts/{composite_id} Permanently delete the underlying row
"""
from __future__ import annotations
import logging
from collections.abc import Callable
from typing import Annotated, Literal
from fastapi import APIRouter, HTTPException, Query, Request, Response
from pydantic import BaseModel
from openexecutive.orchestrator.artifact_formats import get_format
from openexecutive.orchestrator.artifact_records import (
ArtifactNotFound,
ArtifactRecord,
MalformedArtifactId,
Viewer,
artifact_downloads,
load_artifact,
render_artifact_file,
viewer_for_person,
)
from openexecutive.orchestrator.artifact_records import (
delete_artifact as delete_artifact_record,
)
from openexecutive.orchestrator.artifact_records import (
list_artifacts as list_artifact_records,
)
from openexecutive.orchestrator.artifact_records import (
set_archived as set_artifact_archived,
)
from openexecutive.orchestrator.extensions import Change, get_collection
from openexecutive.orchestrator.extensions import notify as notify_collection
router = APIRouter()
logger = logging.getLogger(__name__)
# Max artifacts returned by the list endpoint (mirrors alerts.list_alerts' cap).
_DEFAULT_LIMIT = 200
# Chars of body shown as a card preview. Unrelated to _DEFAULT_LIMIT despite
# the shared value — keep them as separate named knobs.
_PREVIEW_CHARS = 200
class ArtifactSummary(BaseModel):
id: str
kind: Literal["draft", "workflow"]
title: str
source_label: str
created_at: str
preview: str | None = None
status: str
severity: str | None = None
# ISO timestamp when archived; None = active. Lets the detail page show
# Archive vs Restore correctly and keeps the TS interface honest.
archived_at: str | None = None
# Registered format name (artifact_formats.ARTIFACT_FORMAT_NAMES).
format: str = "markdown"
format_label: str = "Document"
# Download targets, first = the artifact's own file. Empty for links.
downloads: list[str] = []
external_url: str | None = None
link_label: str | None = None
supersedes_id: str | None = None
# An installed extension's kind of document (orchestrator/extensions.py):
# the Documents page gives each its own filter.
collection: str | None = None
collection_label: str | None = None
class ArtifactDetail(ArtifactSummary):
# What the page renders: raw (sanitized) HTML for 'html', Markdown for
# every other format (a spreadsheet arrives as Markdown tables).
body: str
rationale: str | None = None
@router.get("/artifacts")
async def list_artifacts(
request: Request, limit: int = _DEFAULT_LIMIT, archived: bool = False
) -> dict[str, list[ArtifactSummary]]:
"""Unified, newest-first list of the artifacts the caller may see.
Defaults to active artifacts; `?archived=true` returns only archived ones
(the gallery's Active / Archived views are clean swaps, not supersets).
"""
records = list_artifact_records(limit, viewer=_viewer(request), archived=archived)
return {"artifacts": [_summary(r) for r in records]}
@router.get("/artifacts/{composite_id}")
async def get_artifact(composite_id: str, request: Request) -> ArtifactDetail:
"""One artifact with its displayable body, addressed by composite id."""
rec = _load(composite_id, request)
stored = rec.stored or ""
body = stored if rec.format == "html" else get_format(rec.format).display(stored)
return ArtifactDetail(**_summary(rec).model_dump(), body=body, rationale=rec.rationale)
@router.get("/artifacts/{composite_id}/download")
async def download_artifact(
composite_id: str,
request: Request,
as_: Annotated[str | None, Query(alias="as")] = None,
) -> Response:
"""The artifact as a file. `?as=docx` exports a Markdown artifact to Word."""
rec = _load(composite_id, request)
try:
file = render_artifact_file(rec, as_)
except ArtifactNotFound as exc:
raise HTTPException(status_code=404, detail=str(exc)) from exc
except Exception as exc:
logger.exception(
"artifact download render failed for %s as %s", composite_id, as_ or rec.format
)
raise HTTPException(status_code=500, detail="Could not render the file") from exc
return Response(
content=file.content,
media_type=file.mime,
headers={
"Content-Disposition": f'attachment; filename="{file.filename}"',
"X-Content-Type-Options": "nosniff",
"Content-Security-Policy": "sandbox",
"Cache-Control": "no-store",
},
)
@router.post("/artifacts/{composite_id}/archive")
async def archive_artifact(composite_id: str, request: Request) -> dict[str, str]:
"""Soft-hide an artifact (reversible). Drops it from the default list and
from the Executive's recall (knowledge index)."""
viewer = _viewer(request)
await _notify_collection(composite_id, request, "archived")
rec = _mutate(lambda: set_artifact_archived(composite_id, archived=True, viewer=viewer))
from openexecutive.orchestrator.artifact_tools import unindex_artifact
await unindex_artifact(rec.id)
return {"status": "archived", "id": composite_id}
@router.post("/artifacts/{composite_id}/restore")
async def restore_artifact(composite_id: str, request: Request) -> dict[str, str]:
"""Un-archive an artifact, returning it to the active list and, for a
drafted artifact, to the knowledge index."""
viewer = _viewer(request)
await _notify_collection(composite_id, request, "restored")
rec = _mutate(lambda: set_artifact_archived(composite_id, archived=False, viewer=viewer))
if rec.kind == "draft" and rec.stored:
from openexecutive.orchestrator.artifact_tools import index_artifact
await index_artifact(rec.id, rec.title, rec.format, rec.stored, rec.owner_person_id)
return {"status": "restored", "id": composite_id}
@router.delete("/artifacts/{composite_id}")
async def delete_artifact(composite_id: str, request: Request) -> dict[str, str]:
"""Permanently delete the underlying alert / workflow-run row."""
viewer = _viewer(request)
await _notify_collection(composite_id, request, "deleted")
rec = _mutate(lambda: delete_artifact_record(composite_id, viewer=viewer))
from openexecutive.orchestrator.artifact_tools import unindex_artifact
# The canonical id (`alert:5`, not whatever spelling the path used) is
# what indexing keyed the chunks on.
await unindex_artifact(rec.id)
return {"status": "deleted", "id": composite_id}
# -----------------------------------------------------------------------------
# Helpers
# -----------------------------------------------------------------------------
def _viewer(request: Request) -> Viewer:
"""The caller, as the artifact read model sees them."""
from openexecutive.api.routes.chat import _resolve_caller_person_id
return viewer_for_person(_resolve_caller_person_id(request))
def _load(composite_id: str, request: Request) -> ArtifactRecord:
try:
return load_artifact(composite_id, viewer=_viewer(request))
except MalformedArtifactId as exc:
raise HTTPException(status_code=400, detail=str(exc)) from exc
except ArtifactNotFound as exc:
raise HTTPException(status_code=404, detail=str(exc)) from exc
async def _notify_collection(composite_id: str, request: Request, change: Change) -> None:
"""Tell an extension collection one of its documents is about to change
(orchestrator/extensions.py). If it can't take the change, nothing
changes: a 502 the page shows as a failed action."""
rec = _load(composite_id, request)
if rec.collection is None:
return
# Archiving what is archived, or restoring what is active, changes
# nothing, so the collection isn't told.
if (change == "archived") == (rec.archived_at is not None) and change != "deleted":
return
try:
await notify_collection(rec.collection, rec.id, change)
except Exception as exc:
logger.exception("artifact %s: collection %s refused %s", rec.id, rec.collection, change)
raise HTTPException(
status_code=502, detail="That couldn't be done right now. Try again in a moment."
) from exc
def _mutate(action: Callable[[], ArtifactRecord]) -> ArtifactRecord:
try:
return action()
except MalformedArtifactId as exc:
raise HTTPException(status_code=400, detail=str(exc)) from exc
except ArtifactNotFound as exc:
raise HTTPException(status_code=404, detail=str(exc)) from exc
def _summary(rec: ArtifactRecord) -> ArtifactSummary:
fmt = get_format(rec.format)
collection = get_collection(rec.collection)
preview = fmt.text(rec.stored)[:_PREVIEW_CHARS] if rec.stored else ""
return ArtifactSummary(
id=rec.id,
kind=rec.kind,
title=rec.title,
source_label=rec.source_label,
created_at=rec.created_at,
preview=preview or None,
status=rec.status,
severity=rec.severity,
archived_at=rec.archived_at,
format=fmt.name,
format_label=rec.link_label if fmt.name == "link" and rec.link_label else fmt.label,
downloads=artifact_downloads(rec),
external_url=rec.url,
link_label=rec.link_label,
supersedes_id=rec.supersedes_id,
collection=rec.collection,
collection_label=collection.label if collection is not None else None,
)