Skip to main content

Entity management

Use entities to keep speaker identity stable across recordings.

Core model​

  • entity.id is the persistent voice identity key.
  • entity.label is an optional human-readable name.
  • Your own database should store pipeline state (stage, status, cohort, owner, etc.).

Resolve then reuse entity IDs​

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

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

await db.people.update({ id: "person_123", mappaEntityId: entityId });

const followUp = await mappa.reports.generateFromUrl({
  url: "https://example.com/follow-up.mp3",
  output: { template: "hiring_report" },
  target: { strategy: "entity_id", entityId },
});

Label entities​

await mappa.entities.update("ent_abc123", { label: "candidate:john-doe" });

const entity = await mappa.entities.get("ent_abc123");
console.info(entity.label);

Clear label:

await mappa.entities.update("ent_abc123", { label: null });

Build a local speaker registry​

interface SpeakerRecord {
  id: string;
  mappaEntityId?: string;
  stage: "new" | "screen" | "technical" | "final" | "hired";
}

async function analyzeSpeaker(speaker: SpeakerRecord, mediaId: string) {
  const target = speaker.mappaEntityId
    ? { strategy: "entity_id" as const, entityId: speaker.mappaEntityId }
    : {
        strategy: "magic_hint" as const,
        hint: "the candidate",
        onMiss: "fallback_dominant" as const,
      };

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

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

  if (!speaker.mappaEntityId && report.entity?.id) {
    await db.speakers.update({ id: speaker.id, mappaEntityId: report.entity.id });
  }

  return report;
}

Best practices​

  • Persist entity.id after the first successful report.
  • Prefer entity_id targeting after identity is known.
  • Keep business metadata in your DB, not in SDK entity fields.
  • Use entities.list()/listAll() for audits and reconciliation tasks.