# Transfer Of Earnings Processing POC

Proof of concept demonstrating automated generation and validation of financial adjustment records for **cross-recoupment**, **transfers**, and **override** workflows.

Given input CSVs containing contract/account data, the system calculates adjustment amounts (from balance x percentage or explicit input values) and produces adjustment files in the standard 16-column template format. It then validates generated output against original adjustments to confirm correctness.

## Quick Start

```bash
# No external dependencies — Python 3.x standard library only

# 1. Place your input CSVs in an input/ directory
# 2. Run the three-step pipeline:
python3 extract_adjustments.py   # Extract originals, create trimmed inputs
python3 generate_adjustments.py  # Generate adjustments from trimmed inputs
python3 create_comparisons.py    # Compare generated vs original
```

## How It Works

The pipeline runs in three stages:

1. **Extract** — Separates original adjustment columns from input CSVs and creates "trimmed" versions (so generation doesn't have access to the answers).
2. **Generate** — Reads trimmed inputs and calculates adjustment amounts using the formula: `amount_from_input` if present, otherwise `balance * percentage`. Outputs 16-column adjustment records.
3. **Compare** — Produces side-by-side CSVs showing generated vs original values with a per-row match indicator and summary statistics.

## Example

The `example/` directory contains synthetic sample data you can use to see the pipeline in action:

```bash
# Copy example data into place and run
cp -r example/input input
python3 extract_adjustments.py && python3 generate_adjustments.py && python3 create_comparisons.py
```

**Example input** (`example/input/input_transfers.csv` — one transfer pair):

| Account Name | Contract ID * | Action | Percentage | Balance | Amount |
|-------------|---------------|--------|-----------|---------|--------|
| alpha.wave | 400001 | Transfer of Income | 75.00% | 800.00 | -600.00 |
| beta.pulse | 400002 | Transfer of Income | 75.00% | 1200.00 | 600.00 |

**Example output** (`example/output/generated_transfers_adjustments.csv`):

| Account Name | Account ID * | Contract Name | Contract ID * | Amount * | Currency * | Adjustment Type * | Client Facing Comments * |
|-------------|-------------|--------------|--------------|---------|-----------|------------------|------------------------|
| alpha.wave | 300001 | alpha.wave Distribution | 400001 | -600.00 | USD | Transfer of Income | Jan 26: 75% Closing Balance Transfer to beta.pulse Distribution (400002) |
| beta.pulse | 300002 | beta.pulse Distribution | 400002 | 600.00 | USD | Transfer of Income | Jan 26: 75% Closing Balance Transfer from alpha.wave Distribution (400001) |

## Project Structure

```
poc/
├── extract_adjustments.py          # Step 1: Extract & trim
├── generate_adjustments.py         # Step 2: Generate adjustments
├── create_comparisons.py           # Step 3: Validate
│
├── contract.py                     # Contract model
├── transfer.py                     # Transfer calculation model
├── transfer_of_earnings_config.py  # Transfer config model
│
├── process_all_inputs.py           # End-to-end processor with reporting
├── parse_transfers.py              # CSV parser → config objects
├── run_transfer.py                 # Interactive CLI calculator
├── example_transfers.py            # Worked examples of all transfer types
│
├── example/                        # Synthetic sample data
│   ├── input/                      #   Sample input CSVs
│   └── output/                     #   Expected generated output
│
├── input/                          # (your data) Source input CSVs
├── trimmed_input/                  # (generated) Inputs with adjustments removed
├── output/                         # (generated) Adjustment files & reports
└── comparisons/                    # (generated) Side-by-side validation CSVs
```

## Transfer Calculation Types

| Type | Example Input | Logic |
|------|---------------|-------|
| Percentage Revenue | `100% Net Revenue Override` | `net_revenue * percentage / 100` |
| Percentage Balance | `50% Closing Balance Transfer` | `closing_balance * percentage / 100` |
| Fixed Amount | `6,300 Override` | Fixed value regardless of balance |
| All Recouped | *(conditional)* | Full revenue if contract is recouped, else 0 |

## Output Format

All generated adjustments follow the standard 16-column template:

| # | Column | Source |
|---|--------|--------|
| 1 | Account Name | Input |
| 2 | Account ID * | Input |
| 3 | Contract Name | Input |
| 4 | Contract ID * | Input |
| 5 | UPC | *(empty)* |
| 6 | **Amount *** | **Calculated** |
| 7 | Currency * | Input |
| 8 | Activity Month * | 1 |
| 9 | Activity Year * | 2026 |
| 10 | Statement Month * | 1 |
| 11 | Statement Year * | 2026 |
| 12 | Adjustment Type * | Input |
| 13 | Client Facing Comments * | Input |
| 14 | Distribution Type | *(empty)* |
| 15 | Internal Note | *(empty)* |
| 16 | Apply to Flowthrough Payment | *(empty)* |

## Additional Scripts

- **`process_all_inputs.py`** — Processes all input CSVs end-to-end using the `Contract`/`Transfer` models, generates debit/credit row pairs, and writes both CSV results and a detailed text report.
- **`parse_transfers.py`** — Parses CSV files with duplicate headers into `Contract`, `Calculation`, and `TransferOfEarningsConfiguration` objects.
- **`run_transfer.py`** — Interactive CLI that walks through a single transfer calculation step-by-step.
- **`example_transfers.py`** — Runnable demonstrations of all four transfer calculation types.