Skip to main content

​
Signature

def create_synthetic_world(
    project_id: str,
    *,
    mode: str = "schema_only",
    seed: int | None = None,
    model: str | None = None,
    failure_profile: dict | None = None,
    platform_url: str | None = None,
    api_key: str | None = None,
    timeout: float = 30.0,
) -> SyntheticWorld

​
Overview

Creates a new synthetic world scoped to a project. The world intercepts tool calls and returns generated responses instead of calling real services. Returns a SyntheticWorld instance that can be used as a context manager. When the context exits, the world is automatically destroyed.

​
Parameters

​
project_id
string
required
The project to scope the world to. Must be a project you own.
​
mode
string
default:"schema_only"
Generation mode:
ValueDescription
schema_onlyGenerate from tool schema alone (fastest)
examplesGround generation in real examples from your traces
statefulRemember prior calls within the session
​
seed
int | None
default:"None"
Seed for deterministic output. Same seed + same input = same response every time.
​
model
string | None
default:"None"
LLM model for response generation. When None, the backend picks a default.
​
failure_profile
dict | None
default:"None"
Error simulation config. When set, a percentage of calls will raise simulated errors.
{"rate": 0.3, "codes": ["timeout", "internal_error"]}
Available codes: timeout, internal_error, rate_limit, not_found, bad_request.Failures are deterministic when a seed is set.
​
platform_url
string | None
default:"None"
RL platform URL. Defaults to RDK_PLATFORM_URL env var or http://localhost:7878.
​
api_key
string | None
default:"None"
Bearer token for authentication. Defaults to RDK_API_KEY env var.
​
timeout
float
default:"30.0"
HTTP request timeout in seconds.

​
Returns

A SyntheticWorld instance.

​
Raises

  • ValueError — if no API key is provided or found in environment
  • httpx.HTTPStatusError — if the backend rejects the request (auth failure, project not found)

​
Examples

​
Minimal

from rdk.synthetic import create_synthetic_world

with create_synthetic_world(project_id="my-project") as world:
    @world.tool
    def get_user(user_id: str) -> dict:
        """Fetch a user."""
        ...

    print(get_user("u1"))

​
With all options

world = create_synthetic_world(
    project_id="my-project",
    mode="stateful",
    seed=42,
    model="gpt-4o",
    failure_profile={"rate": 0.1, "codes": ["timeout"]},
    platform_url="https://platform.example.com",
    api_key="my-token",
)
try:
    # use world
    ...
finally:
    world.close()

​
Environment Variables

VariableEffect
RDK_API_KEYDefault API key
RDK_PLATFORM_URLDefault platform URL

​
See Also