Skip to content

Problem schema#

problem.rbx.yml#

Checker #

Bases: CodeItem

Parameters:

Name Type Description Default
fallback_to Checker | None

Checker to fall back to if the mainly specified checker does not exist.

None
mode Literal['testlib', 'boca']

In which compatibility mode the checker should be run.

'testlib'
Source code in rbx/box/schema.py
class Checker(CodeItem):
    model_config = ConfigDict(extra='forbid')

    fallback_to: Optional[Checker] = Field(
        default=None,
        description="""Checker to fall back to if the mainly specified checker does not exist.""",
    )

    mode: Literal['testlib', 'boca'] = Field(
        default='testlib',
        description="""In which compatibility mode the checker should be run.""",
    )

CheckerTest #

Bases: BaseModel

Parameters:

Name Type Description Default
glob str | None

A glob pattern for the files to be used as unit test input for the checker.

None
testplan Path | None

A testplan to be used as unit test input for the checker.

None
outcome ExpectedOutcome | None

The expected outcome of the checker.

None
Source code in rbx/box/schema.py
class CheckerTest(BaseModel):
    model_config = ConfigDict(extra='forbid')

    glob: Optional[str] = Field(
        default=None,
        description='A glob pattern for the files to be used as unit test input for the checker.',
    )

    testplan: Optional[pathlib.Path] = Field(
        default=None,
        description='A testplan to be used as unit test input for the checker.',
    )

    outcome: Optional[ExpectedOutcome] = Field(
        default=None,
        description='The expected outcome of the checker.',
    )

    @model_validator(mode='after')
    def check_oneof(self):
        if self.glob is None and self.testplan is None:
            raise PydanticCustomError(
                'GLOB_OR_TESTPLAN_REQUIRED',
                'Either a glob or a testplan must be specified.',
            )
        if self.glob is not None and self.testplan is not None:
            raise PydanticCustomError(
                'GLOB_AND_TESTPLAN_NOT_ALLOWED',
                'Either a glob or a testplan must be specified, but not both.',
            )
        return self

    @model_validator(mode='after')
    def check_testplan(self):
        if self.testplan is not None and self.outcome is not None:
            raise PydanticCustomError(
                'OUTCOME_NOT_ALLOWED',
                'Outcome is not allowed for testplan checker tests.',
            )
        return self

    @model_validator(mode='after')
    def check_glob(self):
        if self.glob is not None and self.outcome is None:
            raise PydanticCustomError(
                'OUTCOME_REQUIRED',
                'Outcome is required for glob checker tests.',
            )
        return self

CodeItem #

Bases: BaseModel

Parameters:

Name Type Description Default
path Path

The path to the code file, relative to the package directory.

required
language str | None

The language of the code file.

None
compilationFiles List[str] | None

Extra files that should be available during the compilation of the code file, such as testlib.h, jngen.h, tgen.h, etc.

