Entity tracking recipe

Persist report.entity?.id from the first analysis, then use target.strategy = "entity_id" on future recordings.

First session: resolve entity ID

import { Mappa } from "@mappa-ai/mappa-node";

const mappa = new Mappa({ apiKey: process.env.MAPPA_API_KEY! });

const first = await mappa.reports.generateFromUrl({
  url: "https://example.com/interview-round-1.mp3",
  output: { template: "general_report" },
  target: { strategy: "magic_hint", hint: "the job candidate" },
});

const entityId = first.entity?.id;
if (!entityId) throw new Error("Entity was not resolved");

await db.candidates.update({ id: "cand_123", mappaEntityId: entityId });

Next sessions: target by entity ID

const entityId = await db.candidates.getEntityId("cand_123");

const report = await mappa.reports.generateFromUrl({
  url: "https://example.com/interview-round-2.mp3",
  output: {
    template: "hiring_report",
    templateParams: {
      roleTitle: "Senior Software Engineer",
      roleDescription: "Backend and distributed systems",
      companyCulture: "Collaborative",
    },
  },
  target: { strategy: "entity_id", entityId },
});

console.info(report.id);

Multi-round tracking

async function trackRounds(entityId: string, urls: string[]) {
  const reports = [];

  for (const url of urls) {
    const report = await mappa.reports.generateFromUrl({
      url,
      output: { template: "general_report" },
      target: { strategy: "entity_id", entityId },
    });
    reports.push(report);
  }

  return reports;
}

Fallback strategy

const target = knownEntityId
  ? { strategy: "entity_id" as const, entityId: knownEntityId }
  : {
      strategy: "magic_hint" as const,
      hint: "the candidate",
      onMiss: "fallback_dominant" as const,
    };

const receipt = await mappa.reports.createJob({
  media: { mediaId: "media_123" },
  output: { template: "general_report" },
  target,
});

const report = await (receipt.handle ?? mappa.reports.makeHandle(receipt.jobId)).wait();