StrataSynth Documentation

You need an API key (ss_live_...). Request one from the dashboard. All examples use the REST API directly — no SDK required.

curl -X POST https://api.stratasynth.com/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "ss_live_..."}'

# Response:
# { "data": { "token": "eyJ...", "expires_in": 86400 } }

export TOKEN="eyJ..."

curl -X POST https://api.stratasynth.com/jobs/dataset \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario_id": "FAM-01",
    "conversation_count": 5,
    "complexity": 3,
    "language": "en",
    "adapter": "flat_jsonl"
  }'

# Response:
# { "data": { "jobId": "job_abc123", "status": "QUEUED", "estimated_time": 60 } }

export JOB_ID="job_abc123"

curl -H "Authorization: Bearer $TOKEN" \
  https://api.stratasynth.com/jobs/$JOB_ID

# Repeat every 10s until status = "COMPLETED"
# { "data": { "status": "COMPLETED", "download_url": "https://..." } }

curl -H "Authorization: Bearer $TOKEN" \
  https://api.stratasynth.com/jobs/$JOB_ID/preview

# Returns up to 2 full conversations with per-turn ground truth:
# intent · communication_act · emotional_state · belief_state · relationship_state

# The download_url from step 3 is a presigned S3 URL (valid 24h)
curl "$DOWNLOAD_URL" -o dataset.jsonl

# Each line is a full conversation object:
# { "conversation_id": "...", "turns": [...], "ground_truth": {...}, "metadata": {...} }

StrataSynth generates synthetic conversations between two personas with full psychological ground truth. These are not real transcripts — they are constructed from psychological profiles, tracking emotions, beliefs and relationships turn by turn.

The key difference from other synthetic data generators: StrataSynth separates cognition from language. Each turn starts from a cognitive decision (intent, goal and the communication act to aim for) computed before the LLM generates any text. The LLM writes the words and reports the communication act it actually used; that reported act is the one exported as communication_act.

Each conversation includes:

• The conversation text (turns)
• Per-turn labels: intent and goal from the engine, emotional state, and the communication act reported by the generator
• Relationship evolution: trust, tension, connection, dominance balance
• Belief evolution: 12 beliefs × (value, confidence) per persona
• Labelled deliberate noise (lies, exaggerations, retractions)

Every turn goes through a deterministic cognitive pipeline before any language is generated. This is what separates StrataSynth from LLM wrappers that ask the model to "generate a realistic conversation".

This is what you actually get in your dataset. Every turn in every conversation contains the text plus the cognitive structure that produced it.

{
  "speaker": "A",
  "text": "I'm not upset about the meeting. Really, it's fine.",

  "intent": "deflect",
  "goal": "protect_self",
  "communication_act": "minimization",

  "emotional_state": {
    "tension": 0.71,
    "connection": 0.28,
    "vulnerability": 0.54
  },

  "relationship_state": {
    "trust": 0.52,
    "tension": 0.68,
    "connection": 0.31,
    "dominance_balance": -0.12
  },

  "belief_state": {
    "trust_in_other":        { "value": 0.48, "confidence": 0.76 },
    "self_worth":            { "value": 0.61, "confidence": 0.82 },
    "conflict_is_solvable":  { "value": 0.35, "confidence": 0.63 },
    "partner_supportive":    { "value": 0.29, "confidence": 0.71 }
  },

  "belief_delta": {
    "trust_in_other":       -0.04,
    "conflict_is_solvable": -0.07
  },

  "noise_flags": ["social_lie"]
}

{
  "conversation_id": "conv_abc123",
  "scenario_id": "FAM-01",
  "language": "en",
  "seed": 42,
  "engine_version": "1.2.0",
  "schema_version": "1.1.0",

  "personas": {
    "A": { "persona_id": "psyg_xyz", "archetype": "caregiver", "attachment_style": "anxious_preoccupied" },
    "B": { "persona_id": "psyg_abc", "archetype": "burned_out_exec", "attachment_style": "dismissive_avoidant" }
  },

  "relationship_trajectory": [
    { "turn": 0, "trust": 0.65, "tension": 0.40 },
    { "turn": 5, "trust": 0.52, "tension": 0.68 }
  ],

  "turns": [ ... ],

  "ground_truth": {
    "noise_rejection_rate": 1.0,
    "behavioral_entropy": 0.83,
    "belief_consistency": 0.71
  }
}