The paths should be given relative to the package directory, and are placed at the same package-relative path inside the sandbox (the package directory structure is mirrored). This means a code file in a subdirectory can include a file from elsewhere in the package via a relative path (e.g. #include "../lib.h").

Third-party libraries such as testlib.h, jngen.h and tgen.h are provided by the preset's libraries configuration (see the preset docs), not auto-injected.

[]
executionFiles List[str] | None

Extra files that should be available at execution time, the runtime equivalent of compilationFiles.

The paths should be given relative to the package directory, and are placed at the same package-relative path inside the sandbox (the package directory structure is mirrored). Use this for runtime companion files a compiled binary or interpreted script needs at run time (data files, sibling modules, etc.).

Sibling Python imports and quoted C++ includes are auto-discovered; this field is the escape hatch for files that cannot be discovered automatically.

[]
Source code in rbx/box/schema.py
class CodeItem(BaseModel):
    model_config = ConfigDict(extra='forbid')

    def __eq__(self, other: object) -> bool:
        if not isinstance(other, CodeItem):
            return NotImplemented
        return self.path == other.path

    def __hash__(self) -> int:
        return hash(self.path)

    path: pathlib.Path = Field(
        description="""The path to the code file, relative to the package directory."""
    )

    language: Optional[str] = Field(
        default=None, description="""The language of the code file."""
    )

    compilationFiles: Optional[List[str]] = Field(
        default=[],
        description="""
Extra files that should be available during the compilation of the code file,
such as testlib.h, jngen.h, tgen.h, etc.

The paths should be given relative to the package directory, and are placed at the
same package-relative path inside the sandbox (the package directory structure is
mirrored). This means a code file in a subdirectory can include a file from
elsewhere in the package via a relative path (e.g. `#include "../lib.h"`).

Third-party libraries such as testlib.h, jngen.h and tgen.h are provided by the
preset's `libraries` configuration (see the preset docs), not auto-injected.
""",
    )

    executionFiles: Optional[List[str]] = Field(
        default=[],
        description="""
Extra files that should be available at *execution* time, the runtime equivalent of
`compilationFiles`.

The paths should be given relative to the package directory, and are placed at the
same package-relative path inside the sandbox (the package directory structure is
mirrored). Use this for runtime companion files a compiled binary or interpreted
script needs at run time (data files, sibling modules, etc.).

Sibling Python imports and quoted C++ includes are auto-discovered; this field is the
escape hatch for files that cannot be discovered automatically.
""",
    )

    def href(self, hyperlink: bool = True) -> str:
        return href(self.path, hyperlink=hyperlink)

    def display(self) -> str:
        return self.href(hyperlink=False)

CodeItemWithDigest #

Bases: CodeItem

Parameters:

Name Type Description Default
digest str

The digest of the code file.

required
Source code in rbx/box/schema.py
class CodeItemWithDigest(CodeItem):
    model_config = ConfigDict(extra='forbid')

    digest: str = Field(description="""The digest of the code file.""")

    @classmethod
    def create(cls, code_item: CodeItem, digest: str) -> 'CodeItemWithDigest':
        return cls(
            path=code_item.path,
            language=code_item.language,
            compilationFiles=code_item.compilationFiles,
            executionFiles=code_item.executionFiles,
            digest=digest,
        )

EstimationSolutionTiming #

Bases: BaseModel

What one solution measured during the estimation of a limits profile.

Parameters:

Name Type Description Default
path str

The solution, as named in problem.rbx.yml.

required
language str

The language it was timed as, which decides its group.

required
role InferenceRole

Which side of the limit it bounds: lower for an accepted solution, upper for one expected to be too slow.

required
time int | None

Its running time, in milliseconds, when it finished. Absent for a slow solution that never finished, or was never run.

None
survivedAt int | None

For a slow solution that never finished: the highest limit, in milliseconds, it was seen still running at. Absent when it finished, or was never run.

None
Source code in rbx/box/schema.py
class EstimationSolutionTiming(BaseModel):
    """What one solution measured during the estimation of a limits profile."""

    # Ignored rather than refused, for the reason `LimitsProfile` gives.
    model_config = ConfigDict(extra='ignore')

    path: str = Field(description='The solution, as named in `problem.rbx.yml`.')

    language: str = Field(
        description='The language it was timed as, which decides its group.'
    )

    role: InferenceRole = Field(
        description="""Which side of the limit it bounds: `lower` for an accepted
solution, `upper` for one expected to be too slow."""
    )

    time: Optional[int] = Field(
        default=None,
        description="""Its running time, in milliseconds, when it finished. Absent
for a slow solution that never finished, or was never run.""",
    )

    survivedAt: Optional[int] = Field(
        default=None,
        description="""For a slow solution that never finished: the highest limit,
in milliseconds, it was seen still running at. Absent when it finished, or was
never run.""",
    )

ExpectedOutcome #

Bases: AutoEnum

Source code in rbx/box/schema.py
class ExpectedOutcome(AutoEnum):
    ANY = alias('any')  # type: ignore
    """Expected outcome for any outcome."""

    ACCEPTED = alias('accepted', 'ac', 'correct')  # type: ignore
    """Expected outcome for correct solutions (AC)."""

    ACCEPTED_OR_TLE = alias(
        'accepted or time limit exceeded',  # type: ignore
        'accepted or tle',
        'ac or tle',
        'ac/tle',
        'ac+tle',
    )  # type: ignore
    """Expected outcome for solutions that finish with either AC or TLE.

    Especially useful when you do not care about the running time of this solution, and
    want it to not be considered when calculating the timelimit for the problem."""

    WRONG_ANSWER = alias('wrong answer', 'wa')  # type: ignore
    """Expected outcome for solutions that finish successfully,
    but the produced output are incorrect (WA)."""

    INCORRECT = alias('fail', 'incorrect')  # type: ignore
    """Expected outcome for solutions that finish with any non-AC verdict."""

    PARTIALLY_CORRECT = alias('partially correct', 'partial', 'pc')  # type: ignore
    """Expected outcome for solutions the checker awards part of a test's points
    (testlib `quitp`). Pin how many points with the solution's `score`."""

    RUNTIME_ERROR = alias('runtime error', 'rte', 're')  # type: ignore
    """Expected outcome solutions that finish with non-zero code (RTE)."""

    TIME_LIMIT_EXCEEDED = alias('time limit exceeded', 'timeout', 'tle', 'tl')  # type: ignore
    """Expected outcome for solutions that do not finish in time."""

    MEMORY_LIMIT_EXCEEDED = alias('memory limit exceeded', 'mle', 'ml')  # type: ignore
    """Expected outcome for solutions that use more memory than allowed."""

    OUTPUT_LIMIT_EXCEEDED = alias('output limit exceeded', 'ole', 'ol')  # type: ignore
    """Expected outcome for solutions that use more output than allowed."""

    TLE_OR_RTE = alias('tle or rte', 'tle/rte', 'tle+rte', 'tle or re', 'tle+re')  # type: ignore
    """Expected outcome for solutions that finish with either TLE or RTE.

    Especially useful for environments where TLE and RTE are indistinguishable."""

    MLE_OR_RTE = alias('mle or rte', 'mle/rte', 'mle+rte', 'ml or re', 'ml+re')  # type: ignore
    """Expected outcome for solutions that finish with either MLE or RTE.

    Which of the two a memory-hungry solution gets depends on how the memory limit is
    enforced, and that differs by platform: on Linux the address space is capped, so the
    allocation fails inside the program and it dies of a runtime error, while on macOS
    the solution is killed once its resident memory crosses the limit. Use this to
    declare a solution that exceeds the memory limit without pinning it to one of them."""

    TLE_OR_MLE = alias('tle or mle', 'tle/mle', 'tle+mle', 'tl or ml', 'tl+ml')  # type: ignore
    """Expected outcome for solutions that finish with either TLE or MLE.

    Especially useful for brute force solutions, which run out of whichever resource
    the test exhausts first. On Linux the address space is capped, so a solution that
    runs out of memory dies of a runtime error instead; declare it `TLE_OR_RTE` if it
    must pass there."""

    JUDGE_FAILED = alias('judge failed', 'jf')  # type: ignore
    """Expected outcome for solutions that finish with a judge failed verdict.

    Only useful for checker tests."""

    COMPILATION_ERROR = alias('compilation error', 'ce')  # type: ignore
    """Expected outcome for solutions that finish with a compilation error verdict.

    Only useful for checker tests."""

    def style(self) -> str:
        if self == ExpectedOutcome.ANY:
            return 'bold white'
        if self.match(Outcome.ACCEPTED):
            return 'green'
        if self == ExpectedOutcome.WRONG_ANSWER:
            return 'red'
        if self == ExpectedOutcome.PARTIALLY_CORRECT:
            return 'yellow'
        if self == ExpectedOutcome.INCORRECT:
            return 'red'
        if self.match(Outcome.TIME_LIMIT_EXCEEDED):
            return 'yellow'
        if self.match(Outcome.RUNTIME_ERROR):
            return 'blue'
        if self.match(Outcome.MEMORY_LIMIT_EXCEEDED):
            return 'yellow'
        if self.match(Outcome.COMPILATION_ERROR):
            return 'blue'
        return 'magenta'

    def icon(self) -> str:
        if self == ExpectedOutcome.ANY:
            return '?'
        if self.match(Outcome.ACCEPTED):
            return '✓'
        if self == ExpectedOutcome.PARTIALLY_CORRECT:
            return '~'
        if self.is_slow():
            return '⧖'
        return '✗'

    def icon_markup(self, styled: bool = True) -> str:
        icon = self.icon()
        if styled:
            style = self.style()
            icon = f'[{style}]{icon}[/{style}]'
        return icon

    def full_style(self) -> str:
        style = self.style()
        if self == ExpectedOutcome.ACCEPTED:
            return f'bold {style}'
        return style

    def full_markup(self, styled: bool = True) -> str:
        icon = self.icon_markup()
        name = self.name
        if styled:
            style = self.style()
            name = f'[{style}]{name}[/{style}]'
        return f'{icon} {name}'

    def is_slow(self) -> bool:
        return self in [
            ExpectedOutcome.TIME_LIMIT_EXCEEDED,
            ExpectedOutcome.TLE_OR_RTE,
            ExpectedOutcome.TLE_OR_MLE,
        ]

    def matches_tle_and_is_incorrect(self) -> bool:
        return self.match(Outcome.TIME_LIMIT_EXCEEDED) and not self.match(
            Outcome.ACCEPTED
        )

    def match(self, outcome: Outcome) -> bool:
        if self == ExpectedOutcome.ANY:
            return True
        # A skipped testcase was not awarded, so it satisfies any expectation
        # that does not demand success.
        if outcome == Outcome.SKIPPED:
            return self != ExpectedOutcome.ACCEPTED
        if self == ExpectedOutcome.COMPILATION_ERROR:
            return outcome == Outcome.COMPILATION_ERROR
        if self == ExpectedOutcome.ACCEPTED:
            return outcome == Outcome.ACCEPTED
        if self == ExpectedOutcome.ACCEPTED_OR_TLE:
            return outcome in {Outcome.ACCEPTED} or outcome.is_slow()
        if self == ExpectedOutcome.WRONG_ANSWER:
            return outcome == Outcome.WRONG_ANSWER
        if self == ExpectedOutcome.PARTIALLY_CORRECT:
            return outcome == Outcome.PARTIALLY_CORRECT
        if self == ExpectedOutcome.INCORRECT:
            return (
                outcome
                in {
                    Outcome.PARTIALLY_CORRECT,
                    Outcome.WRONG_ANSWER,
                    Outcome.RUNTIME_ERROR,
                    Outcome.MEMORY_LIMIT_EXCEEDED,
                    Outcome.OUTPUT_LIMIT_EXCEEDED,
                }
                or outcome.is_slow()
            )
        if self == ExpectedOutcome.RUNTIME_ERROR:
            return outcome == Outcome.RUNTIME_ERROR
        if self == ExpectedOutcome.TIME_LIMIT_EXCEEDED:
            return outcome.is_slow()
        if self == ExpectedOutcome.MEMORY_LIMIT_EXCEEDED:
            return outcome == Outcome.MEMORY_LIMIT_EXCEEDED
        if self == ExpectedOutcome.TLE_OR_RTE:
            return outcome in {Outcome.RUNTIME_ERROR} or outcome.is_slow()
        if self == ExpectedOutcome.TLE_OR_MLE:
            return outcome in {Outcome.MEMORY_LIMIT_EXCEEDED} or outcome.is_slow()
        if self == ExpectedOutcome.MLE_OR_RTE:
            return outcome in {
                Outcome.RUNTIME_ERROR,
                Outcome.MEMORY_LIMIT_EXCEEDED,
            }
        if self == ExpectedOutcome.OUTPUT_LIMIT_EXCEEDED:
            return outcome == Outcome.OUTPUT_LIMIT_EXCEEDED
        if self == ExpectedOutcome.JUDGE_FAILED:
            return outcome == Outcome.JUDGE_FAILED
        return False

    def get_matches(self) -> List[Outcome]:
        # SKIPPED is not a verdict a run can be awarded, and it satisfies almost
        # every expectation, so including it here would make every pair of bad
        # expectations look compatible in `intersect`.
        return [
            outcome
            for outcome in Outcome
            if outcome != Outcome.SKIPPED and self.match(outcome)
        ]

    def intersect(self, rhs: 'ExpectedOutcome') -> bool:
        return bool(set(self.get_matches()) & set(rhs.get_matches()))

ACCEPTED = alias('accepted', 'ac', 'correct') #

Expected outcome for correct solutions (AC).

ACCEPTED_OR_TLE = alias('accepted or time limit exceeded', 'accepted or tle', 'ac or tle', 'ac/tle', 'ac+tle') #

Expected outcome for solutions that finish with either AC or TLE.

Especially useful when you do not care about the running time of this solution, and want it to not be considered when calculating the timelimit for the problem.

ANY = alias('any') #

Expected outcome for any outcome.

COMPILATION_ERROR = alias('compilation error', 'ce') #

Expected outcome for solutions that finish with a compilation error verdict.

Only useful for checker tests.

INCORRECT = alias('fail', 'incorrect') #

Expected outcome for solutions that finish with any non-AC verdict.

JUDGE_FAILED = alias('judge failed', 'jf') #

Expected outcome for solutions that finish with a judge failed verdict.

Only useful for checker tests.

MEMORY_LIMIT_EXCEEDED = alias('memory limit exceeded', 'mle', 'ml') #

Expected outcome for solutions that use more memory than allowed.

MLE_OR_RTE = alias('mle or rte', 'mle/rte', 'mle+rte', 'ml or re', 'ml+re') #

Expected outcome for solutions that finish with either MLE or RTE.

Which of the two a memory-hungry solution gets depends on how the memory limit is enforced, and that differs by platform: on Linux the address space is capped, so the allocation fails inside the program and it dies of a runtime error, while on macOS the solution is killed once its resident memory crosses the limit. Use this to declare a solution that exceeds the memory limit without pinning it to one of them.

OUTPUT_LIMIT_EXCEEDED = alias('output limit exceeded', 'ole', 'ol') #

Expected outcome for solutions that use more output than allowed.

PARTIALLY_CORRECT = alias('partially correct', 'partial', 'pc') #

Expected outcome for solutions the checker awards part of a test's points (testlib quitp). Pin how many points with the solution's score.

RUNTIME_ERROR = alias('runtime error', 'rte', 're') #

Expected outcome solutions that finish with non-zero code (RTE).

TIME_LIMIT_EXCEEDED = alias('time limit exceeded', 'timeout', 'tle', 'tl') #

Expected outcome for solutions that do not finish in time.

TLE_OR_MLE = alias('tle or mle', 'tle/mle', 'tle+mle', 'tl or ml', 'tl+ml') #

Expected outcome for solutions that finish with either TLE or MLE.

Especially useful for brute force solutions, which run out of whichever resource the test exhausts first. On Linux the address space is capped, so a solution that runs out of memory dies of a runtime error instead; declare it TLE_OR_RTE if it must pass there.

TLE_OR_RTE = alias('tle or rte', 'tle/rte', 'tle+rte', 'tle or re', 'tle+re') #

Expected outcome for solutions that finish with either TLE or RTE.

Especially useful for environments where TLE and RTE are indistinguishable.

WRONG_ANSWER = alias('wrong answer', 'wa') #

Expected outcome for solutions that finish successfully, but the produced output are incorrect (WA).

FileAttachment #

Bases: BaseModel

Parameters:

Name Type Description Default
path Path

The file to attach, relative to the package directory.

required
name str | None

Name of the file inside the attachments archive. Defaults to the basename of path.

None
stripSecret bool

Derive the contestant version of a C/C++ source: every // BEGIN SECRET ... // END SECRET block is removed, and #include "rbx.h" is replaced by a public shim with no secrets and no vars. The result must compile on its own.

False
Source code in rbx/box/schema.py
class FileAttachment(BaseModel):
    model_config = ConfigDict(extra='forbid')

    path: pathlib.Path = Field(
        description='The file to attach, relative to the package directory.'
    )

    name: Optional[str] = Field(
        default=None,
        description='Name of the file inside the attachments archive. '
        'Defaults to the basename of `path`.',
    )

    stripSecret: bool = Field(
        default=False,
        description="""
Derive the contestant version of a C/C++ source: every `// BEGIN SECRET` ...
`// END SECRET` block is removed, and `#include "rbx.h"` is replaced by a public
shim with no secrets and no vars. The result must compile on its own.
""",
    )

    @property
    def archive_name(self) -> str:
        return self.name or self.path.name

Generator #

Bases: CodeItem

Parameters:

Name Type Description Default
name str

The name of the generator.

required
Source code in rbx/box/schema.py
class Generator(CodeItem):
    model_config = ConfigDict(extra='forbid')

    name: str = Field(description="""The name of the generator.""")

GeneratorCall #

Bases: BaseModel

Parameters:

Name Type Description Default
name str

The name of the generator to call.

required
args str | None

The arguments to pass to the generator.

None
Source code in rbx/box/schema.py
class GeneratorCall(BaseModel):
    model_config = ConfigDict(extra='forbid')

    name: str = Field(description='The name of the generator to call.')

    args: Optional[str] = Field(
        default=None, description='The arguments to pass to the generator.'
    )

    def __str__(self) -> str:
        return f'{self.name} {self.args}'

GeneratorScript #

Bases: CodeItem

Parameters:

Name Type Description Default
root Path

The root directory where the generators should be fetched from.

<dynamic>
format Literal['rbx', 'box']

The format of the generator script.

'rbx'
Source code in rbx/box/schema.py
class GeneratorScript(CodeItem):
    model_config = ConfigDict(extra='forbid')

    root: pathlib.Path = Field(
        default_factory=pathlib.Path,
        description="""The root directory where the generators should be fetched from.""",
    )

    format: Literal['rbx', 'box'] = Field(
        default='rbx', description="""The format of the generator script."""
    )

Grader #

Bases: CodeItem

A grader compiled together with every solution (IOI function-call tasks).

In a batch problem it owns main(), reads the test and prints what the checker reads. In a communication problem it is the stub that talks to the interactor on the contestant's behalf.

Parameters:

Name Type Description Default
secret str

The secret the grader's hidden test header and output framing are derived from. Use a long random string, and keep it out of anything participants receive: changing it changes every judge test and answer.

required
Source code in rbx/box/schema.py
class Grader(CodeItem):
    """A grader compiled together with every solution (IOI function-call tasks).

    In a batch problem it owns `main()`, reads the test and prints what the
    checker reads. In a communication problem it is the stub that talks to the
    interactor on the contestant's behalf.
    """

    model_config = ConfigDict(extra='forbid')

    secret: str = Field(
        min_length=1,
        description="""
The secret the grader's hidden test header and output framing are derived from.
Use a long random string, and keep it out of anything participants receive:
changing it changes every judge test and answer.
""",
    )

InferenceRole #

Bases: AutoEnum

Source code in rbx/box/schema.py
class InferenceRole(AutoEnum):
    LOWER = alias('lower')  # type: ignore
    """The solution bounds the inferred time limit from below.

    The limit will be large enough for this solution to comfortably pass."""

    UPPER = alias('upper')  # type: ignore
    """The solution bounds the inferred time limit from above.

    The limit will be small enough for this solution to comfortably time out."""

LOWER = alias('lower') #

The solution bounds the inferred time limit from below.

The limit will be large enough for this solution to comfortably pass.

UPPER = alias('upper') #

The solution bounds the inferred time limit from above.

The limit will be small enough for this solution to comfortably time out.

Interactor #

Bases: CodeItem

Parameters:

Name Type Description Default
legacy bool

Whether this interactor is a legacy interactor and needs a checker to be specified.

False
capture bool

Whether the interactor should capture the pipes.

True
processes int | None

How many copies of the solution run at once against this interactor, as in CMS Communication with num_processes. Each copy gets its 0-based index as its first command-line argument, and the interactor talks to them through rbx::registerFanoutInteraction. Unset means a single process.

None
Source code in rbx/box/schema.py
class Interactor(CodeItem):
    model_config = ConfigDict(extra='forbid')

    legacy: bool = Field(
        default=False,
        description="""
Whether this interactor is a legacy interactor and needs a checker to be specified.
""",
    )

    capture: bool = Field(
        default=True,
        description="""Whether the interactor should capture the pipes.""",
    )

    processes: Optional[int] = Field(
        default=None,
        ge=2,
        description="""
How many copies of the solution run at once against this interactor, as in CMS
`Communication` with `num_processes`. Each copy gets its 0-based index as its
first command-line argument, and the interactor talks to them through
`rbx::registerFanoutInteraction`. Unset means a single process.
""",
    )

LimitModifiers #

Bases: BaseModel

Parameters:

Name Type Description Default
timeMultiplier float | None

Multiplier for time limit.

None
time int | None

Value to override time limit with, in milliseconds.

None
memory int | None

Value to override memory limit with, in MB.

None
Source code in rbx/box/schema.py
class LimitModifiers(BaseModel):
    timeMultiplier: Optional[float] = Field(
        default=None, description='Multiplier for time limit.'
    )
    time: Optional[int] = Field(
        default=None, description='Value to override time limit with, in milliseconds.'
    )
    memory: Optional[int] = Field(
        default=None, description='Value to override memory limit with, in MB.'
    )

LimitsProfile #

Bases: BaseModel

Parameters:

Name Type Description Default
inheritFromPackage bool

Whether to inherit limits from the package.

False
timeLimit int | None

Time limit of the problem, in milliseconds.

None
memoryLimit int | None

Memory limit of the problem, in MB.

None
outputLimit int | None

Output limit of the problem, in KB.

None
modifiers Dict[str, LimitModifiers]

Limit modifiers that can be specified per language.

{}
formula str | None

A formula to estimate the time limit for the problem.

None
multipliers TimingMultipliers | None

The multipliers this profile was estimated from, when it was estimated from ratios instead of a formula. Presentation-only; never used for limit resolution.

None
groups List[TimingGroupReport] | None

Metadata describing the language grouping used when this profile was estimated. Presentation-only; never used for limit resolution.

None
baseEstimate TimingGroupReport | None

Metadata describing how the base (fallback) time limit was estimated, pooled across every solution. Presentation-only; never used for limit resolution.

None
estimationChecksum str | None

A checksum of everything this estimate was computed from -- the solutions that bound the limit, and, when the tests were built, the interactor and the test inputs. Written by rbx time; consumers compare it against the package to warn that a saved limit predates the current solutions or testset.

Presentation-only; never used for limit resolution. Absent on a profile whose limit was not estimated (inherited from the package, or set by hand).

None
runner str | None

The runner the estimate was measured on (local, moj, ...), as --runner names it. Written by rbx time; consumers compare it with where a run happened before showing that run's verdicts beside this profile, since timings taken on one machine say nothing about another. Presentation-only; never used for limit resolution. Absent on a profile written before it was recorded, or not estimated.

None
solutions List[EstimationSolutionTiming] | None

The timing of every solution the estimate was computed from. Written by rbx time and read by rbx time --edit, which checks a hand-set limit against each solution. Presentation-only; never used for limit resolution. Absent on a profile estimated before it was recorded.

None
runs List[LimitsProfileRun] | None

The verdict of every solution the estimate did not run, judged at the estimated limit. Written by rbx time --run-all and rbx preship once those runs finish. Presentation-only; never used for limit resolution. Absent when the profile was written without --run-all.

None
Source code in rbx/box/schema.py
class LimitsProfile(BaseModel):
    # Unknown keys are ignored, not refused -- the one model in this file that
    # tolerates them, and deliberately.
    #
    # A `limits/<name>.yml` is written by rbx (`rbx time --integrate`, the TUI
    # limits editor), so a setter reads profiles that a *different* rbx wrote:
    # a teammate's, or their own after an upgrade or a downgrade. Under
    # `extra='forbid'` every field added here is a hard break in that direction
    # -- the older rbx refuses to parse the profile at all, and the limits it
    # was going to run under are simply unavailable. `estimationChecksum` was
    # the field that made this concrete.
    #
    # Ignoring costs the typo-catching that `forbid` buys elsewhere, which is a
    # real loss on a file a setter may hand-edit. It is the smaller one: a
    # mistyped key falls back to a documented default, while a refused profile
    # stops the command. This is also what `run_report` already relies on for
    # the same reason -- see its `REPORT_VERSION` note on additive fields.
    model_config = ConfigDict(extra='ignore')

    inheritFromPackage: bool = Field(
        default=False,
        description="""
Whether to inherit limits from the package.
""",
    )

    timeLimit: Optional[int] = Field(
        default=None, description='Time limit of the problem, in milliseconds.'
    )

    memoryLimit: Optional[int] = Field(
        default=None, description='Memory limit of the problem, in MB.'
    )

    outputLimit: Optional[int] = Field(
        default=None, description='Output limit of the problem, in KB.'
    )

    modifiers: Dict[str, LimitModifiers] = Field(
        default={},
        description="""
    Limit modifiers that can be specified per language.
    """,
    )

    formula: Optional[str] = Field(
        default=None,
        description="""
A formula to estimate the time limit for the problem.
""",
    )

    multipliers: Optional[TimingMultipliers] = Field(
        default=None,
        description="""
The multipliers this profile was estimated from, when it was estimated from
ratios instead of a formula. Presentation-only; never used for limit resolution.
""",
    )

    groups: Optional[List[TimingGroupReport]] = Field(
        default=None,
        description="""
Metadata describing the language grouping used when this profile was estimated.
Presentation-only; never used for limit resolution.
""",
    )

    baseEstimate: Optional[TimingGroupReport] = Field(
        default=None,
        description="""
Metadata describing how the base (fallback) time limit was estimated, pooled
across every solution. Presentation-only; never used for limit resolution.
""",
    )

    estimationChecksum: Optional[str] = Field(
        default=None,
        description="""
A checksum of everything this estimate was computed from -- the solutions that
bound the limit, and, when the tests were built, the interactor and the test
inputs. Written by `rbx time`; consumers compare it against the package to warn
that a saved limit predates the current solutions or testset.

Presentation-only; never used for limit resolution. Absent on a profile whose
limit was not estimated (inherited from the package, or set by hand).
""",
    )

    runner: Optional[str] = Field(
        default=None,
        description="""
The runner the estimate was measured on (`local`, `moj`, ...), as `--runner`
names it. Written by `rbx time`; consumers compare it with where a run happened
before showing that run's verdicts beside this profile, since timings taken on
one machine say nothing about another. Presentation-only; never used for limit
resolution. Absent on a profile written before it was recorded, or not estimated.
""",
    )

    # Declared last on purpose: the profile is written in field order, and this
    # list -- one entry per timed solution -- is the bulkiest and least read part
    # of it. It goes below everything a setter opens the file for.
    solutions: Optional[List[EstimationSolutionTiming]] = Field(
        default=None,
        description="""
The timing of every solution the estimate was computed from. Written by
`rbx time` and read by `rbx time --edit`, which checks a hand-set limit against
each solution. Presentation-only; never used for limit resolution. Absent on a
profile estimated before it was recorded.
""",
    )

    # After `solutions`, and apart from it: these are not what the limit was
    # computed from, but what the rest of the package got under it.
    runs: Optional[List[LimitsProfileRun]] = Field(
        default=None,
        description="""
The verdict of every solution the estimate did not run, judged at the estimated
limit. Written by `rbx time --run-all` and `rbx preship` once those runs finish.
Presentation-only; never used for limit resolution. Absent when the profile was
written without `--run-all`.
""",
    )

    def timelimit_for_language(self, language: Optional[str] = None) -> int:
        assert self.timeLimit is not None
        res = self.timeLimit
        if language is not None and language in self.modifiers:
            modifier = self.modifiers[language]
            if modifier.time is not None:
                res = modifier.time
            if modifier.timeMultiplier is not None:
                res = int(res * float(modifier.timeMultiplier))
        if 'RBX_TIME_MULTIPLIER' in utils.environ():
            res = int(res * float(utils.environ()['RBX_TIME_MULTIPLIER']))
        return res

    def memorylimit_for_language(self, language: Optional[str] = None) -> int:
        assert self.memoryLimit is not None
        res = self.memoryLimit
        if language is None:
            return res
        if language not in self.modifiers:
            return res
        modifier = self.modifiers[language]
        if modifier.memory is not None:
            return modifier.memory
        return res

LimitsProfileRun #

Bases: BaseModel

How one solution fared when judged at the limit a profile estimated.

Not evidence the limit was computed from -- that is EstimationSolutionTiming -- but the verdict the rest of the package got under it, recorded by rbx time --run-all (and rbx preship) after the estimate was written.

Parameters:

Name Type Description Default
path str

The solution, as named in problem.rbx.yml.

required
language str

The language it ran as.

required
timeLimit int

The time limit, in milliseconds, it was judged at: the estimated limit of its language at the time it ran. A limit changed by hand afterwards does not change it, so a run can be told apart from the limit it no longer describes.

required
expectedOutcome ExpectedOutcome

The outcome problem.rbx.yml expects of it.

required
outcome Outcome | None

The worst verdict it got. Absent when no testcase was judged.

None
matchesExpectation bool

Whether it behaved as problem.rbx.yml says it does.

required
time int | None

Its running time, in milliseconds, on its slowest testcase. Absent when no testcase reported a time.

None
complete bool | None

false when the run stopped before judging every testcase (--fail-fast): its verdict holds, but its time is only a lower bound. Absent when every testcase was judged.

None
Source code in rbx/box/schema.py
class LimitsProfileRun(BaseModel):
    """How one solution fared when judged at the limit a profile estimated.

    Not evidence the limit was computed from -- that is `EstimationSolutionTiming`
    -- but the verdict the rest of the package got under it, recorded by
    `rbx time --run-all` (and `rbx preship`) after the estimate was written.
    """

    # Ignored rather than refused, for the reason `LimitsProfile` gives.
    model_config = ConfigDict(extra='ignore')

    path: str = Field(description='The solution, as named in `problem.rbx.yml`.')

    language: str = Field(description='The language it ran as.')

    timeLimit: int = Field(
        description="""The time limit, in milliseconds, it was judged at: the
estimated limit of its language at the time it ran. A limit changed by hand
afterwards does not change it, so a run can be told apart from the limit it no
longer describes."""
    )

    expectedOutcome: ExpectedOutcome = Field(
        description='The outcome `problem.rbx.yml` expects of it.'
    )

    outcome: Optional[Outcome] = Field(
        default=None,
        description='The worst verdict it got. Absent when no testcase was judged.',
    )

    matchesExpectation: bool = Field(
        description='Whether it behaved as `problem.rbx.yml` says it does.'
    )

    time: Optional[int] = Field(
        default=None,
        description="""Its running time, in milliseconds, on its slowest testcase.
Absent when no testcase reported a time.""",
    )

    complete: Optional[bool] = Field(
        default=None,
        description="""`false` when the run stopped before judging every testcase
(`--fail-fast`): its verdict holds, but its time is only a lower bound. Absent
when every testcase was judged.""",
    )

OutputFromItem #

Bases: CodeItem

Parameters:

Name Type Description Default
stderr bool

Whether the output should be taken from stderr instead of the stdout.

False
Source code in rbx/box/schema.py
class OutputFromItem(CodeItem):
    model_config = ConfigDict(extra='forbid')

    stderr: bool = Field(
        default=False,
        description="""Whether the output should be taken from stderr instead of the stdout.""",
    )

OutputFromItemWithDigest #

Bases: OutputFromItem, CodeItemWithDigest

Source code in rbx/box/schema.py
class OutputFromItemWithDigest(OutputFromItem, CodeItemWithDigest):
    model_config = ConfigDict(extra='forbid')

    @classmethod
    def create(
        cls, output_from_item: OutputFromItem, digest: str
    ) -> 'OutputFromItemWithDigest':
        return cls(
            path=output_from_item.path,
            language=output_from_item.language,
            compilationFiles=output_from_item.compilationFiles,
            executionFiles=output_from_item.executionFiles,
            digest=digest,
        )

Package #

Bases: BaseModel

Parameters:

Name Type Description Default
name str

The name of the problem.

required
titles Dict[str, str]

Titles for the problem in each language. Languages should be specified as lowercase ISO 639-1 codes.

{}
languages List[str] | None

Languages this package ships statements in, as lowercase ISO 639-1 codes. Statements declared with language: "*" expand to one entry per language listed here. A problem inside a contest inherits the contest list when unset.

None
type TaskType

The type of the problem.

BATCH
scoring ScoreType | PointsScoring

The scoring type of the problem: binary, points, or a mapping configuring points scoring (points is the mapping with every default).

scoring:
  dependencies: ladder
BINARY
timeLimit int

Time limit of the problem, in milliseconds.

required
memoryLimit int

Memory limit of the problem, in MB.

required
outputLimit int

Output limit of the problem, in KB.

4096
timing PackageTiming | None

Problem-level overrides for time limit inference.

None
modifiers Dict[str, LimitModifiers]

Limit modifiers that can be specified per language.

{}
checker Checker | None

The checker for this problem.

None
interactor Interactor | None

The interactor for this problem.

None
grader Grader | None

The grader of a function-call problem (C++ only). It is compiled together with every solution: in a batch problem it owns main() and its output goes to the checker; in a communication problem it is the stub that talks to the interactor.

None
attachments List[FileAttachment | SamplesAttachment]

Files given to contestants, packed into one archive per problem (e.g. a public grader, the task header and a solution template).

[]
validator CodeItem | None

The validator for this problem.

None
extraValidators List[CodeItem]

Extra validators for this problem.

[]
outputValidators List[CodeItem]

A list of output validators to use to validate the output of the testcases of this problem.

[]
visualizer Visualizer | None

The visualizer for this problem. Used to produced visualizations for the testcases.

None
solutionVisualizer Visualizer | None

The solution visualizer for this problem. Used to produced visualizations for the outputs of the testcases.

None
generators List[Generator]

Generators for this problem.

[]
generatorScript GeneratorScript | None

A generator script used as the default for any test group or subgroup that does not specify its own test parameters (testcases, testcaseGlob, generators, generatorScript) and has no subgroups of its own.

Useful when a single script -- usually partitioned with @testgroup blocks -- drives generation for every group, so it does not need to be repeated on each one.

None
solutions List[Solution]

All tested solutions for this problem.

The first solution in this list should be the main solution -- the one that is correct and used as reference -- and should have the accepted outcome.

[]
testcases List[TestcaseGroup]

Testcases for the problem.

[]
stresses List[Stress]

Stress tests for the problem.

[]
statements List[Statement]

Statements for the problem.

[]
tutorials List[Statement]

Tutorials (editorials) for the problem.

[]
vars RecVars

Variables to be re-used across the package.

{}
unitTests UnitTests

Unit tests for components of this problem.

<dynamic>
issues IssuesConfig

Which issues rbx issues and rbx run report for this problem.

<dynamic>
Source code in rbx/box/schema.py
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
class Package(BaseModel):
    model_config = ConfigDict(extra='forbid')

    # `!include` fragments are resolved when loading this model (see
    # rbx.box.yaml_include). Only the four user-authored config kinds people
    # actually share between packages are include-capable; everything else --
    # limits profiles, locks, registries, generated artifacts -- loads plainly
    # and is written back from the model, which would inline any fragment.
    rbx_include_capable: ClassVar[bool] = True

    # Name of the problem.
    name: str = NameField(description='The name of the problem.')

    titles: Dict[str, str] = Field(
        default={},
        description='Titles for the problem in each language. '
        'Languages should be specified as lowercase ISO 639-1 codes.',
    )

    languages: LanguagesList = LanguagesField()

    # Languages inherited from the enclosing contest, injected by the package
    # loader: a model cannot see its contest. Never part of the yml.
    _inherited_languages: Optional[List[str]] = PrivateAttr(default=None)

    type: TaskType = Field(
        default=TaskType.BATCH, description='The type of the problem.'
    )

    scoring: Annotated[
        Union[
            Annotated[ScoreType, Tag('type')],
            Annotated[PointsScoring, Tag('points')],
        ],
        Discriminator(
            lambda v: 'type' if isinstance(v, (str, ScoreType)) else 'points'
        ),
    ] = Field(
        default=ScoreType.BINARY,
        description="""
The scoring type of the problem: `binary`, `points`, or a mapping configuring
points scoring (`points` is the mapping with every default).

```yaml
scoring:
  dependencies: ladder
```
""",
    )

    @field_validator('scoring', mode='before')
    @classmethod
    def expand_points_shorthand(cls, value: Any) -> Any:
        if isinstance(value, str) and value.lower() == 'points':
            return PointsScoring()
        if value == ScoreType.POINTS:
            return PointsScoring()
        return value

    timeLimit: int = Field(description='Time limit of the problem, in milliseconds.')

    memoryLimit: int = Field(description='Memory limit of the problem, in MB.')

    outputLimit: int = Field(
        default=4 * 1024, description='Output limit of the problem, in KB.'
    )

    timing: Optional[PackageTiming] = Field(
        default=None,
        description='Problem-level overrides for time limit inference.',
    )

    modifiers: Dict[str, LimitModifiers] = Field(
        default={},
        description="""
    Limit modifiers that can be specified per language.
    """,
    )

    checker: Optional[Checker] = Field(
        default=None, description='The checker for this problem.'
    )

    interactor: Optional[Interactor] = Field(
        default=None, description='The interactor for this problem.'
    )

    grader: Optional[Grader] = Field(
        default=None,
        description="""
The grader of a function-call problem (C++ only). It is compiled together with
every solution: in a batch problem it owns `main()` and its output goes to the
checker; in a communication problem it is the stub that talks to the interactor.
""",
    )

    attachments: List[Attachment] = Field(
        default=[],
        description="""
Files given to contestants, packed into one archive per problem (e.g. a public
grader, the task header and a solution template).
""",
    )

    validator: Optional[CodeItem] = Field(
        default=None, description='The validator for this problem.'
    )

    extraValidators: List[CodeItem] = Field(
        default=[], description='Extra validators for this problem.'
    )

    outputValidators: List[CodeItem] = Field(
        default=[],
        description="""
A list of output validators to use to validate the output of the testcases of this problem.
""",
    )

    visualizer: Optional[Visualizer] = Field(
        default=None,
        description='The visualizer for this problem. Used to produced visualizations for the testcases.',
    )

    solutionVisualizer: Optional[Visualizer] = Field(
        default=None,
        description='The solution visualizer for this problem. Used to produced visualizations for the outputs of the testcases.',
    )

    generators: List[Generator] = Field(
        default=[], description='Generators for this problem.'
    )

    generatorScript: Optional[GeneratorScript] = Field(
        default=None,
        description="""
A generator script used as the default for any test group or subgroup that does
not specify its own test parameters (testcases, testcaseGlob, generators,
generatorScript) and has no subgroups of its own.

Useful when a single script -- usually partitioned with `@testgroup` blocks --
drives generation for every group, so it does not need to be repeated on each one.
""",
    )

    solutions: List[Solution] = Field(
        default=[],
        description="""
All tested solutions for this problem.

The first solution in this list should be the main solution -- the one
that is correct and used as reference -- and should have the `accepted` outcome.
""",
    )

    testcases: Annotated[
        List[TestcaseGroup],
        AfterValidator(is_unique_testcase_group_names),
    ] = Field(default=[], description='Testcases for the problem.')

    stresses: List[Stress] = Field(
        default=[], description='Stress tests for the problem.'
    )

    statements: Annotated[
        List[Statement],
        AfterValidator(is_unique_problem_statements),
    ] = Field(default=[], description='Statements for the problem.')

    tutorials: Annotated[
        List[Statement],
        AfterValidator(is_unique_problem_statements),
    ] = Field(default=[], description='Tutorials (editorials) for the problem.')

    # Vars to be re-used across the package.
    #   - It will be passed as --key=value arguments to the validator.
    #   - It will be available as \VAR{key} variables in the rbx statement.
    vars: CheckedRecVars = Field(
        default={}, description='Variables to be re-used across the package.'
    )

    unitTests: UnitTests = Field(
        default_factory=UnitTests,
        description='Unit tests for components of this problem.',
    )

    issues: IssuesConfig = Field(
        default_factory=IssuesConfig,
        description='Which issues `rbx issues` and `rbx run` report for this problem.',
    )

    def set_inherited_languages(self, languages: Optional[List[str]]) -> None:
        self._inherited_languages = languages

    @property
    def effective_languages(self) -> List[str]:
        """The languages wildcard statements expand to: own `languages:`, else
        the enclosing contest's, else the distinct languages of the concrete
        statement/tutorial entries in order of appearance."""
        if self.languages is not None:
            return list(self.languages)
        if self._inherited_languages is not None:
            return list(self._inherited_languages)
        return concrete_languages(self.statements + self.tutorials)

    @property
    def expanded_statements(self) -> List[Statement]:
        return expand_problem_statements(
            expand_problem_wildcards(self.statements, self.effective_languages)
        )

    @property
    def expanded_tutorials(self) -> List[Statement]:
        return expand_problem_statements(
            expand_problem_wildcards(self.tutorials, self.effective_languages)
        )

    @property
    def expanded_vars(self) -> Vars:
        return expand_vars(self.vars)

    @property
    def is_communication(self) -> bool:
        """Whether an interactor judges this problem, with one process or several.

        Ask this when the code needs *an interactor* (compile it, pass it along,
        take the answer from its output); ask `is_interactive` / `is_fanout`
        when it depends on how many processes it talks to.
        """
        return self.type == TaskType.COMMUNICATION

    @property
    def fanout_processes(self) -> Optional[int]:
        """How many contestant processes the interactor talks to, when more than one."""
        if not self.is_communication or self.interactor is None:
            return None
        return self.interactor.processes

    @property
    def is_fanout(self) -> bool:
        """A communication problem whose interactor talks to several processes."""
        return self.fanout_processes is not None

    @property
    def is_interactive(self) -> bool:
        """A communication problem with a single contestant process."""
        return self.is_communication and not self.is_fanout

    @property
    def score_type(self) -> ScoreType:
        if isinstance(self.scoring, PointsScoring):
            return ScoreType.POINTS
        return self.scoring

    @property
    def points_scoring(self) -> Optional[PointsScoring]:
        """The points configuration, or `None` for a binary problem."""
        if isinstance(self.scoring, PointsScoring):
            return self.scoring
        return None

    def aggregation_for(self, group_name: str) -> Aggregation:
        """How a group's test scores combine: its own `aggregation`, else the
        problem's. Binary problems are `min`."""
        points = self.points_scoring
        default = points.aggregation if points is not None else Aggregation.MIN
        for group in self.testcases:
            if group.name == group_name and group.aggregation is not None:
                return group.aggregation
        return default

    @property
    def group_dependencies(self) -> GroupDependencies:
        """The groups each group depends on, `scoring.dependencies` included.

        Read dependencies from here, never from `TestcaseGroup.deps`, which holds
        only the declared ones.
        """
        return resolve_dependencies(self)

    def expanded_vars_for_group(self, group_name: Optional[str]) -> Vars:
        """Package vars with the named group's overrides applied.

        The merge happens before expansion, so an override can feed the
        interpolation of any var derived from it.

        Falls back to the package vars when ``group_name`` is None or names no
        declared group (interactive validation, unit tests, samples).
        """
        if group_name is None:
            return self.expanded_vars
        for testcase_group in self.testcases:
            if testcase_group.name == group_name:
                return expand_vars(merge_recvars(self.vars, testcase_group.vars))
        return self.expanded_vars

    @model_validator(mode='after')
    def check_first_solution_is_main_if_there_is_ac(self):
        if all(sol.outcome != ExpectedOutcome.ACCEPTED for sol in self.solutions):
            # No main solution.
            return self
        if self.solutions:
            if self.solutions[0].outcome != ExpectedOutcome.ACCEPTED:
                raise PydanticCustomError(
                    'MISSING_MAIN_SOLUTION',
                    'The first solution in the package must have the "ACCEPTED" outcome if there are ACCEPTED solutions.',
                )
        return self

    @model_validator(mode='after')
    def samples_come_first(self):
        for i, group in enumerate(self.testcases):
            if group.name == 'samples' and i > 0:
                raise PydanticCustomError(
                    'SAMPLES_NOT_FIRST',
                    'The "samples" group must be the first group in the package, but is actually the {i}-th',
                    {'i': i + 1},
                )
        return self

    @model_validator(mode='after')
    def check_scoring_fields(self):
        if self.score_type != ScoreType.POINTS:
            for group in self.testcases:
                if group.deps:
                    raise PydanticCustomError(
                        'DEPS_NOT_ALLOWED',
                        'Dependencies are not allowed for groups of problems with scoring != POINTS.',
                    )
                if group.score != 0:
                    raise PydanticCustomError(
                        'SCORE_NOT_ALLOWED',
                        'Non-zero score is not allowed for groups of problems with scoring != POINTS.',
                    )
                if group.aggregation is not None:
                    raise PydanticCustomError(
                        'AGGREGATION_NOT_ALLOWED',
                        'Aggregation is not allowed for groups of problems with scoring != POINTS.',
                    )
            for solution in self.solutions:
                if solution.score is not None:
                    raise PydanticCustomError(
                        'SCORE_NOT_ALLOWED',
                        'Expected score is not allowed for solutions of problems with scoring != POINTS.',
                    )
                # A BINARY problem judges the testset as one pooled verdict, so a
                # per-group expectation has no scoring semantics to attach to.
                # Rejecting it here lets every consumer downstream assume the
                # per-group layer only ever exists under POINTS.
                if solution.outcomePerGroup:
                    raise PydanticCustomError(
                        'OUTCOME_PER_GROUP_NOT_ALLOWED',
                        'Per-group expected outcomes ("outcomePerGroup") are not allowed '
                        'for solutions of problems with scoring != POINTS, since such '
                        'problems are judged as a single pooled verdict over the whole '
                        'testset. Use "outcome", or set "scoring: points".',
                    )
        return self

    @model_validator(mode='after')
    def check_deps(self):
        for group in self.testcases:
            if group.name == 'samples' and group.deps:
                raise PydanticCustomError(
                    'DEPS_NOT_ALLOWED',
                    'Dependencies are not allowed for the "samples" group.',
                )
        group_names = set(group.name for group in self.testcases)
        for group in self.testcases:
            for dep in group.deps:
                if dep not in group_names:
                    raise PydanticCustomError(
                        'UNKNOWN_DEPENDENCY',
                        'Test group "{group_name}" depends on "{dep}", which is not '
                        'a declared test group.',
                        {'group_name': group.name, 'dep': dep},
                    )
        # Over the resolved graph, so a policy edge closing a cycle with a
        # declared one is caught too.
        depends = self.group_dependencies

        visiting = set()
        visited = set()

        def dfs(u):
            visiting.add(u)
            for v in depends.direct(u):
                if v in visiting:
                    return True
                if v not in visited:
                    if dfs(v):
                        return True
            visiting.remove(u)
            visited.add(u)
            return False

        for group in self.testcases:
            if group.name != 'samples' and group.name not in visited:
                if dfs(group.name):
                    raise PydanticCustomError(
                        'CYCLIC_DEPENDENCY',
                        'Cyclic dependency detected involving test group "{group_name}".',
                        {'group_name': group.name},
                    )
        return self

    # The three `outcomePerGroup` validators below run in declaration order, and
    # that order is load-bearing: an unknown group name is reported before any
    # verdict about satisfiability (a typo'd key resolves to nothing, so every
    # later conclusion about it would be noise), and the main-solution check
    # deliberately pre-empts the vaguer CONTRADICTORY_OUTCOME error, which would
    # otherwise fire first for a reference solution pinned to a bad outcome.
    @model_validator(mode='after')
    def check_outcome_per_group_names(self):
        group_names = set(group.name for group in self.testcases)
        for solution in self.solutions:
            for group_name in solution.outcomePerGroup:
                if group_name == PER_GROUP_OUTCOME_WILDCARD:
                    continue
                if group_name not in group_names:
                    raise PydanticCustomError(
                        'UNKNOWN_OUTCOME_GROUP',
                        'Solution "{path}" declares an expected outcome for group '
                        '"{group}", which is not a testcase group of this package. '
                        'Known groups: {known}.',
                        {
                            'path': str(solution.path),
                            'group': group_name,
                            'known': ', '.join(group.name for group in self.testcases),
                        },
                    )
        return self

    @model_validator(mode='after')
    def check_main_solution_outcome_per_group(self):
        main = next(
            (sol for sol in self.solutions if sol.outcome == ExpectedOutcome.ACCEPTED),
            None,
        )
        if main is None:
            # No reference solution, so there is nothing to hold to ACCEPTED.
            return self
        for group_name, expected in main.outcomePerGroup.items():
            if expected.match(Outcome.ACCEPTED):
                continue
            if group_name == PER_GROUP_OUTCOME_WILDCARD:
                raise PydanticCustomError(
                    'MAIN_SOLUTION_NOT_ACCEPTED',
                    'The first accepted solution generates the reference outputs, so '
                    'it must be accepted everywhere, but it expects "{expected}" as '
                    'the default for every group ("*").',
                    {'expected': expected.name},
                )
            raise PydanticCustomError(
                'MAIN_SOLUTION_NOT_ACCEPTED',
                'The first accepted solution generates the reference outputs, so it '
                'must be accepted everywhere, but it expects "{expected}" on '
                '"{group}".',
                {'expected': expected.name, 'group': group_name},
            )
        return self

    @model_validator(mode='after')
    def check_outcome_per_group_is_satisfiable(self):
        for solution in self.solutions:
            if not solution.outcomePerGroup:
                continue
            for group_name, expected in solution.outcomePerGroup.items():
                if expected.match(Outcome.ACCEPTED):
                    # The group admits a fully accepted run, which never
                    # conflicts with the pooled expectation.
                    continue
                # The group demands a bad verdict; the pooled expectation must
                # admit at least one of the verdicts that would satisfy it.
                if not solution.outcome.intersect(expected):
                    raise PydanticCustomError(
                        'CONTRADICTORY_OUTCOME',
                        'Solution "{path}" expects "{expected}" on "{group}", which '
                        'cannot be satisfied together with the expected outcome '
                        '"{outcome}" for the whole testset.',
                        {
                            'path': str(solution.path),
                            'expected': expected.name,
                            'group': group_name,
                            'outcome': solution.outcome.name,
                        },
                    )

            if solution.outcome.match(Outcome.ACCEPTED) or not self.testcases:
                continue
            # The pooled expectation demands a bad verdict *somewhere*. If every
            # group is individually pinned to an outcome that admits none, there
            # is nowhere for it to happen.
            pinned = [
                solution.expected_outcome_for_group(group.name)
                for group in self.testcases
            ]
            if any(expected is None for expected in pinned):
                # Some group is unconstrained, so it is free to host the failure.
                continue
            # `solution.outcome` does not match ACCEPTED here, so every verdict it
            # matches is a bad one: some group's expectation must admit one of them.
            some_group_can_fail = any(
                solution.outcome.match(verdict)
                for expected in pinned
                for verdict in expected.get_matches()
            )
            if not some_group_can_fail:
                raise PydanticCustomError(
                    'CONTRADICTORY_OUTCOME',
                    'Solution "{path}" expects "{outcome}" for the whole testset, '
                    'but every group is pinned to an outcome that cannot produce '
                    'it, so the expectation cannot be satisfied.',
                    {'path': str(solution.path), 'outcome': solution.outcome.name},
                )
        return self

    @model_validator(mode='after')
    def check_checker_and_interactor_for_task_type(self):
        if self.type == TaskType.BATCH:
            if self.interactor is not None:
                raise PydanticCustomError(
                    'INTERACTOR_NOT_ALLOWED',
                    'Interactor is not allowed for batch problems. Change the task type to COMMUNICATION.',
                )
        if self.type == TaskType.COMMUNICATION:
            if self.checker is not None and (
                self.interactor is None or not self.interactor.legacy
            ):
                raise PydanticCustomError(
                    'CHECKER_NOT_ALLOWED',
                    'Checkers should not be specified for communication problems.',
                )
        return self

    @model_validator(mode='after')
    def check_grader(self):
        if self.grader is None:
            return self
        if self.interactor is not None and self.interactor.legacy:
            raise PydanticCustomError(
                'GRADER_WITH_LEGACY_INTERACTOR',
                'A grader cannot be combined with a legacy interactor: the '
                'interactor must judge the interaction on its own.',
            )
        return self

effective_languages #

The languages wildcard statements expand to: own languages:, else the enclosing contest's, else the distinct languages of the concrete statement/tutorial entries in order of appearance.

fanout_processes #

How many contestant processes the interactor talks to, when more than one.

group_dependencies #

The groups each group depends on, scoring.dependencies included.

Read dependencies from here, never from TestcaseGroup.deps, which holds only the declared ones.

is_communication #

Whether an interactor judges this problem, with one process or several.

Ask this when the code needs an interactor (compile it, pass it along, take the answer from its output); ask is_interactive / is_fanout when it depends on how many processes it talks to.

is_fanout #

A communication problem whose interactor talks to several processes.

is_interactive #

A communication problem with a single contestant process.

points_scoring #

The points configuration, or None for a binary problem.

aggregation_for(group_name) #

How a group's test scores combine: its own aggregation, else the problem's. Binary problems are min.

Source code in rbx/box/schema.py
def aggregation_for(self, group_name: str) -> Aggregation:
    """How a group's test scores combine: its own `aggregation`, else the
    problem's. Binary problems are `min`."""
    points = self.points_scoring
    default = points.aggregation if points is not None else Aggregation.MIN
    for group in self.testcases:
        if group.name == group_name and group.aggregation is not None:
            return group.aggregation
    return default

expanded_vars_for_group(group_name) #

Package vars with the named group's overrides applied.

The merge happens before expansion, so an override can feed the interpolation of any var derived from it.

Falls back to the package vars when group_name is None or names no declared group (interactive validation, unit tests, samples).

Source code in rbx/box/schema.py
def expanded_vars_for_group(self, group_name: Optional[str]) -> Vars:
    """Package vars with the named group's overrides applied.

    The merge happens before expansion, so an override can feed the
    interpolation of any var derived from it.

    Falls back to the package vars when ``group_name`` is None or names no
    declared group (interactive validation, unit tests, samples).
    """
    if group_name is None:
        return self.expanded_vars
    for testcase_group in self.testcases:
        if testcase_group.name == group_name:
            return expand_vars(merge_recvars(self.vars, testcase_group.vars))
    return self.expanded_vars

PackageTiming #

Bases: BaseModel

Parameters:

Name Type Description Default
inferenceTimeout int | None

Overrides the environment inferenceTimeout: the time limit (in milliseconds) enforced on every solution run while the time limit is estimated, whatever the estimation strategy is. Raise it for a problem whose solutions are slower than the environment expects.

None
multipliers TimingMultipliersOverride | None

Per-problem overrides of the environment's timing multipliers. Only the declared fields are overridden.

None
Source code in rbx/box/schema.py
class PackageTiming(BaseModel):
    model_config = ConfigDict(extra='forbid')

    inferenceTimeout: Optional[int] = Field(
        default=None,
        gt=0,
        description="""Overrides the environment `inferenceTimeout`: the time limit
(in milliseconds) enforced on every solution run while the time limit is estimated,
whatever the estimation strategy is. Raise it for a problem whose solutions are
slower than the environment expects.""",
    )

    multipliers: Optional[TimingMultipliersOverride] = Field(
        default=None,
        description="""Per-problem overrides of the environment's timing
multipliers. Only the declared fields are overridden.""",
    )

    @model_validator(mode='after')
    def _validate_single_inference_timeout(self):
        if (
            self.inferenceTimeout is not None
            and self.multipliers is not None
            and self.multipliers.inferenceTimeout is not None
        ):
            raise ValueError(
                'timing.inferenceTimeout and timing.multipliers.inferenceTimeout '
                'are the same setting; keep only timing.inferenceTimeout.'
            )
        return self

PointsScoring #

Bases: BaseModel

Subtasks scoring, configured. Writing scoring: points means the defaults.

Parameters:

Name Type Description Default
dependencies DependencyPolicy

Which dependencies between groups are added on top of the deps each group declares. A group only scores when every group it depends on, directly or not, scored too.

  • manual: none; only the declared deps.
  • samples: every group depends on samples, so failing a sample scores 0.
  • ladder: every group depends on the one declared before it, the first one on samples, so a group only scores when every earlier one did.
MANUAL
aggregation Aggregation

How the results of a group's tests combine into the group's score, unless the group sets its own aggregation. A test scores 1 when it passes, 0 when it fails, and the percentage a checker's quitp awards in between.

  • min: the group scores its score times the lowest score among its tests: all of it when every test passes, nothing when any fails.
  • sum: each test is worth an even share of the group's score and pays it times its own score.
MIN
Source code in rbx/box/schema.py
class PointsScoring(BaseModel):
    """Subtasks scoring, configured. Writing `scoring: points` means the defaults."""

    model_config = ConfigDict(extra='forbid')

    dependencies: DependencyPolicy = Field(
        default=DependencyPolicy.MANUAL,
        description="""
Which dependencies between groups are added on top of the `deps` each group
declares. A group only scores when every group it depends on, directly or not,
scored too.

- `manual`: none; only the declared `deps`.
- `samples`: every group depends on `samples`, so failing a sample scores 0.
- `ladder`: every group depends on the one declared before it, the first one on
  `samples`, so a group only scores when every earlier one did.
""",
    )

    aggregation: Aggregation = Field(
        default=Aggregation.MIN,
        description="""
How the results of a group's tests combine into the group's score, unless the
group sets its own `aggregation`. A test scores 1 when it passes, 0 when it
fails, and the percentage a checker's `quitp` awards in between.

- `min`: the group scores its `score` times the lowest score among its tests: all
  of it when every test passes, nothing when any fails.
- `sum`: each test is worth an even share of the group's `score` and pays it times
  its own score.
""",
    )

SamplesAttachment #

Bases: BaseModel

Parameters:

Name Type Description Default
samples str

Directory inside the attachments archive that receives every sample as NN.in / NN.out.

required
Source code in rbx/box/schema.py
class SamplesAttachment(BaseModel):
    model_config = ConfigDict(extra='forbid')

    samples: str = Field(
        description='Directory inside the attachments archive that receives every '
        'sample as `NN.in` / `NN.out`.',
    )

ScoreType #

Bases: AutoEnum

Source code in rbx/box/schema.py
class ScoreType(AutoEnum):
    BINARY = alias('binary')  # type: ignore
    """Scoring for ICPC-like problems, where the problem is considered a point if it pass all testcases."""

    POINTS = alias('points')  # type: ignore
    """Subtasks scoring, where each passing testgroup is worth a number of points that are summed up."""

BINARY = alias('binary') #

Scoring for ICPC-like problems, where the problem is considered a point if it pass all testcases.

POINTS = alias('points') #

Subtasks scoring, where each passing testgroup is worth a number of points that are summed up.

Solution #

Bases: CodeItem

Parameters:

Name Type Description Default
outcome ExpectedOutcome

The expected outcome of this solution.

ANY
outcomePerGroup Dict[str, ExpectedOutcome]

The expected outcome of this solution for each testcase group, keyed by group name.

Only available for problems with scoring: points. A binary-scored problem is judged as a single pooled verdict over the whole testset, so its groups carry no independent judgement for an expectation to attach to; declaring this field there is an error.

Keys must be top-level group names declared in testcases; subgroups are not addressable here.

The reserved key * sets a default that applies to every group individually, including samples -- add an explicit samples entry to override it there. An entry for a specific group takes precedence over *. Groups that match neither are not checked individually.

This is an extra layer of expectations, checked in addition to outcome: outcome keeps being matched against the whole testset at once, while each entry here is matched against that group's tests alone. A solution fails if either layer fails.

scoring: points
solutions:
  - path: 'sols/partial.cpp'
    outcome: incorrect  # fails somewhere in the testset
    outcomePerGroup:
      '*': accepted     # ...but is correct on every group
      group3: tle       # ...except group3, where it must time out
{}
inference Literal[False] | InferenceRole | None

The role this solution plays when inferring the time limit.

When unset, the role follows the expected outcomes of this solution: a solution expected to be accepted everywhere bounds the time limit from below, a solution expected to be slow (tle, tle-or-rte) anywhere bounds it from above, and anything else -- notably accepted-or-tle -- bounds neither side.

Set it explicitly to override that:

  • false: the solution is left out of the estimation entirely -- it is not run and bounds neither side.
  • lower: the time limit must be large enough for this solution to pass. Not allowed for solutions expected to be slow.
  • upper: the time limit must be small enough for this solution to time out.
solutions:
  - path: 'sols/borderline.cpp'
    outcome: accepted-or-tle
    inference: upper
None
tags List[str]

Tags to be associated with this solution.

[]
score float | Tuple[float | None, float | None] | None

The score of this solution in the final score. Should either be a number, which means the solution should have this exact score, or a tuple of two numbers, which means the solution should have a score between the two numbers (inclusive). Scores are compared rounded to two decimals.

If one of the numbers is set to be null, it means that the solution should have a score between the other number and negative/positive infinity.

None
Source code in rbx/box/schema.py
class Solution(CodeItem):
    model_config = ConfigDict(extra='forbid')

    outcome: ExpectedOutcome = Field(
        default=ExpectedOutcome.ANY,
        description="""The expected outcome of this solution.""",
    )

    outcomePerGroup: Dict[str, ExpectedOutcome] = Field(
        default={},
        description="""The expected outcome of this solution for each testcase group,
keyed by group name.

Only available for problems with `scoring: points`. A binary-scored problem is
judged as a single pooled verdict over the whole testset, so its groups carry no
independent judgement for an expectation to attach to; declaring this field there
is an error.

Keys must be top-level group names declared in `testcases`; subgroups are not
addressable here.

The reserved key `*` sets a default that applies to every group *individually*,
including `samples` -- add an explicit `samples` entry to override it there.
An entry for a specific group takes precedence over `*`. Groups that match
neither are not checked individually.

This is an extra layer of expectations, checked *in addition* to `outcome`:
`outcome` keeps being matched against the whole testset at once, while each
entry here is matched against that group's tests alone. A solution fails if
either layer fails.

```yaml
scoring: points
solutions:
  - path: 'sols/partial.cpp'
    outcome: incorrect  # fails somewhere in the testset
    outcomePerGroup:
      '*': accepted     # ...but is correct on every group
      group3: tle       # ...except group3, where it must time out
```
""",
    )

    inference: Optional[Union[Literal[False], InferenceRole]] = Field(
        default=None,
        description="""The role this solution plays when inferring the time limit.

When unset, the role follows the expected outcomes of this solution: a solution
expected to be `accepted` everywhere bounds the time limit from below, a
solution expected to be slow (`tle`, `tle-or-rte`) anywhere bounds it from
above, and anything else -- notably `accepted-or-tle` -- bounds neither side.

Set it explicitly to override that:

- `false`: the solution is left out of the estimation entirely -- it is not run
  and bounds neither side.
- `lower`: the time limit must be large enough for this solution to pass. Not
  allowed for solutions expected to be slow.
- `upper`: the time limit must be small enough for this solution to time out.

```yaml
solutions:
  - path: 'sols/borderline.cpp'
    outcome: accepted-or-tle
    inference: upper
```
""",
    )

    tags: List[str] = Field(
        default=[],
        description="""Tags to be associated with this solution.""",
    )

    score: Optional[Union[float, Tuple[Optional[float], Optional[float]]]] = Field(
        default=None,
        description="""The score of this solution in the final score.
Should either be a number, which means the solution should have this exact score,
or a tuple of two numbers, which means the solution should have a score between the two numbers (inclusive).
Scores are compared rounded to two decimals.

If one of the numbers is set to be null, it means that the solution should have a score between the other number and negative/positive infinity.""",
    )

    @model_validator(mode='after')
    def check_inference_role(self):
        if self.inference == InferenceRole.LOWER and any(
            outcome.is_slow() for outcome in self.all_expected_outcomes()
        ):
            raise PydanticCustomError(
                'INFERENCE_LOWER_NOT_ALLOWED_FOR_SLOW',
                'Solution {path} is expected to be slow, so it cannot bound the time '
                'limit from below; use `inference: upper` or `inference: false`.',
                {'path': str(self.path)},
            )
        return self

    def expected_outcome_for_group(self, group_name: str) -> Optional[ExpectedOutcome]:
        """The expectation for a single group, or None if the group has none."""
        if group_name in self.outcomePerGroup:
            return self.outcomePerGroup[group_name]
        return self.outcomePerGroup.get(PER_GROUP_OUTCOME_WILDCARD)

    def all_expected_outcomes(self) -> Set[ExpectedOutcome]:
        """Every expectation this solution declares, pooled and per-group."""
        # Consumers that ask a coarse question about a solution ("is it expected
        # to be slow?") must consider all of them, not just `outcome`.
        return {self.outcome} | set(self.outcomePerGroup.values())

    def expected_score_range(self) -> Optional[Tuple[float, float]]:
        if self.score is None:
            return None
        if not isinstance(self.score, tuple):
            return (self.score, self.score)
        assert isinstance(self.score, tuple)
        assert len(self.score) == 2

        lo, hi = self.score
        if lo is None:
            lo = 0
        if hi is None:
            hi = 10**9
        return (lo, hi)

    def href(self, hyperlink: bool = True) -> str:
        return href(self.path, style=self.outcome.full_style(), hyperlink=hyperlink)

all_expected_outcomes() #

Every expectation this solution declares, pooled and per-group.

Source code in rbx/box/schema.py
def all_expected_outcomes(self) -> Set[ExpectedOutcome]:
    """Every expectation this solution declares, pooled and per-group."""
    # Consumers that ask a coarse question about a solution ("is it expected
    # to be slow?") must consider all of them, not just `outcome`.
    return {self.outcome} | set(self.outcomePerGroup.values())

expected_outcome_for_group(group_name) #

The expectation for a single group, or None if the group has none.

Source code in rbx/box/schema.py
def expected_outcome_for_group(self, group_name: str) -> Optional[ExpectedOutcome]:
    """The expectation for a single group, or None if the group has none."""
    if group_name in self.outcomePerGroup:
        return self.outcomePerGroup[group_name]
    return self.outcomePerGroup.get(PER_GROUP_OUTCOME_WILDCARD)

Stress #

Bases: BaseModel

Parameters:

Name Type Description Default
name str

The name of the stress test.

required
generator GeneratorCall

Generator pattern to call during stress-test.

required
finder str

Finder expression to be used to match against generated tests.

required
Source code in rbx/box/schema.py
class Stress(BaseModel):
    model_config = ConfigDict(extra='forbid')

    name: str = NameField(description='The name of the stress test.')

    generator: GeneratorCall = Field(
        description='Generator pattern to call during stress-test.'
    )

    finder: str = Field(
        description='Finder expression to be used to match against generated tests.'
    )

TaskType #

Bases: AutoEnum

Source code in rbx/box/schema.py
class TaskType(AutoEnum):
    BATCH = alias('batch')  # type: ignore
    """Batch task."""

    COMMUNICATION = alias('communication')  # type: ignore
    """Communication task."""

BATCH = alias('batch') #

Batch task.

COMMUNICATION = alias('communication') #

Communication task.

Testcase #

Bases: BaseModel

Parameters:

Name Type Description Default
inputPath Path

The path of the input file.

required
outputPath Path | None

The path of the output file.

None
Source code in rbx/box/schema.py
class Testcase(BaseModel):
    __test__ = False

    model_config = ConfigDict(extra='forbid')

    inputPath: pathlib.Path = Field(description="""The path of the input file.""")

    outputPath: Optional[pathlib.Path] = Field(
        default=None, description="""The path of the output file."""
    )

TestcaseGroup #

Bases: TestcaseSubgroup

Parameters:

Name Type Description Default
subgroups List[TestcaseSubgroup]

A list of test subgroups to define for this group.

[]
validator CodeItem | None

A validator to use to validate the testcases of this group. If specified, will use this validator instead of the package-level validator. Useful in cases where the constraints vary across test groups.

None
vars RecVars

Variables that override the package-level vars for this group only.

Merged leaf-by-leaf onto the package vars, so a partial override keeps its siblings. The effective values are what getVar<T>() returns inside a validator run for this group, and what problem.groups.<name>.vars renders in a statement. Keys need not exist at package level.

{}
score int

The score of this group in the final score. Useful for problems that have points.

0
deps List[str]

A list of other groups this group depends on to run and be considered accepted.

Only these are dependencies unless scoring.dependencies adds more: set it to samples to make every group depend on samples, or to ladder to chain each group to the one before it.

[]
aggregation Aggregation | None

How the results of this group's tests combine into its score; defaults to scoring.aggregation. Only for problems with points.

None
model_solution ForwardRef

The solution to be used to generate outputs for this testgroup.

Can only be set for the "samples" testgroup.

None
validateStatementFiles bool

Whether the statement-only testcase files of this group should be validated.

Statement-only files -- <name>.in.statement and <name>.out.statement -- override what a sample shows in the statement without touching the testcase that is actually judged. By default they are taken at face value: nothing is run over them.

Setting this to true runs this group's validator and extraValidators over every .in.statement file, and its outputValidators over every .out.statement file, so a malformed statement-only file fails the build instead of shipping. The checker is still not run over these files -- skipping it is the whole point of the .statement extension.

Mostly useful in the samples group. Applies to the group's subgroups as well.

False
Source code in rbx/box/schema.py
class TestcaseGroup(TestcaseSubgroup):
    model_config = ConfigDict(extra='forbid')

    subgroups: Annotated[
        List[TestcaseSubgroup],
        AfterValidator(is_unique_testcase_subgroup_names),
    ] = Field(
        default=[],
        description="""
A list of test subgroups to define for this group.
        """,
    )

    validator: Optional[CodeItem] = Field(
        default=None,
        description="""
A validator to use to validate the testcases of this group.
If specified, will use this validator instead of the package-level validator.
Useful in cases where the constraints vary across test groups.
""",
    )

    vars: CheckedRecVars = Field(
        default={},
        description="""
Variables that override the package-level `vars` for this group only.

Merged leaf-by-leaf onto the package `vars`, so a partial override keeps its
siblings. The effective values are what `getVar<T>()` returns inside a
validator run for this group, and what `problem.groups.<name>.vars` renders in
a statement. Keys need not exist at package level.
""",
    )

    score: int = Field(
        default=0,
        ge=0,
        description="""
The score of this group in the final score. Useful for
problems that have points.
""",
    )

    deps: List[str] = Field(
        default=[],
        description="""
A list of other groups this group depends on to run and be considered accepted.

Only these are dependencies unless `scoring.dependencies` adds more: set it to
`samples` to make every group depend on `samples`, or to `ladder` to chain
each group to the one before it.
""",
    )

    aggregation: Optional[Aggregation] = Field(
        default=None,
        description="""
How the results of this group's tests combine into its score; defaults to
`scoring.aggregation`. Only for problems with points.
""",
    )

    model_solution: Optional[Solution] = Field(
        default=None,
        description="""
The solution to be used to generate outputs for this testgroup.

Can only be set for the "samples" testgroup.
""",
    )

    validateStatementFiles: bool = Field(
        default=False,
        description="""
Whether the statement-only testcase files of this group should be validated.

Statement-only files -- `<name>.in.statement` and `<name>.out.statement` -- override
what a sample shows in the statement without touching the testcase that is actually
judged. By default they are taken at face value: nothing is run over them.

Setting this to `true` runs this group's `validator` and `extraValidators` over every
`.in.statement` file, and its `outputValidators` over every `.out.statement` file, so a
malformed statement-only file fails the build instead of shipping. The checker is still
not run over these files -- skipping it is the whole point of the `.statement` extension.

Mostly useful in the `samples` group. Applies to the group's subgroups as well.
""",
    )

    @model_validator(mode='after')
    def check_model_solution_for_samples(self):
        if self.name == 'samples':
            return self
        if self.model_solution is not None:
            raise PydanticCustomError(
                'MODEL_SOLUTION_NOT_ALLOWED',
                'Model solution can only be set for the "samples" testgroup.',
            )
        return self

TestcaseSubgroup #

Bases: BaseModel

Parameters:

Name Type Description Default
name str

The name of the test group.

required
testcases List[Testcase]

The path of testcases to add to this group, in the order they're defined.

[]
testcaseGlob str | None

A Python glob that matches input file paths relative to the package directory. The globbed files should end with the extension ".in", and their corresponding outputs, if defined, should have the same file name, but ending with ".ans".

None
generators List[GeneratorCall]

A list of generators to call to generate testcases for this group.

[]
generatorScript GeneratorScript | None

A generator script to call to generate testcases for this group.

None
extraValidators List[CodeItem]

A list of extra validators to use to validate the testcases of this subgroup.

[]
outputValidators List[CodeItem]

A list of output validators to use to validate the output of the testcases of this subgroup.

[]
visualizer Visualizer | None

The visualizer for this problem. Used to produced visualizations for the testcases. Has priority over the visualizer specified in the package.

None
solutionVisualizer Visualizer | None

The solution visualizer for this problem. Used to produced visualizations for the outputs of the testcases. Has priority over the solution visualizer specified in the package.

None
allowDuplicate bool | None

Whether the tests of this group may duplicate other tests, either by being generated by the same call or by having the same input. A duplicate pair is only warned about when neither of its tests allows it.

A subgroup inherits the value of its group unless it sets its own.

None
Source code in rbx/box/schema.py
class TestcaseSubgroup(BaseModel):
    model_config = ConfigDict(extra='forbid')

    name: str = NameField(description='The name of the test group.')

    testcases: List[Testcase] = Field(
        default=[],
        description="""
The path of testcases to add to this group,
in the order they're defined.""",
    )

    testcaseGlob: Optional[str] = Field(
        default=None,
        description="""
A Python glob that matches input file paths relative to the
package directory. The globbed files should end with the extension
".in", and their corresponding outputs, if defined, should have the same file name,
but ending with ".ans".
""",
    )

    generators: List[GeneratorCall] = Field(
        default=[],
        description="""
A list of generators to call to generate testcases for this group.
""",
    )

    generatorScript: Optional[GeneratorScript] = Field(
        default=None,
        description="""
A generator script to call to generate testcases for this group.
""",
    )

    extraValidators: List[CodeItem] = Field(
        default=[],
        description="""
A list of extra validators to use to validate the testcases of this subgroup.
""",
    )

    outputValidators: List[CodeItem] = Field(
        default=[],
        description="""
A list of output validators to use to validate the output of the testcases of this subgroup.
""",
    )

    visualizer: Optional[Visualizer] = Field(
        default=None,
        description='The visualizer for this problem. Used to produced visualizations for the testcases. '
        'Has priority over the visualizer specified in the package.',
    )

    solutionVisualizer: Optional[Visualizer] = Field(
        default=None,
        description='The solution visualizer for this problem. Used to produced visualizations for the outputs of the testcases. '
        'Has priority over the solution visualizer specified in the package.',
    )

    allowDuplicate: Optional[bool] = Field(
        default=None,
        description="""
Whether the tests of this group may duplicate other tests, either by being generated
by the same call or by having the same input. A duplicate pair is only warned about
when neither of its tests allows it.

A subgroup inherits the value of its group unless it sets its own.
""",
    )

    @model_validator(mode='after')
    def check_oneof(self) -> 'TestcaseSubgroup':
        _check_oneof(
            self,
            [
                'testcases',
                'testcaseGlob',
                'generators',
                'generatorScript',
            ],
        )
        return self

TimingBound #

Bases: BaseModel

Parameters:

Name Type Description Default
value int

The bound, in milliseconds. A lower bound is the smallest time limit it allows, before it is rounded up to timeResolution; an upper bound is the largest time limit it allows.

required
solution str | None

The solution that set this bound, when it came from a measured solution of the group. Absent when the bound was derived from another group's limit.

None
Source code in rbx/box/schema.py
class TimingBound(BaseModel):
    model_config = ConfigDict(extra='forbid')

    value: int = Field(
        description="""The bound, in milliseconds. A lower bound is the smallest
time limit it allows, before it is rounded up to `timeResolution`; an upper bound is
the largest time limit it allows."""
    )

    solution: Optional[str] = Field(
        default=None,
        description="""The solution that set this bound, when it came from a measured
solution of the group. Absent when the bound was derived from another group's limit.""",
    )

TimingGroupReport #

Bases: BaseModel

Parameters:

Name Type Description Default
languages List[str]
required
timeLimit int
required
origin TimingGroupOrigin
required
solutionCount int
0
fastest int | None
None
slowest int | None
None
relativeToLanguage str | None
None
multiplier float | None
None
increment int | None
None
isLeftover bool
False
lowerBound TimingBound | None

The lower bound this group's time limit had to respect, when it was estimated from multipliers. Presentation-only.

None
upperBound TimingBound | None

The upper bound this group's time limit had to respect, when it was estimated from multipliers and some slow solution of the group bounded it. Presentation-only.

None
upperValidation TimingGroupUpperValidation | None

What checking this group's slow solutions against its estimated time limit found. Absent when the group has no slow solutions. Presentation-only.

None
estimatedTimeLimit int | None

The time limit rbx time estimated for this group, recorded only when the setter has since changed timeLimit by hand with rbx time --edit. The bounds and the upper validation of this report were measured against this limit, not against timeLimit. Absent while the limit is the estimated one. Presentation-only.

None
lowerViolation TimingBound | None

The smallest time limit this group's own accepted solutions allow, recorded only when the group's time limit is below it -- that is, when the limit was derived from a reference group or the base estimate instead of being estimated from the group's own solutions, and the group's own solutions do not fit in it. solution is the accepted solution that sets the bound. Absent whenever the limit respects the group's own evidence. Presentation-only.

None
droppedUpper List[str]

Deprecated: replaced by upperValidation. Accepted so that a limits profile written before the estimation was split into two phases still parses; never written.

[]
Source code in rbx/box/schema.py
class TimingGroupReport(BaseModel):
    # Ignored rather than refused, for the reason `LimitsProfile` gives: this is
    # reachable only from a profile (`groups`, `baseEstimate`), it is written by
    # rbx and never by hand, and under `forbid` a field added to it would break
    # an older rbx's parse of the whole profile just as surely as one added a
    # level up.
    model_config = ConfigDict(extra='ignore')

    languages: List[str]
    timeLimit: int
    origin: TimingGroupOrigin
    solutionCount: int = 0
    fastest: Optional[int] = None
    slowest: Optional[int] = None
    relativeToLanguage: Optional[str] = None
    multiplier: Optional[float] = None
    increment: Optional[int] = None
    isLeftover: bool = False

    lowerBound: Optional[TimingBound] = Field(
        default=None,
        description="""The lower bound this group's time limit had to respect, when it
was estimated from multipliers. Presentation-only.""",
    )

    upperBound: Optional[TimingBound] = Field(
        default=None,
        description="""The upper bound this group's time limit had to respect, when it
was estimated from multipliers and some slow solution of the group bounded it.
Presentation-only.""",
    )

    upperValidation: Optional[TimingGroupUpperValidation] = Field(
        default=None,
        description="""What checking this group's slow solutions against its estimated
time limit found. Absent when the group has no slow solutions. Presentation-only.""",
    )

    estimatedTimeLimit: Optional[int] = Field(
        default=None,
        description="""The time limit `rbx time` estimated for this group, recorded
only when the setter has since changed `timeLimit` by hand with `rbx time --edit`.
The bounds and the upper validation of this report were measured against this
limit, not against `timeLimit`. Absent while the limit is the estimated one.
Presentation-only.""",
    )

    lowerViolation: Optional[TimingBound] = Field(
        default=None,
        description="""The smallest time limit this group's own accepted solutions
allow, recorded only when the group's time limit is below it -- that is, when the
limit was derived from a reference group or the base estimate instead of being
estimated from the group's own solutions, and the group's own solutions do not fit
in it. `solution` is the accepted solution that sets the bound. Absent whenever the
limit respects the group's own evidence. Presentation-only.""",
    )

    droppedUpper: List[str] = Field(
        default=[],
        deprecated=True,
        exclude=True,
        description="""Deprecated: replaced by `upperValidation`. Accepted so that a
limits profile written before the estimation was split into two phases still parses;
never written.""",
    )

TimingGroupUpperValidation #

Bases: BaseModel

What checking a group's slow solutions against its time limit found.

Parameters:

Name Type Description Default
confirmed List[str]

Solutions of this group expected to be too slow that were confirmed to be so: they were still running once the estimated time limit times timeLimitToTle had elapsed. Presentation-only.

[]
violating List[TimingBound]

Solutions of this group expected to be too slow that finished within the estimated time limit times timeLimitToTle, so they do not respect the upper bound. value is the time the solution actually took. Presentation-only.

[]
skipped List[str]

Solutions of this group expected to be too slow that were not run, either because timeLimitToTle is unset or because the validation phase was skipped. Presentation-only.

[]
Source code in rbx/box/schema.py
class TimingGroupUpperValidation(BaseModel):
    """What checking a group's slow solutions against its time limit found."""

    model_config = ConfigDict(extra='forbid')

    confirmed: List[str] = Field(
        default=[],
        description="""Solutions of this group expected to be too slow that were
confirmed to be so: they were still running once the estimated time limit times
`timeLimitToTle` had elapsed. Presentation-only.""",
    )

    violating: List[TimingBound] = Field(
        default=[],
        description="""Solutions of this group expected to be too slow that finished
within the estimated time limit times `timeLimitToTle`, so they do not respect the
upper bound. `value` is the time the solution actually took. Presentation-only.""",
    )

    skipped: List[str] = Field(
        default=[],
        description="""Solutions of this group expected to be too slow that were not
run, either because `timeLimitToTle` is unset or because the validation phase was
skipped. Presentation-only.""",
    )

TimingMultipliers #

Bases: BaseModel

Parameters:

Name Type Description Default
acToTimeLimit float

Minimum ratio between the time limit and the slowest accepted solution, used to estimate the time limit from below: the slowest accepted solution times acToTimeLimit must fit within the time limit.

required
fastestToTimeLimit float | None

Minimum ratio between the time limit and the fastest accepted solution, an additional lower bound on top of acToTimeLimit: the fastest accepted solution times fastestToTimeLimit must also fit within the time limit. When set, the estimate is no longer the Kattis rule (which only scales the slowest accepted solution), so a judge that estimates by that rule cannot reproduce it.

None
timeLimitToTle float | None

Minimum ratio between the fastest solution expected to be too slow and the time limit: the time limit times timeLimitToTle must fit within the fastest solution expected to be too slow. When omitted, solutions expected to be too slow are not run and the time limit is not bounded from above.

None
inferenceTimeout int | None

Deprecated: use timing.inferenceTimeout, which applies to every estimation strategy instead of only to multiplier-based ones. Kept for backwards compatibility; setting both is an error.

None
timeResolution int

Granularity (in milliseconds) of the estimated time limit. The estimate is the smallest multiple of this value that is valid.

100
Source code in rbx/box/schema.py
class TimingMultipliers(BaseModel):
    model_config = ConfigDict(extra='forbid', frozen=True)

    acToTimeLimit: float = Field(
        gt=0,
        description="""Minimum ratio between the time limit and the slowest accepted
solution, used to estimate the time limit from below: the slowest accepted solution
times `acToTimeLimit` must fit within the time limit.""",
    )

    fastestToTimeLimit: Optional[float] = Field(
        default=None,
        gt=0,
        description="""Minimum ratio between the time limit and the fastest accepted
solution, an additional lower bound on top of `acToTimeLimit`: the fastest accepted
solution times `fastestToTimeLimit` must also fit within the time limit. When set,
the estimate is no longer the Kattis rule (which only scales the slowest accepted
solution), so a judge that estimates by that rule cannot reproduce it.""",
    )

    timeLimitToTle: Optional[float] = Field(
        default=None,
        gt=0,
        description="""Minimum ratio between the fastest solution expected to be too
slow and the time limit: the time limit times `timeLimitToTle` must fit within the
fastest solution expected to be too slow. When omitted, solutions expected to be too
slow are not run and the time limit is not bounded from above.""",
    )

    inferenceTimeout: Optional[int] = Field(
        default=None,
        gt=0,
        description="""Deprecated: use `timing.inferenceTimeout`, which applies to
every estimation strategy instead of only to multiplier-based ones. Kept for
backwards compatibility; setting both is an error.""",
    )

    timeResolution: int = Field(
        default=100,
        gt=0,
        description="""Granularity (in milliseconds) of the estimated time limit.
The estimate is the smallest multiple of this value that is valid.""",
    )

    @property
    def uses_kattis_estimation(self) -> bool:
        """Whether these multipliers estimate by the Kattis rule alone: the limit is
        the slowest accepted solution times `acToTimeLimit`, rounded up to
        `timeResolution`. A `fastestToTimeLimit` adds a bound that rule does not
        have, so a judge estimating by it (MOJ's `TLMETHOD=kattis`) would not land
        where rbx does."""
        return self.fastestToTimeLimit is None

uses_kattis_estimation #

Whether these multipliers estimate by the Kattis rule alone: the limit is the slowest accepted solution times acToTimeLimit, rounded up to timeResolution. A fastestToTimeLimit adds a bound that rule does not have, so a judge estimating by it (MOJ's TLMETHOD=kattis) would not land where rbx does.

TimingMultipliersOverride #

Bases: BaseModel

Parameters:

Name Type Description Default
acToTimeLimit float | None

Overrides the environment acToTimeLimit: the minimum ratio between the time limit and the slowest accepted solution, which bounds the estimated time limit from below.

None
fastestToTimeLimit float | None

Overrides the environment fastestToTimeLimit: the minimum ratio between the time limit and the fastest accepted solution, an additional lower bound on top of acToTimeLimit. Setting it means the estimate is no longer the Kattis rule.

None
timeLimitToTle float | None

Overrides the environment timeLimitToTle: the minimum ratio between the fastest solution expected to be too slow and the time limit, which bounds the estimated time limit from above.

None
inferenceTimeout int | None

Deprecated: use timing.inferenceTimeout, which applies to every estimation strategy instead of only to multiplier-based ones. Kept for backwards compatibility; setting both is an error.

None
timeResolution int | None

Overrides the environment timeResolution: the granularity (in milliseconds) the estimated time limit is rounded up to.

None
Source code in rbx/box/schema.py
class TimingMultipliersOverride(BaseModel):
    model_config = ConfigDict(extra='forbid')

    acToTimeLimit: Optional[float] = Field(
        default=None,
        gt=0,
        description="""Overrides the environment `acToTimeLimit`: the minimum ratio
between the time limit and the slowest accepted solution, which bounds the estimated
time limit from below.""",
    )

    fastestToTimeLimit: Optional[float] = Field(
        default=None,
        gt=0,
        description="""Overrides the environment `fastestToTimeLimit`: the minimum
ratio between the time limit and the fastest accepted solution, an additional lower
bound on top of `acToTimeLimit`. Setting it means the estimate is no longer the Kattis
rule.""",
    )

    timeLimitToTle: Optional[float] = Field(
        default=None,
        gt=0,
        description="""Overrides the environment `timeLimitToTle`: the minimum ratio
between the fastest solution expected to be too slow and the time limit, which bounds
the estimated time limit from above.""",
    )

    inferenceTimeout: Optional[int] = Field(
        default=None,
        gt=0,
        description="""Deprecated: use `timing.inferenceTimeout`, which applies to
every estimation strategy instead of only to multiplier-based ones. Kept for
backwards compatibility; setting both is an error.""",
    )

    timeResolution: Optional[int] = Field(
        default=None,
        gt=0,
        description="""Overrides the environment `timeResolution`: the granularity
(in milliseconds) the estimated time limit is rounded up to.""",
    )

UnitTests #

Bases: BaseModel

Parameters:

Name Type Description Default
validator List[ValidatorTest]

Unit tests for the validator.

[]
checker List[CheckerTest]

Unit tests for the checker.

[]
Source code in rbx/box/schema.py
class UnitTests(BaseModel):
    model_config = ConfigDict(extra='forbid')

    validator: List[ValidatorTest] = Field(
        default=[],
        description='Unit tests for the validator.',
    )

    checker: List[CheckerTest] = Field(
        default=[],
        description='Unit tests for the checker.',
    )

ValidatorOutcome #

Bases: AutoEnum

Source code in rbx/box/schema.py
class ValidatorOutcome(AutoEnum):
    VALID = alias('valid')  # type: ignore
    """Expected outcome for valid tests."""

    INVALID = alias('invalid')  # type: ignore
    """Expected outcome for invalid tests."""

INVALID = alias('invalid') #

Expected outcome for invalid tests.

VALID = alias('valid') #

Expected outcome for valid tests.

ValidatorTest #

Bases: BaseModel

Parameters:

Name Type Description Default
glob str | None

A glob pattern for the input files to be used as unit test input for the validator.

None
testplan Path | None

A testplan to be used as unit test input for the validator.

None
outcome ValidatorOutcome | None

The expected outcome of the validator.

None
validator CodeItem | None

The validator to use for this test. If not specified, will use the package-level validator.

None
Source code in rbx/box/schema.py
class ValidatorTest(BaseModel):
    model_config = ConfigDict(extra='forbid')

    glob: Optional[str] = Field(
        default=None,
        description='A glob pattern for the input files to be used as unit test input for the validator.',
    )

    testplan: Optional[pathlib.Path] = Field(
        default=None,
        description='A testplan to be used as unit test input for the validator.',
    )

    outcome: Optional[ValidatorOutcome] = Field(
        default=None,
        description='The expected outcome of the validator.',
    )

    validator: Optional[CodeItem] = Field(
        default=None,
        description='The validator to use for this test. If not specified, will use the package-level validator.',
    )

    @model_validator(mode='after')
    def check_oneof(self):
        if self.glob is None and self.testplan is None:
            raise PydanticCustomError(
                'GLOB_OR_TESTPLAN_REQUIRED',
                'Either a glob or a testplan must be specified.',
            )
        if self.glob is not None and self.testplan is not None:
            raise PydanticCustomError(
                'GLOB_AND_TESTPLAN_NOT_ALLOWED',
                'Either a glob or a testplan must be specified, but not both.',
            )
        return self

    @model_validator(mode='after')
    def check_testplan(self):
        if self.testplan is not None and self.outcome is not None:
            raise PydanticCustomError(
                'OUTCOME_NOT_ALLOWED',
                'Outcome is not allowed for testplan validator tests.',
            )
        return self

    @model_validator(mode='after')
    def check_glob(self):
        if self.glob is not None and self.outcome is None:
            raise PydanticCustomError(
                'OUTCOME_REQUIRED',
                'Outcome is required for glob validator tests.',
            )
        return self

Visualizer #

Bases: CodeItem

Parameters:

Name Type Description Default
extension str

The extension of the visualization file generated by the visualizer.

required
answer_from Literal['stderr'] | OutputFromItem | None

Program to generate additional answer file to pass to the visualizer. If not specified, the reference answer file will be used.

None
Source code in rbx/box/schema.py
class Visualizer(CodeItem):
    model_config = ConfigDict(extra='forbid')

    extension: str = Field(
        description="""The extension of the visualization file generated by the visualizer.
        """,
    )

    answer_from: Optional[OutputFrom] = Field(
        default=None,
        description="""Program to generate additional answer file to pass to the visualizer.
        If not specified, the reference answer file will be used.""",
    )

    def get_suffix(self) -> str:
        return f'.{self.extension}'

check_reserved_var_names(vars) #

Reject top-level var names that collide with a testlib/rbx flag.

Only top-level primitive keys are checked: a nested var is emitted as --<parent>.<key>=<value>, which no flag parser matches.

Source code in rbx/box/schema.py
def check_reserved_var_names(vars: RecVars) -> RecVars:
    """Reject top-level var names that collide with a testlib/rbx flag.

    Only top-level *primitive* keys are checked: a nested var is emitted as
    `--<parent>.<key>=<value>`, which no flag parser matches.
    """
    for key, value in vars.items():
        if isinstance(value, dict):
            continue
        if key in RESERVED_VAR_NAMES:
            raise PydanticCustomError(
                'RESERVED_VAR_NAME',
                'Variable "{key}" collides with the testlib/rbx command-line flag '
                '"--{key}": vars are passed to validators as "--{key}=<value>", '
                'which the flag parser would consume instead. '
                'Rename the variable, or nest it under another key '
                '(as in "limits.{key}"). Reserved names: {reserved}.',
                {'key': key, 'reserved': ', '.join(sorted(RESERVED_VAR_NAMES))},
            )
    return vars

Statements#

Statement #

Bases: BaseStatement

A problem-level statement. Identified by (language, variant) — it has no name (design §3.1).

Parameters:

Name Type Description Default
extends str | StatementVariantRef | None

Another problem statement to inherit the build recipe from, referenced by language (extends: en) or by {language, variant}.

None
Source code in rbx/box/statements/schema.py
class Statement(BaseStatement):
    """A problem-level statement. Identified by (language, variant) — it has no
    `name` (design §3.1)."""

    extends: Optional[ProblemStatementExtends] = Field(
        default=None,
        description='Another problem statement to inherit the build recipe from, '
        'referenced by language (`extends: en`) or by '
        '`{language, variant}`.',
    )

    @model_validator(mode='after')
    def _require_file_or_extends(self):
        if self.file is None and self.extends is None:
            raise ValueError(
                'A statement must specify a `file` unless it `extends` another statement.'
            )
        return self

    @property
    def key(self) -> Tuple[str, str]:
        return (self.language, self.variant)

StatementType #

Bases: AutoEnum

Source code in rbx/box/statements/schema.py
class StatementType(AutoEnum):
    rbxTeX = alias('rbx-tex')  # type: ignore
    """Statement written in rbxTeX format."""

    rbxMarkdown = alias('rbxMd', 'rbx-markdown', 'rbx-md')  # type: ignore
    """Statement written in rbxMarkdown format."""

    TeX = alias('tex')  # type: ignore
    """Statement written in pure LaTeX format."""

    Markdown = alias('md', 'markdown')  # type: ignore
    """Statement written in pure Markdown format."""

    JinjaTeX = alias('jinja-tex')  # type: ignore
    """Statement written in LaTeX format with Jinja2 expressions."""

    JinjaMarkdown = alias('jinja-md', 'jinja-markdown')  # type: ignore
    """Statement written in Markdown format with Jinja2 expressions."""

    PDF = alias('pdf')  # type: ignore
    """Statement is a PDF."""

    def get_file_suffix(self) -> str:
        if self == StatementType.TeX:
            return '.tex'
        if self == StatementType.Markdown:
            return '.md'
        if self == StatementType.rbxTeX:
            return '.rbx.tex'
        if self == StatementType.rbxMarkdown:
            return '.rbx.md'
        if self == StatementType.JinjaTeX:
            return '.jinja.tex'
        if self == StatementType.JinjaMarkdown:
            return '.jinja.md'
        if self == StatementType.PDF:
            return '.pdf'
        raise ValueError(f'Unknown statement type: {self}')

    def is_rbx(self) -> bool:
        """rbx* types are the only ones that can JOIN problems into a contest."""
        return self in (StatementType.rbxTeX, StatementType.rbxMarkdown)

rbxTeX = alias('rbx-tex') #

Statement written in rbxTeX format.

rbxMarkdown = alias('rbxMd', 'rbx-markdown', 'rbx-md') #

Statement written in rbxMarkdown format.

TeX = alias('tex') #

Statement written in pure LaTeX format.

Markdown = alias('md', 'markdown') #

Statement written in pure Markdown format.

JinjaTeX = alias('jinja-tex') #

Statement written in LaTeX format with Jinja2 expressions.

JinjaMarkdown = alias('jinja-md', 'jinja-markdown') #

Statement written in Markdown format with Jinja2 expressions.

PDF = alias('pdf') #

Statement is a PDF.

is_rbx() #

rbx* types are the only ones that can JOIN problems into a contest.

Source code in rbx/box/statements/schema.py
def is_rbx(self) -> bool:
    """rbx* types are the only ones that can JOIN problems into a contest."""
    return self in (StatementType.rbxTeX, StatementType.rbxMarkdown)

Conversion nodes#

BaseStatement #

Bases: BaseModel

Fields shared by problem statements, contest statements and documents (design §2.5, "one shared schema").

Parameters:

Name Type Description Default
language str

Language code of this statement (ISO 639-1).

'en'
variant str

Optional discriminator between formats of the same language. Together with language it forms the join key with contest statements.

'default'
title str | None

Title as it appears in the statement. Can be left unset to fall back to the package/contest title.

None
file Path | None

Path to the input statement file. Required unless this statement extends another one to inherit its file.

None
type StatementType

Type of the input statement file.

rbxTeX
params RecVars

This statement's own parameters, exposed to the template as the params namespace (kept separate from problem/contest vars).

{}
samples bool

Whether to build the statement with samples.

True
assets List[str]

Globs (relative to the package root) selecting files to ship as statement resources (e.g. images/PDFs). Inherited via extends. At build time the default image/PDF globs over the statement subtree and each sample subtree are concatenated to this list.

<dynamic>
Source code in rbx/box/statements/schema.py
class BaseStatement(BaseModel):
    """Fields shared by problem statements, contest statements and documents
    (design §2.5, "one shared schema")."""

    model_config = ConfigDict(extra='forbid')

    language: StatementLanguage = Field(
        default='en', description='Language code of this statement (ISO 639-1).'
    )

    variant: str = Field(
        default=DEFAULT_VARIANT,
        description='Optional discriminator between formats of the same language. '
        'Together with `language` it forms the join key with contest statements.',
    )

    title: Optional[str] = Field(
        default=None,
        description='Title as it appears in the statement. Can be left unset to '
        'fall back to the package/contest title.',
    )

    file: Optional[pathlib.Path] = Field(
        default=None,
        description='Path to the input statement file. Required unless this '
        'statement `extends` another one to inherit its file.',
    )

    type: StatementType = Field(
        default=StatementType.rbxTeX, description='Type of the input statement file.'
    )

    params: RecVars = Field(
        default={},
        description="This statement's own parameters, exposed to the template as "
        'the `params` namespace (kept separate from problem/contest `vars`).',
    )

    samples: bool = Field(
        default=True,
        description='Whether to build the statement with samples.',
    )

    assets: List[str] = Field(
        default_factory=list,
        description='Globs (relative to the package root) selecting files to ship '
        'as statement resources (e.g. images/PDFs). Inherited via `extends`. At '
        'build time the default image/PDF globs over the statement subtree and '
        'each sample subtree are concatenated to this list.',
    )

    @property
    def expanded_params(self) -> Vars:
        return expand_vars(self.params)

    @property
    def is_wildcard(self) -> bool:
        return self.language == WILDCARD_LANGUAGE

ConversionType #

Bases: str, Enum

Source code in rbx/box/statements/schema.py
class ConversionType(str, Enum):
    rbxToTex = 'rbx-tex'
    """Conversion from rbxTeX to LaTeX."""

    rbxMarkdownToTeX = 'rbx-md-tex'
    """Conversion from rbxMarkdown to LaTeX."""
    TexToPDF = 'tex2pdf'
    """Conversion from LaTeX to PDF using pdfLaTeX."""

    JinjaTeX = 'jinja-tex'
    """Conversion from LaTeX with Jinja2 expressions to LaTeX."""

    def __repr__(self):
        return str.__repr__(self.value)
JinjaTeX = 'jinja-tex' class-attribute instance-attribute #

Conversion from LaTeX with Jinja2 expressions to LaTeX.

TexToPDF = 'tex2pdf' class-attribute instance-attribute #

Conversion from LaTeX to PDF using pdfLaTeX.

rbxMarkdownToTeX = 'rbx-md-tex' class-attribute instance-attribute #

Conversion from rbxMarkdown to LaTeX.

rbxToTex = 'rbx-tex' class-attribute instance-attribute #

Conversion from rbxTeX to LaTeX.

StatementKind #

Bases: str, Enum

Which parallel section a statement build operates on (design §3): the primary statements or the tutorials (editorials). Both share the same models, engine and build paths — the kind only selects which list to read on the problem and the contest, and the output filename prefix.

Source code in rbx/box/statements/schema.py
class StatementKind(str, Enum):
    """Which parallel section a statement build operates on (design §3): the
    primary ``statements`` or the ``tutorials`` (editorials). Both share the
    same models, engine and build paths — the kind only selects which list to
    read on the problem and the contest, and the output filename prefix."""

    STATEMENTS = 'statements'
    TUTORIALS = 'tutorials'

    @property
    def singular(self) -> str:
        """Noun used in messages and output filenames (statement / tutorial)."""
        return 'tutorial' if self == StatementKind.TUTORIALS else 'statement'
singular property #

Noun used in messages and output filenames (statement / tutorial).

StatementVariantRef #

Bases: BaseModel

A problem-statement extends target referenced by (language, variant).

A bare string extends: en is shorthand for {language: en} with the default variant (design §5).

Parameters:

Name Type Description Default
language str
required
variant str
'default'
Source code in rbx/box/statements/schema.py
class StatementVariantRef(BaseModel):
    """A problem-statement `extends` target referenced by (language, variant).

    A bare string `extends: en` is shorthand for `{language: en}` with the
    default variant (design §5).
    """

    model_config = ConfigDict(extra='forbid')

    language: StatementLanguage
    variant: str = Field(default=DEFAULT_VARIANT)

TexToPDF #

Bases: BaseModel

Configures the conversion between LaTeX and PDF using pdfLaTeX.

Parameters:

Name Type Description Default
type Literal['tex2pdf']
required
externalize bool

Whether to externalize TikZ graphics.

False
demacro bool

Whether to save macro definitions to a JSON file.

False
Source code in rbx/box/statements/schema.py
class TexToPDF(BaseModel):
    """Configures the conversion between LaTeX and PDF using pdfLaTeX."""

    type: Literal[ConversionType.TexToPDF]

    externalize: bool = Field(
        default=False,
        description='Whether to externalize TikZ graphics.',
    )

    demacro: bool = Field(
        default=False,
        description='Whether to save macro definitions to a JSON file.',
    )

rbxToTeX #

Bases: BaseModel

Configures the conversion between rbxTeX and LaTeX.

Parameters:

Name Type Description Default
type Literal['rbx-tex']
required
template Path

Path to the template that should be used to render the rbx-tex blocks.

PosixPath('template.rbx.tex')
externalize bool

Whether to externalize TikZ graphics.

False
Source code in rbx/box/statements/schema.py
class rbxToTeX(BaseModel):
    """Configures the conversion between rbxTeX and LaTeX."""

    type: Literal[ConversionType.rbxToTex]

    template: pathlib.Path = Field(
        default=pathlib.Path('template.rbx.tex'),
        description='Path to the template that should be used to render the rbx-tex blocks.',
    )

    externalize: bool = Field(
        default=False,
        description='Whether to externalize TikZ graphics.',
    )