Skip to main content

​
Get Started in Three Steps

This guide will walk you through running your first repurchase obligation forecast. Here, you’ll see the core components of the Village Operating System in action as you configure and run a complete simulation.
1

Install & Set Up

First, ensure you have access to the Village Labs API. Contact our team at [email protected] for API credentials.
pip install villagelabs-repurchase
2

Prepare Your Input Data

The engine requires four input components:
Set your annual financial and operational assumptions:
operating_assumptions = {
    "contribution_policy": {
        "type": "fixed_amount",
        "annual_amount": 500000
    },
    "share_valuation": {
        "current_price": 100.00,
        "annual_growth_rate": 0.05
    },
    "repurchase_strategy": {
        "timing": "immediate",
        "funding_source": "company_contribution"
    }
}
Provide the current state of your ESOP:
initial_state = {
    "census_year": 2024,
    "participants": [
        {
            "id": "EMP001",
            "age": 45,
            "service_years": 8,
            "allocated_shares": 1000,
            "vested_percentage": 0.80
        }
        # ... more participants
    ],
    "trust_cash": {
        "participant_cash_accounts": 50000,
        "unallocated_contributions": 25000,
        "unallocated_forfeitures": 10000
    },
    "esop_loans": [
        {
            "loan_id": "LOAN_2020",
            "principal_balance": 2000000,
            "interest_rate": 0.065,
            "years_remaining": 8,
            "suspense_shares": 20000
        }
    ]
}
Configure the simulation parameters:
system_config = {
    "projection_years": 20,
    "include_turnover_projection": True,
    "turnover_model": "age_service_based",
    "run_sensitivity_analysis": False
}
3

Run the Simulation

Execute your first simulation:
from villagelabs import RepurchaseEngine

# Initialize the engine
engine = RepurchaseEngine(api_key="your_api_key")

# Run simulation
results = engine.simulate(
    plan_rules=plan_rules,
    operating_assumptions=operating_assumptions,
    initial_state=initial_state,
    system_config=system_config
)

# Access results
print(f"Total 10-year repurchase obligation: ${results.total_repurchase_obligation:,.2f}")
print(f"Peak cash year: {results.peak_cash_year}")

# View year-by-year breakdown
for year in results.annual_projections:
    print(f"Year {year.year}: Repurchases ${year.repurchase_amount:,.2f}")

​
What You Get

After running a simulation, you’ll receive comprehensive results:

Annual Projections

Year-by-year forecasts of all ESOP activities

Repurchase Obligations

Detailed repurchase liability projections

Cash Flow Analysis

Trust cash inflows and outflows

Share Pool Tracking

Allocated, unallocated, and suspense shares

Participant Snapshots

Individual account balances and vesting

Compliance Checks

Diversification and distribution requirements

​
Understanding Your Results

{
  "simulation_id": "sim_2024_001",
  "total_repurchase_obligation": 12500000,
  "peak_cash_year": 2029,
  "peak_cash_amount": 1850000,
  "average_annual_contribution": 525000,
  "final_trust_cash_balance": 450000
}

​
Next Steps

Explore Architecture

Learn how the engine works under the hood

Data Models

Understand the core data structures

Advanced Examples

See complex multi-loan scenarios

API Reference

Full API documentation
Tip: Start with a simple single-loan ESOP to understand the basics, then progress to more complex scenarios with multiple loans and advanced strategies.

​
Common First-Time Questions

The engine uses deterministic logic based on your inputs. Accuracy depends on the quality of your census data, financial assumptions, and turnover projections. We recommend annual recalibration.
Yes! Run multiple simulations with different operating_assumptions (e.g., different contribution levels) and compare results side-by-side.
The engine fully supports leveraged ESOPs with multiple debt tranches. Each loan is modeled independently with its own suspense account. See Multi-Loan Examples.
Diversification is automatically calculated based on participant age and service. The engine flags eligible participants and models elections in your projections.

​
Need Help?

Contact Support

Our team is here to help you get started. Reach out with questions about setup, data preparation, or results interpretation.