Bespoke Curator – Quick‑Start Overview

What it is – A Python library that lets you build large‑scale synthetic‑data pipelines using LLMs. It handles prompt construction, parallel / batch inference, caching, retries, and lets you pipe the results straight into Hugging Face Dataset objects or a fine‑tuning workflow.

🎯 Core purpose

Generate or transform massive amounts of text (or multimodal) data for training, evaluation, or extraction tasks.
Provide a structured‑output interface (via Pydantic models) so the LLM’s response is automatically parsed into clean JSON‑like records.
Offer bulk inference with support for OpenAI, Anthropic, Gemini, DeepSeek, Ollama, vLLM, and any LiteLLM‑compatible provider, including their batch APIs to cut token costs.
Integrate with the Tinker SDK for one‑click LoRA fine‑tuning of the curated dataset.

🛠️ Main components (as described in the README)

Component	Role	Key features
`curator.LLM`	Base class you subclass to define a prompt and a parsing step.	• Accepts a Pydantic `response_format` for structured output. • Handles async calls, retries, caching, and optional batch mode. • Returns a Hugging Face `Dataset` or a plain list.
Providers	Backend adapters for different APIs.	OpenAI, Anthropic, Gemini, DeepSeek, Ollama, vLLM, `litellm`, `kluster.ai`. Each can be configured with custom `backend_params` (rate limits, base URLs, API keys).
Batch mode	Sends many prompts in a single request where the provider supports it.	Roughly 50 % token‑cost reduction; enabled by `batch=True` on the `LLM` instance.
CodeExecutor	Optional runtime that can execute Python code generated by the LLM.	Supports local multiprocessing, Ray, Docker, or the e2b SaaS backend.
TinkerTrainer	Thin wrapper around the Tinker SDK for LoRA fine‑tuning.	Simple config object, checkpoint‑resume, and a `sample` method to query the fine‑tuned model.
Viewer	UI (CLI gif shown) to monitor generation progress and see live statistics.

🚀 Typical workflow (from README examples)

Define a structured output model with Pydantic.
Subclass curator.LLM and implement:
- prompt(self, input) – returns the text sent to the LLM.
- parse(self, input, response) – converts the structured response into rows.
Instantiate the class with a model name and optional batch=True.
Call the instance on a list or a Hugging Face Dataset – Curator handles parallelism, caching, and retries.
(Optional) Chain blocks – output of one LLM can feed another, e.g., generate topics → generate poems.
(Optional) Fine‑tune the resulting dataset with TinkerTrainer.

📦 Installation

pip install bespokelabs-curator          # core library
pip install bespokelabs-sandbox          # optional sandbox utilities
# For fine‑tuning
pip install tinker

All packages share the top‑level import namespace bespokelabs:

from bespokelabs import curator, sandbox

📚 Example snippets (directly from the README)

Sentiment analysis (bulk inference)

class Sentiment(BaseModel):
    sentiment: Literal["positive", "negative", "neutral"]

class SentimentAnalyzer(curator.LLM):
    def prompt(self, product):
        return f"Determine the sentiment of the product from the review: {product['review']}"
    def parse(self, product, response: Sentiment):
        return [{"name": product["name"], "sentiment": response.sentiment}]

analyzer = SentimentAnalyzer(model_name="gpt-4o-mini", batch=False)
reviews = analyzer(dataset)   # dataset can be a list or HF Dataset

Poem generation (chaining two LLM blocks)

class Topics(BaseModel):
    topics_list: List[str]

class TopicGenerator(curator.LLM):
    response_format = Topics
    def prompt(self, subject):
        return f"Return 3 topics related to {subject}"
    def parse(self, _, resp: Topics):
        return [{"topic": t} for t in resp.topics_list]

class Poet(curator.LLM):
    response_format = Poem
    def prompt(self, inp):
        return f"Write two poems about {inp['topic']}"
    def parse(self, _, resp: Poem):
        return [{"title": resp.title, "poem": resp.poem}]

topics = TopicGenerator(model_name="gpt-4o-mini")("Mathematics")
poems = Poet(model_name="gpt-4o-mini")(topics)

Fine‑tuning with Tinker

from bespokelabs.curator import TinkerTrainer, TinkerTrainerConfig
config = TinkerTrainerConfig(
    base_model="Qwen/Qwen3-8B",
    epochs=3, batch_size=4,
    lora_config={"rank": 16, "alpha": 32, "dropout": 0.05},
    checkpoint_every_epoch=True,
)
trainer = TinkerTrainer(config)
result = trainer.train(training_data)
print(trainer.sample("Explain recursion in Python"))

🌐 Ecosystem & Community

Docs & tutorials – docs.bespokelabs.ai (getting‑started, how‑to guides, API reference).
Hosted API – console.bespokelabs.ai for managed inference.
Discord & Twitter – active community channels for support and announcements.
Recent highlights (2025‑2026):
- Used to build the OpenThoughts‑Agents and several high‑quality reasoning datasets (Stratos‑17k, OpenThoughts‑114k, etc.).
- Integrated with Fireworks AI, Gemini, Claude 3.7 Sonnet, and batch APIs.
- Added a code‑execution engine supporting Ray, Docker, and e2b.

✅ When to use Bespoke Curator

You need large‑scale, structured synthetic data for fine‑tuning or evaluation.
You want cost‑effective bulk inference (batch mode, caching, retries).
You prefer a single Pythonic interface that works with any LLM provider you already have access to.
You plan to fine‑tune the curated data with LoRA via the Tinker SDK.

❓ Limitations / Things to watch

Relies on external LLM APIs; quota and latency depend on the chosen provider.
Structured output parsing requires a correct Pydantic schema – mismatches will raise validation errors.
Batch mode is only available for a subset of providers (OpenAI, Anthropic, Gemini, kluster.ai, Mistral at time of writing).

TL;DR

Bespoke Curator is a production‑ready Python toolkit for building high‑throughput LLM‑driven data pipelines, with built‑in support for structured outputs, caching, batch inference, and seamless LoRA fine‑tuning via Tinker. It targets researchers and engineers who need to generate or curate massive datasets for post‑training tasks.

bespokelabsai/curator