Project Settings

Every Solarian project has a settings.py that tells the framework which Robot, Controller, and Server subclasses belong to this project. It's the smallest possible registry — just three string class paths — but it's what lets the CLI run any of them with the right configuration.

The pattern is borrowed from Django: a single Python module per project, loaded lazily, accessible globally as solarian.conf.settings.

The settings.py file

A scaffolded project ships with this content (see solarian/templates/settings.py.tmpl):

"""
Solarian settings for myrobot project.

Generated by 'solarian create-project'.
"""

ROBOT_CLASS = 'myrobot.robot.MyrobotRobot'
CONTROLLER_CLASS = 'myrobot.controller.MyrobotController'
SERVER_CLASS = 'myrobot.server.MyrobotServer'
  • Name
    ROBOT_CLASS
    Type
    str
    Description

    Dotted import path to your Robot subclass. Used by solarian run-robot.

  • Name
    CONTROLLER_CLASS
    Type
    str
    Description

    Dotted import path to your Controller subclass. Used by solarian run-controller, record, and replay.

  • Name
    SERVER_CLASS
    Type
    str
    Description

    Dotted import path to your RelayServer subclass. Used by solarian run-server.

You can add any number of additional constants to settings.py and read them through solarian.conf.settings.YOUR_VALUE from anywhere in your code.

Where it lives

The CLI looks for settings.py in this order (solarian/cli/manage.py):

  1. The path passed via --settings.
  2. <package_name>/settings.py, where <package_name> is the name field in your pyproject.toml (with hyphens replaced by underscores).
  3. The first Python package in the current directory that contains a settings.py.
  4. conf/settings.py (legacy fallback).

A scaffolded project lands in (2): myrobot/myrobot/settings.py.

Environment variables

Once located, the settings path is exported into the environment so that subprocesses (modules forked off the robot, the AI controller's think process) can re-resolve it without needing the original CLI args:

  • Name
    SOLARIAN_SETTINGS
    Type
    env
    Description

    Absolute path to settings.py. Set automatically by the CLI; you can also set it manually if you embed Solarian in a non-CLI script.

  • Name
    SOLARIAN_PROJECT_PATH
    Type
    env
    Description

    Absolute path to your project root. Solarian also sys.path.insert(0, ...)s it so your project package is importable.

  • Name
    SOLARIAN_CONF_PATH
    Type
    env
    Description

    Absolute path to the Hydra config directory (defaults to ./conf). Used by every module to find its conf/<module_name>.yaml.

  • Name
    SOLARIAN_CURRENT_CONFIG
    Type
    env
    Description

    Set during command execution to the absolute path of the active config file. Used to print friendlier validation errors.

Reading settings from your code

Import the lazy singleton:

from solarian.conf import settings

print(settings.ROBOT_CLASS)

The first attribute access loads the module from SOLARIAN_SETTINGS and caches it. If the environment variable isn't set, you'll get:

ValueError: SOLARIAN_SETTINGS environment variable not set

This is the standard error you'll see when you run a script that depends on solarian.conf.settings without going through the CLI. Either run via solarian <subcommand> or set SOLARIAN_SETTINGS yourself before importing.

Running with custom settings

Two common scenarios:

Different settings per environment

Keep settings.py, settings_dev.py, and settings_prod.py side by side; pick one explicitly:

solarian run-robot --settings myrobot/settings_prod.py

Embedding Solarian outside the CLI

When using Solarian from a notebook or your own script:

import os
os.environ["SOLARIAN_SETTINGS"] = "/absolute/path/to/myrobot/settings.py"
os.environ["SOLARIAN_PROJECT_PATH"] = "/absolute/path/to/myrobot"
os.environ["SOLARIAN_CONF_PATH"] = "/absolute/path/to/myrobot/conf"

from solarian.conf import settings
from solarian.utils import get_class

RobotCls = get_class(settings.ROBOT_CLASS)

How the CLI uses settings

When you run a solarian subcommand:

  1. Resolve settings.py (CLI arg or auto-discovery).
  2. Set SOLARIAN_SETTINGS, SOLARIAN_PROJECT_PATH, and SOLARIAN_CONF_PATH.
  3. Initialize Hydra against the config directory.
  4. Compose the YAML for this command (config_name from the CommandRegistry entry).
  5. Call solarian.setup.setup(modules=...) to import the project files needed by this command (robot.py, observation.py, action.py, controller.py, server.py).
  6. Hand the validated config to the command's handle().

This is what makes commands like run-robot work without any explicit imports on the user side: the CLI imports your project's robot.py, which imports your Robot subclass, which references your modules — and the settings module is the bootstrap point for that whole chain.

See also

Was this page helpful?