Entity label workflow

Tags are no longer part of the workflow. Use:

• entity.id as the stable key
• entities.update(entityId, { label }) for a human-readable name
• your own database fields for stage, status, and segmentation

Hiring pipeline example

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

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

// Round 1: identify candidate and persist entity ID
const first = await mappa.reports.generateFromUrl({
  url: "https://example.com/phone-screen.mp3",
  output: { template: "general_report" },
  target: { strategy: "magic_hint", hint: "the job candidate" },
});

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

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

await db.candidates.create({
  id: "cand_123",
  entityId,
  stage: "phone-screen",
});

// Round 2: use entity_id for deterministic targeting
const second = await mappa.reports.generateFromUrl({
  url: "https://example.com/technical-interview.mp4",
  output: {
    template: "hiring_report",
    templateParams: {
      roleTitle: "Senior Software Engineer",
      roleDescription: "Backend systems",
      companyCulture: "Collaborative",
    },
  },
  target: { strategy: "entity_id", entityId },
});

await db.candidates.update({
  id: "cand_123",
  stage: "technical",
  lastReportId: second.id,
});

Sales workflow example

async function analyzeProspect(prospectId: string, url: string) {
  const prospect = await db.prospects.get(prospectId);

  const target = prospect.entityId
    ? { strategy: "entity_id" as const, entityId: prospect.entityId }
    : {
        strategy: "magic_hint" as const,
        hint: "the potential customer or prospect",
        onMiss: "fallback_dominant" as const,
      };

  const report = await mappa.reports.generateFromUrl({
    url,
    output: { template: "sales_playbook" },
    target,
  });

  if (!prospect.entityId && report.entity?.id) {
    await db.prospects.update(prospectId, { entityId: report.entity.id });
  }

  return report;
}

Query and segmentation (your DB)

// SDK entities.list() does not filter by custom workflow stage fields.
// Keep stage/status in your own tables and query there.

const finalists = await db.candidates.findMany({ stage: "final" });

for (const candidate of finalists) {
  const report = await mappa.reports.generate({
    media: { mediaId: candidate.latestMediaId },
    output: { template: "hiring_report" },
    target: { strategy: "entity_id", entityId: candidate.entityId },
  });

  console.info(candidate.id, report.id);
}