synthlab 0.1.6

Generate high-quality synthetic multi-turn chat datasets with Gemini

SynthLab

SynthLab turns Gemini into a synthetic data engine for multi-turn chat datasets.

Describe any domain in a short brief. SynthLab designs the persona, invents realistic scenarios, generates conversations, and exports JSONL ready for fine-tuning, evaluation, or RAG-style instruction data.

Why SynthLab

• Any domain — finance, support, healthcare intake, legal FAQ, sales, HR, education, coding copilots, and more
• Any language or register — formal, casual, bilingual, technical; controlled entirely by your brief
• Plan → generate — Gemini proposes scenarios, then fills assistant turns as the teacher model
• Fine-tuning ready — standard system / user / assistant message format
• CLI + Python API — ship in CI or script custom pipelines

Use cases

Area	Example briefs
Customer support	Order tracking, returns, billing disputes, product troubleshooting
Finance & banking	Card blocks, transfers, loans, KYC, fraud triage, personal finance coaching
Insurance	Claims intake, policy questions, coverage explanations
Healthcare	Appointment booking, symptom intake (non-diagnostic), insurance eligibility
Legal / compliance	FAQ-style guidance, document checklist flows (not legal advice)
Sales & success	Discovery calls, objection handling, onboarding walkthroughs
HR & internal ops	PTO policy, IT helpdesk, expense reports
Education	Tutors, exam prep, language practice, Socratic teaching
Developer tools	API helpers, debugging assistants, code-review chat
Local / multilingual	Any locale or dialect mix you specify in the brief

The package does not ship domain presets. Quality and scope come from how precise your --brief is.

Features

• Scenario planning — Gemini invents varied multi-turn user skeletons from one brief
• Persona synthesis — system prompts generated or supplied by you
• Short chat realism — configurable turn depth (default: 3 user / 3 assistant)
• Temporary sessions — generation avoids polluting your Gemini history
• Preview & stats — inspect samples before training
• JSONL export — one sample per line for common fine-tuning loaders

Installation

pip install -U synthlab

Optional browser cookie import:

pip install -U "synthlab[browser]"

Requires Python 3.10+.

Authentication

SynthLab uses a Gemini web session.

1. Open https://gemini.google.com and sign in
2. DevTools → Network → refresh → copy:
   • __Secure-1PSID (required)
   • __Secure-1PSIDTS (if present)
3. Save as cookies.json:

{
  "__Secure-1PSID": "value...",
  "__Secure-1PSIDTS": "value..."
}

Environment variables: SYNTHLAB_SECURE_1PSID, SYNTHLAB_SECURE_1PSIDTS.
For containers / long-running jobs, set SYNTHLAB_COOKIE_PATH to persist refreshed cookies.

Quickstart

synthlab auth check --cookies-json cookies.json
synthlab init

synthlab plan --cookies-json cookies.json \
  --brief "Retail banking assistant. Topics: cards, transfers, fraud alerts. Concise, professional, multilingual-ready. Ask one clarifying question when needed." \
  --count 10 --turns 3

synthlab generate --cookies-json cookies.json --out data/dataset.jsonl
synthlab preview --n 2
synthlab stats

Swap the brief for any vertical — same commands.

CLI reference

Global options (before the subcommand):

--cookies-json PATH   Cookie file
--proxy URL           HTTP(S) proxy
--verbose             Debug logs
--timeout SEC         Request timeout (default 90)

Command	Description
synthlab init	Create synthlab.yaml and data/
synthlab auth check	Validate the Gemini session
synthlab persona new	Set persona via --prompt or --from-brief
synthlab plan	Invent scenarios from --brief
synthlab generate	Run the plan and append JSONL
synthlab preview	Print the last N samples
synthlab stats	Sample counts by style and turn length
synthlab ask	One-shot Gemini prompt (debugging)

Python API

import asyncio
from synthlab import GeminiClient, SynthPipeline

async def main():
    client = GeminiClient("YOUR_1PSID", "YOUR_1PSIDTS")
    await client.init()

    pipeline = SynthPipeline(client)
    pack = await pipeline.plan(
        brief=(
            "B2B SaaS onboarding specialist. Help new admins configure SSO, "
            "invites, and billing. Short multi-turn, clear next steps."
        ),
        count=5,
        turns=3,
    )
    samples = await pipeline.generate(pack)
    for sample in samples:
        print(sample.id, len(sample.messages))

    await client.close()

asyncio.run(main())

Output format

Each JSONL line:

{
  "id": "sso_setup",
  "style": "professional",
  "messages": [
    {"role": "system", "content": "..."},
    {"role": "user", "content": "..."},
    {"role": "assistant", "content": "..."}
  ],
  "meta": {
    "created_at": "2026-07-14T00:00:00+00:00",
    "persona": "onboarding_specialist"
  }
}

Project layout after init

synthlab.yaml      # persona + scenario plan
data/
  dataset.jsonl    # generated samples
cookies.json       # secrets (gitignored)

Writing strong briefs

Good briefs usually specify:

1. Role — who the assistant is
2. Scope — topics in / out of bounds
3. Tone & language — formal, casual, bilingual, technical
4. Behavior — reply length, when to ask questions, safety limits
5. Variation — styles of users (angry, confused, expert, first-time)

Example:

You are a claims intake assistant for a P&C insurer.
Handle FNOL, document requests, and status checks only.
Professional English, 1–3 short sentences per turn.
Never invent claim IDs or coverage decisions.
Vary user styles: calm, frustrated, elderly, broker-assisted.

Tips

• Prefer short turns (--turns 3) for naturalistic chat data
• Use a dedicated browser session for cookies when possible
• Always preview a few samples before training
• Increase --count iteratively; review quality before large runs

License

AGPL-3.0 — see LICENSE.