Getting Started#

Installation#

Install from PyPI:

pip install synora

Install from source:

git clone https://github.com/ParamThakkar123/synora.git
cd synora
pip install -e .

For development and tests:

pip install -e ".[dev]"

Logging with Weights & Biases and TensorBoard#

Synora supports logging experiment results to Weights & Biases (WandB) and TensorBoard.

Weights & Biases#

To use WandB logging, set the WANDB_API_KEY environment variable (anonymous logins are no longer supported). You can get your key from wandb.ai.

cfg.enable_wandb = True
cfg.wandb_project = "synora"
cfg.wandb_entity = "your-entity"

TensorBoard#

Enable TensorBoard logging:

cfg.enable_tensorboard = True
cfg.log_dir = "runs"

Logs will be saved to the specified directory and can be viewed with tensorboard --logdir runs.

Quick Start: Friendly API#

The recommended entrypoint for common workflows is synora. It mirrors the Synora implementation package, but gives users short factory helpers for discovery, model creation, and environment creation.

import synora

print(synora.list_models())
print(synora.list_env_backends())

# Runs on `pip install synora[gym]`. Use env="walker-walk" (default backend)
# with `pip install synora[dmc]` for DeepMind Control tasks.
agent = synora.create_model(
    "dreamer", env="Pendulum-v1", env_backend="gym", total_steps=5_000
)
env = synora.make_env("CartPole-v1", backend="gym")

You can still import direct research components from synora when you need lower-level control:

from synora import DreamerAgent, DreamerConfig

cfg = DreamerConfig()
cfg.env_backend = "gym"  # or the default "dmc" with synora[dmc] installed
cfg.env = "Pendulum-v1"
agent = DreamerAgent(cfg)

Quick Start: Dreamer#

Synora implements multiple world model algorithms. Click on each to see detailed documentation:

Algorithm	Description	Quick Start
Dreamer	Model-based RL with latent dynamics	Dreamer: Model-Based RL with Latent Dynamics
JEPA	Self-supervised visual representations	JEPA: Joint Embedding Predictive Architecture
IRIS	Sample-efficient RL with Transformers	IRIS: Transformers for Sample-Efficient World Models
DiT	Diffusion models with Transformers	DiT: Diffusion Transformer and Diffusion Models

Train a complete world model pipeline (VAE + MDNRNN + Controller) on any Gym environment:

# Train on CarRacing
python -m synora.training.train_world_model --env CarRacing-v2

# Train on Pendulum
python -m synora.training.train_world_model --env Pendulum-v1

# Test trained model
python -m synora.training.train_world_model --env CarRacing-v2 --test

# Specify action size manually for environments with missing dependencies
python -m synora.training.train_world_model --env BipedalWalker-v3 --action_size 4

Dreamer supports multiple backends through DreamerConfig.env_backend; the top-level synora.make_env() helper uses the same backend names for standalone environment creation:

Backend	Description
`dmc`	DeepMind Control Suite tasks (e.g. `walker-walk`)
`dmlab`	DeepMind Lab 3D navigation tasks (e.g. `rooms_collect_good_objects_train`)
`gym`	Gym/Gymnasium environment IDs or an existing environment instance
`mujoco`	Gymnasium MuJoCo task IDs or native MJCF/MJB models
`robotics`	Any ID registered by the installed Gymnasium Robotics package
`procgen`	Procgen benchmark games such as `coinrun` and `heist`
`brax`	JAX/Brax continuous-control environments
`unity_mlagents`	Unity ML-Agents executable environments

Typical Training Flow#

Choose an algorithm (Dreamer, JEPA, IRIS, or DiT)
Create a config object for that algorithm
Override dataset/environment and optimization fields
Instantiate the corresponding agent
Call train() and monitor logs/checkpoints

For complete API details, see API Reference.