@coywolf/emdash 0.0.0-stage → 0.35.14

package/src/ai/entities.ts

@@ -0,0 +1,59 @@
+/**
+ * Read the grounded entities for an entry, for Schema.org output.
+ *
+ * The Schema module calls `getEntryEntities(ctx, collection, id)` (inside the
+ * plugin context) or `getEntryEntities(db, collection, id)` with the site's
+ * D1 database (outside it, e.g. an Astro component), and merges `about` and
+ * `mentions` into its Article/WebPage node. Returns empty lists when the
+ * "ai.entities" feature is off or nothing has been analyzed yet.
+ */
+import type { PluginContext, StorageCollection } from "emdash";
+
+import { PLUGIN_ID, cachedCtxFeatures, isOn, siteFeatures } from "../core/features.js";
+import { noteReadFailure } from "../core/read-failures.js";
+import { type Entity, entityNodes } from "./logic.js";
+import type { EntryRecord } from "./store.js";
+
+export interface EntryEntities {
+	entities: Entity[];
+	about: Record<string, unknown>[];
+	mentions: Record<string, unknown>[];
+}
+
+const EMPTY: EntryEntities = { entities: [], about: [], mentions: [] };
+
+type Source = Pick<PluginContext, "storage" | "settings"> | D1Database;
+
+function isD1(source: Source): source is D1Database {
+	return typeof (source as D1Database).prepare === "function";
+}
+
+/**
+ * `preloaded.record`: the entry's aiEntries doc, already read by the caller
+ * (Schema & Social reads it with the entry's other docs), so nothing is read
+ * here; the caller has checked the "ai.entities" switch.
+ */
+export async function getEntryEntities(source: Source, collection: string, id: string, preloaded?: { record: EntryRecord | null }): Promise<EntryEntities> {
+	try {
+		let record: EntryRecord | null = null;
+		if (preloaded) {
+			record = preloaded.record ?? null;
+		} else if (isD1(source)) {
+			if (!isOn(await siteFeatures(), "ai.entities")) return EMPTY;
+			const row = await source
+				.prepare("SELECT data FROM _plugin_storage WHERE plugin_id = ? AND collection = ? AND id = ?")
+				.bind(PLUGIN_ID, "aiEntries", `${collection}:${id}`)
+				.first<{ data: string }>();
+			record = row?.data ? (JSON.parse(row.data) as EntryRecord) : null;
+		} else {
+			if (!isOn(await cachedCtxFeatures(source), "ai.entities")) return EMPTY;
+			const entries = (source.storage as Record<string, StorageCollection>).aiEntries as StorageCollection<EntryRecord> | undefined;
+			record = (await entries?.get(`${collection}:${id}`)) ?? null;
+		}
+		const entities = Array.isArray(record?.entities) ? record.entities : [];
+		return { entities, ...entityNodes(entities) };
+	} catch {
+		noteReadFailure("AI entities"); // The page goes out without its entities: not into the edge cache.
+		return EMPTY; // Schema output must never fail because of enrichment.
+	}
+}

package/src/ai/export.ts

@@ -0,0 +1,61 @@
+/**
+ * AI Enrichment CSV export: every analyzed entry with the entities found in
+ * it (one row per entity) and its AI-written description. Pure, so the admin
+ * page and the tests share it.
+ */
+import { type CsvCell, toCsv } from "../core/csv.js";
+
+export interface ExportEntry {
+	collection: string;
+	entryId: string;
+	title: string;
+	status: string;
+	error: string;
+	entities: Array<{ name: string; type: string; description: string; qid: string; wikipedia: string; website: string; primary: boolean }>;
+	description: string;
+	descriptionStatus: string;
+	updated: string;
+}
+
+export const ENTITY_CSV_COLUMNS = [
+	"collection",
+	"entry_id",
+	"entry_title",
+	"analysis",
+	"entity",
+	"entity_type",
+	"role",
+	"wikidata_id",
+	"wikidata_url",
+	"wikipedia",
+	"website",
+	"entity_description",
+	"ai_description",
+	"description_status",
+	"updated",
+] as const;
+
+/** Spreadsheet-safe CSV. An entry with no entities still gets one row, so its description and errors are kept. */
+export function entitiesToCsv(entries: ExportEntry[]): string {
+	const rows: CsvCell[][] = [[...ENTITY_CSV_COLUMNS]];
+	for (const e of entries) {
+		const base = [e.collection, e.entryId, e.title, e.status === "error" ? `error: ${e.error}` : "ok"];
+		const tail = [e.description, e.descriptionStatus, e.updated];
+		if (!e.entities.length) rows.push([...base, "", "", "", "", "", "", "", "", ...tail]);
+		for (const x of e.entities) {
+			rows.push([
+				...base,
+				x.name,
+				x.type,
+				x.primary ? "about" : "mentions",
+				x.qid,
+				x.qid ? `https://www.wikidata.org/wiki/${x.qid}` : "",
+				x.wikipedia,
+				x.website,
+				x.description,
+				...tail,
+			]);
+		}
+	}
+	return toCsv(rows, { guard: true });
+}