# API reference

Every public name is documented in the pages below, one per area of the
library (listed in the sidebar), in the order in which it appears in the
source. The documentation is generated from the
docstrings of `src/rl_mind`, so it always describes the code of the version it
was built from — shown in the sidebar, and the one students get from PyPI.

**Import conventions.** Everything listed below (except the extra
environments, `rl_mind.envs` / `rl_mind.mazemdp_env`, and `rl_mind.profiles`)
is re-exported by the package, so both of these work:

```python
from rl_mind import VecEnv, Transitions          # short
from rl_mind.env import VecEnv                   # explicit, used by the sources
```

The extra environments are deliberately *not* re-exported: importing them
registers gymnasium environments, and importing `rl_mind` must have no side
effect.

**Shapes.** `B` is the number of parallel environments, `N` a flat batch size,
`T` a number of time steps. A "structure" is a `TensorStruct`: a frozen
dataclass whose fields are tensors, indexed and stacked as a whole.

**Reading the signatures.** Constructor arguments are documented on
`__init__`; the fields of a dataclass (`Action`, `EnvStep`, `Transitions`,
`Rollout`, `Episode`, `EvalResult`) are documented as `:param:` entries of the
class itself, since that is how they are passed.

## At a glance

The names a training loop is made of, in the order they come into play:

| Name | What it is for | Page |
|---|---|---|
| {py:obj}`~rl_mind.core.Actor` | the policy: `actor(obs)` explores, `actor.act(obs)` evaluates | [Actors & actions](api/core.md) |
| {py:obj}`~rl_mind.core.Action`, {py:obj}`~rl_mind.core.StochasticAction` | what an actor returns | [Actors & actions](api/core.md) |
| {py:obj}`~rl_mind.core.TensorStruct` | the base of every container: index, stack, concatenate | [Actors & actions](api/core.md) |
| {py:obj}`~rl_mind.env.VecEnv` | `B` gymnasium copies, torch tensors in and out | [Environments](api/env.md) |
| {py:obj}`~rl_mind.env.EnvStep` | what one step of a `VecEnv` returns | [Environments](api/env.md) |
| {py:obj}`~rl_mind.data.Transitions`, {py:obj}`~rl_mind.data.ReplayBuffer` | off-policy data, and where it is kept | [Data](api/data.md) |
| {py:obj}`~rl_mind.data.Episode`, {py:obj}`~rl_mind.data.Rollout` | episodic and on-policy data | [Data](api/data.md) |
| {py:obj}`~rl_mind.collectors.TransitionCollector` | off-policy collection (DQN, DDPG, TD3, SAC) | [Collectors](api/collectors.md) |
| {py:obj}`~rl_mind.collectors.EpisodeCollector` | whole episodes (REINFORCE) | [Collectors](api/collectors.md) |
| {py:obj}`~rl_mind.collectors.RolloutCollector` | `[T, B]` rollouts (A2C, PPO) | [Collectors](api/collectors.md) |
| {py:obj}`~rl_mind.evaluation.Evaluator` | periodic evaluation, keeps the best actor | [Evaluation](api/evaluation.md) |
| {py:obj}`~rl_mind.rendering.RenderWidget` | watching an environment live in a notebook | [Rendering](api/rendering.md) |
| {py:obj}`~rl_mind.nn.build_mlp`, {py:obj}`~rl_mind.nn.soft_update` | network helpers | [Utilities](api/utilities.md) |
| {py:obj}`~rl_mind.notebook.run_directory` | where a run writes its outputs | [Utilities](api/utilities.md) |

```{toctree}
:maxdepth: 1
:hidden:

Actors & actions <api/core>
Environments <api/env>
Data <api/data>
Collectors <api/collectors>
Evaluation <api/evaluation>
Rendering <api/rendering>
Utilities <api/utilities>
Extra environments <api/extra-envs>
Profiles <api/profiles>
```