Snapshot import — bootstrap a character from real data

Why this exists

Manual or auto character creation gives you a blank-slate persona. Snapshot import gives you a persona grounded in real material — chat history, written prose, mailbox archives. Three things drop in pre-filled:

• Big Five — calibrated from communication patterns, not a default 0.5.
• Seed memories — concrete facts (occupation, hobbies, family, current concerns) ready in the bot's memory store.
• Relationship state (optional) — the bot already feels like a friend / family member / partner instead of a stranger.

When to use it

• Memorial / digital twin — recreate someone close from preserved messages and writing.
• Companion bootstrap — give a character a deeper baseline than a one-line hint.
• Onboarding from existing data — clients with chat archives, support transcripts, journaling.

If you just need a fresh fictional character, use manual or auto creation. Snapshot import shines when there's real source material the bot should already know.

How it works

Three data sources

Quick start (curl, plain text)

curl -X POST https://api.vilow.dev/v1/users/u_alex/characters/from_snapshot \
  -H "X-API-Key: $VILOW_API_KEY" \
  -F "subject_name=Marek Sokol" \
  -F "data_source=plain_text" \
  -F "subject_description=Marek is a 41-year-old Czech architect..."

Response (202 Accepted):

{
  "snapshot_job_id": "snap_9ad6eb14a6f04a9c...",
  "status": "pending",
  "estimated_seconds": 60
}

Poll until completion:

curl https://api.vilow.dev/v1/snapshot_jobs/snap_9ad6eb14a6f04a9c... \
  -H "X-API-Key: $VILOW_API_KEY"

# {"snapshot_job_id":"snap_…","status":"completed",
#  "character_id": 42,"extraction_confidence": 0.9,"warnings": [],
#  "error": null,"created_at":"…","completed_at":"…"}

Then chat as usual:

curl -X POST https://api.vilow.dev/v1/chat/u_alex/42/send \
  -H "X-API-Key: $VILOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Hey, how is the Cascais project going?"}'

Quick start (Slack export)

curl -X POST https://api.vilow.dev/v1/users/u_alex/characters/from_snapshot \
  -H "X-API-Key: $VILOW_API_KEY" \
  -F "subject_name=Lena" \
  -F "data_source=slack_export" \
  -F "target_identifier=U02ABCD" \
  -F "file=@workspace_export.zip"

Larger uploads take longer to extract, but the API call still returns 202 immediately and you poll the job for completion.

Quick start (Gmail mbox)

curl -X POST https://api.vilow.dev/v1/users/u_alex/characters/from_snapshot \
  -H "X-API-Key: $VILOW_API_KEY" \
  -F "subject_name=Sofia" \
  -F "data_source=gmail_mbox" \
  -F "target_identifier=sofia@example.com" \
  -F "file=@Mail.mbox"

Mbox files from Google Takeout often run several gigabytes. We process them in-place — no need to pre-filter on your side. Only messages with From: sofia@example.com are kept and analysed.

What lands on the character

After completion, the character row has these fields populated from the mapping:

The job result also returns:

• extraction_confidence — 0..1, how well the source grounded the output. ≥ 0.7 on rich material.
• warnings — list of specific gaps in the source (e.g. "no info on family situation"). Empty when the source covered everything.

Signal floor

The job rejects with 422 if the input is too thin to ground a character: fewer than 30 messages and no documents and a description shorter than 200 characters. Drop more signal in or use a richer source.

Endpoint reference

POST /v1/users/{external_id}/characters/from_snapshot

Multipart/form-data. Accepts an upload up to 200 MB, text up to 500 KB.

Returns 202 Accepted:

{ "snapshot_job_id": "snap_…", "status": "pending", "estimated_seconds": 60 }

GET /v1/snapshot_jobs/{snapshot_job_id}

Poll for status. Returns:

{
  "snapshot_job_id":"snap_…",
  "status":"pending|running|completed|failed",
  "character_id": 42,
  "extraction_confidence": 0.9,
  "warnings": [],
  "error": null,
  "created_at": "...",
  "completed_at": "..."
}

Status codes

Quotas and pricing

Snapshot imports are counted independently from chat messages — they consume a separate counter on the tenant.

Overage charges go through Stripe directly — no top-up required. We charge the same payment method that pays your subscription, off-session, before the pipeline runs. If the card is declined the API returns 402 and no character is created.

A failed job is not counted against quota — the counter is refunded automatically. If the failed job was an overage charge, the €7 is refunded to the same card via stripe.Refund.create immediately. The SnapshotJob row keeps the stripe_payment_intent_id and refunded_at for traceability.

Privacy and retention

• Uploaded files are read into memory, processed, and discarded. Only the SHA-256 hash is recorded for traceability.
• Pipeline intermediate dumps (extracted bundle, analysis markdown, mapper output) are kept for 90 days in an admin-only off-web directory, then auto-deleted.
• DELETE /v1/users/{external_id}/characters/{character_id} cascades to all Memory rows and conversations. The on-disk pipeline dump is also removed.
• Snapshot imports that produce a character generate seed memories with source = "snapshot_import" — distinguishable from chat-extracted memories if you ever need to inspect or filter.

Best practices

• Plain text imports: use text_content for anything over a paragraph — the 8000-character cap on subject_description is for short summaries. text_content takes 500 KB.
• Curl gotcha: when piping multi-line text, use -F "text_content=<path/to/file.txt" to read from disk. Shell variable substitution can truncate at the first paragraph break.
• Chat-export sources: add a subject_description alongside the file. The importer's prose tells the analyzer how the subject fits into your life — useful when the chat alone is professional and reveals little personality.
• Confidence below 0.5: the job still completes — but expect the persona to feel generic. Either feed richer source material or accept it as a starting point and edit through the dashboard.
• Don't import the same person twice expecting different output — the mapper is mostly deterministic at low temperature. Fix the source instead.

What's not in scope (yet)

• WhatsApp / Telegram / Discord / Signal exports.
• Direct OAuth into Slack or Gmail. We accept exports/archives only.
• Re-running a snapshot to update a character — re-import creates a new character. Updating an existing one through the standard PATCH endpoint is the supported path.
• Conversational refinement of an imported persona ("he wouldn't say that"). Vilow's runtime memory and emotion system already absorbs that signal through normal chat — no special UI needed.