# Contract Balance Allocator - Build Instructions

## Overview
Create a Streamlit web application that models contract balances and allocates positive balances to negative balances using a specific allocation algorithm.

## Technical Requirements
- Use Streamlit for the web interface
- Use Pandas for data display
- Create a `requirements.txt` file with:
  - streamlit>=1.28.0
  - pandas>=2.0.0

## Application Features

### 1. Configuration Section
- Allow user to configure the number of contracts (2-20 contracts)
- Use `st.number_input()` with appropriate min/max values
- For each contract, provide an input field to set its balance
  - Balances can be positive, negative, or zero
  - Use float inputs with 2 decimal places
  - Arrange inputs in a responsive column layout (max 3 columns)
- Store balances in Streamlit session state to persist across interactions

### 2. Current State Display
- Show a table/dataframe with all contracts and their current balances
- Format: Contract name (e.g., "Contract 1", "Contract 2") and Balance

### 3. Allocation Button
- Provide a primary button labeled "Allocate Balances"
- When clicked, run the allocation algorithm and display results

### 4. Allocation Algorithm
The algorithm must follow these exact rules:

**Step 1: Sort Positive Balances**
- Identify all contracts with positive balances (balance > 0)
- Sort them in descending order (largest to smallest)

**Step 2: Sort Negative Balances**
- Identify all contracts with negative balances (balance < 0)
- When allocating, always choose the negative balance closest to 0 first
- Re-evaluate after each allocation to find the next closest to 0

**Step 3: Allocation Process**
- Start with the largest positive balance
- Allocate to the negative balance closest to 0
- Allocate enough to bring the negative balance to exactly 0, or exhaust the positive balance (whichever comes first)
- Never allow a negative balance to exceed 0
- After each allocation, re-evaluate which negative balance is now closest to 0
- Continue until the current positive balance is exhausted
- Move to the next largest positive balance and repeat
- Continue until all positive balances are exhausted or all negative balances reach 0

**Example:**
```
Initial state:
Contract 1: 1000 (positive)
Contract 2: -100 (negative)
Contract 3: 500 (positive)
Contract 4: -300 (negative)
Contract 5: -500 (negative)

Process:
1. Use 1000 from Contract 1 to fill -100 from Contract 2 → Contract 2 goes to 0, Contract 1 has 900 left
2. Use 900 from Contract 1 to fill -300 from Contract 4 (now closest to 0) → Contract 4 goes to 0, Contract 1 has 600 left
3. Use 600 from Contract 1 to fill -500 from Contract 5 → Contract 5 goes to -100, Contract 1 has 0 left
4. Use 500 from Contract 3 to fill -100 from Contract 5 → Contract 5 goes to 0, Contract 3 has 400 left

Final state:
Contract 1: 0
Contract 2: 0
Contract 3: 400
Contract 4: 0
Contract 5: 0
```

### 5. Results Display
When the allocation button is clicked, show:

**a) Allocation Details Section**
- A table showing each individual allocation transaction:
  - From: Which contract gave the funds
  - To: Which contract received the funds
  - Amount: How much was transferred
- If no allocations occurred, show an info message

**b) Results Section**
- A table with columns:
  - Contract name
  - Original Balance
  - Final Balance
  - Change (difference between final and original)

**c) Summary Statistics**
- Display three metrics side-by-side:
  - Total Original: Sum of all original balances
  - Total Final: Sum of all final balances (should equal original)
  - Remaining Positive: Sum of all positive balances after allocation

## File Structure
```
app.py              # Main Streamlit application
requirements.txt    # Python dependencies
```

## Implementation Notes
- Use session state to maintain contract balances across reruns
- The allocation algorithm should dynamically re-evaluate which negative balance to fill next (don't pre-sort the entire list)
- Format currency values with dollar signs and commas (e.g., $1,234.56)
- Use appropriate Streamlit components: `st.title()`, `st.header()`, `st.subheader()`, `st.dataframe()`, `st.metric()`, etc.
- Make the UI clean and intuitive with clear section headers

## Running the Application
Users should be able to run the app with:
```bash
pip install -r requirements.txt
streamlit run app.py
```