# RRLS Studio v0.7

**Relational Rotation / Lift / Collapse Solver — persistent vocabulary edition**

RRLS Studio is an experimental finite-pattern discovery engine. It searches low-dimensional relationships first, validates candidate laws against held-out coordinates, collapses exact relations, and only escalates to more expensive relation families when cheaper structures fail.

v0.7 adds a persistent **recursive relation vocabulary**. Validated reductions are stored as reusable primitives, generalized into schemas, merged across operator families, and recompressed into recurring macros. The learned vocabulary is also an active solver: stored relations are tried on future inputs, but they must still pass the same held-out validation before RRLS accepts them.

## Windows quick start

### Run from Python

1. Install Python 3.11+ from python.org and enable **Add Python to PATH**.
2. Unzip the RRLS Studio folder.
3. Double-click `launch_windows.bat`.

The runtime uses Python's standard library and Tkinter. No third-party runtime package is required.

### Compile a standalone EXE

1. Install Python 3.11+.
2. Double-click `build_windows.bat`.
3. PyInstaller is installed as a build dependency and produces:

`dist\RRLS_Studio_v07.exe`

The resulting EXE can be launched without manually starting Python.

## Input

Paste or load a finite sequence containing integers, decimals, scientific notation, or exact fractions. Examples:

- `1, 2, 3, 4`
- `0.1 0.2 0.3`
- `1e3, 2e3, 3e3`
- `1/3, 2/3, 1`

Whitespace, commas, semicolons, pipes, and newlines are accepted separators.

## Current relation vocabulary

The base detector vocabulary includes:

- constants
- arithmetic progressions
- geometric progressions
- periodic sequences
- exact finite-difference polynomials
- affine recurrences
- exact rational linear recurrences
- whole-integer XOR / GF(2) recurrences
- modular affine / LCG sequences
- interleaved lower-dimensional subsequences

## Persistent recursive vocabulary

The default library is stored at:

`%USERPROFILE%\.rrls_studio\vocabulary.json`

It has four levels.

### 1. Primitive relation templates

A validated relation is stored without coordinates that are merely initial conditions. For example, a Fibonacci-like relation is stored as its coefficients `[1, 1]`, not as the original starting values. A future sequence with different initial coordinates can therefore reuse the same law.

### 2. Parameterized schemas

Different exact relations are grouped into schemas such as:

- `linear_recurrence(order=2)`
- `xor_recurrence(order=13,taps=3)`
- `periodic(period=4)`
- `interleaved(stride=2)`

### 3. Cross-operator meta-families

RRLS runs compression over its own vocabulary. Arithmetic, geometric, affine, constant, and order-1 linear recurrence relations can all collapse into a higher-level rational recurrence family. XOR recurrence and modular recurrence live in different algebraic domains but use the same recurrence concept.

This means the program can discover that several apparently different operator vocabularies are specializations of a smaller meta-vocabulary.

### 4. Composition macros

Nested derivations are tokenized and recurrent token groups are mined as macros. Interleaved models are recursively stored with their child relation templates, so a macro such as:

`INTERLEAVE( arithmetic(step=2), geometric(ratio=2) )`

can be replayed on a new sequence with different starting values.

The **Vocabulary** tab lets you inspect, recompress, export, or reset the library.

## Validation rules

A stored relation is never accepted merely because it was seen before. RRLS fits or replays a relation on the training prefix and requires exact prediction of the hidden suffix before labeling it **validated**.

If RRLS cannot find a compact validated law, it reports:

`unresolved in current model vocabulary`

This does not claim the sequence is fundamentally random. It means the currently available transforms and operators did not expose a compact validated representation.

Only validated relations are admitted to the persistent reusable vocabulary by default. This prevents failed fits from contaminating future searches.

## Adaptive search

RRLS keeps two separate forms of memory:

- `operator_stats.json` learns which expensive search operators tend to pay off.
- `vocabulary.json` stores actual validated relation templates and compressed relation families.

The engine therefore learns both **which search move to try** and **which previously discovered mathematical relation to test immediately**.

## Measured v0.7 vocabulary benchmark

The included `benchmark_v07_vocabulary.py` uses fresh initial states so replay cannot succeed by memorizing the original sequence.

Measured in the provided container:

- Stored order-13 XOR relation, 8,000 values, new initial state:
  - cold rediscovery: ~0.352 s
  - vocabulary replay: ~0.039 s
  - speedup: **~9.10x**
  - both methods held-out validated exactly

- Cross-vocabulary composition macro: arithmetic lane + geometric lane, new starting values:
  - cold rediscovery: ~0.0055 s
  - macro replay: ~0.0023 s
  - speedup: **~2.39x**
  - holdout validation exact

- Example trained library after the benchmark:
  - 31 primitive templates
  - 21 schemas
  - 13 meta-families
  - 4 cross-operator merges
  - 3 learned composition macros

Timing is hardware- and data-dependent. These are benchmark measurements, not universal speedup guarantees.

## Important engine optimization found during v0.7 development

The previous affine detector could repeatedly verify long candidate sequences inside a nested search. v0.7 reduces the exact affine test to **O(N)**: two transitions with distinct predecessor values uniquely determine the candidate affine relation, after which one linear verification pass is sufficient.

## CLI

Example:

```bat
py rrls_cli.py --sequence "1,1,2,3,5,8,13,21,34,55,89,144" --mode adaptive --forecast 8
```

Use a custom vocabulary file:

```bat
py rrls_cli.py --file pattern.txt --vocab my_relations.json --mode adaptive
```

Analyze without modifying vocabulary:

```bat
py rrls_cli.py --file pattern.txt --no-vocab-learn
```

## Reproduce tests

```bat
py self_test.py
py benchmark_v07_vocabulary.py
```

`self_test.py` specifically verifies that a learned recurrence can solve a new sequence with different initial values via vocabulary replay.

## Scope and limitation

RRLS can search, validate, reuse, and recompress relations inside its current model vocabulary. It does **not** prove that a discovered model is the unique metaphysical cause of finite data, nor can it guarantee the globally shortest possible program for arbitrary input. A finite sequence can admit multiple exact continuations. Held-out validation and minimum-description ranking reduce overfitting but do not eliminate that fundamental ambiguity.

The development target is therefore precise: continuously expand the relation/transform vocabulary while making exact validated relations progressively cheaper to recover and compose.