Fb Occupancy Factorization

---
name: fb_occupancy_factorization
description: Create and validate reduced forward-backward successor-occupancy factorizations from reward-free transition tables.
---

# Forward-Backward Occupancy Factorization

Use this skill when a recovery or implementation needs the FB paper mechanism that summarizes reward-free dynamics before any downstream reward is known. Do not use it for task-specific Q-learning or reward-conditioned training.

## Inputs

- A finite transition table with states, actions, next states, and discount.
- A desired embedding rank for a reduced factorization.
- Optional optimization settings for a bounded gradient step.

## Outputs

- Discounted successor occupancy rows for state-action pairs.
- Forward embeddings `F`, backward embeddings `B`, and scalar reconstruction losses.
- Diagnostics showing whether at least one parameter update reduced loss.

## Workflow

1. Build the transition matrix over state-action rows under a deterministic or supplied behavior policy.
2. Compute the discounted successor occupancy matrix `(I - gamma P)^-1`.
3. Initialize a low-rank FB factorization and run a bounded update that changes trainable parameters.
4. Report `loss_before`, `loss_after`, parameter snapshots, and shape checks.
5. Keep this module reward-free; reward projection belongs to `reward_projection`.

## Validation

Run `python scripts/fb_factorization.py --self-test` or validate through `tests/test_fb_factorization.py`. The tests use a tiny chain/grid and require nonnegative discounted occupancies plus reduced reconstruction loss.

## Limitations

This skill is a reduced deterministic implementation for recovery evidence. It does not claim to reproduce the paper's neural TD training scale.