@person.run/sdk

TypeScript SDK for the person.run API.

Install

npm install @person.run/sdk

Quickstart

import { PersonClient } from "@person.run/sdk";

const client = new PersonClient({
  apiKey: process.env.PERSON_API_KEY!,
  defaultTenantId: "your-tenant-id",
});

// Create a persona
const { persona } = await client.createPersona({
  seed: {
    firstName: "Aria",
    lastName: "Chen",
    age: 32,
    location: "San Francisco",
    baseOccupation: "Product designer",
  },
});

// Create a factual draft persona from Wikipedia
const wiki = await client.createWikipediaPersona({
  wikipediaUrl: "https://en.wikipedia.org/wiki/Ada_Lovelace",
  idempotencyKey: "wiki-import-ada-lovelace",
});

// Or enqueue async and poll
const wikiJob = await client.createWikipediaPersona({
  wikipediaUrl: "https://en.wikipedia.org/wiki/Alan_Turing",
  mode: "async",
  responseUrl: "https://example.com/persona-callback",
});
const wikiJobStatus = await client.getWikipediaPersonaCreateJob(wikiJob.jobId);

// Prompt the persona
const reply = await client.prompt({
  personaId: wiki.persona.id,
  userPrompt: "How do you approach design challenges?",
});

console.log(reply.response);

// Stream a response
for await (const event of client.promptStream({
  personaId: persona.id,
  userPrompt: "Tell me about your career journey.",
})) {
  if (event.event === "delta") {
    process.stdout.write((event.data as { delta: string }).delta);
  }
}

Features

• Auto-generated types from OpenAPI spec — always in sync with the API
• Built-in retries with exponential backoff on 429/5xx
• SSE streaming support
• defaultTenantId to avoid passing tenant on every call
• Full coverage: personas, prompting, timeline, safety policy, populations, and studies

License

MIT