> ## Documentation Index
> Fetch the complete documentation index at: https://village-docs.villagelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Run your first forecast in 5 minutes with our Repurchase Engine.

## 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.

<Steps>
  <Step title="Install & Set Up">
    First, ensure you have access to the Village Labs API. Contact our team at [support@villagelabs.com](mailto:support@villagelabs.com) for API credentials.

    <CodeGroup>
      ```python Python theme={null}
      pip install villagelabs-repurchase
      ```

      ```javascript JavaScript theme={null}
      npm install @villagelabs/repurchase-engine
      ```
    </CodeGroup>
  </Step>

  <Step title="Prepare Your Input Data">
    The engine requires four input components:

    <AccordionGroup>
      <Accordion title="1. PlanRules (The Legal Framework)">
        Define the ESOP's legal structure and compliance requirements:

        ```python theme={null}
        plan_rules = {
            "plan_name": "Acme Corp ESOP",
            "plan_year_end": "12/31",
            "vesting_schedule": {
                "type": "graded",
                "years_to_full_vesting": 6
            },
            "distribution_policy": {
                "timing": "termination_plus_1_year",
                "form": "lump_sum"
            },
            "cash_usage_policy": [
                "unallocated_company_contributions",
                "unallocated_forfeiture_cash",
                "participant_cash_accounts"
            ]
        }
        ```
      </Accordion>

      <Accordion title="2. OperatingAssumptions (Annual Strategy)">
        Set your annual financial and operational assumptions:

        ```python theme={null}
        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"
            }
        }
        ```
      </Accordion>

      <Accordion title="3. InitialState (Starting Point)">
        Provide the current state of your ESOP:

        ```python theme={null}
        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
                }
            ]
        }
        ```
      </Accordion>

      <Accordion title="4. SystemConfiguration (Simulation Settings)">
        Configure the simulation parameters:

        ```python theme={null}
        system_config = {
            "projection_years": 20,
            "include_turnover_projection": True,
            "turnover_model": "age_service_based",
            "run_sensitivity_analysis": False
        }
        ```
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Run the Simulation">
    Execute your first simulation:

    <CodeGroup>
      ```python Python theme={null}
      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}")
      ```

      ```javascript JavaScript theme={null}
      import { RepurchaseEngine } from '@villagelabs/repurchase-engine';

      // Initialize the engine
      const engine = new RepurchaseEngine({ apiKey: 'your_api_key' });

      // Run simulation
      const results = await engine.simulate({
        planRules,
        operatingAssumptions,
        initialState,
        systemConfig
      });

      // Access results
      console.log(`Total 10-year obligation: $${results.totalRepurchaseObligation}`);
      console.log(`Peak cash year: ${results.peakCashYear}`);

      // View year-by-year breakdown
      results.annualProjections.forEach(year => {
        console.log(`Year ${year.year}: Repurchases $${year.repurchaseAmount}`);
      });
      ```

      ```bash cURL theme={null}
      curl -X POST https://api.villagelabs.com/v1/simulate \
        -H "Authorization: Bearer YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "planRules": {...},
          "operatingAssumptions": {...},
          "initialState": {...},
          "systemConfig": {...}
        }'
      ```
    </CodeGroup>
  </Step>
</Steps>

## What You Get

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

<CardGroup cols={2}>
  <Card title="Annual Projections" icon="chart-line">
    Year-by-year forecasts of all ESOP activities
  </Card>

  <Card title="Repurchase Obligations" icon="money-bill-wave">
    Detailed repurchase liability projections
  </Card>

  <Card title="Cash Flow Analysis" icon="hand-holding-dollar">
    Trust cash inflows and outflows
  </Card>

  <Card title="Share Pool Tracking" icon="shapes">
    Allocated, unallocated, and suspense shares
  </Card>

  <Card title="Participant Snapshots" icon="users">
    Individual account balances and vesting
  </Card>

  <Card title="Compliance Checks" icon="shield-check">
    Diversification and distribution requirements
  </Card>
</CardGroup>

## Understanding Your Results

<Tabs>
  <Tab title="Overview Metrics">
    ```json theme={null}
    {
      "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
    }
    ```
  </Tab>

  <Tab title="Annual Breakdown">
    ```json theme={null}
    {
      "year": 2025,
      "company_contribution": 500000,
      "shares_released": 5000,
      "shares_allocated": 5000,
      "repurchase_events": [
        {
          "participant_id": "EMP042",
          "shares_repurchased": 850,
          "repurchase_amount": 93500,
          "event_type": "retirement"
        }
      ],
      "ending_trust_cash": 425000
    }
    ```
  </Tab>

  <Tab title="Participant Status">
    ```json theme={null}
    {
      "participant_id": "EMP001",
      "year": 2025,
      "allocated_shares": 1200,
      "vested_shares": 1000,
      "account_value": 132000,
      "cash_balance": 5000,
      "diversification_eligible": false
    }
    ```
  </Tab>
</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card title="Explore Architecture" icon="building" href="/architecture/overview">
    Learn how the engine works under the hood
  </Card>

  <Card title="Data Models" icon="database" href="/models/overview">
    Understand the core data structures
  </Card>

  <Card title="Advanced Examples" icon="code" href="/examples/multi-loan">
    See complex multi-loan scenarios
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Full API documentation
  </Card>
</CardGroup>

<Note>
  **Tip:** Start with a simple single-loan ESOP to understand the basics, then progress to more complex scenarios with multiple loans and advanced strategies.
</Note>

## Common First-Time Questions

<AccordionGroup>
  <Accordion title="How accurate are the projections?">
    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.
  </Accordion>

  <Accordion title="Can I compare different scenarios?">
    Yes! Run multiple simulations with different `operating_assumptions` (e.g., different contribution levels) and compare results side-by-side.
  </Accordion>

  <Accordion title="What if I have multiple ESOP loans?">
    The engine fully supports leveraged ESOPs with multiple debt tranches. Each loan is modeled independently with its own suspense account. See [Multi-Loan Examples](/examples/multi-loan).
  </Accordion>

  <Accordion title="How do I handle diversification?">
    Diversification is automatically calculated based on participant age and service. The engine flags eligible participants and models elections in your projections.
  </Accordion>
</AccordionGroup>

## Need Help?

<Card title="Contact Support" icon="headset" href="mailto:support@villagelabs.com">
  Our team is here to help you get started. Reach out with questions about setup, data preparation, or results interpretation.
</Card>