> ## Documentation Index
> Fetch the complete documentation index at: https://docs.canary.effectiveai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Download a program

> Save a program from Effective's library to a local folder or ZIP file, pinned to one version, to load it offline.

Download a program from Effective's library to a folder next to your work:

```python theme={null}
from relativities import Program

path = Program.download("effective://example-ca-ppa", "example-ca-ppa")
sorted(item.name for item in path.iterdir())
# ['program', 'program-manifest.json', 'rater-manifest.json', 'rater.py', 'rater.rsl', 'tables']
```

The folder is the program bundle. It has two layers, and each layer has its own manifest:

```text theme={null}
example-ca-ppa/
  rater.rsl              # the rating algorithm, in RSL
  tables/                # one CSV file per rating table, such as BaseRate.csv
  rater.py               # Python that rslc generates from rater.rsl
  rater-manifest.json    # the engine: its bundle_id and each file's SHA-256
  program/
    program.py           # prepare(book) and SCHEMA, the book the program accepts
    record.py            # a helper that program.py imports
    examples/
      book/              # the example book, in the Book.read_csv layout
      expected.csv       # each example's expected status and premium
  program-manifest.json  # the program: its bundle_id, the engine's ID and each program file's SHA-256
```

The rater layer alone is a rater bundle, which `Rater.load` reads. The program's `bundle_id` covers
the engine and each program file, so it pins `prepare` and the rater together.
A library program needs an [Effective API key](/relativities/setup#load-a-library-program) with access to it.

## Read the source

Read the program in three places, in this order:

1. `program/program.py`: `prepare(book)` turns your book's columns into the rater's inputs. Its docstring lists each step, such as dates to whole years.
2. `rater.rsl`: the rating manual as code. Read it top to bottom: the value sets, the filed constants, the tables, then the rating steps for the policy, each driver and each vehicle.
3. `tables/`: the rate pages. Each CSV file is one table that `rater.rsl` declares and cites, such as `BaseRate.csv`.

`program/examples/expected.csv` gives each example policy's premium. `rater.py` and the two manifests are
generated files, and `Program.load` checks them.

In Python, each table is a DataFrame, and `explain` follows one premium through these files:

```python theme={null}
program = Program.load(path)
program.rater.tables["BaseRate"].head(2)
#           coverage  rate
# 0    bodily_injury   550
# 1  property_damage   358
steps = program.explain(program.example_book, "S000001")
bi = steps["name"].str.startswith("vehicles[0].") & steps["name"].str.endswith(".bodily_injury")
steps.loc[bi, ["name", "value"]]
#                                             name value
# 94             vehicles[0].carried.bodily_injury  True
# 106   vehicles[0].territory_factor.bodily_injury  0.95
# 116      vehicles[0].symbol_factor.bodily_injury   1.1
# 130     vehicles[0].mileage_factor.bodily_injury  0.88
# 140         vehicles[0].use_factor.bodily_injury  0.92
# 150       vehicles[0].limit_factor.bodily_injury     1
# 160  vehicles[0].anti_theft_factor.bodily_injury     1
# 174       vehicles[0].driver_class.bodily_injury  0.95
# 184   vehicles[0].coverage_premium.bodily_injury   262
```

Each `name` is a calculation in `rater.rsl`, such as `territory_factor` in the vehicle's `factors`
step. [RSL at a glance](/relativities/rsl/language-tour) explains each part of `rater.rsl`.

## Load the download offline

Load the folder by its path, as the example above does. The program has the same `bundle_id` as the library's copy:

```python theme={null}
program.rater.bundle_id == Program.load("effective://example-ca-ppa").rater.bundle_id  # True
```

`Program.load` verifies each file's hash before the program runs.

## Download one archive

To get one archive file, give a path that ends in `.zip`:

```python theme={null}
Program.download("effective://example-ca-ppa", "example-ca-ppa.zip")  # PosixPath('example-ca-ppa.zip')
```

The path must be new or an empty folder. Any other path raises `FileExistsError`.

## Pin a version

Pass `revision=` to choose a version:

* A whole number, such as `revision=1`, chooses a published version.
* A `bundle_id` chooses one exact bundle. Use it to rerun a study exactly.

```python theme={null}
Program.download("effective://example-ca-ppa", "example-ca-ppa-v1", revision=1)
```

Record the `bundle_id` with each result. Each row of `rate` carries it too.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.