What teams are building with StrataSynth.

The fastest path to value. No code required. Configure scenarios, inspect jobs, preview datasets, generate personas and request evaluations from the browser.

pip install stratasynth-cli
stratasynth auth login --api-key ss_live_...

# List available scenarios
stratasynth scenarios list

# Generate a dataset
stratasynth generate \
  --scenario FAM-01 \
  --count 100 \
  --complexity 3 \
  --adapter huggingface_dataset \
  --language en

# Watch job status
stratasynth jobs list
stratasynth jobs status job_abc123

# Download completed dataset
stratasynth jobs download --job-id job_abc123 --output ./dataset.jsonl

# Generate a PsycheGraph persona
stratasynth personas generate --archetype working_mother --complexity 4

# Evaluate a completed job
stratasynth evaluate start --job-id job_abc123
stratasynth evaluate results --eval-id eval_abc123

pip install stratasynth-client

from stratasynth_client import StrataSynthClient

client = StrataSynthClient(api_key="ss_live_...")

# Generate and wait
result = client.jobs.create(
    scenario_id="FAM-01",
    conversation_count=50,
    complexity=3,
    language="en",
    adapter="flat_jsonl",
)
result.wait()

# Download and work with data
dataset = result.download()
df = dataset.to_dataframe()           # pandas
hf = dataset.to_huggingface()         # Hugging Face Dataset
hf.push_to_hub("my-org/my-dataset")

# Reuse a persona across multiple jobs
persona = client.personas.generate(archetype="burnt_out_professional", complexity=4)
job1 = client.jobs.create(scenario_id="PRO-01", persona_a_id=persona.persona_id, ...)
job2 = client.jobs.create(scenario_id="ROM-02", persona_a_id=persona.persona_id, ...)

All endpoints require a JWT obtained by exchanging your API key. Tokens are valid for 24 hours.

# 1. Authenticate
curl -X POST https://api.stratasynth.com/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "ss_live_..."}'
# → { "data": { "token": "eyJ...", "expires_in": 86400 } }

TOKEN="eyJ..."

# 2. List scenarios
curl -H "Authorization: Bearer $TOKEN" https://api.stratasynth.com/scenarios

# 3. Create a generation job
curl -X POST https://api.stratasynth.com/jobs/dataset \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario_id": "FAM-01",
    "conversation_count": 20,
    "complexity": 3,
    "language": "en",
    "adapter": "flat_jsonl"
  }'

# 4. Poll status
curl -H "Authorization: Bearer $TOKEN" https://api.stratasynth.com/jobs/{jobId}

# 5. Download (presigned S3 URL in response)
curl "$DOWNLOAD_URL" -o dataset.jsonl

Four end-to-end Jupyter notebooks ready to run against the API. Download and open in Jupyter or Google Colab.

All metrics are computed without LLM — numpy, scikit-learn, sentence-transformers only. This avoids circular validation (LLM-generated data evaluated by another LLM).

The open schema that defines what a PsycheGraph persona looks like. Install it to get typed enums and interfaces in TypeScript or JavaScript projects — no API key needed.

npm install @stratasynth/psychegraph-schema
# or: pnpm add @stratasynth/psychegraph-schema

import {
  AttachmentStyle,
  Archetype,
  ConflictStyle,
  NoiseType,
  ArcType,
  PrimaryDefense,
} from "@stratasynth/psychegraph-schema";

// Enums give you all valid values — IDE autocompletes, TypeScript validates
const filter = {
  attachment: AttachmentStyle.ANXIOUS_PREOCCUPIED,   // "anxious_preoccupied"
  archetype:  Archetype.BURNED_OUT_EXEC,             // "burned_out_exec"
  conflict:   ConflictStyle.STONEWALLING,            // "stonewalling"
};

// Filter conversations from a downloaded dataset
const relevant = conversations.filter(conv =>
  conv.persona_a.attachment_style === AttachmentStyle.DISMISSIVE_AVOIDANT
);

// List all valid values at runtime
console.log(Object.values(AttachmentStyle));