# Enterprise Implementation Source: https://village-docs.villagelabs.com/ai-advisory/enterprise-implementation Building custom AI-powered workflows and systems for service providers on the Village Operating System. # Enterprise Strategy Source: https://village-docs.villagelabs.com/ai-advisory/enterprise-strategy Developing a strategic roadmap for service providers and advisory firms to become AI-Native. # AI Strategy for ESOPs Source: https://village-docs.villagelabs.com/ai-advisory/esop-strategy Strategic AI implementation for employee-owned companies ## AI for ESOP Companies Employee-owned companies face unique challenges that AI can help address. We help ESOPs leverage AI to improve operations, enhance decision-making, and ensure long-term sustainability. ## Common ESOP AI Use Cases ### Repurchase Obligation Planning **Challenge:** Forecasting future repurchase obligations is complex and critical **AI Solution:** * Automated scenario modeling * Predictive analytics for turnover and valuation * Cash flow impact analysis * Stress testing different assumptions **Impact:** Better financial planning and reduced repurchase risk ### Administrative Automation **Challenge:** Manual processes for participant communications, document management, and reporting **AI Solution:** * Automated participant statements and communications * Intelligent document processing * Compliance monitoring and alerts * Automated report generation **Impact:** Reduced administrative burden and improved accuracy ### Financial Analysis & Forecasting **Challenge:** Understanding complex financial scenarios and their impact on the ESOP **AI Solution:** * Natural language financial queries * Automated sensitivity analysis * Contribution strategy optimization * Long-term sustainability modeling **Impact:** More informed strategic decisions ### Compliance & Governance **Challenge:** Staying compliant with DOL, IRS, and ERISA requirements **AI Solution:** * Automated compliance checks * Document review and gap analysis * Policy monitoring and alerts * Regulatory change tracking **Impact:** Reduced compliance risk and audit costs ## Implementation Approach ### Phase 1: Foundation (Months 1-3) **Focus:** Data infrastructure and quick wins **Activities:** * Assess current data quality and systems * Implement data collection and storage * Deploy first high-impact use case * Train core team on AI tools **Outcome:** First AI capability in production ### Phase 2: Expansion (Months 4-9) **Focus:** Scale successful use cases **Activities:** * Roll out additional AI capabilities * Integrate with existing systems * Expand user base * Refine and optimize **Outcome:** Multiple AI tools in regular use ### Phase 3: Transformation (Months 10+) **Focus:** AI-driven operations **Activities:** * Advanced analytics and insights * Predictive capabilities * Automated workflows * Continuous optimization **Outcome:** AI embedded in core operations ## Success Stories ### Manufacturing ESOP (\$50M Valuation) **Challenge:** Manual repurchase forecasting taking days of work **Solution:** Automated repurchase modeling with AI-powered scenario analysis **Results:** * Forecasting time reduced from days to minutes * Identified \$2M cash flow gap 3 years in advance * Implemented proactive mitigation strategy ### Professional Services ESOP (\$25M Valuation) **Challenge:** Time-consuming participant communication and reporting **Solution:** AI-powered automated statements and communications **Results:** * 80% reduction in administrative time * Improved participant engagement * Reduced errors in communications ## ROI Expectations **Typical ROI for ESOP AI implementations:** * **Time Savings:** 50-80% reduction in manual tasks * **Cost Reduction:** 30-50% lower administrative costs * **Risk Reduction:** Earlier identification of financial issues * **Decision Quality:** More data-driven strategic choices **Payback Period:** Typically 12-18 months for initial investment ## Getting Started Get a free assessment of AI opportunities for your ESOP # Implementation Services Source: https://village-docs.villagelabs.com/ai-advisory/implementation End-to-end AI implementation for ESOP organizations ## AI Implementation Services We handle the complete lifecycle of AI implementation, from initial concept through production deployment and ongoing optimization. ## Our Implementation Process ### Discovery Phase **What we do:** * Interview stakeholders across your organization * Map current workflows and pain points * Assess data quality and availability * Identify technical requirements * Define success criteria **Deliverables:** * Current state assessment * Opportunity analysis * Prioritized use case recommendations * High-level implementation roadmap **Duration:** 2-4 weeks ### Design Phase **What we do:** * Design solution architecture * Create detailed technical specifications * Plan data pipelines and integrations * Design user interfaces and workflows * Identify security and compliance requirements **Deliverables:** * Technical design document * Architecture diagrams * Integration specifications * Security and compliance plan **Duration:** 3-4 weeks ### Development Phase **What we do:** * Build AI models and algorithms * Develop user interfaces * Implement integrations * Create data pipelines * Build testing and monitoring frameworks **Deliverables:** * Working AI system * Integration with existing systems * Admin and monitoring tools * Technical documentation **Duration:** 8-16 weeks (varies by scope) ### Testing & Validation **What we do:** * Conduct comprehensive testing * Validate with real data and scenarios * Perform security and compliance reviews * Gather user feedback * Refine based on testing results **Deliverables:** * Test results and validation report * Security audit results * User acceptance documentation * Refined system ready for launch **Duration:** 2-3 weeks ### Deployment **What we do:** * Deploy to production environment * Implement monitoring and alerting * Configure backup and disaster recovery * Conduct final security checks * Provide launch support **Deliverables:** * Production deployment * Monitoring dashboard * Operations runbook * Support documentation **Duration:** 1-2 weeks ### Training & Enablement **What we do:** * Conduct hands-on training sessions * Create user guides and documentation * Establish support processes * Train internal champions * Provide ongoing assistance **Deliverables:** * Trained team * Comprehensive documentation * Support framework * Knowledge base **Duration:** 2-4 weeks ### Ongoing Support **What we do:** * Monitor system performance * Implement improvements and updates * Provide technical support * Scale to additional use cases * Stay current with AI advancements **Deliverables:** * Regular performance reports * Feature updates and enhancements * Responsive support * Continuous optimization **Duration:** Ongoing ## Technical Capabilities ### AI & Machine Learning * Large Language Models (LLMs) * Predictive analytics and forecasting * Natural language processing * Computer vision * Anomaly detection ### Integration & Automation * API development and integration * Workflow automation * Data pipeline development * ETL processes * System orchestration ### Infrastructure & Deployment * Cloud infrastructure (AWS, Azure, GCP) * Containerization and orchestration * CI/CD pipelines * Monitoring and observability * Security and compliance ## Quality Assurance ### Testing Approach We implement comprehensive testing: * **Unit testing** - Verify individual components * **Integration testing** - Ensure systems work together * **User acceptance testing** - Validate with real users * **Performance testing** - Ensure scalability * **Security testing** - Identify vulnerabilities ### Compliance & Security Every implementation includes: * Data encryption (at rest and in transit) * Access controls and authentication * Audit logging * Compliance with relevant regulations * Regular security assessments ## Pricing Models ### Fixed-Price Projects Best for well-defined scope and deliverables **Typical range:** $50K - $250K depending on complexity ### Time & Materials Best for exploratory work or evolving requirements **Typical rate:** \$200-300/hour depending on expertise level ### Retainer Arrangements Best for ongoing development and support **Typical monthly:** $15K - $50K depending on scope ## What's Included **All implementations include:** * Project management and coordination * Technical development and testing * Documentation and training materials * Post-launch support (30-90 days) * Knowledge transfer ## Get Started Send us your requirements for a detailed proposal Discuss your project needs with our team # AI Advisory Source: https://village-docs.villagelabs.com/ai-advisory/index Partner with Village Labs to transform your organization into an AI-Native powerhouse. AI Advisory ## Your Partner in AI Transformation Welcome to Village Labs AI Advisory, a strategic service designed to help our clients—both ESOPs and the enterprises that serve them—re-architect their operations to fully leverage the power of Artificial Intelligence. Our mission is to guide you on the journey to becoming an **AI-Native Company**. This isn't just about adopting new tools; it's about fundamentally rethinking how work gets done, enabling your organization to automatically benefit from the exponential improvements in AI technology. Leverage AI to enhance operations, from administration to strategy. Build custom, AI-powered services for your clients on the Village OS. ## Becoming an AI-Native Company An AI-Native company is built to automatically absorb and benefit from progress in AI. As models become more powerful and costs decrease, your organization becomes more efficient, powerful, and scalable. We guide you through three stages of maturity. graph TD A\[Stage 1: Task Automation] --> B\[Stage 2: Workflow Integration] B --> C\[Stage 3: Strategic Oversight] subgraph A direction LR A1\[Individual agents perform discrete tasks] A2\[Example: Auditing a single report] end subgraph B direction LR B1\[Agents are connected into custom workflows] B2\[Example: Full trust reconciliation process] end subgraph C direction LR C1\[Humans oversee swarms of agents handling complex operations] C2\[Example: Managing an entire TPA service line] end style A fill:#E3F2FD,stroke:#90CAF9 style B fill:#E8F5E9,stroke:#A5D6A7 style C fill:#FFFDE7,stroke:#FFF59D ### The Core Principles * **Automatic Scaling:** Your capabilities grow as AI technology advances, without constant reinvestment. * **Cost Efficiency:** Operating costs decrease as inference and data infrastructure become cheaper. * **Human Elevation:** Your team transitions from performing tedious tasks to overseeing high-value work executed by agent swarms, focusing on strategy and client relationships. ## Our Engagement Process We offer a structured, two-tiered engagement model designed to provide a clear path to AI transformation, built upon the powerful foundation of the Peninsula platform and the Kelso agent. Our engagement begins with a two-person team conducting an intensive on-site visit. We immerse ourselves in your business: interviewing executives, observing workflows, and analyzing your current systems. **Deliverable: The AI Audit Report** Within two weeks, we deliver a comprehensive AI Audit Report. This isn't a static PDF; it's a dynamic, queryable knowledge base installed directly into your Kelso instance. It includes: * A full analysis of AI opportunities within your operations. * A technical plan for custom tools and agentic systems. * An ongoing resource for you to ask Kelso questions about your AI transformation roadmap. Following the audit, we move to implementation. We use the Village Operating System to build the custom modules, tools, and templatized agent workflows identified in your roadmap. This is a collaborative process to build the precise systems you need to become AI-Native. # AI Advisory Source: https://village-docs.villagelabs.com/ai-advisory/overview Generative AI advisory and implementation services # AI Advisory We work with ESOPs and advisory firms to help them identify where to leverage generative AI effectively. Then design and deploy tailored systems and agents. ## What We Offer Our AI advisory services help organizations become AI-native by: * Identifying high-impact AI opportunities * Designing custom AI solutions and agent systems * Implementing and deploying AI tools * Training teams to use AI effectively ## For ESOPs and Advisory Firms Whether you're an ESOP company looking to improve operations or an advisory firm wanting to serve clients better, we help you leverage AI strategically. Learn about our complete AI transformation approach # The State of AI Source: https://village-docs.villagelabs.com/ai-advisory/state-of-ai Insights and analysis on AI in the ESOP industry ## The State of AI in ESOPs An ongoing analysis of how artificial intelligence is transforming the employee ownership landscape. ## Key Insights ### 1. AI Adoption is Accelerating The ESOP industry is beginning to embrace AI, with early adopters seeing significant benefits: * **Administrative automation** is the most common entry point * **Financial forecasting** is rapidly gaining traction * **Advisory firms** are ahead of direct ESOPs in adoption * **ROI is becoming more predictable** as use cases mature ### 2. The Data Challenge Quality data remains the biggest barrier to AI adoption: * Many ESOPs lack centralized, clean data * Legacy systems make integration difficult * Data governance is often informal * But: the barrier is shrinking as tools improve ### 3. Regulatory Considerations AI in ESOPs must navigate specific compliance requirements: * DOL oversight of fiduciary decisions * IRS requirements for valuation and fairness * ERISA compliance for plan administration * Need for explainable AI in critical decisions ### 4. Competitive Advantage AI is becoming a differentiator: * **Early adopters** are gaining operational efficiency * **Advisory firms** using AI can serve more clients * **Better forecasting** leads to better outcomes * **Automation** frees up time for strategic work ### 5. The Human Element Remains Critical AI augments, not replaces, human expertise: * Complex decisions still require human judgment * Fiduciary duties can't be delegated to AI * Relationship-building remains essential * AI handles routine tasks, humans handle exceptions ## Industry Trends ### Short Term (1-2 Years) **Expected developments:** * Widespread adoption of AI-powered repurchase forecasting * Automated compliance monitoring becomes standard * Natural language interfaces for ESOP data * AI-assisted document review and processing ### Medium Term (3-5 Years) **Expected developments:** * Predictive analytics for ESOP sustainability * AI-powered trustee decision support * Automated valuation assistance tools * Industry-wide benchmarking and insights ### Long Term (5+ Years) **Expected developments:** * AI-native ESOP administration platforms * Real-time regulatory compliance monitoring * Predictive models for optimal ESOP structure * Industry transformation through AI integration ## Opportunities by Organization Type ### For ESOP Companies **High-impact opportunities:** * Repurchase obligation forecasting * Participant communication automation * Financial scenario modeling * Compliance monitoring ### For Advisory Firms **High-impact opportunities:** * Client analysis and reporting * Proposal generation and customization * Research and market intelligence * Workflow automation ### For TPAs **High-impact opportunities:** * Administrative task automation * Document processing and review * Regulatory compliance checking * Client communication ### For Valuation Firms **High-impact opportunities:** * Data collection and analysis * Comparable company identification * Report generation * Sensitivity analysis ## Common Misconceptions ### "AI will replace ESOP professionals" **Reality:** AI augments professional expertise, handling routine tasks so professionals can focus on high-value strategic work. ### "AI is too expensive for smaller ESOPs" **Reality:** AI costs are dropping rapidly, and SaaS models make powerful tools accessible to organizations of all sizes. ### "AI decisions aren't explainable" **Reality:** Modern AI systems can provide clear explanations for their recommendations, important for fiduciary compliance. ### "We need perfect data before starting" **Reality:** AI can help improve data quality over time. Starting with imperfect data is better than waiting. ### "AI is a future concern" **Reality:** AI is already being used successfully in the ESOP industry. The question is when to adopt, not if. ## Getting Started with AI ### Step 1: Assess Your Readiness * Evaluate current data infrastructure * Identify pain points and opportunities * Determine resource availability * Set realistic expectations ### Step 2: Start Small * Choose one high-impact use case * Pilot with a limited scope * Measure results carefully * Learn and iterate ### Step 3: Build Foundation * Improve data quality and governance * Establish AI policies and guidelines * Train team on AI capabilities * Create internal champions ### Step 4: Scale Strategically * Expand successful use cases * Add additional capabilities * Integrate across operations * Continuously optimize ## Resources Learn how Village Labs can help you implement AI Explore our AI-powered forecasting engine Try our AI assistant for ESOP analysis ## Stay Updated The AI landscape is evolving rapidly. We regularly publish new insights and analysis. Get notified when we publish new State of AI content # API Introduction Source: https://village-docs.villagelabs.com/api-reference/introduction Getting started with the Repurchase Engine API ## Overview The Repurchase Engine API provides programmatic access to all simulation, scenario management, and data retrieval capabilities. **Base URL:** `https://api.villagelabs.com/v1` All API requests require authentication via API key. ## Authentication Include your API key in the `Authorization` header: ```bash theme={null} Authorization: Bearer YOUR_API_KEY ``` ### Get Your API Key Contact [support@villagelabs.com](mailto:support@villagelabs.com) to receive your API credentials. ## Quick Start ```bash Python theme={null} pip install villagelabs-repurchase ``` ```bash JavaScript theme={null} npm install @villagelabs/repurchase-engine ``` ```python Python theme={null} from villagelabs import RepurchaseEngine engine = RepurchaseEngine(api_key="your_api_key") ``` ```javascript JavaScript theme={null} import { RepurchaseEngine } from '@villagelabs/repurchase-engine'; const engine = new RepurchaseEngine({ apiKey: 'your_api_key' }); ``` ```python Python theme={null} results = engine.simulate( plan_rules=plan_rules, operating_assumptions=operating_assumptions, initial_state=initial_state ) ``` ```javascript JavaScript theme={null} const results = await engine.simulate({ planRules, operatingAssumptions, initialState }); ``` ## Core Endpoints Run a new simulation List all scenarios Create a new scenario Get simulation run details ## Request Format All requests use JSON: ```json theme={null} { "planRules": { "plan_name": "Acme Corp ESOP", "vesting_schedule": {...} }, "operatingAssumptions": { "contribution_policy": {...} }, "initialState": { "participants": [...] } } ``` ## Response Format Standard API response structure: ```json theme={null} { "success": true, "data": { "simulation_id": "sim_2024_001", "status": "completed", "results": {...} }, "meta": { "execution_time_ms": 1842, "api_version": "1.0" } } ``` ## Error Handling Errors return standard HTTP status codes with detailed messages: ```json theme={null} { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Invalid vesting schedule", "details": { "field": "vesting_schedule.years", "issue": "Must be between 2 and 7" } } } ``` ## Rate Limits 100 requests/hour 10 simulations/hour Unlimited requests Dedicated infrastructure ## SDKs & Libraries ```bash theme={null} pip install villagelabs-repurchase ``` [GitHub Repository](https://github.com/villagelabsdotapp/repurchase-python) ```bash theme={null} npm install @villagelabs/repurchase-engine ``` [GitHub Repository](https://github.com/villagelabsdotapp/repurchase-js) Direct HTTP calls to `api.villagelabs.com/v1` Works with any language/tool ## Data Schemas Legal framework schema Strategy configuration schema Output data structures ## Webhooks Subscribe to simulation events: ```json theme={null} { "event": "simulation.completed", "simulation_id": "sim_2024_001", "status": "completed", "webhook_url": "https://your-app.com/webhooks/simulations" } ``` ## Best Practices Use SDK validation methods before making API calls to catch errors early Store simulation results locally; re-run only when inputs change For long-running simulations, use webhooks instead of polling Implement retry logic with exponential backoff for transient errors ## Next Steps Execute your first API simulation Create and organize scenarios Complete schema reference See full code examples ## Support **Email:** [support@villagelabs.com](mailto:support@villagelabs.com) **Documentation:** You're reading it! **GitHub Issues:** Report bugs and request features # Simulation Runs API Source: https://village-docs.villagelabs.com/api-reference/runs Retrieve simulation results ## Get Run `GET /runs/{id}` Returns complete simulation results including: * Annual projections * Participant snapshots * Trust states * Summary metrics ## List Runs `GET /runs?scenario_id={id}` Filter runs by scenario. See [API Introduction](/api-reference/introduction) for details. # Scenarios API Source: https://village-docs.villagelabs.com/api-reference/scenarios Manage scenario configurations ## List Scenarios `GET /scenarios` ## Create Scenario `POST /scenarios` ```json theme={null} { "name": "Conservative Strategy", "plan_rules": { }, "operating_assumptions": { } } ``` ## Get Scenario `GET /scenarios/{id}` See [API Introduction](/api-reference/introduction) for authentication details. # OperatingAssumptions API Schema Source: https://village-docs.villagelabs.com/api-reference/schemas/operating-assumptions Complete OperatingAssumptions schema ## Schema See [OperatingAssumptions Model](/models/operating-assumptions) for detailed documentation. ```typescript theme={null} interface OperatingAssumptions { contribution_policy: ContributionPolicy; share_valuation: ValuationAssumptions; repurchase_strategy: RepurchaseStrategy; financial_projections: FinancialProjections; } ``` # PlanRules API Schema Source: https://village-docs.villagelabs.com/api-reference/schemas/plan-rules Complete PlanRules schema reference ## Schema Complete JSON schema for PlanRules object. See [PlanRules Model](/models/plan-rules) for detailed documentation. ```typescript theme={null} interface PlanRules { plan_name: string; plan_year_end: string; vesting_schedule: VestingSchedule; distribution_policy: DistributionPolicy; cash_usage_policy: string[]; diversification_rules: DiversificationRules; } ``` # API Response Schemas Source: https://village-docs.villagelabs.com/api-reference/schemas/responses Output data structures ## Simulation Response ```typescript theme={null} interface SimulationResponse { simulation_id: string; status: 'completed' | 'running' | 'failed'; total_repurchase_obligation: number; peak_cash_year: number; peak_cash_amount: number; annual_projections: AnnualProjection[]; } interface AnnualProjection { year: number; company_contribution: number; shares_released: number; repurchase_amount: number; ending_trust_cash: number; } ``` See [API Introduction](/api-reference/introduction) for more details. # POST /simulate Source: https://village-docs.villagelabs.com/api-reference/simulate POST https://api.villagelabs.com/v1/simulate Run a new ESOP simulation ## Request ```json theme={null} { "planRules": { }, "operatingAssumptions": { }, "initialState": { }, "systemConfig": { } } ``` ## Response ```json theme={null} { "success": true, "data": { "simulation_id": "sim_2024_001", "status": "completed", "results": { "total_repurchase_obligation": 8450000, "peak_cash_year": 2029, "annual_projections": [ ] } } } ``` See [Quick Start](/quickstart) for complete example. # Data Layer Source: https://village-docs.villagelabs.com/architecture/data-layer Immutable, versioned database architecture ## The System of Record The Data Layer is a **versioned, relational database** that serves as the immutable system of record for all modeling activities. Every input, execution, and output is permanently archived with full audit trails. **Core Principle:** Nothing is ever overwritten. All data is append-only, creating perfect reproducibility and temporal analysis capabilities. ## Database Architecture ```mermaid theme={null} erDiagram SCENARIOS ||--o{ SIMULATION_RUNS : generates CENSUSES ||--o{ SIMULATION_RUNS : uses SIMULATION_RUNS ||--o{ ANNUAL_COMPANY_STATES : produces SIMULATION_RUNS ||--o{ ANNUAL_TRUST_STATES : produces SIMULATION_RUNS ||--o{ ANNUAL_PARTICIPANT_SNAPSHOTS : produces SIMULATION_RUNS ||--o{ PROCESSING_LOGS : records SCENARIOS ||--|| PLAN_RULES : contains SCENARIOS ||--|| OPERATING_ASSUMPTIONS : contains ``` ## Core Tables ### Input Tables Immutable records of all versioned scenario configurations. ```sql theme={null} CREATE TABLE scenarios ( id VARCHAR PRIMARY KEY, created_at TIMESTAMP, created_by VARCHAR, name VARCHAR, description TEXT, plan_rules_id VARCHAR, operating_assumptions_id VARCHAR, version INTEGER, parent_scenario_id VARCHAR -- For scenario variants ); ``` **Key Features:** * Every scenario is versioned * Scenarios can fork from parent scenarios * Immutable once created Versioned participant data snapshots. ```sql theme={null} CREATE TABLE censuses ( id VARCHAR PRIMARY KEY, created_at TIMESTAMP, census_year INTEGER, participant_count INTEGER, version INTEGER, data_source VARCHAR -- 'actual' or 'projected' ); CREATE TABLE census_participants ( census_id VARCHAR, participant_id VARCHAR, age INTEGER, service_years DECIMAL, compensation DECIMAL, allocated_shares DECIMAL, vested_percentage DECIMAL, PRIMARY KEY (census_id, participant_id) ); ``` Legal framework configurations. ```sql theme={null} CREATE TABLE plan_rules ( id VARCHAR PRIMARY KEY, plan_name VARCHAR, plan_year_end VARCHAR, vesting_schedule JSONB, distribution_policy JSONB, diversification_rules JSONB, cash_usage_policy JSONB, created_at TIMESTAMP ); ``` Annual strategy settings. ```sql theme={null} CREATE TABLE operating_assumptions ( id VARCHAR PRIMARY KEY, contribution_policy JSONB, share_valuation JSONB, repurchase_strategy JSONB, financial_projections JSONB, turnover_assumptions JSONB, created_at TIMESTAMP ); ``` ### Processing Tables Execution metadata connecting inputs to outputs. ```sql theme={null} CREATE TABLE simulation_runs ( id VARCHAR PRIMARY KEY, scenario_id VARCHAR, census_id VARCHAR, system_config JSONB, started_at TIMESTAMP, completed_at TIMESTAMP, status VARCHAR, -- 'running', 'completed', 'failed' projection_start_year INTEGER, projection_end_year INTEGER, error_message TEXT, execution_metrics JSONB -- performance stats ); ``` **The Logbook:** This table is the permanent record connecting specific inputs to specific outputs. Step-by-step audit trail. ```sql theme={null} CREATE TABLE processing_logs ( id SERIAL PRIMARY KEY, simulation_run_id VARCHAR, year INTEGER, step_number INTEGER, step_name VARCHAR, timestamp TIMESTAMP, duration_ms INTEGER, inputs JSONB, outputs JSONB, decisions JSONB, warnings TEXT[] ); ``` **Complete Transparency:** Every decision the engine makes is logged. All modeled transactions. ```sql theme={null} CREATE TABLE events ( id SERIAL PRIMARY KEY, simulation_run_id VARCHAR, year INTEGER, event_type VARCHAR, -- 'termination', 'repurchase', etc. participant_id VARCHAR, event_date DATE, shares_affected DECIMAL, cash_amount DECIMAL, details JSONB, created_at TIMESTAMP ); ``` ### Output Tables Year-by-year company financial snapshots. ```sql theme={null} CREATE TABLE annual_company_states ( simulation_run_id VARCHAR, year INTEGER, source_type VARCHAR, -- 'actual' or 'simulated' revenue DECIMAL, ebitda DECIMAL, total_payroll DECIMAL, esop_contribution DECIMAL, financial_metrics JSONB, PRIMARY KEY (simulation_run_id, year) ); ``` **Source Type:** Distinguishes historical actuals from future projections. Year-by-year ESOP trust snapshots. ```sql theme={null} CREATE TABLE annual_trust_states ( simulation_run_id VARCHAR, year INTEGER, source_type VARCHAR, total_shares_outstanding DECIMAL, allocated_shares DECIMAL, suspense_shares DECIMAL, unallocated_shares DECIMAL, cash_ledger JSONB, loans JSONB, share_price DECIMAL, PRIMARY KEY (simulation_run_id, year) ); ``` Individual participant account states per year. ```sql theme={null} CREATE TABLE annual_participant_snapshots ( simulation_run_id VARCHAR, year INTEGER, participant_id VARCHAR, source_type VARCHAR, allocated_shares DECIMAL, vested_percentage DECIMAL, vested_shares DECIMAL, account_value DECIMAL, cash_balance DECIMAL, status VARCHAR, -- 'active', 'terminated', etc. age INTEGER, service_years DECIMAL, diversification_eligible BOOLEAN, PRIMARY KEY (simulation_run_id, year, participant_id) ); ``` ## Versioning Strategy ### Scenario Versioning Scenarios can be versioned to track changes over time: ```python theme={null} # Original scenario (June 2024) scenario_v1 = Scenario( id="acme_base", version=1, contribution_amount=500_000 ) # Updated scenario (September 2024) scenario_v2 = Scenario( id="acme_base", version=2, parent_scenario_id="acme_base_v1", contribution_amount=450_000, # Reduced change_log="Reduced contribution due to market conditions" ) ``` ### Source Type Classification All data is tagged with `source_type`: * **`'actual'`**: Historical, verified data * **`'simulated'`**: Forecasted data from model runs This enables powerful queries: ```sql theme={null} -- Compare actual vs. projected for year 2024 SELECT actual.repurchase_amount as actual_repurchases, simulated.repurchase_amount as projected_repurchases, (actual.repurchase_amount - simulated.repurchase_amount) as variance FROM annual_trust_states actual JOIN annual_trust_states simulated ON actual.year = simulated.year WHERE actual.source_type = 'actual' AND simulated.source_type = 'simulated' AND actual.year = 2024; ``` ## Temporal Analysis Capabilities The immutable architecture enables sophisticated temporal queries: Track how your forecasts changed over time: ```sql theme={null} -- How did our 2028 repurchase forecast evolve? SELECT sr.completed_at as forecast_date, ats.repurchase_amount as projected_2028_repurchases FROM simulation_runs sr JOIN annual_trust_states ats ON sr.id = ats.simulation_run_id WHERE ats.year = 2028 AND ats.source_type = 'simulated' ORDER BY sr.completed_at; ``` Identify which assumption changes drove result differences: ```sql theme={null} -- What changed between runs? SELECT jsonb_diff( old_run.operating_assumptions, new_run.operating_assumptions ) as assumption_changes FROM scenarios old_run, scenarios new_run WHERE old_run.id = 'acme_v1' AND new_run.id = 'acme_v2'; ``` Compare forecasts to actuals to measure model accuracy: ```sql theme={null} -- How accurate was our 2024 forecast made in 2023? SELECT projected.repurchase_amount as forecast, actual.repurchase_amount as actual, ABS(projected.repurchase_amount - actual.repurchase_amount) / actual.repurchase_amount as error_percentage FROM annual_trust_states projected JOIN annual_trust_states actual ON projected.year = actual.year WHERE projected.source_type = 'simulated' AND projected.simulation_run_id = 'run_2023_forecast' AND actual.source_type = 'actual' AND actual.year = 2024; ``` ## Data Integrity ### Constraints & Validation ```sql theme={null} -- Ensure share conservation ALTER TABLE annual_trust_states ADD CONSTRAINT shares_balance_check CHECK ( total_shares_outstanding = allocated_shares + suspense_shares + unallocated_shares ); -- Prevent negative cash ALTER TABLE annual_trust_states ADD CONSTRAINT cash_positive_check CHECK ( (cash_ledger->>'total_cash')::DECIMAL >= 0 ); ``` ### Referential Integrity ```sql theme={null} -- All simulation runs must reference valid scenarios ALTER TABLE simulation_runs ADD FOREIGN KEY (scenario_id) REFERENCES scenarios(id); -- All participant snapshots must reference valid runs ALTER TABLE annual_participant_snapshots ADD FOREIGN KEY (simulation_run_id) REFERENCES simulation_runs(id) ON DELETE CASCADE; ``` ## Query Patterns ### Common Queries ```sql theme={null} SELECT * FROM simulation_runs WHERE scenario_id = 'acme_base' ORDER BY completed_at DESC LIMIT 1; ``` ```sql theme={null} SELECT s1.year, s1.repurchase_amount as scenario_a, s2.repurchase_amount as scenario_b, s2.repurchase_amount - s1.repurchase_amount as difference FROM annual_trust_states s1 JOIN annual_trust_states s2 ON s1.year = s2.year WHERE s1.simulation_run_id = 'run_scenario_a' AND s2.simulation_run_id = 'run_scenario_b'; ``` ```sql theme={null} SELECT year, repurchase_amount FROM annual_trust_states WHERE simulation_run_id = 'run_123' ORDER BY repurchase_amount DESC LIMIT 1; ``` ```sql theme={null} SELECT year, allocated_shares, vested_shares, account_value FROM annual_participant_snapshots WHERE simulation_run_id = 'run_123' AND participant_id = 'EMP001' ORDER BY year; ``` ## Backup & Recovery Restore database to any point in history Export specific runs for offline archival Daily backups with 90-day retention Multi-region replication for business continuity ## Performance Considerations ```sql theme={null} -- Fast simulation run lookups CREATE INDEX idx_runs_scenario ON simulation_runs(scenario_id, completed_at); -- Fast year-based queries CREATE INDEX idx_trust_year ON annual_trust_states(simulation_run_id, year); -- Fast participant lookups CREATE INDEX idx_participant ON annual_participant_snapshots(participant_id, year); ``` Large tables partitioned by simulation\_run\_id for faster queries and easier archival. Pre-computed aggregations for common dashboard queries (e.g., total repurchase obligations by year). ## Next Steps Explore the object models built on this database Learn how to query and manipulate data via API # Core Design Principles Source: https://village-docs.villagelabs.com/architecture/design-principles The foundational concepts that drive the Repurchase Engine architecture ## Foundational Philosophy The Repurchase Engine is built upon three core design principles that ensure its robustness, auditability, and extensibility. These principles inform every architectural decision and distinguish this system from traditional financial modeling tools. Distinguish legal rules from business strategy Never overwrite; always append High-level intents, not low-level functions *** ## Principle 1: Separation of Concerns ### Plan Rules vs. Operating Assumptions The engine's input framework makes a **crucial distinction** between two types of information:
### PlanRules **The "Constitution"** The stable, legal framework of the ESOP as defined in the official plan document. **Characteristics:** * Non-discretionary * Legally binding * Changes infrequently * Requires plan amendments **Examples:** * Vesting schedule * Distribution timing * Diversification eligibility * Cash usage hierarchy
### OperatingAssumptions **The "Annual Strategy"** The discretionary, variable financial decisions made by the company on an annual basis. **Characteristics:** * Discretionary * Business decisions * Changes annually * No legal filing required **Examples:** * Contribution amounts * Share valuations * Repurchase timing * Growth assumptions
### Why This Matters This separation directly reflects how plan sponsors and fiduciaries actually think and operate. The plan document is the unchanging foundation, while annual business decisions vary based on financial conditions. To compare scenarios, you simply swap out `OperatingAssumptions` while keeping `PlanRules` constant. No need to duplicate or modify legal configurations. ```python theme={null} # Scenario 1: Conservative conservative = engine.simulate( plan_rules=legal_framework, operating_assumptions=conservative_strategy ) # Scenario 2: Aggressive aggressive = engine.simulate( plan_rules=legal_framework, # Same rules! operating_assumptions=aggressive_strategy ) ``` By structurally separating legal requirements from business decisions, the system prevents common errors like accidentally modifying vesting schedules when you meant to change contribution levels. ### Implementation Example ```json theme={null} { "plan_name": "Acme Corp ESOP", "plan_year_end": "12/31", "vesting_schedule": { "type": "graded", "schedule": [0, 0, 20, 40, 60, 80, 100] }, "distribution_policy": { "timing": "termination_plus_1_year", "form": "lump_sum", "in_service_allowed": false }, "cash_usage_policy": [ "unallocated_company_contributions", "unallocated_forfeiture_cash", "participant_cash_accounts" ] } ``` ☝️ *These rarely change* ```json theme={null} { "contribution_policy": { "type": "fixed_amount", "amount": 500000 }, "share_valuation": { "current_price": 100.00, "annual_growth_rate": 0.05 }, "repurchase_strategy": { "timing": "immediate", "funding_source": "company_contribution" }, "financial_projections": { "revenue_growth": 0.08, "ebitda_margin": 0.22 } } ``` ☝️ *These change annually* *** ## Principle 2: Immutability ### The Database as a System of Record The data layer is a **temporal, stateful, and immutable system of record**. **First Principle:** A model's credibility is tied to its reproducibility. We never overwrite data; every input scenario and simulation run is a permanent, versioned record. ### The Problem with Traditional Approaches Most financial models overwrite results: ``` ❌ Traditional Model: Run 1 (June) → results.xlsx → ✓ Run 2 (Sept) → results.xlsx → ✓ [Run 1 data lost!] Questions: - What changed between runs? - Can we reproduce June's results? - Which assumptions drove the differences? Answer: 🤷 Unknown ``` ### The Immutable Approach The Repurchase Engine appends, never overwrites: ``` ✅ Immutable System: Run 1 (June) → Scenario A v1 → SimRun #123 → Results archived Run 2 (Sept) → Scenario A v2 → SimRun #456 → Results archived Questions: - What changed? → Diff Scenario v1 vs v2 - Reproduce June? → Replay SimRun #123 - Compare results? → Query both runs Answer: ✅ Fully auditable ``` ### Implementation Every simulation creates permanent, timestamped records: ```sql theme={null} scenarios id: "scenario_2024_06_15_001" created_at: "2024-06-15T10:30:00Z" plan_rules: {...} operating_assumptions: {...} version: 1 ``` ```sql theme={null} simulation_runs id: "run_123" scenario_id: "scenario_2024_06_15_001" run_at: "2024-06-15T10:31:22Z" status: "completed" duration_ms: 1842 ``` ```sql theme={null} annual_trust_states simulation_run_id: "run_123" year: 2025 cash_balance: 425000 allocated_shares: 45000 source_type: "simulated" ``` ### Benefits Rerun any historical simulation and get identical results Compare how forecasts evolved over time Complete record of all modeling decisions Trace back to exact inputs that produced any output ### Real-World Application ```python theme={null} # September 2024: Review June's forecast june_run = engine.get_run("run_123") sept_run = engine.get_run("run_456") # Compare assumptions diff = engine.compare_scenarios( june_run.scenario_id, sept_run.scenario_id ) # Analyze: "Why did repurchase obligations increase?" print(diff.changes) # Output: # - share_valuation.annual_growth_rate: 0.05 → 0.08 # - contribution_policy.amount: 500000 → 450000 ``` *** ## Principle 3: Abstraction ### The Agent Toolkit as a User Intent Layer The engine is designed for deep integration with AI agents like Kelso (or Claude, GPT, etc.). **First Principle:** The tools exposed to an agent represent high-level **user intents** (e.g., "compare two scenarios"), not a direct mapping to internal engine functions. ### The Problem with Tight Coupling ``` ❌ Tight Coupling: Agent Tool: get_share_pool() Engine Function: _calculate_share_pool_with_loan_releases() Problem: If engine refactors internal logic, agent breaks ``` ### The Abstraction Layer ``` ✅ Abstraction: Agent Tool: compare_scenarios(scenario_a, scenario_b) Intent: "User wants to understand differences" Engine: Can completely change internal implementation Result: Agent still works because intent is preserved ``` ### Agent Toolkit Design The toolkit exposes **user-facing intents**, not technical functions: ```python theme={null} # High-level, stable intent-based API agent_toolkit = [ "create_scenario", # "I want to model a plan" "run_simulation", # "Show me the forecast" "compare_scenarios", # "How do these differ?" "analyze_repurchase_risk", # "Where are the danger zones?" "optimize_contribution", # "What's the ideal amount?" "export_results" # "Give me a report" ] ``` ☝️ *Stable, semantic, user-oriented* ```python theme={null} # Complex internal implementation (hidden from agents) def compare_scenarios(scenario_a_id, scenario_b_id): # 1. Load scenarios from database # 2. Run differential analysis # 3. Identify key drivers of differences # 4. Generate natural language summary # 5. Create visualization data # 6. Package for agent consumption # This can be completely rewritten without breaking agents ``` ☝️ *Complex, technical, implementation-specific* ### Benefits The agent's core conversational and analytical abilities remain intact even if the engine's internal logic is completely overhauled. Agent tools map directly to how users think and speak: ``` User: "Can you compare my June and September forecasts?" Agent: compare_scenarios("june_forecast", "sept_forecast") ``` Agent developers don't need deep knowledge of ESOP mechanics or engine internals. They work with high-level concepts that match user needs. ### Real-World Example ``` User: "Kelso, what happens if we reduce our contribution by 20%?" Agent (Internal): 1. create_scenario(base_scenario, modify={contribution: -20%}) 2. run_simulation(new_scenario) 3. compare_scenarios(base_scenario, new_scenario) 4. analyze_repurchase_risk(new_scenario) Agent (Response): "If you reduce contributions by 20%, your 10-year repurchase obligation increases by $1.2M due to slower loan paydown and reduced cash reserves. Peak cash years shift from 2028 to 2030..." ``` *** ## How These Principles Work Together The three principles create a powerful, resilient system: ``` ┌──────────────────────────────────────────────────────┐ │ Agent Layer (Abstraction) │ │ High-level user intents │ └─────────────────┬────────────────────────────────────┘ │ ↓ ┌──────────────────────────────────────────────────────┐ │ Engine Layer (Separation of Concerns) │ │ PlanRules + OperatingAssumptions → Processing │ └─────────────────┬────────────────────────────────────┘ │ ↓ ┌──────────────────────────────────────────────────────┐ │ Data Layer (Immutability) │ │ Versioned, append-only system of record │ └──────────────────────────────────────────────────────┘ ``` * **Separation** makes configuration intuitive * **Immutability** makes results reproducible * **Abstraction** makes integration stable → Result: A system that's both powerful and maintainable ## Next Steps See how these principles are implemented in processing Explore the immutable database structure # System Overview Source: https://village-docs.villagelabs.com/architecture/overview An overview of our enterprise-grade ESOP financial modeling architecture. ## System Philosophy At Village Labs, we designed the Repurchase Engine for **transparency, fidelity, and scalability**. Our architecture separates the core simulation logic from data intake and reporting, allowing for maximum flexibility. This modular design is a key principle of our **Village Operating System**, ensuring that each component is specialized and highly effective. The architecture is grounded in the legal and financial first principles of ESOPs. This ensures that the outputs from our engine are not only predictive but also robust, auditable, and defensible. ## Core Capability The engine's core capability is to **process a company's census data and financial state through a discrete, step-by-step annual simulation cycle**, producing a detailed year-over-year forecast of all ESOP activities. ```mermaid theme={null} graph LR A[Input Data] --> B[Simulation Engine] B --> C[Year 1 Processing] C --> D[Year 2 Processing] D --> E[...] E --> F[Year N Processing] F --> G[Complete Forecast] style B fill:#29371F,color:#fff style G fill:#3D5030,color:#fff ``` ## System Architecture Discrete annual processing pipeline Immutable, versioned system of record Foundational architectural concepts PlanRules, OperatingAssumptions, and more ## High-Level Flow Provide four structured inputs: * **PlanRules**: Legal framework * **OperatingAssumptions**: Annual strategy * **InitialState**: Current ESOP state * **SystemConfiguration**: Simulation settings For each projection year, execute ordered processing steps: * Turnover projection * Share pool calculation * Contribution determination * Diversification processing * Repurchase events Record complete snapshots: * Company financial state * Trust cash and shares * Individual participant accounts * All transactions and events Generate comprehensive results: * Annual projections * Repurchase obligations * Cash flow analysis * Participant snapshots ## Key Components ### 1. Simulation Core The heart of the system is a **discrete, step-by-step annual processing pipeline**. For each year of a projection, the engine executes a sequence of modules, each responsible for a specific aspect of ESOP administration. ```python theme={null} # Conceptual annual processing flow for year in range(start_year, end_year): # Step 0: Project employee turnover (optional) turnover_events = project_turnover(participants, year) # Step 1: Initialize year - calculate share price share_price = calculate_share_price(company_equity, outstanding_shares) # Step 2: Determine share pool for allocation share_pool = calculate_share_pool(esop_loans, contributions) # Step 3: Allocate shares to participants allocations = allocate_shares(share_pool, eligible_participants) # Step 4: Calculate company contribution contribution = determine_contribution(policy, financial_state) # Step 5: Update vesting status vesting_updates = update_vesting(participants, vesting_schedule) # Step 6: Process diversification elections diversifications = process_diversifications(eligible_participants) # Step 7: Process repurchase events repurchases = process_repurchases(terminated_participants, funding_waterfall) # Step 8: Year-end closing - roll forward and evolve year_end_closing(participants, company_state, trust_state) # Capture year-end state save_annual_snapshot(year, company_state, trust_state, participants) ``` **Critical Design Choice:** This strict order of operations ensures that legal obligations are met before discretionary actions are taken. ### 2. Data Layer All inputs and outputs are managed in a **versioned, relational database** that serves as the immutable system of record for all modeling activities. * `Scenarios`: Versioned scenario configurations * `Censuses`: Versioned participant data * `PlanRules`: Legal framework definitions * `OperatingAssumptions`: Annual strategy settings * `SimulationRuns`: Execution metadata * `ProcessingLogs`: Step-by-step audit trail * `Events`: All modeled transactions * `AnnualCompanyStates`: Company financials per year * `AnnualTrustStates`: Trust assets per year * `AnnualParticipantSnapshots`: Individual accounts per year ### 3. Input Framework The engine requires structured input organized into four distinct categories: **The "Constitution"** Stable legal framework: * Vesting schedule * Distribution policy * Cash usage policy * Diversification rules **The "Annual Strategy"** Variable financial decisions: * Contribution amounts * Repurchase strategy * Share valuations * Growth projections **Starting Point** Current ESOP status: * Participant census * Trust cash balances * ESOP loan details * Share allocations **Simulation Settings** Runtime parameters: * Projection years * Turnover models * Sensitivity analysis * Output preferences ## Processing Pipeline The annual simulation cycle executes a precise sequence of operations: ```mermaid theme={null} graph TD A[Start Year N] --> B[Step 0: Turnover Projection] B --> C[Step 1: Initialization] C --> D[Step 2: Determine Share Pool] D --> E[Step 3: Allocate Shares] E --> F[Step 4: Calculate Contribution] F --> G[Step 5: Update Vesting] G --> H[Step 6: Process Diversification] H --> I[Step 7: Process Repurchases] I --> J[Step 8: Year-End Closing] J --> K[Capture Year-End State] K --> L[End Year N] style A fill:#29371F,color:#fff style L fill:#29371F,color:#fff ``` The order of operations is **legally significant**. For example, vesting must be updated before repurchases are processed to determine what employees are entitled to receive. ## Data Flow Architecture ``` ┌─────────────────────────────────────────────────────────┐ │ Input Layer │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ PlanRules │ │ Operating │ │ InitialState │ │ │ │ │ │ Assumptions │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └────────────────────────┬────────────────────────────────┘ │ ↓ ┌─────────────────────────────────────────────────────────┐ │ Simulation Engine │ │ ┌──────────────────────────────────────────────────┐ │ │ │ Annual Processing Pipeline │ │ │ │ → Turnover → Share Pool → Contributions → │ │ │ │ → Diversification → Repurchases │ │ │ └──────────────────────────────────────────────────┘ │ └────────────────────────┬────────────────────────────────┘ │ ↓ ┌─────────────────────────────────────────────────────────┐ │ Data Layer (Immutable Database) │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Company │ │ Trust │ │ Participant │ │ │ │ Snapshots │ │ Snapshots │ │ Snapshots │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └────────────────────────┬────────────────────────────────┘ │ ↓ ┌─────────────────────────────────────────────────────────┐ │ Output Layer │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Forecast │ │ Analytics │ │ Exports │ │ │ │ Results │ │ & Insights │ │ & Reports │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────┘ ``` ## Key Architectural Features Leveraged ESOPs with multiple debt tranches are modeled with precision. Each `ESOPLoan` object owns its specific suspense shares, and the engine iterates through each loan independently to calculate share releases. **Why It Matters:** Prevents cross-contamination of suspense accounts and ensures accurate modeling of complex debt structures. The repurchase processing module implements a strict, rules-based sequence for drawing funds from the trust's cash accounts, following the `PlanRules.cash_usage_policy`. **Why It Matters:** Ensures legal compliance and prevents improper use of restricted cash sources (e.g., forfeitures). Every simulation run creates a complete, timestamped snapshot of all system state. Nothing is ever overwritten. **Why It Matters:** Perfect reproducibility and the ability to perform temporal analysis (e.g., "How did our June forecast compare to September?"). The engine exposes high-level user intent functions designed for AI agent integration. **Why It Matters:** Stable API for conversational interfaces, allowing internal refactoring without breaking agent capabilities. ## Performance Characteristics 20-year projection: **\< 2 seconds** 100-participant census Tested up to **10,000 participants** 50-year projections **Deterministic** results Bit-for-bit reproducible ## Next Steps Understand the foundational concepts Dive into the processing pipeline Explore the database structure Learn the core data structures # Simulation Core Source: https://village-docs.villagelabs.com/architecture/simulation-core The annual processing pipeline that powers ESOP forecasts ## The Heart of the Engine The Simulation Core is a **discrete, step-by-step annual processing pipeline**. For each year of a projection, the engine executes a sequence of modules, each responsible for a specific aspect of ESOP administration. This strict order of operations ensures that legal obligations are met before discretionary actions are taken. ## Annual Processing Cycle ```mermaid theme={null} graph TD START[Start Year N] --> S0[Step 0: Turnover Projection] S0 --> S1[Step 1: Initialization] S1 --> S2[Step 2: Determine Share Pool] S2 --> S3[Step 3: Allocate Shares] S3 --> S4[Step 4: Calculate Contribution] S4 --> S5[Step 5: Update Vesting] S5 --> S6[Step 6: Process Diversification] S6 --> S7[Step 7: Process Repurchases] S7 --> S8[Step 8: Year-End Closing] S8 --> SNAPSHOT[Capture Year-End State] SNAPSHOT --> END[End Year N] style START fill:#29371F,color:#fff style END fill:#29371F,color:#fff style S2 fill:#3D5030,color:#fff style S7 fill:#3D5030,color:#fff ``` ## Processing Steps Overview **Optional predictive module** Uses statistical models to forecast which employees will terminate in the current year. **Inputs:** * Participant age, tenure, compensation * Historical turnover rates * Industry benchmarks **Output:** * List of projected termination events with probabilities **Calculate share price and prepare for annual processing** Initialize the annual processing cycle by calculating current share price and preparing state variables. **Actions:** * Calculate per-share value from company equity and outstanding shares * Apply annual growth rate to company equity value * Initialize security-specific prices in multi-class mode * Set up year-specific state variables **Calculate shares available for allocation** Critical step that implements loan-by-loan share release mechanics. **Sources:** * New company contributions (stock) * Released suspense shares from ESOP loans * Reallocated forfeitures **See:** [Loan-by-Loan Mechanics](#loan-by-loan-share-release) **Distribute shares to participant accounts** Apply allocation formula to credit shares to individual accounts. **Formula Options:** * Pro-rata by compensation * Pro-rata by hours * Integrated (Social Security-adjusted) **Determine annual company contribution** Based on `contribution_policy` in OperatingAssumptions. **Policy Types:** * Fixed amount * Percentage of payroll * Discretionary formula * Loan payment-based **Calculate vested balances and potential forfeitures** Apply the plan's vesting schedule to determine vested vs unvested portions of participant accounts. **Actions:** * Apply vesting schedule based on years of service * Calculate vested percentages for each participant * Identify non-vested amounts subject to forfeiture * Track vesting per security in multi-class mode * Apply vesting to both shares and cash balances **Handle statutory diversification** Process elections from eligible participants (age 55+ with 10+ years). **Actions:** * Identify eligible participants * Process diversification elections * Calculate amounts (25% or 50% of account) * Move funds to diversified investments **Execute share repurchases** Repurchase shares from terminated participants using the Funding Waterfall. **See:** [Funding Waterfall](#funding-waterfall) **Finalize annual results and prepare for next year** Roll account balances forward, evolve employee data, and capture year-end snapshots. **Actions:** * Move allocated/diversified amounts to opening balances * Age employees by 1 year and increment service years * Apply compensation growth rates * Remove fully distributed participants * Capture year-end state snapshots and KPIs ## Key Logic Modules ### Loan-by-Loan Share Release For leveraged ESOPs with multiple debt tranches, the engine implements precise loan-by-loan accounting. **Critical:** Each `ESOPLoan` object directly owns the shares that collateralize it. This prevents cross-contamination of suspense accounts. #### How It Works ```python theme={null} for loan in esop_loans: if loan.principal_balance > 0: process_loan_payment(loan) ``` Determine principal and interest for current year based on loan terms ```python theme={null} # Release shares proportional to principal paid shares_to_release = ( loan.suspense_shares * (principal_payment / original_loan_amount) ) loan.suspense_shares -= shares_to_release share_pool += shares_to_release ``` ```python theme={null} loan.principal_balance -= principal_payment ``` #### Example: Multi-Loan Scenario ```python theme={null} # Year 2025 Processing # Loan 1: Original $3M loan from 2020 loan_1 = ESOPLoan( loan_id="LOAN_2020", principal_balance=2_000_000, suspense_shares=20_000, annual_payment=400_000 # $300K principal + $100K interest ) # Loan 2: New $2M loan from 2023 loan_2 = ESOPLoan( loan_id="LOAN_2023", principal_balance=1_800_000, suspense_shares=15_000, annual_payment=300_000 # $200K principal + $100K interest ) # Process Loan 1 shares_released_loan_1 = 20_000 * (300_000 / 3_000_000) = 2_000 shares loan_1.suspense_shares = 20_000 - 2_000 = 18_000 # Process Loan 2 shares_released_loan_2 = 15_000 * (200_000 / 2_000_000) = 1_500 shares loan_2.suspense_shares = 15_000 - 1_500 = 13_500 # Total shares available for allocation share_pool = 2_000 + 1_500 = 3_500 shares ``` **Why This Matters:** Without loan-by-loan tracking, shares from one loan could incorrectly be released when paying down another loan, violating ERISA requirements and creating audit risk. ### Funding Waterfall The repurchase processing module implements a **strict, rules-based sequence** for drawing funds from the trust's cash accounts. #### The Waterfall Sequence The engine follows `PlanRules.cash_usage_policy` to draw funds in the specified order: ```python theme={null} cash_usage_policy = [ "unallocated_company_contributions", # 1st priority "unallocated_forfeiture_cash", # 2nd priority "participant_cash_accounts" # 3rd priority ] ``` #### Processing Algorithm ```python theme={null} total_repurchase_obligation = sum( participant.vested_shares * current_share_price for participant in terminated_participants ) ``` ```python theme={null} remaining_need = total_repurchase_obligation for cash_source in cash_usage_policy: if remaining_need <= 0: break available = trust_cash_ledger[cash_source] amount_to_use = min(available, remaining_need) trust_cash_ledger[cash_source] -= amount_to_use remaining_need -= amount_to_use log_transaction(cash_source, amount_to_use) ``` ```python theme={null} if remaining_need > 0: # Unfunded repurchase obligation defer_to_next_year(remaining_need) # OR trigger company loan/contribution ``` #### Example: Waterfall in Action ``` Repurchase Need: $500,000 Trust Cash Ledger: ├─ unallocated_company_contributions: $200,000 ├─ unallocated_forfeiture_cash: $150,000 └─ participant_cash_accounts: $300,000 Waterfall Execution: 1. Draw $200,000 from unallocated_contributions → $300,000 remaining 2. Draw $150,000 from unallocated_forfeitures → $150,000 remaining 3. Draw $150,000 from participant_cash → $0 remaining Result: ✅ Fully funded ``` **Legal Compliance:** The order matters! For example, forfeiture cash often has restrictions on use. The waterfall ensures compliance with plan document rules and ERISA regulations. ## State Capture At the end of each annual cycle, the engine captures complete snapshots: ```json theme={null} { "simulation_run_id": "run_123", "year": 2025, "revenue": 10_000_000, "ebitda": 2_200_000, "total_payroll": 3_500_000, "esop_contribution": 500_000, "source_type": "simulated" } ``` ```json theme={null} { "simulation_run_id": "run_123", "year": 2025, "total_shares_outstanding": 100_000, "allocated_shares": 68_000, "suspense_shares": 32_000, "unallocated_shares": 0, "cash_ledger": { "unallocated_contributions": 50_000, "unallocated_forfeitures": 25_000, "participant_cash": 125_000 }, "loans": [...] } ``` ```json theme={null} { "simulation_run_id": "run_123", "year": 2025, "participant_id": "EMP001", "allocated_shares": 1_200, "vested_percentage": 0.80, "vested_shares": 960, "account_value": 132_000, "cash_balance": 2_500, "status": "active" } ``` ## Error Handling & Validation The engine performs extensive validation at each step: * Schema compliance * Business rule checks * Data completeness * Referential integrity * Share count reconciliation * Cash balance validation * Loan payment calculations * Legal compliance flags * Total shares consistency * Cash flow balance * Participant account totals * Year-over-year deltas * Every transaction logged * Decision points captured * Assumption tracking * Error breadcrumbs ## Performance Optimizations Participant-level calculations use NumPy for efficient batch processing. Historical snapshots loaded on-demand, not preloaded into memory. Frequently accessed reference data (e.g., plan rules) cached per simulation run. Independent scenario runs can execute in parallel for sensitivity analysis. ## Next Steps Detailed breakdown of each simulation step How state is persisted and retrieved Core objects used in processing See the engine in action # ESOP Basics Source: https://village-docs.villagelabs.com/concepts/esop-basics Essential concepts for understanding the Repurchase Engine ## What is an ESOP? An **Employee Stock Ownership Plan (ESOP)** is a qualified retirement plan that invests primarily in the stock of the sponsoring company. ESOPs are unique in that they allow employees to become owners of the company through their retirement accounts. ESOPs are governed by ERISA (Employee Retirement Income Security Act) and the Internal Revenue Code, which establish strict rules for plan administration, fiduciary duties, and participant rights. ## Key ESOP Concepts ### The ESOP Trust The **ESOP Trust** is a legal entity that holds company stock on behalf of plan participants. All ESOP assets—shares and cash—are owned by the trust, not by individual participants directly. ``` Company → Contributes cash/shares → ESOP Trust ↓ Holds assets ↓ Allocates to → Individual Participant Accounts ``` ### Leveraged vs. Non-Leveraged ESOPs The ESOP borrows money to purchase company stock. The loan is repaid using company contributions, and shares are released from a **suspense account** as the loan is repaid. **Example:** * ESOP borrows \$5M to buy 50,000 shares * Shares held in suspense (not allocated to participants) * As loan is repaid, shares are released and allocated * Loan typically repaid over 7-15 years The company contributes cash to the ESOP, which then purchases shares. No debt is involved, and shares are allocated immediately. **Example:** * Company contributes \$500K annually * ESOP buys 5,000 shares at \$100/share * Shares immediately allocated to participants * No suspense account needed ### Share Allocation Shares in an ESOP are allocated to individual participant accounts based on a formula, typically related to compensation or hours worked. Calculate total shares available for allocation (from contributions or loan releases) Allocate shares proportionally based on compensation or service Credit shares to individual participant accounts ### Vesting **Vesting** determines what percentage of a participant's account balance they own. Common schedules: Gradual vesting over time: * Year 1-2: 0% * Year 3: 20% * Year 4: 40% * Year 5: 60% * Year 6: 80% * Year 7+: 100% All-or-nothing after a period: * Years 1-2: 0% * Year 3+: 100% ## The Repurchase Obligation The **repurchase obligation** is the ESOP's legal requirement to buy back shares from terminating participants. This is the primary financial challenge that ESOPs must manage. ### Why Repurchase Obligations Exist Most ESOP companies are privately held, meaning there's no stock exchange where participants can sell their shares. The ESOP must provide liquidity. Federal law requires that participants receive the fair market value of their shares when they terminate employment or reach specified ages. In non-C corporations, participants have a "put option"—they can require the company or ESOP to repurchase their shares at fair market value. ### Distribution Timeline Participant retires, quits, is terminated, becomes disabled, or passes away Plan document specifies when distributions must begin (often 1 year after termination) Lump sum or installments over up to 5 years (or longer for large accounts) ESOP or company buys back shares at current fair market value ## Cash Flow in an ESOP Understanding ESOP cash flow is critical for managing the repurchase obligation: ### Cash Inflows Annual employer contributions (cash or stock) Initial cash from ESOP loans (leveraged plans) Non-vested balances of terminated participants Dividends paid on ESOP-held stock (if applicable) ### Cash Outflows Buying back shares from terminated participants Principal and interest on ESOP debt Administration, valuation, and trustee fees Buying shares from the company or shareholders ## Diversification Rights Participants who meet specific age and service requirements have the right to diversify a portion of their ESOP accounts. **Standard Rule:** Participants age 55+ with 10+ years of plan participation can diversify 25% of their account. At age 60, they can diversify up to 50%. ### How Diversification Works ``` 1. Eligible participant elects to diversify 2. ESOP sells shares back to company or uses cash 3. Proceeds invested in diversified options (mutual funds, etc.) 4. Reduces participant's concentration risk 5. Creates additional liquidity demand on ESOP/company ``` ## Why Forecasting Matters The Repurchase Engine helps you project and plan for these obligations: Know when you'll need cash for repurchases Set sustainable annual contribution levels Design debt repayment to match cash flows Identify years with peak obligations Demonstrate prudent long-term planning Understand how repurchases affect company value ## Key Terms Glossary | Term | Definition | | ----------------------- | -------------------------------------------------------------- | | **Allocated Shares** | Shares credited to individual participant accounts | | **Suspense Account** | Shares held as collateral for an ESOP loan, not yet allocated | | **Unallocated Shares** | Shares owned by the trust but not yet credited to participants | | **Put Option** | Participant's right to require share repurchase | | **Fair Market Value** | Annual valuation of company stock (required by law) | | **Forfeitures** | Non-vested account balances of terminated participants | | **Distribution** | Payment of account balance to terminated participant | | **Pass-Through Voting** | Requirement to pass voting rights to participants | ## Next Steps Apply these concepts with a hands-on example See how the engine models these concepts # InitialState Guide Source: https://village-docs.villagelabs.com/configuration/initial-state-guide A deep dive into the InitialState object, the snapshot of your ESOP at the start of a simulation. ## Overview The `InitialState` object is a snapshot of your ESOP at the beginning of a simulation. It contains all the necessary data about your participants, trust assets, and ESOP loans. **Source of Truth:** Your TPA's annual report, census data, trust statements, and loan documents. ## Complete Field Reference Below is a detailed walkthrough of each field in the `InitialState` object. ### `census_year` * **Type:** `integer` * **Required:** Yes * **Description:** The year of the census data. * **Example:** `2024` ### `participants` * **Type:** `array` of objects * **Required:** Yes * **Description:** An array of all current ESOP participants. Each object in the array represents one participant. - **`id`**: `string` (Required) - A unique identifier for the employee. - **`age`**: `integer` (Required) - The participant's age. - **`service_years`**: `integer` (Required) - The participant's years of service for vesting purposes. - **`compensation`**: `number` (Required) - The participant's annual compensation. - **`allocated_shares`**: `number` (Required) - The number of shares allocated to the participant's account. - **`vested_percentage`**: `number` (Optional) - The participant's current vested percentage. If not provided, it will be calculated based on the `vesting_schedule`. - **`cash_balance`**: `number` (Optional) - The cash balance in the participant's account. ### `trust_cash` * **Type:** `object` * **Required:** Yes * **Description:** The cash balances in the ESOP trust, segregated by source. - **Type:** `number` - **Description:** Cash that has been segregated for participants who have terminated but have not yet been paid out. * **Type:** `number` * **Description:** Cash from company contributions that has not yet been used. * **Type:** `number` * **Description:** Cash from forfeited (unvested) shares of terminated participants. ### `esop_loans` * **Type:** `array` of objects * **Required:** No * **Description:** An array of all outstanding ESOP loans. - **`loan_id`**: `string` (Required) - A unique identifier for the loan. - **`principal_balance`**: `number` (Required) - The outstanding principal balance. - **`interest_rate`**: `number` (Required) - The annual interest rate. - **`years_remaining`**: `integer` (Required) - The number of years left on the loan. - **`suspense_shares`**: `number` (Required) - The number of shares held as collateral for this loan. ## Complete Example ```json theme={null} { "census_year": 2024, "participants": [ { "id": "EMP001", "age": 45, "service_years": 8, "compensation": 120000, "allocated_shares": 1000, "vested_percentage": 0.80 }, { "id": "EMP002", "age": 35, "service_years": 5, "compensation": 80000, "allocated_shares": 500, "vested_percentage": 0.60 } ], "trust_cash": { "participant_cash_accounts": 50000, "unallocated_company_contributions": 25000, "unallocated_forfeiture_cash": 10000 }, "esop_loans": [ { "loan_id": "LOAN_2020", "principal_balance": 2000000, "interest_rate": 0.065, "years_remaining": 8, "suspense_shares": 20000 } ] } ``` # OperatingAssumptions Guide Source: https://village-docs.villagelabs.com/configuration/operating-assumptions-guide A deep dive into the OperatingAssumptions object, your annual strategic and financial inputs. ## Overview The `OperatingAssumptions` object is where you define the discretionary, variable financial and strategic decisions for your ESOP on a year-by-year basis. You will create many different `OperatingAssumptions` objects to model various "what-if" scenarios and plan for the future. **Source of Truth:** Your company's financial forecasts and strategic plans. ## Complete Field Reference Below is a detailed walkthrough of each field in the `OperatingAssumptions` object. ### `contribution_policy` * **Type:** `object` * **Required:** Yes * **Description:** Defines your company's policy for making contributions to the ESOP. - **Type:** `string` - **Values:** `"fixed_amount"`, `"percentage_of_payroll"` - **Description:** The method for calculating the annual contribution. * **Type:** `number` * **Description:** Required if `type` is `"fixed_amount"`. The total dollar amount to be contributed. * **Example:** `500000` * **Type:** `number` * **Description:** Required if `type` is `"percentage_of_payroll"`. The percentage of total payroll to contribute. * **Example:** `0.10` for 10% of payroll. ### `share_valuation` * **Type:** `object` * **Required:** Yes * **Description:** Defines the current and projected future value of the company's stock. - **Type:** `number` - **Description:** The current price per share of the stock, typically from your most recent 409A valuation. - **Example:** `100.00` * **Type:** `number` * **Description:** The projected annual growth rate of the share price. * **Example:** `0.05` for 5% annual growth. ### `repurchase_strategy` * **Type:** `object` * **Required:** Yes * **Description:** Defines how and when the company will repurchase shares from terminated participants. - **Type:** `string` - **Values:** `"immediate"`, `"deferred"` - **Description:** Whether shares are repurchased immediately upon distribution or deferred. * **Type:** `string` * **Values:** `"trust_cash"`, `"company_contribution"`, `"company_loan"` * **Description:** The source of funds for repurchasing shares. ### `financial_projections` * **Type:** `object` * **Required:** No * **Description:** Your company's financial projections, which can influence other assumptions. * **Example:** ```json theme={null} "financial_projections": { "revenue_growth_rate": 0.10, "ebitda_margin": 0.15 } ``` ## Complete Example ```json theme={null} { "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" }, "financial_projections": { "revenue_growth_rate": 0.10, "ebitda_margin": 0.15 } } ``` # Configuration Overview Source: https://village-docs.villagelabs.com/configuration/overview Understanding the core configuration objects of the Repurchase Engine. ## The Configuration Philosophy The Repurchase Engine's configuration is designed around a core philosophy: the separation of stable, legal rules from variable, strategic assumptions. This separation makes your simulations more accurate, easier to manage, and less prone to error. The legal framework of your ESOP, based on your plan document. Changes rarely. Your annual strategic and financial decisions. Changes frequently. ## The Three Core Configuration Objects Every simulation in the Repurchase Engine is driven by three main configuration objects: 1. **`PlanRules`**: This object defines the legal and administrative rules of your ESOP. Think of it as a digital version of your plan document. It includes things like your vesting schedule, distribution policies, and eligibility requirements. Once set up, `PlanRules` rarely change. 2. **`OperatingAssumptions`**: This object defines the financial and strategic assumptions for a given year. It includes your contribution strategy, share valuation growth, and repurchase strategy. You will likely create many different `OperatingAssumptions` to model different "what-if" scenarios. 3. **`InitialState`**: This object is a snapshot of your ESOP at the beginning of the simulation. It includes your employee census data, the current state of your trust's cash and share accounts, and the details of any outstanding ESOP loans. ## How They Work Together Think of it like this: * `PlanRules` are the **rules of the game**. * `OperatingAssumptions` is your **strategy for the year**. * `InitialState` is the **state of the board at the start of the game**. You run a simulation by providing the engine with these three objects. The engine then projects the future of your ESOP, year by year, by applying your annual `OperatingAssumptions` within the constraints of your `PlanRules`, starting from your `InitialState`. ```mermaid theme={null} graph TD A[InitialState] --> C{Simulation Engine}; B[PlanRules] --> C; D[OperatingAssumptions] --> C; C --> E[Projected Results]; ``` ## Getting Started Ready to dive in? Here's our recommended path: 1. Start with the **[PlanRules Guide](/configuration/plan-rules-guide)** to model your plan document. 2. Next, read the **[OperatingAssumptions Guide](/configuration/operating-assumptions-guide)** to learn how to model your financial strategies. 3. Finally, use the **[InitialState Guide](/configuration/initial-state-guide)** to prepare your starting census and financial data. # PlanRules Guide Source: https://village-docs.villagelabs.com/configuration/plan-rules-guide A deep dive into the PlanRules object, the legal framework of your ESOP. ## Overview The `PlanRules` object is where you define the stable, legal framework of your ESOP, as specified in your plan document. These rules change infrequently and typically require a formal plan amendment. Getting the `PlanRules` right is the first and most important step in accurately modeling your ESOP. **Source of Truth:** Your ESOP's Plan Document. ## Complete Field Reference Below is a detailed walkthrough of each field in the `PlanRules` object. ### `plan_name` * **Type:** `string` * **Required:** Yes * **Description:** The official name of your ESOP plan. * **Example:** `"Acme Corp Employee Stock Ownership Plan"` ### `plan_year_end` * **Type:** `string` (MM/DD format) * **Required:** Yes * **Description:** The end date of your plan year. This is a critical field that affects the timing of many calculations. * **Example:** `"12/31"` ### `vesting_schedule` * **Type:** `object` * **Required:** Yes * **Description:** Defines how participants earn ownership of their ESOP shares over time. - **Type:** `string` - **Values:** `"graded"`, `"cliff"` - **Description:** The type of vesting schedule. "Graded" vesting increases gradually over time, while "cliff" vesting happens all at once. * **Type:** `array` of numbers * **Description:** Required for `graded` vesting. An array representing the percentage of shares vested at each year of service. * **Example:** `[0, 0, 20, 40, 60, 80, 100]` for a 6-year graded schedule where vesting begins after 2 years. * **Validation:** Must start at 0, end at 100, and be monotonically increasing. * **Type:** `integer` * **Description:** Required for `cliff` vesting. The number of years of service required to become 100% vested. * **Example:** `3` for a 3-year cliff. ### `distribution_policy` * **Type:** `object` * **Required:** Yes * **Description:** Defines when and how participants receive their vested account balances after termination. - **Type:** `string` - **Values:** `"immediate"`, `"termination_plus_1_year"`, etc. - **Description:** When distributions begin after a termination event. * **Type:** `string` * **Values:** `"lump_sum"`, `"installments"` * **Description:** How distributions are paid out. ### `cash_usage_policy` * **Type:** `array` of strings * **Required:** No * **Description:** The priority order for using different sources of cash within the trust to fund distributions and repurchases. * **Example:** `["unallocated_company_contributions", "unallocated_forfeiture_cash", "participant_cash_accounts"]` ### `diversification_rules` * **Type:** `object` * **Required:** No * **Description:** Defines the rules for statutory diversification. The engine can model this automatically if this section is included. ## Complete Example ```json theme={null} { "plan_name": "Acme Corp ESOP", "plan_year_end": "12/31", "vesting_schedule": { "type": "graded", "schedule": [0, 0, 20, 40, 60, 80, 100] }, "distribution_policy": { "timing": "termination_plus_1_year", "form": "lump_sum" }, "cash_usage_policy": [ "unallocated_company_contributions", "unallocated_forfeiture_cash", "participant_cash_accounts" ], "diversification_rules": { "min_age": 55, "min_service": 10 } } ``` # Deployment Options Source: https://village-docs.villagelabs.com/enterprise/deployment-options Deploy the Repurchase Engine on our secure cloud, your private cloud, or on-premise. ## Flexible Deployment for Your Needs We understand that enterprise clients have diverse infrastructure, security, and compliance requirements. That's why we offer a range of deployment options for the Repurchase Engine. Our standard SaaS offering. We handle all the infrastructure, security, and maintenance, so you can focus on your clients. A dedicated, single-tenant instance of our platform deployed in a virtual private cloud (VPC) on AWS, Azure, or Google Cloud. For clients with the strictest data residency or security requirements, we offer an on-premise deployment option. ## Managed Cloud Our Managed Cloud offering is the fastest and easiest way to get started with the Repurchase Engine. * **Fully Managed:** We handle all updates, backups, and maintenance. * **High Availability:** Our platform is deployed across multiple availability zones for high availability and disaster recovery. * **Secure:** Our cloud infrastructure is SOC 2 compliant and includes robust security features. * **Scalable:** Our cloud platform can scale to meet the needs of your growing business. **Best for:** Most clients who want a secure, reliable, and maintenance-free solution. ## Private Cloud A Private Cloud deployment provides the benefits of a managed service with the enhanced security and control of a dedicated environment. * **Single-Tenant Environment:** Your instance of the Repurchase Engine is completely isolated from other clients. * **Choice of Cloud Provider:** Deploy in your preferred cloud environment (AWS, Azure, GCP). * **VPC Peering:** Connect your VPC with ours for secure, private communication between the Repurchase Engine and your other systems. * **Custom Security Configurations:** Implement custom security controls and network configurations to meet your specific requirements. **Best for:** Clients who require a higher level of isolation and control than our standard multi-tenant cloud offering. ## On-Premise For organizations with strict data residency requirements or those who need to integrate the Repurchase Engine deeply with on-premise systems. * **Complete Control:** You have full control over the infrastructure and deployment environment. * **Data Residency:** Keep all of your data within your own data centers. * **Air-Gapped Environments:** The Repurchase Engine can be deployed in environments with no outbound internet access. * **Deep Integration:** Tightly integrate with your on-premise HRIS, accounting, and other systems. **Requirements:** * You are responsible for providing and managing the underlying infrastructure (servers, storage, networking). * Your team will be responsible for updates and maintenance, with support from our team. * Requires a dedicated team with experience in managing enterprise software. **Best for:** Financial institutions, government agencies, and other organizations with the strictest security and data residency requirements. ## Choosing the Right Option | Feature | Managed Cloud | Private Cloud | On-Premise | | :---------------------- | :-----------: | :---------------: | :--------------: | | **Deployment Time** | Hours | Days | Weeks | | **Infrastructure Mgt.** | We handle it | We handle it | You handle it | | **Data Isolation** | Multi-tenant | Single-tenant | Single-tenant | | **Custom Security** | Limited | Yes | Yes | | **Data Residency** | Our regions | Your cloud region | Your data center | | **Maintenance** | We handle it | We handle it | You handle it | Contact our sales team to discuss the best deployment option for your organization. # For Enterprise Source: https://village-docs.villagelabs.com/enterprise/index Advanced solutions for large-scale ESOP management, TPAs, and financial institutions. ## Powering ESOPs at Scale The **Village Labs Repurchase Engine**, a core component of our Village Operating System, provides a robust, scalable, and customizable platform for enterprise clients. We designed our enterprise solution specifically for TPAs, valuation firms, and large corporations that require advanced capabilities, deployment flexibility, and our dedicated support. Deliver a branded, seamless experience to your clients with our customizable platform. Deploy on our secure cloud, your private cloud, or on-premise to meet your infrastructure and compliance needs. Meet the strictest security and compliance requirements with features like SSO, audit logs, and data encryption. Receive priority support, dedicated account management, and service level agreements to ensure business continuity. ## Who It's For Manage your entire client portfolio from a single, powerful platform. Automate repetitive tasks, standardize reporting, and provide advanced forecasting services to your clients. Our multi-tenant architecture ensures complete data isolation and security for each client. Enhance your advisory services with sophisticated ESOP modeling and scenario analysis. Integrate the Repurchase Engine into your existing workflows to provide data-driven insights on sustainability, share value, and long-term planning. Manage your complex, mature ESOP with a tool that can handle multiple loans, diverse participant demographics, and sophisticated repurchase strategies. Integrate with your HRIS and financial systems for a seamless data workflow. For banks and other lenders in the ESOP space, use the Repurchase Engine for due diligence, risk assessment, and monitoring the long-term health of your ESOP loans. ## Key Enterprise Benefits * **Scalability:** From tens to thousands of participants, our engine is built to handle the load. * **Customization:** Adapt the platform to your specific workflows and client needs. * **Integration:** Connect with your existing systems through our flexible API. * **Control:** Choose the deployment model that fits your security and operational requirements. * **Support:** Access our team of experts for implementation, training, and ongoing support. ## Get Started Contact our enterprise sales team to discuss your specific needs and learn how the Repurchase Engine can be tailored for your organization. # Security & Compliance Source: https://village-docs.villagelabs.com/enterprise/security-compliance Enterprise-grade security and compliance features to protect your data. ## A Commitment to Security We understand that ESOP data is highly sensitive. We are committed to protecting your data and your clients' data with enterprise-grade security and compliance features. ## Core Security Features * **Data Encryption:** All data is encrypted at rest using AES-256 and in transit using TLS 1.2+. * **Data Isolation:** In our multi-tenant cloud environment, each client's data is logically isolated. For complete isolation, we offer a single-tenant private cloud deployment. * **Regular Security Audits:** We conduct regular internal and third-party security audits and penetration tests to identify and address potential vulnerabilities. * **Secure Software Development:** We follow a secure software development lifecycle (SSDLC) to ensure that security is built into our platform from the ground up. ## Compliance * **SOC 2:** Our managed cloud platform is SOC 2 Type II compliant. We can provide our SOC 2 report upon request under an NDA. * **GDPR & CCPA:** We are committed to complying with data privacy regulations like GDPR and CCPA. ## Enterprise Security Features * **Single Sign-On (SSO):** Integrate with your existing identity provider (e.g., Okta, Azure AD, SAML) for secure and convenient authentication. * **Role-Based Access Control (RBAC):** We can work with you to define custom roles and permissions for your team members, ensuring that users only have access to the data and features they need. * **Audit Logs:** A detailed audit trail of all actions taken within the platform, including user logins, simulation runs, and configuration changes. * **IP Whitelisting:** Restrict access to the platform to a list of approved IP addresses. * **Data Residency:** For clients with specific data residency requirements, we can deploy the platform in a specific geographic region in our Private Cloud offering, or you can use our On-Premise offering. ## Your Responsibilities Security is a shared responsibility. While we provide a secure platform, you are responsible for: * **Securely Managing API Keys:** Treat your API keys like passwords and keep them secure. * **Managing User Access:** Ensure that only authorized users have access to the platform and that their permissions are appropriate for their role. * **Securely Configuring Your Systems:** If you are using our On-Premise or Private Cloud offerings, you are responsible for securely configuring your underlying infrastructure. Contact our security team for more detailed information about our security and compliance program. # White-Label Platform Source: https://village-docs.villagelabs.com/enterprise/white-label-platform Deliver a branded, seamless ESOP forecasting experience to your clients. ## A Branded Experience for Your Clients For TPAs, valuation firms, and financial advisors, presenting a cohesive, branded experience to your clients is crucial. The Repurchase Engine is designed to be white-label ready, allowing you to offer our powerful forecasting tools under your own brand. **Note:** White-labeling is a professional service offered to our enterprise clients. Our team will work with you to create a branded solution that meets your needs. ## Key White-Labeling Capabilities * **Custom Branding:** We will customize the platform's UI with your logo, color scheme, and typography to ensure a seamless brand experience. * **Custom Domain:** Host the platform on a custom domain (e.g., `esop.yourfirm.com`) to provide a fully integrated feel for your clients. * **Branded Reports:** All PDF and Excel reports generated from the platform will be branded with your logo and company information. * **Branded Communications:** Any email notifications or other communications sent from the platform can be customized to match your brand. ## Multi-Tenant Client Management Our platform's multi-tenant architecture is designed for firms that manage multiple ESOP clients. ### Administrator & Analyst Workflow * **Centralized Client Dashboard:** A secure portal for your team to view and manage all of your clients. * **Client Data Isolation:** Each client's data is stored in a logically separate container, ensuring strict data privacy and security. The `data/clients` structure in our engine is designed for this purpose. * **Role-Based Access Control (RBAC):** We can configure different roles and permissions for your team members (e.g., Administrator, Analyst, Read-Only) to control access to client data and system settings. * **Run Simulations on Behalf of Clients:** Your analysts can easily switch between client contexts to run simulations, create scenarios, and generate reports. * **Client-Specific Configurations:** The system supports client-specific importers and configurations, as seen with `client_specific.basden_loader` in the engine's codebase. ### The End-Client Experience You can provide your clients with a secure, branded portal to view their ESOP data and simulation results. * **Simplified, Read-Only Access:** By default, clients are given read-only access to their reports and dashboards. * **Self-Service Scenario Modeling (Optional):** For sophisticated clients, you can enable self-service capabilities, allowing them to create and compare their own "what-if" scenarios. * **Secure Data Access:** Clients log in to a secure portal to view only their own data. ## API-Driven Customization For deeper integration, our REST API can be used to build a completely custom front-end experience or integrate our engine's capabilities into your existing client portal. * **Programmatic Simulation Runs:** Trigger simulation runs from your own application. * **Retrieve Results:** Pull simulation results into your own dashboards and reporting tools. * **Manage Scenarios:** Create, update, and delete scenarios via the API. Contact our sales team to learn more about how we can create a white-labeled solution for your firm. # Basic Simulation Example Source: https://village-docs.villagelabs.com/examples/basic-simulation Complete walkthrough of a simple ESOP simulation ## Scenario Overview Let's model **Acme Corporation**, a 100-person manufacturing company that established an ESOP in 2020 with a \$3M loan. We'll project 10 years to forecast repurchase obligations. **Company Profile:** * 100 employees * Single ESOP loan from 2020 * \$500K annual contribution budget * Current share price: \$100/share ## Step 1: Define Plan Rules The legal framework that rarely changes: ```python theme={null} from villagelabs import PlanRules, VestingSchedule, DistributionPolicy plan_rules = PlanRules( plan_name="Acme Corporation ESOP", plan_year_end="12/31", # 6-year graded vesting vesting_schedule=VestingSchedule( type="graded", schedule=[0, 0, 20, 40, 60, 80, 100] # Years 0-6 ), # Distribute 1 year after termination distribution_policy=DistributionPolicy( timing="termination_plus_1_year", form="lump_sum", in_service_distributions=False ), # Cash usage hierarchy for repurchases cash_usage_policy=[ "unallocated_company_contributions", "unallocated_forfeiture_cash", "participant_cash_accounts" ], # Diversification per ERISA standards diversification_rules={ "enabled": True, "age_requirement": 55, "service_requirement": 10, "first_election_percentage": 0.25, "final_election_percentage": 0.50, "final_election_age": 60 } ) ``` ## Step 2: Set Operating Assumptions The annual business strategy: ```python theme={null} from villagelabs import OperatingAssumptions operating_assumptions = OperatingAssumptions( # Fixed $500K contribution contribution_policy={ "type": "fixed_amount", "annual_amount": 500_000 }, # Share valuation assumptions share_valuation={ "current_price": 100.00, "annual_growth_rate": 0.05 # 5% growth }, # Repurchase timing and funding repurchase_strategy={ "timing": "immediate", # Buy shares right away "funding_source": "trust_cash" # Use available cash }, # Company financial projections financial_projections={ "revenue_growth": 0.06, "ebitda_margin": 0.22, "payroll_growth": 0.03 }, # Turnover assumptions turnover_assumptions={ "use_predictive_model": True, "base_turnover_rate": 0.08 # 8% annual turnover } ) ``` ## Step 3: Provide Initial State Current ESOP status (simplified for example): ```python theme={null} from villagelabs import InitialState, Participant, ESOPLoan initial_state = InitialState( census_year=2024, # Employee census (showing 3 of 100 for brevity) participants=[ Participant( id="EMP001", age=45, hire_date="2016-01-15", service_years=8, annual_compensation=75_000, allocated_shares=950, vested_percentage=0.80 ), Participant( id="EMP002", age=38, hire_date="2019-03-20", service_years=5, annual_compensation=65_000, allocated_shares=600, vested_percentage=0.60 ), Participant( id="EMP003", age=55, hire_date="2014-08-10", service_years=10, annual_compensation=95_000, allocated_shares=1_200, vested_percentage=1.00 ), # ... 97 more employees ], # Trust cash balances trust_cash={ "participant_cash_accounts": 75_000, "unallocated_company_contributions": 100_000, "unallocated_forfeiture_cash": 25_000 }, # ESOP loan details esop_loans=[ ESOPLoan( loan_id="LOAN_2020_INITIAL", origination_date="2020-01-01", original_principal=3_000_000, principal_balance=2_100_000, # 4 years paid interest_rate=0.065, term_years=10, payment_schedule="amortizing", suspense_shares=21_000, # 9,000 already released original_suspense_shares=30_000 ) ], # Share counts total_shares_outstanding=80_000, allocated_shares=59_000, # To 100 participants unallocated_shares=0 ) ``` ## Step 4: Configure Simulation Runtime settings: ```python theme={null} from villagelabs import SystemConfiguration system_config = SystemConfiguration( projection_years=10, # 2025-2034 include_turnover_projection=True, run_sensitivity_analysis=False, output_format="detailed" ) ``` ## Step 5: Run Simulation Execute the forecast: ```python theme={null} from villagelabs import RepurchaseEngine # Initialize 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 ) print(f"Simulation completed in {results.execution_time_ms}ms") ``` ## Step 6: Analyze Results ### Summary Metrics ```python theme={null} # High-level insights print(f"10-Year Repurchase Obligation: ${results.total_repurchase_obligation:,.0f}") # Output: 10-Year Repurchase Obligation: $8,450,000 print(f"Peak Cash Year: {results.peak_cash_year}") # Output: Peak Cash Year: 2029 print(f"Peak Cash Amount: ${results.peak_cash_amount:,.0f}") # Output: Peak Cash Amount: $1,250,000 print(f"Average Annual Contribution: ${results.average_annual_contribution:,.0f}") # Output: Average Annual Contribution: $500,000 print(f"Final Trust Cash (2034): ${results.final_trust_cash:,.0f}") # Output: Final Trust Cash (2034): $425,000 ``` ### Year-by-Year Breakdown ```python theme={null} # Detailed annual projections for year in results.annual_projections: print(f"\n=== Year {year.year} ===") print(f" Contribution: ${year.company_contribution:,.0f}") print(f" Shares Released: {year.shares_released:,.0f}") print(f" Repurchases: ${year.repurchase_amount:,.0f}") print(f" Ending Cash: ${year.ending_trust_cash:,.0f}") # Output: # === Year 2025 === # Contribution: $500,000 # Shares Released: 3,000 # Repurchases: $425,000 # Ending Cash: $275,000 # # === Year 2026 === # Contribution: $500,000 # Shares Released: 3,000 # Repurchases: $680,000 # Ending Cash: $195,000 # ... ``` ### Repurchase Obligation Trend ```python theme={null} import matplotlib.pyplot as plt years = [proj.year for proj in results.annual_projections] repurchases = [proj.repurchase_amount for proj in results.annual_projections] plt.figure(figsize=(10, 6)) plt.plot(years, repurchases, marker='o', linewidth=2) plt.title('Projected Repurchase Obligations') plt.xlabel('Year') plt.ylabel('Repurchase Amount ($)') plt.grid(True, alpha=0.3) plt.tight_layout() plt.show() ``` ### Participant Analysis ```python theme={null} # Focus on a specific participant emp_003_timeline = results.get_participant_timeline("EMP003") for snapshot in emp_003_timeline: print(f"Year {snapshot.year}: {snapshot.allocated_shares} shares, " f"${snapshot.account_value:,.0f} value") # Output: # Year 2025: 1,230 shares, $136,290 value # Year 2026: 1,260 shares, $150,570 value # Year 2027: 1,295 shares, $166,805 value # ... ``` ## Step 7: Create Scenarios Compare different contribution strategies: ```python theme={null} # Scenario A: Current plan ($500K/year) results_a = engine.simulate(..., contribution=500_000) # Scenario B: Reduced contribution ($400K/year) operating_assumptions_b = operating_assumptions.copy() operating_assumptions_b.contribution_policy["annual_amount"] = 400_000 results_b = engine.simulate(..., operating_assumptions=operating_assumptions_b) # Compare comparison = engine.compare_scenarios(results_a, results_b) print(f"Contribution difference: ${comparison.contribution_delta:,.0f}") print(f"Repurchase obligation impact: ${comparison.repurchase_delta:,.0f}") print(f"Recommendation: {comparison.recommendation}") # Output: # Contribution difference: $1,000,000 over 10 years # Repurchase obligation impact: +$450,000 (Scenario B higher) # Recommendation: Maintain $500K contribution for better cash management ``` ## Key Insights from Example This is when early participants (hired 2014-2016) begin retiring with significant vested balances. Plan sponsors should begin accumulating cash reserves now. Once the 2020 loan is fully paid (2030), no more suspense shares remain for allocation. Future contributions must be cash, not share releases. Participants over 55 with 10+ years can diversify starting in 2025. This creates additional cash needs beyond repurchases. 5% annual growth means account values grow faster than contributions, increasing future repurchase costs. ## Next Steps Model a complex leveraged ESOP with multiple loans Focus on diversification impact Full API documentation Deep dive into object structures # Diversification Planning Example Source: https://village-docs.villagelabs.com/examples/diversification Model the impact of diversification elections ## Scenario Project the cash impact of diversification elections as your workforce ages. ## Key Insights * Diversification eligible participants grow over time * Creates additional cash demand beyond repurchases * 25% at age 55, 50% at age 60 See [ESOP Basics](/concepts/esop-basics#diversification-rights) for requirements. Coming soon: Complete diversification analysis. # Multi-Loan ESOP Example Source: https://village-docs.villagelabs.com/examples/multi-loan Complex leveraged ESOP with multiple debt tranches ## Scenario Model an ESOP with two loans: an original 2020 loan and a 2023 refinancing loan. ## Key Concepts * Loan-by-loan share release * Multiple suspense accounts * Coordinated debt service See [ESOPLoan](/models/esop-loan) for detailed model structure. ## Example ```python theme={null} loans = [ ESOPLoan(loan_id="LOAN_2020", suspense_shares=15_000), ESOPLoan(loan_id="LOAN_2023", suspense_shares=15_000) ] # Each loan releases its own shares for loan in loans: loan.process_payment(principal, interest) ``` Coming soon: Complete multi-loan walkthrough. # Distributions Processing Source: https://village-docs.villagelabs.com/in-development/distributions-processing Automated processing of ESOP distributions and payments ## Distributions Processing System **Status:** Roadmap (2026-2027) An intelligent platform for automating ESOP distribution processing—from triggering event identification through final payment and tax reporting. ## The Challenge ESOP distribution processing is complex and error-prone: * Multiple triggering events (retirement, termination, death, disability) * Complex vesting calculations * Various distribution options * Tax withholding requirements * Regulatory compliance (IRC 409, ERISA) * Repurchase obligation tracking * Beneficiary management **Current reality for TPAs and plan sponsors:** * Manual calculations prone to errors * Time-consuming participant communications * Complex tax withholding calculations * Difficult tracking of payment schedules * High risk of compliance violations ## The Solution **Automated, intelligent distribution processing:** * AI-powered triggering event identification * Automated vesting and valuation calculations * Smart distribution options analysis * Automatic tax withholding * Integrated payment processing * Comprehensive compliance tracking ## Key Features ### Triggering Event Management **Intelligent event tracking:** * Automated event identification from census data * Manual event entry with validation * Beneficiary designation management * Required documentation tracking * Timeline and deadline management ### Distribution Calculations **Accurate, automated calculations:** * Vested account balance determination * Share valuation at distribution date * Distribution timing calculations * Installment option modeling * Put option calculations * IRA rollover amounts ### Distribution Options **Help participants choose wisely:** * Lump sum vs. installment comparison * Tax impact modeling * IRA rollover analysis * Put option implications * Personalized recommendations ### Tax Withholding **Automatic, compliant tax handling:** * Federal income tax withholding * State tax withholding (where applicable) * FICA calculations (if applicable) * 1099-R generation * Year-end tax reporting ### Payment Processing **Streamlined payment execution:** * Direct deposit setup * Check generation * IRA custodian coordination * Payment confirmation tracking * Failed payment handling ### Participant Communications **Clear, timely communications:** * Distribution notice generation * Election form delivery * Confirmation letters * Payment notifications * Tax document delivery ### Compliance Monitoring **Stay compliant automatically:** * IRC Section 409 compliance * ERISA distribution rules * Put option requirements * Minimum distribution rules * Required documentation ### Repurchase Tracking **Integrate with repurchase obligations:** * Cash requirement forecasting * Payment schedule tracking * Put option exercise monitoring * Future liability projection ## Benefits ### For Plan Administrators **Operational efficiency:** * **80% reduction** in processing time * **95% fewer errors** in calculations * **Automated compliance** checking * **Scalable operations** **Risk reduction:** * **Consistent processing** * **Complete audit trails** * **Regulatory compliance** * **Error prevention** ### For Plan Sponsors **Cost savings:** * Reduced TPA fees * Fewer compliance issues * Less internal time spent **Better participant experience:** * Faster processing * Clearer communications * More accurate calculations ### For Participants **Better service:** * **Faster distributions** * **Clear communication** * **Accurate calculations** * **Easy decision-making** **Financial planning:** * Distribution options comparison * Tax impact understanding * Retirement planning support ## Technology ### AI-Powered Automation **Intelligent agents handle:** * Event identification and validation * Calculation accuracy checking * Document generation * Communication personalization * Exception identification ### Integration Capabilities **Connect with:** * Payroll systems * Banking/payment systems * IRA custodians * Tax filing systems * Document management * Repurchase forecasting systems ### Security & Compliance * SOC 2 Type II certified * Bank-level encryption * Secure payment processing (PCI DSS) * Complete audit trails * Regular security audits ### Reporting & Analytics **Comprehensive reporting:** * Distribution activity tracking * Payment status monitoring * Tax reporting * Repurchase obligation impact * Historical analysis ## Workflow Example ### Standard Distribution Process 1. **Event Identification** * System detects triggering event * Validates event type and date * Identifies required documents 2. **Calculation** * Determines vested balance * Calculates distribution amount * Models distribution options * Computes tax withholding 3. **Participant Election** * Sends distribution notice * Presents options with modeling * Receives and validates election * Confirms choices 4. **Processing** * Executes payment * Applies tax withholding * Coordinates IRA rollovers * Confirms completion 5. **Reporting** * Generates 1099-R * Updates repurchase tracking * Creates audit documentation * Archives all records ## Pricing Model (Proposed) ### Per-Distribution Pricing **Simple, transparent costs:** * \$50-150 per distribution * Based on complexity * All features included * Volume discounts available ### Subscription Option **For high-volume processors:** * Monthly fee + per-distribution * Unlimited participants * Priority support * Custom integrations ## Roadmap **Development timeline:** * **2026 Q1-Q2:** Requirements gathering with TPAs * **2026 Q3-Q4:** Core development * **2027 Q1:** Beta testing * **2027 Q2-Q3:** Phased rollout * **2027 Q4:** General availability ## Design Partners Wanted We're seeking TPAs and plan sponsors to help design this system: **What we're looking for:** * TPAs processing 50+ distributions/year * Plan sponsors with distribution challenges * Forward-thinking organizations * Commitment to feedback and testing **Benefits:** * Shape product features * Early access * Preferred pricing * Competitive advantage Express interest ## Why Automate Distributions? ### Reduce Errors Manual processing leads to: * Calculation mistakes * Tax withholding errors * Compliance violations * Participant dissatisfaction ### Save Time Automated processing: * 80% less time per distribution * Handle more volume * Focus on exceptions * Scale operations ### Improve Compliance Automated compliance: * Built-in rule validation * Complete documentation * Audit trail generation * Regular updates for law changes ### Better Experience Participants get: * Faster processing * Clearer communications * Better decision support * Accurate calculations ## Get Notified Stay updated on development progress: Subscribe to updates ## Questions? Ask about distributions processing # Participant Portals Source: https://village-docs.villagelabs.com/in-development/participant-portals This page contains information about the upcoming Participant Portals features. # Sustainability Source: https://village-docs.villagelabs.com/in-development/sustainability This page contains information about the upcoming Sustainability features. # Third Party Administration Source: https://village-docs.villagelabs.com/in-development/third-party-administration Agent-driven systems to streamline TPA workflows ## Third Party Administration Platform **Status:** Roadmap (2026-2027) An AI-powered platform designed specifically for ESOP third-party administrators. Built to automate routine tasks, enhance accuracy, and scale operations efficiently. ## The Vision Transform ESOP administration through intelligent automation and AI agents that handle: * Census processing and validation * Compliance testing and monitoring * Report generation and customization * Participant communications * Document management ## Core Capabilities ### Automated Census Processing **Intelligent data handling:** * Automated data ingestion from payroll systems * AI-powered validation and error detection * Smart reconciliation with prior year data * Automatic corrections for common issues * Exception highlighting for manual review ### Compliance Testing **Continuous compliance monitoring:** * Automated coverage testing * Non-discrimination testing (ADP/ACP) * Top-heavy determination * Contribution limit tracking * Real-time compliance alerts ### Report Generation **Customizable, automated reporting:** * Participant statements * Trustee reports * Plan sponsor dashboards * Regulatory filings (5500, 1099-R) * Custom analytics and insights ### Participant Support **AI-powered participant experience:** * 24/7 chatbot for common questions * Automated statement delivery * Distribution request processing * Beneficiary management * Educational resources ### Agent-Driven Workflows **Intelligent automation:** * Census agents that learn from corrections * Compliance agents that monitor continuously * Communication agents that personalize outreach * Document agents that organize and retrieve * Audit agents that ensure accuracy ## Benefits for TPAs ### Operational Efficiency * **Reduce manual work** by 60-80% * **Faster turnaround** on deliverables * **Scale without headcount** growth * **Focus on advisory** services ### Improved Accuracy * **AI validation** catches errors early * **Consistent processing** across plans * **Audit trail** for all actions * **Compliance confidence** ### Enhanced Service * **Faster response** times * **Better client experience** * **Proactive issue** identification * **Modern interfaces** ### Competitive Advantage * **Differentiated offering** * **Higher margins** on administration * **Ability to serve** more clients * **Technology leadership** ## Technology Architecture ### AI Agent System **Specialized agents for:** * Data processing and validation * Compliance monitoring * Report generation * Participant communication * Workflow orchestration ### Integration Capabilities **Connect with:** * Payroll systems (ADP, Paychex, etc.) * Recordkeeping platforms * Valuation providers * Document management systems * Email and SMS systems ### Security & Compliance * SOC 2 Type II compliant * Bank-level encryption * Role-based access control * Complete audit trails * Regular security audits ## Pricing Model (Proposed) ### Per-Participant Pricing **Scalable, predictable costs:** * \$10-25 per participant per year * Based on plan complexity * All features included * Volume discounts available ### White-Label Option **For enterprise TPAs:** * Custom branding * API access * Dedicated infrastructure * Premium support * Custom development ## Roadmap **Planned development:** * **2026 Q1-Q2:** Research & design phase * **2026 Q3-Q4:** Core platform development * **2027 Q1-Q2:** Beta testing with select TPAs * **2027 Q3:** General availability ## Join Our Design Partners Program We're seeking 3-5 forward-thinking TPAs to help shape this platform: **Benefits:** * Shape product features * Early access to technology * Preferred pricing * Direct access to development team * Competitive advantage Express interest in partnering ## Why Village Labs? ### Deep ESOP Expertise Our team combines: * Years of TPA experience * Advanced AI capabilities * Understanding of DOL/IRS requirements * Knowledge of industry pain points ### Proven Technology * Battle-tested repurchase forecasting * Enterprise-grade AI platform * Successful automation track record * Trusted by industry leaders ### Partnership Approach * Work with TPAs, not against them * Enhance your practice * White-label options available * Ongoing support and training ## Get Updates Stay informed about development progress and launch plans: Subscribe to updates ## Questions? Contact us about the TPA platform # Transaction Management Source: https://village-docs.villagelabs.com/in-development/transaction-management Streamlined ESOP transaction coordination ## Transaction Management Platform **Status:** In Development (Beta Q4 2025) A centralized platform for managing ESOP transactions. Made to enable collaboration and efficiency between selling owners, trustees, and their advisors. ## The Problem ESOP transactions (initial formation, buy-ins, add-ons) are complex: * Multiple stakeholders (seller, trustee, advisors, legal) * Extensive documentation requirements * Regulatory compliance needs * Timeline pressure * Coordination challenges **Today's reality:** * Email overload * Lost documents * Missed deadlines * Unclear status * Inefficient communication ## The Solution **A centralized transaction platform:** * All stakeholders in one place * Organized document management * Clear workflow and timeline * Real-time status tracking * Automated compliance checking ## Key Features ### Transaction Dashboard **See everything at a glance:** * Transaction status and timeline * Pending action items * Document status * Recent activity * Key milestones ### Document Management **Organized documentation:** * Centralized repository * Version control * Required document checklist * Automatic reminders * Secure sharing ### Stakeholder Collaboration **Work together effectively:** * Role-based access * Task assignments * Comments and discussions * @mentions and notifications * Activity tracking ### Workflow Management **Stay on track:** * Customizable workflows * Milestone tracking * Deadline management * Progress monitoring * Bottleneck identification ### Valuation Coordination **Streamline valuations:** * Coordinate with valuators * Track submission and delivery * Link to transaction documents * Historical record ### Trustee Support **Facilitate trustee review:** * Organized materials * Decision documentation * Compliance verification * Fiduciary record ### Compliance Tracking **Ensure regulatory compliance:** * DOL requirements * IRS rules * State regulations * Document completeness * Timeline adherence ## Who It's For ### Selling Shareholders **Navigate the process:** * Clear visibility into progress * Organized communications * Document access * Timeline clarity ### ESOP Trustees **Fulfill fiduciary duties:** * Complete information access * Organized review materials * Decision documentation * Compliance confidence ### Advisory Firms **Manage client transactions:** * Efficient coordination * Clear communication * Professional presentation * Scalable process ### Legal Teams **Handle legal work efficiently:** * Document organization * Version control * Collaboration tools * Compliance tracking ## Use Cases ### ESOP Formation **Initial ESOP creation:** * Seller engagement * Document gathering * Valuation coordination * Trustee approval * Closing coordination ### Buy-In Transactions **Additional shareholder purchases:** * Multiple seller coordination * Incremental purchases * Document management * Compliance tracking ### Add-On Acquisitions **Company acquisitions:** * Acquisition integration * Participant addition * Document coordination * Trustee approval process ## Benefits ### For All Stakeholders * **Transparency** - See transaction status anytime * **Efficiency** - Less time on coordination * **Organization** - No lost documents or emails * **Peace of mind** - Know nothing is missed ### For Advisors * **Scalability** - Handle more transactions * **Professionalism** - Impress clients * **Efficiency** - Less administrative burden * **Differentiation** - Stand out from competitors ### For Trustees * **Confidence** - Complete information * **Documentation** - Clear fiduciary record * **Efficiency** - Streamlined review * **Compliance** - Meet all requirements ## Technology ### Platform Features * Cloud-based (access anywhere) * Mobile-responsive * Real-time updates * Secure infrastructure * Integration-ready ### Security & Compliance * Bank-level encryption * Role-based access control * Audit trails * SOC 2 Type II compliance * Regular security audits ### Integrations **Connect with:** * Document management systems * Email (Gmail, Outlook) * Calendar applications * Accounting systems * Custom integrations (API) ## Pricing (Expected) ### Per-Transaction Model **Pay per transaction:** * $2,500 - $5,000 per transaction * Based on complexity * All features included * Unlimited stakeholders ### Subscription Model (for advisors) **Unlimited transactions:** * \$1,500/month (1-5 transactions/year) * \$3,000/month (6-15 transactions/year) * Custom pricing (15+ transactions/year) ## Beta Program **Join our beta:** * Early access (Q4 2025) * Preferred pricing * Shape development * Direct support Apply for beta access ## Timeline **Development phases:** * **Q1 2025:** Design & planning * **Q2-Q3 2025:** Development * **Q4 2025:** Beta launch * **Q1 2026:** General availability ## Get Updates Receive launch notification ## Questions? Contact us with questions # Trust Accounting Source: https://village-docs.villagelabs.com/in-development/trust-accounting This page contains information about the upcoming Trust Accounting features. # Village Labs Source: https://village-docs.villagelabs.com/index We're developing AI technology for employee stock ownership plans and our products include offerings for ESOP companies and advisory firms. Village Labs Hero Light Village Labs Hero Dark ## Welcome to Village Labs **Village Labs** is a technology company building AI and agentic systems for the employee stock ownership plan (ESOP) industry. We develop tools for ESOP professionals—including trustees, fiduciaries, and administrators—to better manage employee ownership plans. Our solutions help deliver precision, strategic foresight, and operational efficiency by transforming complex data into actionable intelligence and streamlining critical workflows. AI assistant for ESOP professionals Enterprise-grade ESOP financial modeling AI platform for financial services ## Products & Services ### Generative AI Advisory & Implementation We work with ESOPs and advisory firms to help them identify where to leverage generative AI effectively. Then design and deploy tailored systems and agents. Learn about our AI transformation services ### AI Assistant for ESOP Professionals Your AI-powered ESOP expert, available 24/7 to answer questions, run forecasts, and provide guidance on plan administration. Ask questions in plain English and get instant projections grounded in ESOP law. Learn about Kelso's capabilities ### Enterprise-Grade ESOP Financial Modeling A comprehensive financial modeling system for projecting ESOP repurchase obligations, cash flows, and trust health over decades. Run discrete annual simulations with support for leveraged ESOPs and complex scenarios. Learn about our forecasting engine ### Enterprise AI Platform for Financial Services Our foundational AI platform that powers all Village Labs products with specialized financial domain expertise. Built with multi-model architecture, enterprise security, and API-first design for seamless integration. Learn about our AI platform ## In Development Modeling long-term plan health and sustainability. Automated accounting and record-keeping for ESOP trusts. Secure, intuitive portals for employee-owners. ## Roadmap Agent-driven systems to streamline TPA workflows. Automated processing of distributions and payments. A centralized platform for managing ESOP transactions. ## Why Village Labs? Our team combines decades of ESOP experience with cutting-edge AI capabilities. We understand both the legal frameworks and the practical challenges of employee ownership. Every product is designed with fiduciary responsibility in mind—providing audit trails, reproducibility, and transparent reasoning for all outputs. Enterprise SLAs, SOC 2 compliance, and proven scalability. Our systems are built to support mission-critical financial operations. We integrate seamlessly with existing workflows, data systems, and service providers. Village Labs enhances your practice without replacing your tools. ## Who We Serve Make data-driven decisions about repurchase obligations and cash requirements Ensure compliance and maintain sustainable trust operations Deliver sophisticated forecasting and analysis to ESOP clients Provide accurate projections and streamlined administration ## Get Started Select the Village Labs product that fits your needs—Kelso for conversational AI, Repurchase Engine for detailed modeling, or Village Intelligence for custom AI solutions. Contact our team to schedule a demo and discuss your specific requirements. Our team will help you integrate Village Labs into your existing workflows and systems. Ongoing support, training, and updates to ensure you get maximum value from our products. See Village Labs in action Discuss your specific needs **Questions?** Reach out to our team at [roger@villagelabs.app](mailto:roger@villagelabs.app) or visit [villagelabs.com](https://villagelabs.com). # Kelso Features Source: https://village-docs.villagelabs.com/kelso/features Comprehensive capabilities of the Kelso AI Agent ## Kelso Features A comprehensive overview of Kelso's AI-powered capabilities for ESOP analysis and planning. ## Core Capabilities ### Natural Language Interface **Ask questions like you would to an ESOP expert:** * "What happens if we increase our contribution rate?" * "How does our repurchase obligation change if turnover increases?" * "What vesting schedule would minimize costs while staying competitive?" **Get expert answers that include:** * Direct answers to your questions * Supporting data and analysis * Visual charts and graphs * Related considerations * Recommended actions ### Repurchase Forecasting **Predict future obligations with confidence:** * Year-by-year obligation forecasts * Multiple scenario modeling * Cash flow impact analysis * Sensitivity testing * Monte Carlo simulations **Customizable assumptions:** * Turnover rates by demographics * Valuation growth projections * Future contributions * Diversification elections * Distribution patterns ### Plan Design Analysis **Evaluate plan design options:** * Vesting schedule comparisons * Allocation formula modeling * Eligibility requirement analysis * Distribution policy impact * Diversification feature evaluation **Compare scenarios side-by-side:** * Participant impact analysis * Company cost projections * Cash flow implications * Competitive benchmarking * Compliance verification ### Scenario Modeling **Test "what-if" scenarios:** * Growth rate variations * Turnover assumptions * Acquisition modeling * Downsizing impact * Valuation changes **Comprehensive outputs:** * Financial projections * Participant account values * Company contributions * Repurchase obligations * Cash flow statements ### Compliance Checking **Built-in regulatory knowledge:** * DOL prohibited transaction rules * IRS coverage and non-discrimination tests * ERISA fiduciary standards * Valuation requirements * Distribution regulations **Automated compliance alerts:** * Coverage test warnings * Top-heavy test monitoring * Anti-cutback violations * Adequate consideration issues * Required distribution tracking ## Advanced Features ### Multi-Year Forecasting Forecast 10+ years into the future with: * Participant lifecycle modeling * Hiring and turnover projections * Compensation growth trends * Valuation trajectory analysis * Obligation accumulation tracking ### Sensitivity Analysis Understand which assumptions matter most: * Identify key drivers of outcomes * Test ranges of assumptions * Visualize sensitivity * Focus planning on critical factors * Reduce forecast uncertainty ### Integration Capabilities Connect Kelso to your existing systems: * Payroll system integration * Valuation data import * TPA system connectivity * Financial system exports * Custom API access ### Reporting & Visualization Professional outputs for stakeholders: * Board presentation materials * Trustee reports * Management dashboards * Participant communications * Advisor deliverables ### Historical Analysis Learn from your ESOP's history: * Analyze past trends * Compare forecasts to actuals * Identify patterns * Improve future predictions * Understand drivers of change ## User Experience ### Intuitive Interface * Clean, modern design * Natural conversation flow * Visual results presentation * Easy scenario saving * Quick access to common tasks ### Fast Performance * Instant responses to simple queries * Complex scenarios in seconds * Real-time updates * No waiting for batch processing * Always available ### Collaborative Tools * Share analyses with team members * Comment on scenarios * Version control for plans * Audit trail of decisions * Export to common formats ## Data & Security ### Your Data, Protected * Bank-level encryption * SOC 2 Type II compliant * HIPAA-ready architecture * Regular security audits * Granular access controls ### Data Ownership * You own your data * Export anytime * No vendor lock-in * Delete on request * Privacy-first design ### Model Transparency * Understand how Kelso makes recommendations * See the data behind predictions * Review assumptions used * Challenge results * Build confidence in outputs ## Platform Capabilities ### Multi-User Support * Unlimited users per ESOP * Role-based permissions * Activity tracking * Collaborative workspaces * SSO integration ### Version Control * Track changes over time * Compare different plan designs * Revert to previous scenarios * Document decision rationale * Maintain audit trail ### Integrations **Current integrations:** * Repurchase Forecasting Engine * Common TPA systems * Excel import/export * API access **Coming soon:** * Additional TPA platforms * Valuation firm systems * Accounting software * Document management ## Support & Training ### Included Support * Email support (24-hour response) * In-app chat * Comprehensive documentation * Video tutorials * Webinar training sessions ### Premium Support (Enterprise) * Phone support * Dedicated account manager * Custom training sessions * Priority feature requests * Quarterly business reviews ## Updates & Improvements Kelso is continuously improving: * Regular feature updates * Model accuracy enhancements * New integrations * User-requested features * Latest AI capabilities All updates are included in your subscription at no additional cost. ## Get Started Get up and running in minutes Explore how others use Kelso # How to Use Kelso Source: https://village-docs.villagelabs.com/kelso/how-to-use Comprehensive guide to using Kelso effectively ## How to Use Kelso A complete guide to getting the most out of Kelso AI Agent. ## Getting Started ### Initial Setup Sign up at [villagelabs.com/kelso](https://villagelabs.com/kelso) Provide basic information about your ESOP Set up vesting, allocation, and distribution rules Upload census and historical data for better accuracy ## Asking Questions ### Natural Language Interface Kelso understands questions asked naturally: **Good questions:** * "What will our repurchase obligations be in 2025?" * "How does changing to 6-year vesting affect our costs?" * "What happens if we grow at 15% per year?" **Tips for better questions:** * Be specific about what you want to know * Include timeframes when relevant * Ask follow-up questions to dig deeper * Reference specific plan features ### Example Conversations **Repurchase Planning:** ``` You: What are our repurchase obligations for the next 5 years? Kelso: Based on your current participants and assumptions, your repurchase obligations are projected to be: 2025: $450K 2026: $520K 2027: $680K 2028: $750K 2029: $820K The increase in years 2027-2029 is driven by your demographic bulge of participants ages 60-65. You: What if turnover is 20% higher? Kelso: With 20% higher turnover, obligations would be: 2025: $510K (+13%) 2026: $595K (+14%) 2027: $750K (+10%) 2028: $825K (+10%) 2029: $880K (+7%) Higher turnover creates earlier distributions but smaller account balances. ``` ## Working with Scenarios ### Creating Scenarios Begin with your current ESOP configuration Use a descriptive name (e.g., "2024 Conservative Case") Modify the parameters you want to test Generate forecasts and projections Preserve your work for future reference ### Comparing Scenarios View scenarios side-by-side to understand differences: **Comparison views:** * Obligation forecasts by year * Cash flow requirements * Participant impact analysis * Key metrics dashboard * Cost comparisons **Export options:** * PDF reports * Excel spreadsheets * PowerPoint slides * CSV data files ## Common Workflows ### Annual Planning Workflow **Frequency:** Once per year **Steps:** 1. Update participant census 2. Review and update assumptions 3. Run base case forecast 4. Create conservative stress test 5. Present to board/trustee 6. Set contribution for year **Time required:** 2-4 hours ### Board Presentation Workflow **Frequency:** Quarterly or annually **Steps:** 1. Update current forecast 2. Compare to prior forecast 3. Explain key changes 4. Present stress scenarios 5. Recommend actions 6. Export presentation materials **Time required:** 1-2 hours ### Plan Design Evaluation Workflow **Frequency:** As needed **Steps:** 1. Document current plan design 2. Create scenarios for alternatives 3. Run comparative analysis 4. Evaluate participant impact 5. Assess cost implications 6. Present recommendations **Time required:** 3-5 hours ### Quick Analysis Workflow **Frequency:** As questions arise **Steps:** 1. Ask specific question 2. Review Kelso's answer 3. Ask follow-ups as needed 4. Export results if needed **Time required:** 5-15 minutes ## Interpreting Results ### Key Metrics to Watch **Repurchase Obligations:** * Annual obligation amounts * Cumulative obligations * Peak obligation years * Cash vs. promissory note split **Participant Accounts:** * Total value by participant * Average account values * Distribution of account sizes * Vested vs. unvested balances **Company Impact:** * Required contributions * Cash flow requirements * Tax deductions available * Financing needs **Compliance:** * Coverage test results * Top-heavy status * Anti-cutback warnings * Distribution compliance ### Understanding Charts **Obligation Forecasts:** * Bar charts show year-by-year obligations * Line charts show cumulative totals * Stacked charts break down by type **Sensitivity Analysis:** * Tornado charts show impact of assumptions * Range charts show possible outcomes * Waterfall charts show drivers of change ## Tips for Success ### Data Quality Matters Better data = better insights: * Keep census data current * Update assumptions regularly * Use actual valuation history * Track forecast accuracy ### Start Simple, Add Complexity Don't overcomplicate initially: * Begin with basic scenarios * Master core features first * Add advanced techniques gradually * Focus on actionable insights ### Collaborate with Your Team Kelso works best with multiple perspectives: * Share scenarios with colleagues * Get input on assumptions * Discuss results together * Document decisions made ### Regular Use Builds Expertise The more you use Kelso: * Better questions you'll ask * Deeper insights you'll gain * More efficient you'll become * More confident in results ## Common Mistakes to Avoid ### Unrealistic Assumptions ❌ Using overly optimistic projections ❌ Ignoring historical patterns ❌ Assuming best-case scenarios ✅ Use conservative, realistic assumptions ### Not Testing Alternatives ❌ Only running one scenario ❌ Not stress testing ❌ Assuming assumptions are certain ✅ Create multiple scenarios ### Ignoring Small Changes ❌ Only looking at big differences ❌ Missing gradual trends ❌ Not tracking over time ✅ Monitor even modest changes ### Not Documenting ❌ Not saving important analyses ❌ Not explaining assumptions ❌ Not tracking decisions ✅ Document everything thoroughly ## Getting Help ### In-App Resources * **Help Center:** Searchable documentation * **Video Tutorials:** Step-by-step guides * **Templates:** Pre-built scenario templates * **Tips:** Contextual suggestions ### Support Channels **Email Support:** * Email: [support@villagelabs.com](mailto:support@villagelabs.com) * Response time: 24 hours * Include screenshots when helpful **Chat Support:** * In-app chat available * Faster for quick questions * Can escalate to phone if needed **Training:** * Free webinar training * Custom training sessions available * Best practices workshops * One-on-one coaching ## Next Steps Explore common use cases Learn from experienced users Discover all capabilities Contact our team # Kelso AI Agent Source: https://village-docs.villagelabs.com/kelso/index Meet Kelso, the AI agent that does the work. Leverage deep domain knowledge and powerful workflow automation to handle your most complex ESOP tasks. Kelso AI Agent ## Your Agent for ESOPs Welcome to Kelso, your AI partner for navigating the complexities of the ESOP ecosystem. Kelso is not just a chatbot; it is a powerful agent designed with one fundamental goal: **to do your work.** Powered by our proprietary **Village Intelligence** knowledge core and fully integrated into the **Peninsula Operating System**, Kelso can understand, automate, and execute your most tedious and demanding workflows. Move beyond manual processes and unlock unprecedented efficiency. Learn how to give Kelso your first task in minutes. Explore practical examples for Trustees, TPAs, and CFOs. ## Core Capabilities Delegate complex, multi-step tasks with simple natural language commands. Have Kelso perform a mathematical audit on valuation report financials, cross-reference plan documents, or validate census data in seconds, not hours. Ask complex questions about ESOP mechanics, compliance rules, or strategic best practices. Kelso leverages Village Intelligence—our fine-tuned ESOP knowledge core—to provide accurate, context-aware answers and guidance. Kelso can write and execute Python code to query, analyze, and visualize data from across the platform. Ask for a breakdown of ESOPs by state from the 5500 database or model the impact of a specific plan rule change on your participant data. Interact with the powerful Repurchase Forecasting engine conversationally. Ask Kelso to model highly specific scenarios, like "What happens to our forecast if we change the turnover projection for our top 3 engineers by two years?" ## The Village Labs Difference: Enterprise AI Consumer AI tools are useful, but enterprise challenges demand a more powerful, integrated solution. Kelso represents the fusion of three critical components: Built on a robust, IDE-like framework, Kelso can execute complex, multi-stage tasks and will soon support "Agent Swarms" for even deeper workflow automation. Kelso is powered by Village Intelligence, our proprietary ESOP knowledge core, ensuring all its actions and answers are contextually relevant and accurate. Kelso is plugged directly into Peninsula, the ESOP Operating System, giving it secure access to your structured data to perform real work, not just answer questions. ## Who Uses Kelso? Automate compliance checks and valuation report reviews. Streamline census data validation and plan administration tasks. Accelerate financial analysis and report generation. Model complex financial scenarios and get strategic guidance. # Kelso AI Agent Source: https://village-docs.villagelabs.com/kelso/overview AI assistant for ESOP professionals # Kelso AI Assistant Your AI-powered ESOP expert, available 24/7 to answer questions, run forecasts, and provide guidance on plan administration. ## Key Capabilities * **Natural Language Queries** - Ask questions in plain English * **Instant Projections** - Generate multi-year forecasts in seconds * **Scenario Comparison** - Compare multiple planning strategies * **Expert Guidance** - Get answers grounded in ESOP law ## Who It's For Kelso serves ESOP trustees, administrators, CFOs, and advisors who need quick access to ESOP expertise and forecasting capabilities. Learn more about Kelso AI Agent # Quick Start Guide Source: https://village-docs.villagelabs.com/kelso/quickstart Get started with Kelso in minutes ## Quick Start Get up and running with Kelso in just a few minutes. ## Step 1: Create Your Account Visit [villagelabs.com/kelso](https://villagelabs.com/kelso) and create your account Check your email and verify your account Select the plan that fits your needs ## Step 2: Set Up Your ESOP Enter your ESOP's basic details: * Company name * Plan year * Number of participants * Current share price Configure your plan rules: * Vesting schedule * Allocation formula * Eligibility requirements * Distribution rules Import participant and historical data: * Upload census data * Import valuations * Load contribution history ## Step 3: Ask Your First Question Now you're ready to start using Kelso! ### Example Questions to Try **Forecasting:** ``` What will our repurchase obligations be over the next 5 years? ``` **Plan Design:** ``` What would happen if we changed our vesting to 6 years instead of 4? ``` **Scenario Analysis:** ``` How does 15% annual growth impact our ESOP over 10 years? ``` **Compliance:** ``` Are we at risk of failing the coverage test this year? ``` ## Step 4: Create Your First Scenario Click "New Scenario" in the dashboard Adjust the assumptions you want to test: * Growth rates * Turnover rates * Contribution amounts * Valuation multiples Click "Analyze" to see results Examine the forecast outputs: * Obligations by year * Cash flow impact * Participant accounts * Key metrics Save the scenario and share with your team ## Common First Tasks ### Forecast Repurchase Obligations **Goal:** Understand your future cash needs 1. Go to "Repurchase Forecasting" 2. Review default assumptions 3. Adjust as needed for your situation 4. Run 10-year forecast 5. Export results ### Compare Plan Design Options **Goal:** Evaluate a proposed plan change 1. Create "Current Plan" scenario 2. Create "Proposed Plan" scenario 3. Adjust plan rules in proposed version 4. Run side-by-side comparison 5. Review participant impact ### Stress Test Your ESOP **Goal:** See how your ESOP handles adverse conditions 1. Create base case scenario 2. Create stress scenarios: * Low growth * High turnover * Valuation decline 3. Compare outcomes 4. Identify vulnerabilities 5. Plan mitigations ## Tips for Success ### Start Simple Don't try to perfect all your assumptions on day one. Start with rough estimates and refine over time as you learn. ### Ask Follow-Up Questions Kelso maintains context, so you can ask follow-up questions: * "What about if growth is only 5%?" * "Show me the impact by participant age group" * "How sensitive is that to the turnover assumption?" ### Save Important Scenarios Save scenarios you'll want to reference later: * Annual planning scenarios * Board presentation analyses * Different strategic options * Stress tests ### Use the Templates Kelso includes templates for common analyses: * Annual repurchase forecast * Plan design comparison * Acquisition modeling * Downsizing impact ### Get Help When Needed Don't hesitate to reach out: * In-app chat support * Email: [support@villagelabs.com](mailto:support@villagelabs.com) * Video tutorials in help center * Schedule 1-on-1 training ## Next Steps Learn about all of Kelso's capabilities See how to use Kelso for plan design Learn from experienced users Book a personalized training session ## Need Help? Our team is here to help you succeed with Kelso # For ESOP CFOs & Executives Source: https://village-docs.villagelabs.com/kelso/use-cases/for-cfos Use Kelso for advanced financial modeling and strategic decision support. # For ESOP Trustees Source: https://village-docs.villagelabs.com/kelso/use-cases/for-trustees Leverage Kelso to deepen your plan understanding and ensure fiduciary compliance. # ESOPLoan Source: https://village-docs.villagelabs.com/models/esop-loan Self-contained loan object with dedicated suspense shares ## Overview Each `ESOPLoan` object represents a debt obligation of the ESOP, with shares held in a **dedicated suspense account** as collateral. This self-contained design ensures accurate loan-by-loan accounting for leveraged ESOPs. **Critical Concept:** Each loan directly owns its suspense shares. When Loan A is paid down, only Loan A's shares are released—never shares from Loan B. ## Model Structure ```python theme={null} class ESOPLoan(BaseModel): """ A self-contained ESOP loan with dedicated suspense shares. """ # Identification loan_id: str origination_date: date # Loan Terms original_principal: Decimal principal_balance: Decimal interest_rate: Decimal term_years: int payment_schedule: str # 'amortizing' or 'balloon' # Collateral suspense_shares: Decimal # Shares held for THIS loan only original_suspense_shares: Decimal # Metadata lender: str loan_purpose: str # 'initial_esop_purchase', 'refinancing', etc. ``` ## Why Loan-Specific Suspense Matters **Single Suspense Pool (Incorrect)** ```python theme={null} # BAD: All suspense shares in one pool trust = { "total_suspense_shares": 50_000, "loans": [ {"id": "LOAN_A", "balance": 2_000_000}, {"id": "LOAN_B", "balance": 1_500_000} ] } # Problem: When paying LOAN_A, which shares get released? # You can't tell! This violates ERISA requirements. ``` **Why It Fails:** * Can't determine which shares collateralize which loan * Violates ERISA's specific collateral requirements * Creates audit and compliance risk **Loan-Specific Suspense (Correct)** ```python theme={null} # GOOD: Each loan owns its shares loan_a = ESOPLoan( loan_id="LOAN_A", principal_balance=2_000_000, suspense_shares=30_000 # These shares belong to LOAN_A ) loan_b = ESOPLoan( loan_id="LOAN_B", principal_balance=1_500_000, suspense_shares=20_000 # These shares belong to LOAN_B ) # Clear: Paying LOAN_A releases LOAN_A's shares only ``` **Why It Works:** * Clear collateral ownership * ERISA compliant * Accurate share release calculations ## Share Release Mechanics When a loan payment is made, shares are released **proportionally** to the principal paid: ```python theme={null} def calculate_share_release( loan: ESOPLoan, principal_payment: Decimal ) -> Decimal: """ Calculate shares to release based on principal payment. """ # Percentage of original loan being paid release_percentage = principal_payment / loan.original_principal # Release that percentage of original suspense shares shares_to_release = loan.original_suspense_shares * release_percentage return shares_to_release # Example loan = ESOPLoan( original_principal=3_000_000, principal_balance=2_400_000, original_suspense_shares=30_000, suspense_shares=30_000 # None released yet ) # Pay $300K principal shares_released = calculate_share_release(loan, 300_000) # = 30,000 * (300,000 / 3,000,000) # = 30,000 * 0.10 # = 3,000 shares # Update loan loan.principal_balance -= 300_000 # 2,400K → 2,100K loan.suspense_shares -= 3_000 # 30,000 → 27,000 ``` **ERISA Requirement:** Shares must be released proportionally as the loan is repaid. This prevents "back-loading" where all shares are released at the end. ## Loan Types & Payment Schedules Equal principal + interest payments each year. ```python theme={null} loan = ESOPLoan( original_principal=3_000_000, interest_rate=0.065, term_years=10, payment_schedule='amortizing' ) # Calculate annual payment (simplified) annual_payment = calculate_amortizing_payment( principal=3_000_000, rate=0.065, years=10 ) # ≈ $415,000/year # Each year: consistent payment, increasing principal portion ``` Interest-only payments with principal due at maturity. ```python theme={null} loan = ESOPLoan( original_principal=3_000_000, interest_rate=0.065, term_years=10, payment_schedule='balloon' ) # Years 1-9: Interest only annual_interest = 3_000_000 * 0.065 # $195,000 # Year 10: Interest + full principal final_payment = 195_000 + 3_000_000 # $3,195,000 # Share release: All at once in year 10 ``` **Risk:** Balloon payments create large share releases and cash needs in final year. Plan carefully! Flexible payment structure. ```python theme={null} loan = ESOPLoan( original_principal=3_000_000, interest_rate=0.065, payment_schedule='custom', payment_stream=[ # Year 1: Lower payment {"year": 1, "principal": 150_000, "interest": 195_000}, # Year 2: Higher payment {"year": 2, "principal": 400_000, "interest": 185_000}, # ... ] ) ``` ## Methods & Operations ```python theme={null} def process_payment( self, principal_payment: Decimal, interest_payment: Decimal ) -> LoanPaymentResult: """ Process a loan payment and release shares. """ # Calculate share release release_pct = principal_payment / self.original_principal shares_to_release = self.original_suspense_shares * release_pct # Validate if shares_to_release > self.suspense_shares: raise ValueError("Cannot release more shares than in suspense") # Update loan state self.principal_balance -= principal_payment self.suspense_shares -= shares_to_release return LoanPaymentResult( principal_paid=principal_payment, interest_paid=interest_payment, shares_released=shares_to_release, remaining_balance=self.principal_balance, remaining_suspense=self.suspense_shares ) ``` ```python theme={null} def calculate_annual_payment(self, year: int) -> Tuple[Decimal, Decimal]: """ Calculate principal and interest for a given year. """ if self.payment_schedule == 'amortizing': # Standard amortization formula annual_payment = calculate_pmt( rate=self.interest_rate, nper=self.term_years, pv=self.original_principal ) interest = self.principal_balance * self.interest_rate principal = annual_payment - interest return (principal, interest) elif self.payment_schedule == 'balloon': interest = self.principal_balance * self.interest_rate # Principal due in final year only if year == self.term_years: principal = self.principal_balance else: principal = Decimal(0) return (principal, interest) ``` ```python theme={null} def loan_status(self) -> Dict: """ Get current loan status and metrics. """ percent_paid = ( (self.original_principal - self.principal_balance) / self.original_principal ) shares_released_count = ( self.original_suspense_shares - self.suspense_shares ) return { "loan_id": self.loan_id, "balance": self.principal_balance, "percent_paid": percent_paid, "suspense_shares": self.suspense_shares, "shares_released_to_date": shares_released_count, "fully_paid": self.principal_balance == 0 } ``` ## Multi-Loan Example Here's a complete example with two loans: ```python theme={null} # Loan 1: Original ESOP loan from 2020 loan_2020 = ESOPLoan( loan_id="LOAN_2020_INITIAL", origination_date=date(2020, 1, 1), original_principal=3_000_000, principal_balance=2_100_000, # Some paid down interest_rate=0.065, term_years=10, payment_schedule='amortizing', original_suspense_shares=30_000, suspense_shares=21_000, # 9,000 released so far lender="Local Bank", loan_purpose="initial_esop_purchase" ) # Loan 2: Refinancing loan from 2023 loan_2023 = ESOPLoan( loan_id="LOAN_2023_REFI", origination_date=date(2023, 6, 1), original_principal=2_000_000, principal_balance=1_900_000, interest_rate=0.070, term_years=8, payment_schedule='amortizing', original_suspense_shares=15_000, suspense_shares=14_250, # 750 released so far lender="Regional Credit Union", loan_purpose="refinancing" ) # Process payments for year 2025 result_1 = loan_2020.process_payment( principal_payment=300_000, interest_payment=136_500 ) # Releases: 30,000 * (300,000 / 3,000,000) = 3,000 shares result_2 = loan_2023.process_payment( principal_payment=200_000, interest_payment=133_000 ) # Releases: 15,000 * (200,000 / 2,000,000) = 1,500 shares # Total shares released in 2025: 4,500 # Total debt payment: $769,500 ($500K principal + $269.5K interest) ``` ## Integration with ESOPTrust The `ESOPTrust` aggregates all loans: ```python theme={null} trust = ESOPTrust( loans=[loan_2020, loan_2023], ... ) # Total suspense shares across all loans total_suspense = trust.total_suspense_shares() # = 21,000 + 14,250 = 35,250 # Total debt outstanding total_debt = sum(loan.principal_balance for loan in trust.loans) # = 2,100,000 + 1,900,000 = 4,000,000 # Process all loan payments for the year for loan in trust.loans: principal, interest = loan.calculate_annual_payment(current_year) result = loan.process_payment(principal, interest) trust.unallocated_shares += result.shares_released ``` ## Best Practices Always store `original_principal` and `original_suspense_shares` for accurate release calculations Ensure released shares never exceed suspense shares Record why each loan was taken (purchase, refinancing, expansion) Track debt-to-equity and ensure sustainable debt levels ## Common Issues **Problem:** Accidentally releasing shares from Loan B when paying Loan A. **Solution:** Each loan owns its shares. Never aggregate suspense shares. **Problem:** Share releases don't add up due to rounding. **Solution:** Use high-precision decimals and track cumulative releases. **Problem:** Large balloon payment creates cash crisis. **Solution:** Model balloon loans carefully and plan cash reserves. ## Next Steps See how loan share releases feed into allocation How loans fit into the trust structure # ESOPTrust Source: https://village-docs.villagelabs.com/models/esop-trust The central accounting hub for all ESOP assets and liabilities ## Overview The `ESOPTrust` is the **central accounting hub** for all plan assets and liabilities. It represents the legal entity that holds company stock and cash on behalf of plan participants. **New in v0.2:** Enhanced multi-loan support with dedicated suspense share tracking per loan! All ESOP assets are owned by the trust, not by individual participants directly. The trust allocates shares and cash to individual participant accounts according to plan rules. ## Model Structure ```python theme={null} class ESOPTrust(BaseModel): """ The ESOP Trust: Central hub for all plan assets. """ # Identification trust_id: str plan_name: str trust_established_date: date # Cash Management cash_ledger: TrustCashLedger # Share Management total_shares_outstanding: Decimal allocated_shares: Decimal unallocated_shares: Decimal # Debt Management loans: List[ESOPLoan] = [] # Metadata current_year: int last_valuation_date: date current_share_price: Decimal ``` ## Key Properties The `TrustCashLedger` manages all trust cash, segregated by source: ```python theme={null} trust.cash_ledger = TrustCashLedger( participant_cash_accounts=125_000, unallocated_company_contributions=50_000, unallocated_forfeiture_cash=25_000 ) # Total cash available total_cash = trust.cash_ledger.total_cash() # 200,000 ``` **See:** [TrustCashLedger Details](/models/trust-cash-ledger) Shares are categorized by their allocation status: ```python theme={null} # Shares credited to individual participant accounts trust.allocated_shares = 45_000 # Shares owned by trust but not yet allocated trust.unallocated_shares = 5_000 # Shares held as collateral for loans (in suspense) trust.total_suspense_shares() = 30_000 # Sum across all loans # Total shares must always balance assert trust.total_shares_outstanding == ( trust.allocated_shares + trust.unallocated_shares + trust.total_suspense_shares() ) # 45,000 + 5,000 + 30,000 = 80,000 ✓ ``` **Share Conservation Law:** Total shares must always equal the sum of allocated, unallocated, and suspense shares. The engine validates this after every processing step. The trust can have multiple loans, each with dedicated suspense shares: ```python theme={null} trust.loans = [ ESOPLoan( loan_id="LOAN_2020", principal_balance=1_500_000, interest_rate=0.065, suspense_shares=15_000 ), ESOPLoan( loan_id="LOAN_2023", principal_balance=1_200_000, interest_rate=0.070, suspense_shares=15_000 ) ] # Total suspense shares across all loans total_suspense = trust.total_suspense_shares() # 30,000 ``` **See:** [ESOPLoan Details](/models/esop-loan) ## Methods & Operations ### Core Methods ```python theme={null} # Total suspense shares across all loans def total_suspense_shares(self) -> Decimal: return sum(loan.suspense_shares for loan in self.loans) # Total market value of trust assets def total_asset_value(self) -> Decimal: share_value = self.total_shares_outstanding * self.current_share_price cash_value = self.cash_ledger.total_cash() return share_value + cash_value # Shares available for immediate allocation def allocable_share_pool(self) -> Decimal: return self.unallocated_shares ``` ```python theme={null} # Process a share repurchase def repurchase_shares( self, participant_id: str, shares: Decimal, cash_sources: List[str] ) -> RepurchaseTransaction: repurchase_amount = shares * self.current_share_price # Draw cash from specified sources (waterfall) cash_drawn = self.cash_ledger.draw_cash( amount=repurchase_amount, sources=cash_sources ) # Remove shares from circulation self.allocated_shares -= shares self.total_shares_outstanding -= shares return RepurchaseTransaction(...) # Receive company contribution def receive_contribution( self, cash_amount: Decimal, stock_shares: Decimal = 0 ): self.cash_ledger.unallocated_company_contributions += cash_amount self.unallocated_shares += stock_shares self.total_shares_outstanding += stock_shares ``` ```python theme={null} # Process annual loan payment and release shares def process_loan_payment( self, loan_id: str, principal_payment: Decimal, interest_payment: Decimal ) -> Decimal: loan = self.get_loan(loan_id) # Calculate shares to release release_percentage = principal_payment / loan.original_principal shares_to_release = loan.suspense_shares * release_percentage # Release shares from suspense loan.suspense_shares -= shares_to_release loan.principal_balance -= principal_payment # Add to allocable pool self.unallocated_shares += shares_to_release # Pay interest from cash self.cash_ledger.unallocated_company_contributions -= interest_payment return shares_to_release ``` ```python theme={null} # Validate trust state consistency def validate(self) -> List[ValidationError]: errors = [] # Check share conservation total_calculated = ( self.allocated_shares + self.unallocated_shares + self.total_suspense_shares() ) if total_calculated != self.total_shares_outstanding: errors.append(ValidationError( "Share conservation violated", f"Expected {self.total_shares_outstanding}, got {total_calculated}" )) # Check cash non-negativity if self.cash_ledger.total_cash() < 0: errors.append(ValidationError( "Negative cash balance", f"Total cash: {self.cash_ledger.total_cash()}" )) # Check loan balances for loan in self.loans: if loan.principal_balance < 0: errors.append(ValidationError( f"Negative loan balance: {loan.loan_id}" )) return errors ``` ## Lifecycle Example Here's how an `ESOPTrust` evolves during a simulation year: ```python theme={null} trust = ESOPTrust( allocated_shares=45_000, unallocated_shares=5_000, loans=[ESOPLoan(suspense_shares=30_000, ...)], cash_ledger=TrustCashLedger( unallocated_contributions=50_000, ... ) ) ``` ```python theme={null} # Company contributes $500K trust.receive_contribution(cash_amount=500_000) # Cash ledger updated: # unallocated_contributions: 50,000 → 550,000 ``` ```python theme={null} # Pay loan, release shares shares_released = trust.process_loan_payment( loan_id="LOAN_2020", principal_payment=200_000, interest_payment=100_000 ) # Results: # - Suspense shares: 30,000 → 28,000 # - Unallocated shares: 5,000 → 7,000 # - Cash: 550,000 → 450,000 (interest paid) ``` ```python theme={null} # Allocate released shares to participants trust.allocate_shares(shares=7_000, formula='pro_rata') # Results: # - Allocated shares: 45,000 → 52,000 # - Unallocated shares: 7,000 → 0 ``` ```python theme={null} # Repurchase from terminated participant trust.repurchase_shares( participant_id="EMP042", shares=850, cash_sources=[ 'unallocated_contributions', 'unallocated_forfeitures', 'participant_cash' ] ) # Results: # - Allocated shares: 52,000 → 51,150 # - Total shares outstanding: 80,000 → 79,150 # - Cash: 450,000 → 365,000 (assuming $100/share) ``` ```python theme={null} snapshot = trust.create_snapshot(year=2025) # Immutable record saved to database ``` ## Relationship to Other Models ```mermaid theme={null} graph TD TRUST[ESOPTrust] --> CASH[TrustCashLedger] TRUST --> LOANS[ESOPLoans] TRUST --> PARTICIPANTS[Participants] LOANS --> LOAN1[Loan 1: suspense_shares] LOANS --> LOAN2[Loan 2: suspense_shares] PARTICIPANTS --> P1[Participant 1: allocated_shares] PARTICIPANTS --> P2[Participant 2: allocated_shares] TRUST -.validates.-> CONSERVATION[Share Conservation] CONSERVATION -.ensures.-> SUM[allocated + unallocated + suspense = total] style TRUST fill:#29371F,color:#fff ``` ## Real-World Example A typical ESOP Trust state: ```python theme={null} acme_esop = ESOPTrust( trust_id="TRUST_ACME_001", plan_name="Acme Corporation ESOP", trust_established_date=date(2020, 1, 1), # Cash (segregated by source) cash_ledger=TrustCashLedger( participant_cash_accounts=125_000, unallocated_company_contributions=200_000, unallocated_forfeiture_cash=35_000 ), # Total: $360,000 # Shares total_shares_outstanding=100_000, allocated_shares=68_000, # Credited to 150 participants unallocated_shares=2_000, # Available for next allocation # Loans loans=[ ESOPLoan( loan_id="LOAN_2020_INITIAL", principal_balance=1_800_000, interest_rate=0.065, original_principal=3_000_000, suspense_shares=30_000 ) ], # Valuation current_year=2025, last_valuation_date=date(2024, 12, 31), current_share_price=Decimal("110.50") ) # Validate state errors = acme_esop.validate() assert len(errors) == 0 # ✓ Consistent state # Calculate metrics print(f"Total asset value: ${acme_esop.total_asset_value():,.2f}") # Output: Total asset value: $11,410,000 # (100,000 shares * $110.50 + $360,000 cash) print(f"Shares in suspense: {acme_esop.total_suspense_shares():,.0f}") # Output: Shares in suspense: 30,000 print(f"Percentage allocated: {acme_esop.allocated_shares / acme_esop.total_shares_outstanding:.1%}") # Output: Percentage allocated: 68.0% ``` ## Best Practices Call `trust.validate()` after any state-modifying operation Create snapshots before and after major operations Use provided methods rather than directly modifying attributes Log rationale for any manual adjustments ## Next Steps Cash segregation details Loan structure and mechanics How trust state evolves during processing # OperatingAssumptions Schema Source: https://village-docs.villagelabs.com/models/operating-assumptions Annual strategy configuration ## Overview `OperatingAssumptions` define the discretionary, variable financial decisions made annually. These change frequently based on business conditions. ## Schema ```json theme={null} { "contribution_policy": { "type": "fixed_amount" | "percentage_of_payroll", "annual_amount": 500000 }, "share_valuation": { "current_price": 100.00, "annual_growth_rate": 0.05 }, "repurchase_strategy": { "timing": "immediate" | "deferred", "funding_source": "trust_cash" | "company_loan" } } ``` ## Example See [Quick Start](/quickstart) for complete example. # Data Models Overview Source: https://village-docs.villagelabs.com/models/overview High-fidelity models that accurately reflect ESOP structures ## Model Philosophy At Village Labs, we built our Repurchase Engine on a set of **high-fidelity data models** that we designed to accurately reflect ESOP accounting and legal structures. We believe that models should not be mere data containers; they must embody the complex relationships and rules that govern ESOP operations. **Our Design Goal:** To create models that map 1:1 to real-world ESOP concepts, making the system intuitive for practitioners while maintaining the technical precision we demand. ## Core Models Central accounting hub for all plan assets and liabilities Non-fungible cash accounting by source Self-contained loan with dedicated suspense shares Individual participant account and demographics Legal framework and compliance rules Annual strategy and financial assumptions ## Model Hierarchy ```mermaid theme={null} graph TD ESOP[ESOPTrust] --> CASH[TrustCashLedger] ESOP --> LOANS[ESOPLoans[]] ESOP --> SHARES[Share Pools] LOANS --> LOAN1[ESOPLoan 1] LOANS --> LOAN2[ESOPLoan 2] LOAN1 --> SUSPENSE1[Suspense Shares] LOAN2 --> SUSPENSE2[Suspense Shares] PARTICIPANTS[Participants[]] --> P1[Participant 1] PARTICIPANTS --> P2[Participant 2] P1 --> ACCOUNT1[Account Balance] P2 --> ACCOUNT2[Account Balance] style ESOP fill:#29371F,color:#fff style CASH fill:#3D5030,color:#fff style LOANS fill:#3D5030,color:#fff ``` ## Key Modeling Concepts ### 1. Non-Fungible Cash **Problem:** In traditional accounting, all cash is fungible (interchangeable). But ESOP trust cash has **source-based restrictions** on use. **Solution:** The `TrustCashLedger` segregates cash by source: ```python theme={null} class TrustCashLedger: participant_cash_accounts: Decimal # Can only be used for participant distributions unallocated_company_contributions: Decimal # Flexible use per plan rules unallocated_forfeiture_cash: Decimal # Restricted use (typically contributions or reallocations) ``` **Real-World Analog:** Think of it like a restaurant where tips (participant cash) can only go to employees, while owner contributions can be used flexibly. ### 2. Loan-Owned Suspense Shares **Problem:** Multiple ESOP loans each collateralized by specific shares. Shares from Loan A shouldn't be released when paying Loan B. **Solution:** Each `ESOPLoan` directly owns its suspense shares: ```python theme={null} class ESOPLoan: loan_id: str principal_balance: Decimal interest_rate: Decimal suspense_shares: Decimal # ← Directly owned by THIS loan ``` **Critical:** This prevents cross-contamination and ensures ERISA compliance. ### 3. Separation of Legal vs. Strategy **Problem:** Mixing unchanging legal requirements with variable business decisions leads to configuration errors. **Solution:** Two distinct input models: ```python theme={null} class PlanRules: vesting_schedule: VestingSchedule distribution_policy: DistributionPolicy diversification_rules: DiversificationRules cash_usage_policy: List[CashSource] ``` Changes rarely, requires amendments ```python theme={null} class OperatingAssumptions: contribution_policy: ContributionPolicy share_valuation: ValuationAssumptions repurchase_strategy: RepurchaseStrategy financial_projections: FinancialProjections ``` Changes annually, business decisions ## Data Model Principles All models use strong typing with validation: ```python theme={null} from pydantic import BaseModel, Field, validator class ESOPLoan(BaseModel): principal_balance: Decimal = Field(ge=0) interest_rate: Decimal = Field(ge=0, le=1) suspense_shares: Decimal = Field(ge=0) @validator('interest_rate') def reasonable_interest_rate(cls, v): if v > 0.20: # 20% raise ValueError('Interest rate seems unreasonably high') return v ``` Historical snapshots are immutable; current state is mutable during processing: ```python theme={null} @dataclass(frozen=True) # Immutable class AnnualTrustSnapshot: year: int cash_balance: Decimal allocated_shares: Decimal @dataclass # Mutable during processing class TrustCashLedger: participant_cash: Decimal unallocated_contributions: Decimal ``` Models include descriptions and constraints: ```python theme={null} class VestingSchedule(BaseModel): """ Defines how participants earn ownership of their ESOP accounts. Common schedules: - Graded: Gradual vesting over 2-6 years - Cliff: All-or-nothing after 3 years """ type: Literal['graded', 'cliff'] years_to_full_vesting: int = Field( ge=2, le=7, description="Years until 100% vested (ERISA limits: 2-7)" ) ``` Models enforce referential integrity: ```python theme={null} class ESOPTrust: loans: List[ESOPLoan] def total_suspense_shares(self) -> Decimal: """Sum suspense shares across all loans.""" return sum(loan.suspense_shares for loan in self.loans) def validate_share_conservation(self): """Ensure total shares equal allocated + suspense + unallocated.""" total = ( self.allocated_shares + self.total_suspense_shares() + self.unallocated_shares ) assert total == self.total_shares_outstanding ``` ## Model Lifecycle Models flow through distinct lifecycle stages: User provides input data (PlanRules, OperatingAssumptions, InitialState) Models are validated for completeness, consistency, and legal compliance Engine manipulates mutable models during annual simulation cycle End-of-year state captured as immutable snapshot Snapshot saved to database with full audit trail ## Common Patterns ### Composition Over Inheritance Models favor composition for flexibility: ```python theme={null} class ESOPTrust: cash_ledger: TrustCashLedger # ← Composed loans: List[ESOPLoan] # ← Composed share_pool: SharePool # ← Composed # Not inheritance: # class ESOPTrust(CashLedger, LoanContainer, ShareManager) ``` ### Builder Pattern for Complexity Complex models use builders: ```python theme={null} trust = ( ESOPTrustBuilder() .with_cash_ledger(initial_cash=100_000) .add_loan( principal=2_000_000, rate=0.065, term_years=10, suspense_shares=20_000 ) .with_allocated_shares(30_000) .build() ) ``` ### Factory Methods for Common Scenarios ```python theme={null} # Standard graded vesting vesting = VestingSchedule.standard_graded() # Quick cliff vesting vesting = VestingSchedule.cliff(years=3) # Custom vesting = VestingSchedule( type='graded', schedule=[0, 0, 20, 40, 60, 80, 100] ) ``` ## Serialization & Deserialization All models support JSON serialization: ```python theme={null} # To JSON trust_json = trust.model_dump_json() # From JSON trust = ESOPTrust.model_validate_json(trust_json) # To database db.save(trust.model_dump()) # From database trust = ESOPTrust.model_validate(db.load(trust_id)) ``` ## Model Documentation Each model includes comprehensive documentation: * **Field descriptions**: What each field represents * **Constraints**: Valid ranges and rules * **Examples**: Common use cases * **Related models**: How models connect * **Legal context**: ERISA/IRS requirements ## Next Steps The central accounting hub Non-fungible cash tracking Loan-specific suspense shares Legal framework schema Strategy configuration Full API schema reference # PlanRules Schema Source: https://village-docs.villagelabs.com/models/plan-rules The legal framework configuration ## Overview `PlanRules` define the stable, legal framework of the ESOP as specified in the plan document. These rules change infrequently and require plan amendments. See [Design Principles](/architecture/design-principles) for the distinction between PlanRules and OperatingAssumptions. ## Schema ```json theme={null} { "plan_name": "string", "plan_year_end": "MM/DD", "vesting_schedule": { "type": "graded" | "cliff", "schedule": [0, 0, 20, 40, 60, 80, 100] }, "distribution_policy": { "timing": "immediate" | "termination_plus_1_year", "form": "lump_sum" | "installments" }, "cash_usage_policy": ["source1", "source2", "source3"], "diversification_rules": { } } ``` ## Example ```python theme={null} plan_rules = PlanRules( plan_name="Acme Corp ESOP", plan_year_end="12/31", vesting_schedule=VestingSchedule(type="graded"), distribution_policy=DistributionPolicy(timing="termination_plus_1_year"), cash_usage_policy=["unallocated_company_contributions", "unallocated_forfeiture_cash"] ) ``` # TrustCashLedger Source: https://village-docs.villagelabs.com/models/trust-cash-ledger Non-fungible cash accounting segregated by source ## The Non-Fungible Cash Problem In traditional accounting, all cash is fungible—any dollar can be used for any purpose. But **ESOP trust cash is different**. The source of cash determines how it can be legally used. Using restricted cash for the wrong purpose can result in ERISA violations, DOL audits, and plan disqualification. ## Model Structure The `TrustCashLedger` segregates cash by source, each with different usage rules: ```python theme={null} class TrustCashLedger(BaseModel): """ Non-fungible cash ledger tracking cash by source. """ # Individual participant cash balances participant_cash_accounts: Decimal = Field(ge=0) # Company contributions not yet allocated unallocated_company_contributions: Decimal = Field(ge=0) # Forfeitures not yet reallocated or used unallocated_forfeiture_cash: Decimal = Field(ge=0) def total_cash(self) -> Decimal: return ( self.participant_cash_accounts + self.unallocated_company_contributions + self.unallocated_forfeiture_cash ) ``` ## Cash Sources Explained **What It Is:** The sum of all cash held in individual employee accounts. **How It Gets There:** * Cash dividends on ESOP shares * Proceeds from diversification elections * Forfeitures reallocated as cash **Usage Restrictions:** * ✅ Can be used for distributions to that participant * ✅ Can fund repurchases per plan document * ❌ Cannot be used for plan expenses * ❌ Cannot be used for other participants ```python theme={null} # Example: Participant has $5,000 cash in account # Can be distributed to participant on termination # Or used to repurchase their shares (per plan rules) ``` **What It Is:** Company contributions that have been received but not yet credited to individual participants. **How It Gets There:** * Annual company cash contributions * Loan proceeds (for leveraged ESOPs) **Usage Restrictions:** * ✅ Can be used for share purchases * ✅ Can fund repurchases (per plan document) * ✅ Can be allocated to participants * ✅ Flexible use per cash\_usage\_policy ```python theme={null} # Most flexible cash source # Temporary holding account before allocation ``` **Timing Gap:** There's often a delay between when a contribution is made and when shares are allocated. This account bridges that gap. **What It Is:** Cash from the non-vested accounts of terminated participants. **How It Gets There:** * Terminated participant had non-vested shares * Shares sold, proceeds held here **Usage Restrictions:** * ✅ Can reduce company contributions (most common) * ✅ Can be reallocated to remaining participants * ✅ Can fund administrative expenses (if plan allows) * ⚠️ Usage strictly governed by plan document ```python theme={null} # Example: Employee terminates with 40% vesting # Non-vested 60% becomes forfeiture # Shares sold → cash held here ``` **Highly Restricted:** Plan document specifies exactly how forfeitures can be used. Deviation can cause plan disqualification. ## The Funding Waterfall When the trust needs cash (e.g., for repurchases), it draws from sources in a specific order defined by `PlanRules.cash_usage_policy`: ```python theme={null} # Example cash_usage_policy cash_usage_policy = [ "unallocated_company_contributions", # Draw from here first "unallocated_forfeiture_cash", # Then here "participant_cash_accounts" # Last resort ] # Process a $500,000 repurchase ledger = TrustCashLedger( participant_cash_accounts=150_000, unallocated_contributions=200_000, unallocated_forfeitures=100_000 ) result = ledger.draw_cash( amount=500_000, sources=cash_usage_policy ) # Execution: # 1. Draw $200K from unallocated_contributions → $300K remaining # 2. Draw $100K from unallocated_forfeitures → $200K remaining # 3. Draw $200K from participant_cash → $0 remaining ✓ ``` ## Methods & Operations ```python theme={null} def draw_cash( self, amount: Decimal, sources: List[str] ) -> CashDrawResult: """ Draw cash following the waterfall sequence. """ remaining_need = amount transactions = [] for source in sources: if remaining_need <= 0: break available = getattr(self, source) amount_to_draw = min(available, remaining_need) if amount_to_draw > 0: # Deduct from source setattr(self, source, available - amount_to_draw) remaining_need -= amount_to_draw transactions.append( CashTransaction( source=source, amount=amount_to_draw ) ) return CashDrawResult( requested=amount, drawn=amount - remaining_need, shortfall=remaining_need, transactions=transactions ) ``` ```python theme={null} def deposit_cash( self, amount: Decimal, source: str ): """ Add cash to a specific source. """ current = getattr(self, source) setattr(self, source, current + amount) # Example usage ledger.deposit_cash( amount=500_000, source="unallocated_company_contributions" ) ``` ```python theme={null} def transfer( self, amount: Decimal, from_source: str, to_source: str ): """ Move cash between sources (e.g., allocation). """ # Validate sufficient funds available = getattr(self, from_source) if available < amount: raise InsufficientFundsError() # Execute transfer setattr(self, from_source, available - amount) current_dest = getattr(self, to_source) setattr(self, to_source, current_dest + amount) # Example: Allocate forfeitures ledger.transfer( amount=25_000, from_source="unallocated_forfeiture_cash", to_source="participant_cash_accounts" ) ``` ```python theme={null} def validate(self) -> List[ValidationError]: """ Ensure all cash balances are non-negative. """ errors = [] if self.participant_cash_accounts < 0: errors.append(ValidationError( "Negative participant cash", self.participant_cash_accounts )) if self.unallocated_company_contributions < 0: errors.append(ValidationError( "Negative unallocated contributions", self.unallocated_company_contributions )) if self.unallocated_forfeiture_cash < 0: errors.append(ValidationError( "Negative forfeiture cash", self.unallocated_forfeiture_cash )) return errors ``` ## Real-World Example Here's a complete annual cycle showing cash flow through the ledger: ```python theme={null} ledger = TrustCashLedger( participant_cash=125_000, unallocated_contributions=50_000, unallocated_forfeitures=25_000 ) # Total: $200,000 ``` ```python theme={null} ledger.deposit_cash( amount=500_000, source="unallocated_company_contributions" ) # unallocated_contributions: 50K → 550K ``` ```python theme={null} # Reallocate forfeitures to participants ledger.transfer( amount=25_000, from_source="unallocated_forfeiture_cash", to_source="participant_cash_accounts" ) # forfeitures: 25K → 0 # participant_cash: 125K → 150K ``` ```python theme={null} # Need $400K for terminated participants result = ledger.draw_cash( amount=400_000, sources=[ "unallocated_company_contributions", "unallocated_forfeiture_cash", "participant_cash_accounts" ] ) # Execution: # Draw $400K from unallocated_contributions # unallocated_contributions: 550K → 150K ``` ```python theme={null} ledger = TrustCashLedger( participant_cash=150_000, unallocated_contributions=150_000, unallocated_forfeitures=0 ) # Total: $300,000 ``` ## Why This Matters Proper segregation ensures ERISA compliance and prevents DOL issues Clear source tracking makes audits straightforward Knowing what cash is available for what purpose improves forecasting Demonstrates prudent management of plan assets ## Common Mistakes to Avoid **Don't:** * ❌ Use participant cash for other participants * ❌ Use forfeiture cash without checking plan rules * ❌ Ignore the cash\_usage\_policy waterfall * ❌ Allow negative balances in any account **Do:** * ✅ Follow the plan document's cash usage rules * ✅ Validate after every cash operation * ✅ Log all cash movements * ✅ Review cash sources before making decisions ## Next Steps See how cash ledger fits into trust structure Detailed repurchase processing logic # Administration Guide Source: https://village-docs.villagelabs.com/peninsula/administration How Peninsula handles your ESOP administration ## ESOP Administration with Peninsula Understanding how Peninsula manages your ESOP. ## Annual Administration Cycle ### Q1: Year-End Processing **January-March** **Key activities:** * Process year-end census * Calculate contributions and allocations * Perform compliance testing * Update account balances * Generate trustee reports **Deliverables:** * Final account balances * Compliance test results * Trustee certification * Allocation reports ### Q2: Reporting & Filing **April-June** **Key activities:** * Prepare participant statements * Draft Form 5500 * Coordinate audit (if applicable) * File regulatory reports * Distribute participant communications **Deliverables:** * Annual participant statements * Form 5500 filing * Summary annual report * Required notices ### Q3: Mid-Year Review **July-September** **Key activities:** * Update interim census * Review plan performance * Assess contribution strategy * Plan for upcoming changes * Evaluate plan design **Deliverables:** * Mid-year status report * Contribution projections * Planning recommendations ### Q4: Planning & Preparation **October-December** **Key activities:** * Finalize contribution amounts * Project year-end results * Prepare for valuation * Update census data * Plan for next year **Deliverables:** * Year-end projections * Contribution recommendations * Valuation preparation * Next year planning ## Compliance Management ### Regular Testing **Ongoing monitoring:** * Coverage testing * Nondiscrimination testing (401(a)(4)) * Top-heavy testing * 415 limit compliance * Distribution compliance **Automated alerts:** * Potential compliance issues * Required actions * Deadline reminders * Regulatory changes ### Regulatory Updates **Stay current:** * Monitor DOL guidance * Track IRS changes * Update plan operations * Communicate impacts * Implement required changes ## Participant Services ### Annual Statements **Comprehensive information:** * Account balance * Year's activity * Vesting schedule * Distribution options * Contact information **Delivery:** * Mailed statements * Online portal access * Mobile-friendly * On-demand access ### Distribution Processing **Professional handling:** * Eligibility verification * Tax withholding calculation * Payment processing * Beneficiary coordination * Required documentation **Timeline:** * Request received * Documentation review: 5 business days * Payment processing: 10 business days * Total: \~3 weeks ### Participant Support **Responsive service:** * Email support * Phone support * Online resources * FAQ library * Educational materials ## Technology Platform ### Online Portal **For plan sponsors:** * View reports and statements * Access plan documents * Upload census data * Message your administrator * Download files **For participants:** * View account balance * Access statements * Update beneficiaries * Request distributions * Educational resources ### Data Security **Enterprise-grade protection:** * Bank-level encryption * Secure data transmission * Regular backups * Access controls * Audit trails ### Integration **Connect your systems:** * Payroll integration * Accounting systems * Document management * Single sign-on * API access ## Communication ### Regular Updates **Stay informed:** * Quarterly newsletters * Annual planning meetings * Ad hoc updates as needed * Regulatory alerts * Best practice tips ### Dedicated Support **Your administration team:** * Primary administrator * Support team access * Management oversight * Specialist resources **Response times:** * Urgent: Same day * Standard: 1 business day * Routine: 2-3 business days ## Quality Assurance ### Review Process **Multiple checkpoints:** * Automated validation * TPA professional review * Secondary review * Client approval * Final quality check ### Accuracy **We ensure:** * Data accuracy * Calculation correctness * Regulatory compliance * Timely delivery * Clear communication ## Get Help Reach out with questions anytime # Agent Swarms Source: https://village-docs.villagelabs.com/peninsula/agent-swarms Scale your productivity by parallelizing work with Agent Swarms, a core capability of the Village Operating System. ## The Power of Parallelization In a traditional workflow, tasks are handled sequentially. An analyst can only review one valuation report at a time, or run one forecast scenario at a time. This creates a linear, and often slow, path to completing complex projects. Agent Swarms fundamentally change this paradigm by introducing **work parallelization**. Instead of being limited to a single instance of Kelso, you can deploy a "swarm" of multiple agents to execute tasks concurrently. This capability transforms your potential output, allowing you to accomplish in minutes what might have previously taken hours or days. ## How Agent Swarms Work There are two primary ways to leverage Agent Swarms, both designed to dramatically increase your efficiency. ### 1. Parallelizing One Workflow This is the most common use case: applying a single, complex workflow to many different inputs at the same time. Instead of a one-to-one relationship between you and an agent, you become an overseer of a team of agents all performing the same task in parallel. graph TD subgraph A\[Traditional Workflow] direction TB U1\[User] --> T1\[Task 1: Review Report A] T1 --> T2\[Task 2: Review Report B] T2 --> T3\[Task 3: Review Report C] end subgraph B\[Agent Swarm Workflow] direction TB U2\[User as Overseer] --> S\[Deploys Swarm] S --> AG1\[Agent 1: Review Report A] S --> AG2\[Agent 2: Review Report B] S --> AG3\[Agent 3: Review Report C] end style A fill:#FFF3F3,stroke:#FF6666 style B fill:#F3FFF3,stroke:#66FF66 **Example:** You have ten valuation reports from ten different clients that all need a standard mathematical audit. Instead of opening each one and prompting Kelso ten separate times, you can simply instruct the swarm: > "Deploying a swarm of 10 agents. Each agent is to perform a full mathematical audit on one of the valuation reports in the `[Client Reports Q3]` folder and notify me upon completion." ### 2. Parallelizing Many Unrelated Tasks You can also deploy a swarm to handle multiple, distinct tasks simultaneously, allowing you to gather diverse information and accelerate your research process. **Example:** You are preparing for a client strategy meeting and need to assemble information from several sources. You can deploy a swarm to work on these unrelated tasks concurrently: * **Agent 1:** "Summarize the section on `[Distribution Policy]` from the client's Plan Document." * **Agent 2:** "Pull the historical account balances for all participants who terminated in the last three years." * **Agent 3:** "Query the 5500 database for the three largest ESOPs in the same industry and state as our client." While each task is different, the swarm executes them in parallel, gathering all the necessary information for your meeting in a fraction of the time it would take to do it sequentially. This allows you, the human operator, to focus on the high-level strategic thinking the meeting requires, rather than the low-level data gathering. # System Architecture Source: https://village-docs.villagelabs.com/peninsula/architecture Understanding the Village OS: A look at the integrated, IDE-like environment that powers your ESOP workflows. ## The IDE for ESOPs The Peninsula platform is designed from the ground up as an "IDE for ESOPs"—an integrated development environment for employee ownership professionals. This architecture brings together your data, tools, and the powerful Kelso AI Agent into a single, cohesive interface, eliminating the need to switch between disparate applications and manually transfer data. The user interface is built on a simple yet powerful three-pane layout, ensuring that you have access to everything you need without losing context. graph TD subgraph A\[The Village Operating System] direction LR subgraph B\[Left Sidebar] C\[Workspaces] D\[Clients & Cases] E\[Modules & Tools] end subgraph F\[Main View] G\[File Viewer
(PDF, DOCX, XLSX)] H\[Dashboards] I\[Data Grids] end subgraph J\[Right Sidebar] K\[Kelso AI Agent] end end B -- Manages --> F E -- Extends --> K K -- Acts On --> F style B fill:#f9f9f9,stroke:#333,stroke-width:2px style F fill:#f9f9f9,stroke:#333,stroke-width:2px style J fill:#f9f9f9,stroke:#333,stroke-width:2px ### 1. Left Sidebar: Navigation & Tooling This is your command center for navigating workspaces and accessing your toolset. * **Workspaces:** Switch between different client environments or internal projects. Each workspace contains its own set of clients, files, and configurations. * **Clients & Cases:** Drill down into specific client data, managing all related files and information in a structured manner. * **Modules & Tools:** This is where you can add and manage specialized capabilities. Kelso gains access to any tools installed here, allowing it to perform new, more advanced workflows. Examples include the Repurchase Forecasting module, a custom Fairness Opinion generator, or a Plan Document analyzer. ### 2. Main View: Your Workspace Canvas The main view is a flexible canvas where your work gets done. It's fundamentally a powerful file viewer that can render various formats: * **PDFs:** Review valuation reports or plan documents. * **Spreadsheets:** Analyze financial models or census data. * **Documents:** Draft plan amendments or review legal opinions. This is your active context. Any file or data you open here becomes the immediate focus for Kelso, allowing you to ask questions and issue commands about the specific information on your screen. ### 3. Right Sidebar: The Kelso AI Agent Kelso is always available in the right sidebar, ready to work. It maintains awareness of your context in the Main View and can leverage all the tools installed in the Left Sidebar. This tight integration is the key to its power, enabling you to: * **Ask questions about the open file:** "Summarize the vesting schedule in this plan document." * **Execute complex workflows:** "Reconcile the transactions in this bank statement against our trust accounting data." * **Run analyses:** "Using the Repurchase Forecasting tool, model the impact of a 10% increase in company valuation on the open spreadsheet." # Compliance & Regulations Source: https://village-docs.villagelabs.com/peninsula/compliance How Peninsula ensures ESOP compliance ## ESOP Compliance with Peninsula Comprehensive compliance monitoring and support. ## Regulatory Framework ### Key Regulations **DOL (Department of Labor):** * ERISA compliance * Fiduciary duties * Prohibited transactions * Reporting requirements **IRS (Internal Revenue Service):** * Qualification requirements * Coverage and nondiscrimination * Distribution rules * Tax compliance **Other Requirements:** * Securities regulations * State requirements * Plan document compliance ## Automated Compliance Testing ### Coverage Testing **Ensuring adequate participation:** * Ratio percentage test * Average benefit test * Minimum participation standards **Frequency:** Annual (automatically) **Alerts:** If test results indicate issues ### Nondiscrimination Testing **Fair allocation verification:** * General test (401(a)(4)) * Safe harbor compliance * Cross-testing if applicable **Frequency:** Annual **Support:** Corrective action guidance if needed ### Top-Heavy Testing **Monitoring key employee benefits:** * Automatic calculation * Minimum contribution requirements * Reporting to participants **Frequency:** Annual **Action:** Implement minimums if top-heavy ### 415 Limits **Annual additions limits:** * Monitor contributions and forfeitures * Track annual additions * Prevent excess contributions **Frequency:** Real-time monitoring **Protection:** Automatic alerts before limits exceeded ## Plan Document Compliance ### Document Updates **Keep plan current:** * Regulatory changes * Discretionary amendments * Restatements * Required updates **Process:** * Monitor regulatory changes * Draft amendments * Client review and approval * Implement and file ### Required Notices **Timely participant communications:** * Summary Annual Report (SAR) * Summary of Material Modifications (SMM) * Safe harbor notices * Other required notices **Delivery:** * Automatic scheduling * Multiple delivery methods * Proof of delivery * Archive for records ## Regulatory Filing ### Form 5500 **Annual filing:** * Complete preparation * Accuracy review * Timely filing * Electronic submission **Included schedules:** * Schedule R (distributions) * Schedule H or I (financial) * Other required schedules **Timeline:** * Draft: June * Review: June-July * Filing: Before deadline (extension if needed) ### Other Filings **As required:** * Form 8955-SSA (participant statements) * Determination letter applications * VCP filings if needed * State filings ## Fiduciary Support ### Plan Administration **Prudent procedures:** * Documented processes * Regular monitoring * Timely actions * Proper records ### Trustee Support **Fiduciary assistance:** * Annual trustee reports * Compliance certifications * Transaction documentation * Ongoing consultation ### Audit Support **If plan requires audit:** * Coordinate with auditors * Provide documentation * Respond to requests * Review audit results ## Correction Programs ### Identifying Issues **Proactive monitoring:** * Automated alerts * Regular reviews * Compliance checks * Error detection ### Correction Methods **Address issues promptly:** * Self-correction (EPCRS) * Voluntary Correction Program (VCP) * Proper documentation * Preventive measures **Our role:** * Identify issues early * Recommend correction method * Assist with filings * Prevent recurrence ## Regulatory Updates ### Monitoring Changes **Stay current:** * DOL guidance * IRS notices * Legislative changes * Court decisions **Communication:** * Alert clients to changes * Explain impacts * Recommend actions * Implement updates ### Plan Updates **Keep plan compliant:** * Required amendments * Document updates * Process changes * Participant communications ## Best Practices ### Documentation **Maintain proper records:** * Plan documents * Amendments * Board resolutions * Participant communications * Compliance test results **Retention:** * Permanent: Plan documents * 6+ years: Compliance tests, distributions * Per policy: Other records ### Regular Reviews **Scheduled compliance checks:** * Quarterly operations review * Annual compliance assessment * Periodic plan audit * Strategic planning ### Education **Keep stakeholders informed:** * Trustee education * Board presentations * Committee training * Staff awareness ## Compliance Resources **Available support:** * Compliance manual * Regulatory updates * Best practice guides * Training materials * Expert consultation ## Questions? Contact our compliance team # Peninsula System Source: https://village-docs.villagelabs.com/peninsula/index The operating system for ESOPs. A single, integrated environment to manage your clients, data, and workflows with unparalleled power and security. Peninsula Operating System ## The ESOP Operating System Welcome to Peninsula, the foundational platform that brings your entire ESOP workflow into a single, powerful environment. Designed as an "IDE for ESOPs," Peninsula provides the structure, tools, and security you need to manage your clients and data with confidence. Peninsula is the home where the **Kelso AI Agent** operates and where the deep knowledge of **Village Intelligence** is applied. It is the robust core that enables true workflow automation. Learn how to set up your workspace and manage clients. Explore the Trust Accounting module and data management tools. ## An Integrated Environment Peninsula is built on the principle that your tools should work together seamlessly. Manage all your clients, cases, and plan documents from a single, intuitive navigation panel. Utilize our standardized format for all ESOP state data—participants, plans, and trusts—enabling powerful analytics and reliable accounting. The Kelso AI Agent is always available in the sidebar, ready to work on your data and automate your tasks directly within your environment. # Onboarding Process Source: https://village-docs.villagelabs.com/peninsula/onboarding Get started with Peninsula administration ## Onboarding to Peninsula A smooth transition to professional ESOP administration. ## Onboarding Timeline ### Weeks 1-2: Discovery & Setup **Activities:** * Kickoff meeting with your team * Review current plan documents * Assess data sources and systems * Set up secure data exchange * Establish communication protocols **Deliverables:** * Project plan and timeline * Data requirements checklist * Contact directory * Access credentials ### Weeks 3-4: Data Migration **Activities:** * Gather historical data * Import participant census * Load prior year information * Validate data accuracy * Configure plan rules in system **Deliverables:** * Complete census database * Historical records loaded * Data validation report * System configuration complete ### Weeks 5-6: Testing & Training **Activities:** * Run test calculations * Review compliance testing * Generate sample reports * Train your team on portal * Establish ongoing processes **Deliverables:** * Test results validation * User training completed * Process documentation * Go-live approval ### Week 7: Go Live **Activities:** * Final data verification * Production cutover * Announce to participants * Monitor initial operations * Provide go-live support **Deliverables:** * Live system * Participant communications * Support resources * Success metrics ## What We Need From You ### Initial Information **Plan documents:** * Adoption agreement * Plan document * Summary plan description * Recent amendments **Participant data:** * Current census * Account balances * Vesting schedules * Historical contributions **Company information:** * Payroll system details * Valuation reports * Prior year Form 5500 * Trustee information ### Ongoing Information **Quarterly:** * Updated census data * Payroll changes * New hire information * Term terminations **Annually:** * Year-end census * Current valuation * Contribution information * Plan amendments ## Making the Transition Smooth ### Communication We'll keep you informed: * Weekly status updates * Regular check-in meetings * Clear escalation process * Responsive support ### Support Help when you need it: * Dedicated implementation manager * Technical support team * Training and resources * Post-launch assistance ### Flexibility We adapt to your needs: * Flexible timeline * Customized approach * Work with your schedule * Address unique requirements ## After Go-Live ### First 90 Days **Extra attention:** * More frequent check-ins * Proactive monitoring * Additional training * Process refinement ### Ongoing Success **Long-term partnership:** * Regular business reviews * Continuous improvement * Strategic consulting * Responsive support ## Common Questions Typical onboarding is 6-8 weeks. Timeline depends on data availability and complexity. Yes! We can start administration at any point in the plan year. We handle all transition coordination with your prior TPA. No separate onboarding fee. It's included in your annual administration. ## Get Started Contact us to start your transition # TPA Partner Program Source: https://village-docs.villagelabs.com/peninsula/partner-program Partnership opportunities for third-party administrators ## Peninsula TPA Partner Program Scale your ESOP administration practice with AI-powered technology. ## Program Overview Peninsula provides TPAs with a complete ESOP administration platform powered by AI, enabling you to: * **Scale efficiently** - Handle 3x more clients per staff member * **Reduce costs** - Lower cost per client through automation * **Improve quality** - Fewer errors, better compliance * **Enhance service** - Faster turnaround, better insights ## Partnership Models ### Platform Partnership **Use Peninsula for your clients:** * Access to full platform * Your branding throughout * Client-facing portal * API integration * Dedicated support **Pricing:** Per-client subscription **Best for:** Established TPAs looking to scale ### Referral Partnership **Refer clients to Peninsula:** * Ongoing referral fees * Client relationship maintained * No technology investment * No administration burden **Pricing:** Referral fee per client **Best for:** TPAs focusing on advisory services ### White-Label Partnership **Fully branded solution:** * Complete white-label platform * Custom workflows * Your company branding * Dedicated infrastructure * Priority support **Pricing:** Custom enterprise agreement **Best for:** Large TPAs, established practices ## Platform Benefits ### AI-Powered Automation **Delegate routine tasks to AI:** * Census data processing * Eligibility calculations * Allocation computations * Compliance testing * Report generation **Result:** 70% reduction in manual work ### Intelligent Workflows **Streamlined processes:** * Automated data validation * Smart error detection * Guided correction * Quality assurance checks * Approval workflows **Result:** Faster, more accurate processing ### Professional Outputs **Client-ready deliverables:** * Participant statements * Trustee reports * Form 5500 packages * Board presentations * Custom reports **Result:** Impress clients with quality ### Compliance Confidence **Built-in safeguards:** * Automated testing * Regulatory monitoring * Update notifications * Documentation support * Audit assistance **Result:** Reduce compliance risk ## Technology Features ### Modern Platform * Cloud-based architecture * Mobile-responsive design * Real-time collaboration * Secure data storage * 99.9% uptime SLA ### Integration Ready **Connect your systems:** * Payroll integrations * Accounting software * Document management * CRM systems * Custom APIs ### Client Portal **Self-service access:** * View reports * Download documents * Upload data * Message administrator * Access resources ### Analytics & Insights **Business intelligence:** * Client portfolio dashboard * Profitability analysis * Efficiency metrics * Trend identification * Growth opportunities ## Implementation ### Onboarding Process Understand your practice and requirements Set up platform with your workflows and branding Comprehensive team training on platform Migrate first client(s) with support Go live with ongoing success support **Timeline:** 4-6 weeks ### Training & Support **We ensure your success:** * Comprehensive training program * Ongoing education * Dedicated support team * Regular check-ins * Community access ## Economics ### Cost Structure **Platform costs:** * Per-client subscription * Volume-based pricing * No upfront investment * Predictable monthly costs **Typical savings:** * 40-60% reduction in labor costs * 3x capacity increase per staff * Improved profitability per client ### Pricing Tiers **Starter** (1-10 clients) * \$400/client/month * Standard features * Email support **Professional** (11-50 clients) * \$300/client/month * All features * Priority support **Enterprise** (51+ clients) * Custom pricing * White-label options * Dedicated support * Custom integrations ## Support & Resources ### Dedicated Support **Your success team:** * Account manager * Technical support * Implementation specialist * Training resources **Response times:** * Critical: 1 hour * Urgent: 4 hours * Standard: Next business day ### Partner Resources **Tools for success:** * Sales enablement materials * Client onboarding templates * Marketing resources * Best practice guides * Training library ### Partner Community **Connect with peers:** * Private community forum * Monthly webinars * Annual conference * Networking opportunities * Knowledge sharing ## Success Stories ### Regional TPA Firm **Challenge:** 2 staff administering 15 ESOPs, hitting capacity **Solution:** Implemented Peninsula platform **Results:** * Now handling 40 ESOPs with same staff * 35% increase in profit margin * 90% client satisfaction score * Expanding to new markets ### Boutique Advisory Firm **Challenge:** Wanted to offer administration without building team **Solution:** White-label Peninsula partnership **Results:** * Added administration services * 25% revenue increase * Deeper client relationships * Competitive differentiation ## Get Started See Peninsula in action We'll understand your practice and goals Receive tailored partnership proposal Finalize partnership terms Begin onboarding and training ## Next Steps See the platform in action Get detailed program information Common questions answered Discuss partnership opportunities # Pricing Source: https://village-docs.villagelabs.com/peninsula/pricing Transparent pricing for ESOP administration ## Peninsula Pricing Competitive, transparent pricing for professional ESOP administration. ## For Plan Sponsors ### Annual Administration Fees **Small Plans (\< 50 participants)** * Base fee: $8,000 - $12,000 annually * Includes all core services * No setup fees **Medium Plans (50-200 participants)** * Base fee: $12,000 - $25,000 annually * Volume-based pricing * Comprehensive services **Large Plans (200+ participants)** * Custom pricing * Dedicated account manager * Enhanced services ### Additional Services **Distribution Processing:** $150 per distribution **Loan Administration:** $500 annually per loan **Special Projects:** \$200/hour ## For TPAs ### Platform Licensing **Per-Client Model:** * $200 - $500 per client monthly * Volume discounts available * Unlimited users **White-Label Partnership:** * Custom pricing * Full platform access * Your branding * Dedicated support ## What's Included All pricing includes: * Complete annual administration * Compliance testing and monitoring * Participant statements * Trustee reporting * Form 5500 preparation * Online access * Email and phone support * Regulatory updates ## No Hidden Fees We believe in transparent pricing: * ✅ All-inclusive service * ✅ Predictable costs * ✅ No surprise charges * ✅ Volume discounts ## Get a Quote Get pricing specific to your situation # Resources & Support Source: https://village-docs.villagelabs.com/peninsula/resources Resources for Peninsula users ## Peninsula Resources Everything you need to succeed with Peninsula. ## Documentation ### User Guides **For plan sponsors:** * Getting started guide * Annual administration process * Using the participant portal * Data submission guidelines * FAQ **For TPAs:** * Platform overview * Administration workflows * Client onboarding * Best practices * Technical documentation ### Video Tutorials **Available topics:** * Platform overview (10 min) * Census data processing (15 min) * Running compliance tests (12 min) * Generating reports (8 min) * Client portal walkthrough (7 min) ## Support ### Contact Options **Email Support:** * Email: [support@villagelabs.com](mailto:support@villagelabs.com) * Response: Within 1 business day * Best for: Non-urgent questions **Phone Support:** * Available: 9am-5pm ET * For: Urgent issues * Priority for Enterprise clients **Chat Support:** * In-platform chat * Quick questions * Technical help ### Support Hours **Standard:** * Monday-Friday: 9am-5pm ET * Email monitored evenings/weekends **Enterprise:** * Extended hours available * Dedicated support line * After-hours emergency support ## Training ### Live Training **Webinars:** * Monthly training sessions * Topic-specific workshops * Q\&A sessions * Recorded for later viewing **Custom Training:** * Tailored to your team * On-site or virtual * Flexible scheduling * Ongoing education ### Self-Paced Learning **Learning Center:** * Video tutorials * Step-by-step guides * Best practices * Tips and tricks **Certifications:** * Peninsula Administrator certification * Advanced features certification * Continuing education credits ## Community ### User Forum **Connect with peers:** * Ask questions * Share best practices * Learn from others * Vote on features ### Events **Annual Conference:** * User presentations * Networking * Product updates * Expert sessions **Regional Meetups:** * Local gatherings * Casual networking * Knowledge sharing ## Updates & News ### Product Updates **Release notes:** * New features * Improvements * Bug fixes * Coming soon **Frequency:** Monthly ### Newsletter **Topics covered:** * Product news * Industry updates * Tips and tricks * Success stories **Frequency:** Monthly ### Regulatory Updates **Stay informed:** * DOL guidance * IRS changes * Compliance alerts * Action required **Delivery:** As needed ## Tools & Templates ### For TPAs **Available downloads:** * Client onboarding checklist * Data submission templates * Communication templates * Sales materials * Marketing resources ### For Plan Sponsors **Available downloads:** * Census template * Distribution request form * Beneficiary designation form * Plan summary template ## FAQ ### General Questions Click "Forgot Password" on login screen, or contact support. Email [support@villagelabs.com](mailto:support@villagelabs.com) or use in-app chat. Log in to your account and visit the Learning Center. Yes, you can export all your data at any time. ### Technical Questions Chrome, Firefox, Safari, and Edge (latest versions). No app required - the platform is mobile-responsive. Bank-level encryption, SOC 2 certified, regular audits. Automatic daily backups with 30-day retention. ## Additional Help Get help from our team Book a training session Suggest an improvement Report a technical problem # Administration Services Source: https://village-docs.villagelabs.com/peninsula/services Comprehensive ESOP administration services ## Peninsula Administration Services Full-service ESOP administration powered by AI technology. ## Core Services ### Annual Administration Complete plan administration services: * Census data processing and validation * Eligibility determination * Contribution and allocation calculations * Annual valuations coordination * Compliance testing (coverage, 415, top-heavy) * Form 5500 preparation and filing * Participant statements * Trustee reporting ### Compliance Services Stay compliant with all regulations: * DOL compliance monitoring * IRS regulatory updates * ERISA fiduciary oversight * Plan document maintenance * Amendment tracking * Required notices * Regulatory filings ### Participant Services Support for plan participants: * Annual benefit statements * Distribution processing * Beneficiary management * Loan administration * Diversification elections * Rollover processing ### Strategic Services Advisory support for plan success: * Plan design consulting * Repurchase obligation forecasting * Contribution strategy * Fiduciary guidance * Best practice recommendations ## Service Delivery ### Data Collection **Streamlined process:** * Automated payroll integration * Secure file exchange * Data validation * Error correction ### Processing & Analysis **AI-powered efficiency:** * Automated calculations * Compliance testing * Report generation * Quality assurance ### Review & Approval **Expert oversight:** * TPA professional review * Exception handling * Client communication * Final approval ### Delivery & Support **Professional service:** * Timely deliverables * Online access * Responsive support * Ongoing consultation ## Timeline **Typical annual cycle:** **Q1:** Plan year end processing, compliance testing **Q2:** Form 5500 filing, participant statements **Q3:** Mid-year check-in, planning for next year **Q4:** Year-end projections, contribution planning ## Pricing Transparent, predictable pricing: * Based on number of participants * All-inclusive service * No hidden fees * Volume discounts available **Contact for a custom quote** ## Get Started Get pricing for your ESOP # Quick Start Source: https://village-docs.villagelabs.com/quickstart 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. First, ensure you have access to the Village Labs API. Contact our team at [support@villagelabs.com](mailto:support@villagelabs.com) for API credentials. ```python Python theme={null} pip install villagelabs-repurchase ``` ```javascript JavaScript theme={null} npm install @villagelabs/repurchase-engine ``` The engine requires four input components: 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" ] } ``` 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" } } ``` 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 } ] } ``` 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 } ``` Execute your first simulation: ```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": {...} }' ``` ## What You Get After running a simulation, you'll receive comprehensive results: Year-by-year forecasts of all ESOP activities Detailed repurchase liability projections Trust cash inflows and outflows Allocated, unallocated, and suspense shares Individual account balances and vesting Diversification and distribution requirements ## Understanding Your Results ```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 } ``` ```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 } ``` ```json theme={null} { "participant_id": "EMP001", "year": 2025, "allocated_shares": 1200, "vested_shares": 1000, "account_value": 132000, "cash_balance": 5000, "diversification_eligible": false } ``` ## Next Steps Learn how the engine works under the hood Understand the core data structures See complex multi-loan scenarios 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](/examples/multi-loan). Diversification is automatically calculated based on participant age and service. The engine flags eligible participants and models elections in your projections. ## Need Help? Our team is here to help you get started. Reach out with questions about setup, data preparation, or results interpretation. # Repurchase Forecasting Source: https://village-docs.villagelabs.com/repurchase-forecasting/index An introduction to our powerful repurchase obligation forecasting engine, a core application of the Village Operating System. Repurchase Engine ## Welcome Welcome to the Repurchase Forecasting module, a core application of the **Village Operating System**. At Village Labs, we've built our powerful Repurchase Engine to give you unparalleled insight into your long-term ESOP sustainability. We designed it to be a high-fidelity forecasting tool that moves beyond simple spreadsheets, allowing you to model complex scenarios with confidence and precision. This documentation will guide you through the architecture, data models, and simulation pipeline that power our engine. Get your first simulation running in 5 minutes Understand how the engine works Explore the core data structures Integrate the engine into your applications ## Key Features Process census data through a step-by-step annual cycle, modeling every aspect of ESOP administration from share releases to repurchase obligations. Built on ESOP legal principles with strict adherence to statutory requirements for diversification, share releases, and cash usage policies. Every input scenario and simulation run is permanently versioned, providing complete reproducibility and temporal analysis capabilities. Accurately model leveraged ESOPs with multiple debt tranches using loan-by-loan share release mechanics. Deep integration with AI agents through a high-level toolkit designed for natural language interactions and scenario analysis. ## Core Capabilities Project long-term repurchase obligations with precision Model trust cash flows and contribution requirements Track allocated, unallocated, and suspense shares Simulate statutory diversification requirements Compare multiple planning scenarios side-by-side Forecast employee terminations using predictive models ## Design Philosophy The Repurchase Engine is built on three core design principles: Distinguish between **PlanRules** (the legal "constitution") and **OperatingAssumptions** (annual strategy), mirroring how plan sponsors actually operate. Maintain a temporal, stateful database where nothing is ever overwritten—ensuring complete reproducibility and audit trails. Expose high-level user intents to AI agents, creating a stable integration that survives internal engine changes. ## Who Uses the Repurchase Engine? Model long-term repurchase obligations and cash requirements Ensure compliance and sustainable trust operations Provide data-driven guidance to ESOP clients Deliver accurate forecasting for plan administration ## Get Started New to ESOPs? Start here for foundational concepts. Follow our quickstart guide to run a simulation. **Need Help?** Contact our support team at [support@villagelabs.com](mailto:support@villagelabs.com) or check out our [GitHub repository](https://github.com/villagelabsdotapp/docs-repurchase). # Repurchase Forecasting Source: https://village-docs.villagelabs.com/repurchase-forecasting/overview Enterprise-grade ESOP financial modeling # Repurchase Forecasting A comprehensive financial modeling system for projecting ESOP repurchase obligations, cash flows, and trust health over decades. ## Core Features * **Discrete Annual Simulation** - Step-by-step modeling of ESOP operations * **Multi-Loan Support** - Accurate leveraged ESOP modeling * **Immutable Audit Trail** - Complete reproducibility and versioning * **API Integration** - Embed forecasting into your workflows ## Enterprise-Grade Solution Built for trustees, advisors, and plan sponsors who need accurate, auditable forecasting for ESOP repurchase obligations and cash flow planning. Learn about our complete forecasting solution # Simulation Overview Source: https://village-docs.villagelabs.com/simulation/overview Understanding the annual processing pipeline ## What is a Simulation? A simulation is a **year-by-year projection** of all ESOP activities, from company contributions and share releases to diversification elections and repurchase obligations. The engine processes each year as a discrete unit, applying a strict sequence of operations that mirror real-world ESOP administration. ## The Annual Cycle Each simulation year follows a 9-step process: ```mermaid theme={null} graph LR S0[Step 0: Turnover] --> S1[Step 1: Initialization] S1 --> S2[Step 2: Share Pool] S2 --> S3[Step 3: Allocate] S3 --> S4[Step 4: Contribution] S4 --> S5[Step 5: Vesting] S5 --> S6[Step 6: Diversification] S6 --> S7[Step 7: Repurchases] S7 --> S8[Step 8: Year-End] style S2 fill:#29371F,color:#fff style S7 fill:#29371F,color:#fff ``` ## Key Processing Steps Forecast which employees will terminate Calculate share price and prepare for annual processing Calculate shares available for allocation (loan-by-loan mechanics) Distribute shares to eligible participants pro-rata by compensation Determine company contribution for the year Calculate vested balances and potential forfeitures Process diversification elections Execute share repurchases using the Funding Waterfall Finalize annual results and prepare for next year Complete step-by-step breakdown ## Simulation Inputs Legal framework (rarely changes) ```json theme={null} { "vesting_schedule": {...}, "distribution_policy": {...}, "cash_usage_policy": [...] } ``` Annual strategy (changes frequently) ```json theme={null} { "contribution_policy": {...}, "share_valuation": {...}, "repurchase_strategy": {...} } ``` Current ESOP status ```json theme={null} { "participants": [...], "trust_cash": {...}, "esop_loans": [...] } ``` Simulation settings ```json theme={null} { "projection_years": 20, "include_turnover": true } ``` ## Simulation Outputs After running a simulation, you receive: Year-by-year forecasts for all key metrics: * Company contributions * Share releases and allocations * Repurchase obligations * Trust cash flows * Loan balances Individual account details for every participant, every year: * Allocated shares * Vested percentages * Account values * Diversification status Complete trust accounting: * Cash balances by source * Share pools (allocated, suspense, unallocated) * Loan balances and terms Key insights: * Total 10/20-year repurchase obligations * Peak cash year * Average annual contribution * Final trust solvency ## Simulation Types Single projection with best-estimate assumptions. **Use For:** * Annual planning * Budget preparation * Board presentations Multiple simulations with different assumptions. **Use For:** * Comparing contribution strategies * Evaluating refinancing options * Stress testing **Example:** * Scenario A: \$500K annual contribution * Scenario B: \$600K annual contribution * Compare 10-year obligations Systematically vary key assumptions. **Use For:** * Understanding model sensitivity * Identifying key drivers * Risk assessment **Example:** Vary share price growth: -5%, 0%, +5%, +10% ## Running a Simulation Configure PlanRules, OperatingAssumptions, InitialState ```python theme={null} results = engine.simulate( plan_rules=plan_rules, operating_assumptions=operating_assumptions, initial_state=initial_state, system_config=system_config ) ``` Analyze outputs, visualize trends, identify issues Adjust assumptions and re-run as needed ## Best Practices Begin with basic assumptions, add complexity gradually Ensure census data and financials are accurate Don't rely on a single forecast Record rationale for all major assumptions Recalibrate models with actual results Look for patterns, not individual year precision ## Next Steps Create your first simulation See complete simulation examples Deep dive into each step Full API documentation # Step 0: Turnover Projection Source: https://village-docs.villagelabs.com/simulation/step-0-turnover Forecast employee terminations ## Overview Optional predictive module that forecasts which employees will terminate based on age, service, compensation, and historical patterns. ## How It Works ```python theme={null} turnover_projections = model.predict(participants, assumptions) # Returns list of projected termination events with probabilities ``` See [Simulation Core](/architecture/simulation-core) for full details. # Step 1: Initialization Source: https://village-docs.villagelabs.com/simulation/step-1-initialization Calculate share price and prepare for annual processing ## Overview Step 1 initializes the annual processing cycle by calculating the current share price and preparing all state variables for the year's simulation. This is the **foundation step** that establishes share valuations used throughout all subsequent steps. ## Core Responsibilities Calculate per-share value from company equity and outstanding shares Initialize security-specific prices and aggregate metrics Apply annual growth rate to company equity value *** ## Processing Logic ### Single-Class Mode The simplest calculation: ```python theme={null} # Calculate share price from company equity share_price = company_equity_value / total_outstanding_shares # Example: # Company Equity: $50,000,000 # Outstanding Shares: 100,000 # Share Price: $50,000,000 / 100,000 = $500.00/share ``` ### Multi-Class Mode When multiple securities exist, Step 1: Set each security's price from its FMV or use company aggregate price as fallback Sum equity value across all securities: ```python theme={null} equity_total = sum( security.current_share_price * security.total_outstanding_shares for security in securities.values() ) ``` For legacy compatibility: ```python theme={null} company_share_price = equity_total / total_outstanding_shares ``` Set up per-security recycled and forfeited share pools **Example Multi-Class Calculation:** ```python theme={null} # Class A: 60,000 shares at $600/share = $36,000,000 # Class B: 40,000 shares at $400/share = $16,000,000 # Total Equity: $52,000,000 # Aggregate Price: $52,000,000 / 100,000 = $520/share ``` *** ## Growth Application After initializing prices, Step 1 applies the annual growth rate: ```python theme={null} growth_rate = 1 + share_price_growth_rate # e.g., 1.05 for 5% company_equity_value *= growth_rate # Example: # Beginning Equity: $50,000,000 # Growth Rate: 5% (1.05) # Ending Equity: $50,000,000 * 1.05 = $52,500,000 # New Share Price: $52,500,000 / 100,000 = $525/share ``` Growth is applied **uniformly across all securities**: ```python theme={null} growth_rate = 1 + share_price_growth_rate for security in securities.values(): security.current_share_price *= growth_rate # Recalculate aggregate equity equity_total = sum( security.current_share_price * security.total_outstanding_shares for security in securities.values() ) company_equity_value = equity_total ``` **Example:** * Class A: $600 * 1.05 = $630/share * Class B: $400 * 1.05 = $420/share * New aggregate: ($630 * 60,000) + ($420 \* 40,000) = \$54,600,000 Growth is applied to **equity value**, not share count. Outstanding shares remain constant unless modified by redemptions in Step 7. *** *** ## Compliance Events Step 1 emits two compliance events: Initial price before growth: ```json theme={null} { "year": 2025, "phase": "initialization", "event": "share_price_calculated", "details": { "share_price": 500.00, "equity_value": 50000000.00, "outstanding_shares": 100000.0 } } ``` Price after applying growth: ```json theme={null} { "year": 2025, "phase": "init", "event": "share_price_initialized", "details": { "growth_applied": 1.05, "new_equity_value": 52500000.00 } } ``` Complete audit trail: ```json theme={null} { "year": 2025, "phase": "init", "event": "share_price_computed", "entity_type": "company", "entity_id": null, "inputs": { "equity_value": 50000000.00, "outstanding_shares": 100000.0, "share_price_growth_rate": 0.05 }, "outputs": { "share_price": 525.00, "new_equity_value": 52500000.00 } } ``` *** ## Data Flow ### Inputs ```python theme={null} { "company_equity_value": 50000000.00, # Total company value "total_outstanding_shares": 100000.0, # Shares in circulation "securities": { # Multi-class mode only "CLASS_A": { "security_id": "CLASS_A", "initial_fair_market_value": 600.00, "total_outstanding_shares": 60000.0, "initial_recycled_shares": 500.0, "initial_forfeited_shares": 150.0 }, "CLASS_B": {...} } } ``` ```python theme={null} { "share_price_growth_rate": 0.05 # 5% annual growth } ``` ### Outputs ```python theme={null} { "current_share_price": 525.00, # New price after growth "company_equity_value": 52500000.00, # New equity after growth "securities": { # Multi-class mode "CLASS_A": { "current_share_price": 630.00 # Grown price }, "CLASS_B": { "current_share_price": 420.00 # Grown price } } } ``` ```python theme={null} { "recycled_shares_by_security": { # Multi-class mode "CLASS_A": 500.0, "CLASS_B": 0.0 }, "forfeited_shares_next_year_by_security": { "CLASS_A": 150.0, "CLASS_B": 0.0 } } ``` *** ## Implementation Notes ### Division by Zero Protection ```python theme={null} # If no shares outstanding, use default denominator denominator = total_outstanding_shares if total_outstanding_shares > 0 else Decimal("1") share_price = company_equity_value / denominator ``` ### Precision Handling All financial calculations use `Decimal` type to avoid floating-point errors: ```python theme={null} from decimal import Decimal growth_rate = Decimal(str(1 + share_price_growth_rate)) company_equity_value *= growth_rate ``` *** ## Related Steps Uses share price to value loan releases and contributions Uses share price to enforce ERISA annual addition caps Reconciles TrustCashLedger balances Data model for company equity and shares *** ## Timing Note **Important:** Yearly evolution of employee data (age, service years, compensation growth) happens in **Step 8**, not Step 1. Step 1 focuses solely on share price and company-level state initialization. *** ## Example Scenario **Setup:** * Company Equity: \$50M * Outstanding Shares: 100,000 * Growth Rate: 5% * Multi-class: Class A (60K shares), Class B (40K shares) **Processing:** ```python theme={null} # 1. Initialize Class A CLASS_A.current_share_price = 600.00 CLASS_A_equity = 600.00 * 60,000 = $36,000,000 # 2. Initialize Class B CLASS_B.current_share_price = 400.00 CLASS_B_equity = 400.00 * 40,000 = $16,000,000 # 3. Calculate aggregate company_equity_value = $36M + $16M = $52M company_share_price = $52M / 100,000 = $520/share # 4. Apply growth (5%) CLASS_A.current_share_price = 600.00 * 1.05 = $630.00 CLASS_B.current_share_price = 400.00 * 1.05 = $420.00 # 5. Recalculate aggregate company_equity_value = (630 * 60K) + (420 * 40K) = $54.6M company_share_price = $54.6M / 100,000 = $546/share # (Removed OIA BOY setup in v0.3) ``` **Result:** * ✅ Share prices calculated and grown * ✅ Aggregate metrics updated * ✅ Ready for Step 2 *** ## Summary Step 1 is a **foundational initialization step** that: * ✅ Calculates share price from company equity * ✅ Supports both single-class and multi-class modes * ✅ Applies annual growth rate * ✅ Sets up per-security carry-over pools * ✅ Emits comprehensive compliance events This step establishes the **pricing basis** used throughout all subsequent steps in the annual cycle. # Step 2: Share Pool Calculation Source: https://village-docs.villagelabs.com/simulation/step-2-share-pool Loan-by-loan share release mechanics ## Overview Calculate shares available for allocation from company contributions and loan releases. ## Loan-by-Loan Release See [Simulation Core](/architecture/simulation-core#loan-by-loan-share-release) for detailed explanation. ```python theme={null} # Release shares proportional to principal paid on each loan for loan in esop_loans: release_pct = principal_payment / loan.original_principal shares_released = loan.original_suspense_shares * release_pct # Update loan suspense and trust unallocated pool loan.suspense_shares -= shares_released trust.unallocated_shares += shares_released ``` ### Example: Two Loans ```python theme={null} # Loan 1: Original $3M, suspense 30,000; principal paid this year: $300K shares1 = 30_000 * (300_000 / 3_000_000) # = 3,000 # Loan 2: Original $2M, suspense 15,000; principal paid this year: $200K shares2 = 15_000 * (200_000 / 2_000_000) # = 1,500 # Total pool from releases this year share_pool_from_loans = shares1 + shares2 # = 4,500 # Trust unallocated pool increases by 4,500 shares trust.unallocated_shares += share_pool_from_loans ``` Shares are released strictly from the paying loan's suspense account. This prevents cross-loan contamination and aligns with ERISA collateral rules. # Step 3: Allocate Shares Source: https://village-docs.villagelabs.com/simulation/step-3-allocation Distribute shares to eligible participants pro-rata by compensation ## Overview Step 3 allocates shares from the pool (determined in Step 2) to eligible participants, applying eligibility rules and ERISA caps. This is where participants actually receive their **annual allocation** of ESOP shares based on their compensation. ## Core Responsibilities Identify which employees qualify for allocation Distribute shares proportional to eligible compensation Apply compensation and annual addition caps Allocate across multiple securities in proper proportions *** ## Processing Phases ### Phase 1: Determine Eligibility Employees must meet **all three criteria** to receive allocations: ```python theme={null} is_eligible = ( employee.age >= eligibility_age # e.g., 21 AND employee.service_years >= eligibility_service_years # e.g., 1.0 AND employee.hours_worked >= eligibility_min_hours # e.g., 1000 ) ``` **Example:** * Eligibility Age: 21 * Eligibility Service: 1 year * Eligibility Hours: 1,000 hours/year **Employee A:** Age 35, 5 years service, 2,080 hours → ✅ **Eligible**\ **Employee B:** Age 22, 0.5 years service, 2,080 hours → ❌ **Not eligible** (service)\ **Employee C:** Age 24, 2 years service, 800 hours → ❌ **Not eligible** (hours) Every employee gets an eligibility evaluation event in the compliance log, regardless of outcome. *** ### Phase 2: Calculate Eligible Compensation Apply the **ERISA Compensation Cap** (IRC §401(a)(17)): ```python theme={null} max_compensation = 345_000 # 2025 ERISA limit (adjusts annually) for employee in eligible_employees: if employee.compensation > max_compensation: capped_compensation = max_compensation # Log compensation cap event else: capped_compensation = employee.compensation total_eligible_compensation += capped_compensation ``` **Example:** * Employee A: $80,000 comp → capped at $80,000 (under limit) * Employee B: $250,000 comp → capped at $250,000 (under limit) * Employee C: $400,000 comp → capped at $345,000 (over limit) ⚠️ Total eligible comp = $80K + $250K + $345K = $675,000 **IRS Regulation:** IRC §401(a)(17) limits compensation that can be considered for qualified plan contributions. **Purpose:** Prevents disproportionate benefits for highly compensated employees. **2025 Limit:** \$345,000 (indexed annually for inflation) **Impact:** High earners get allocations based on capped amount, not actual pay. *** ### Phase 3: Allocate Shares Shares are distributed **pro-rata by eligible compensation**: ```python theme={null} for employee in eligible_employees: allocation_ratio = employee.capped_compensation / total_eligible_compensation shares_to_allocate = total_share_pool * allocation_ratio ``` **Example Allocation:** | Employee | Compensation | Capped Comp | Ratio | Share Pool | Allocation | | --------- | ------------- | ------------- | -------- | ---------- | ---------------- | | A | \$80,000 | \$80,000 | 11.85% | 5,000 | 593 shares | | B | \$250,000 | \$250,000 | 37.04% | 5,000 | 1,852 shares | | C | \$400,000 | \$345,000 | 51.11% | 5,000 | 2,555 shares | | **Total** | **\$730,000** | **\$675,000** | **100%** | **5,000** | **5,000 shares** | Notice Employee C's allocation is based on $345K, not their actual $400K compensation. *** ### Phase 4: Apply Annual Addition Cap **ERISA Annual Addition Limit** (IRC §415): Maximum value that can be added to an employee's account in a year: **\$69,000** (2025 limit). This includes employer contributions, forfeitures allocated, and certain other additions. ```python theme={null} max_annual_addition = 69_000 # 2025 ERISA limit for employee in eligible_employees: allocation_value = shares_to_allocate * share_price if allocation_value > max_annual_addition: # Scale down allocation to cap shares_to_allocate = max_annual_addition / share_price # Log annual addition cap event ``` **Example:** * Share Price: \$500 * Employee C allocated: 2,555 shares * Value: 2,555 \* $500 = $1,277,500 ⚠️ **WAY OVER** **Capped Allocation:** * Max value: \$69,000 * Capped shares: $69,000 / $500 = **138 shares** * Employee C receives: 138 shares (not 2,555) When share price is high, annual addition cap severely limits allocations: **Low Share Price (\$50):** * Cap: \$69,000 * Max shares: $69,000 / $50 = **1,380 shares** **Medium Share Price (\$500):** * Cap: \$69,000 * Max shares: $69,000 / $500 = **138 shares** **High Share Price (\$5,000):** * Cap: \$69,000 * Max shares: $69,000 / $5,000 = **13.8 shares** As companies mature and share price increases, **fewer shares** can be allocated per participant due to this cap. In multi-class mode, cap is applied to the **combined value** across all securities: ```python theme={null} # Calculate total value across all securities total_value = 0 for security_id, quantity in allocations_by_security.items(): security_price = securities[security_id].current_share_price total_value += quantity * security_price # If over cap, scale down ALL securities proportionally if total_value > max_annual_addition: scale_factor = max_annual_addition / total_value for security_id in allocations_by_security.keys(): allocations_by_security[security_id] *= scale_factor ``` **Example:** * Class A allocation: 50 shares @ $600 = $30,000 * Class B allocation: 100 shares @ $400 = $40,000 * Total value: $70,000 (over $69K cap) * Scale factor: $69,000 / $70,000 = 0.9857 **Scaled Allocations:** * Class A: 50 \* 0.9857 = 49.29 shares * Class B: 100 \* 0.9857 = 98.57 shares * New total: \$68,996 ✅ *** ## Multi-Class Allocation When `multi_class_mode=True`, allocations are distributed **per security**: From Step 2, each security has its own share pool: ```python theme={null} share_pool_by_security = { "CLASS_A": 3_000.0, # shares available "CLASS_B": 2_000.0 # shares available } ``` ```python theme={null} for employee in eligible_employees: allocation_ratio = employee.capped_comp / total_eligible_comp for security_id, pool_quantity in share_pool_by_security.items(): employee_allocation[security_id] = pool_quantity * allocation_ratio ``` Calculate **combined value** and scale if necessary ```python theme={null} for security_id, quantity in employee_allocation.items(): if not employee.holdings.get(security_id): employee.holdings[security_id] = Holding() employee.holdings[security_id].shares += quantity ``` **Example Multi-Class Allocation:** | Employee | Comp Ratio | Class A Pool | Class A Alloc | Class B Pool | Class B Alloc | | -------- | ---------- | ------------ | ------------- | ------------ | ------------- | | A | 20% | 3,000 | 600 | 2,000 | 400 | | B | 35% | 3,000 | 1,050 | 2,000 | 700 | | C | 45% | 3,000 | 1,350 | 2,000 | 900 | *** ## Data Flow ### Inputs ```python theme={null} { "total_shares_for_pool": 5000.0, # Single-class mode "share_pool_by_security": { # Multi-class mode "CLASS_A": 3000.0, "CLASS_B": 2000.0 } } ``` ```python theme={null} { "eligibility_age": 21, "eligibility_service_years": 1.0, "eligibility_min_hours": 1000 } ``` ```python theme={null} { "max_compensation": 345_000, # §401(a)(17) "max_annual_addition": 69_000 # §415 } ``` ```python theme={null} { "employee_id": "EMP001", "age": 35, "service_years": 5.0, "hours_worked": 2080, "compensation": 125_000.0 } ``` ### Outputs ```python theme={null} { "allocated_shares": 1250.0, # Total allocated (aggregate) "holdings": { # Multi-class mode "CLASS_A": { "shares": 750.0 # Allocated Class A }, "CLASS_B": { "shares": 500.0 # Allocated Class B } } } ``` Per employee: * `eligibility_evaluated` * `compensation_capped` (if over limit) * `shares_allocated` * `annual_addition_capped` (if over limit) * `allocation_computed` (structured event) *** ## Compliance Events Every employee gets evaluated: ```json theme={null} { "year": 2025, "phase": "eligibility", "event": "eligibility_evaluated", "entity_type": "employee", "entity_id": "EMP001", "inputs": { "age": 35, "service_years": 5.0, "hours_worked": 2080, "eligibility_age": 21, "eligibility_service_years": 1.0, "eligibility_min_hours": 1000 }, "outputs": { "eligible": true } } ``` When compensation exceeds ERISA limit: ```json theme={null} { "year": 2025, "phase": "allocation", "event": "compensation_capped", "entity_type": "employee", "entity_id": "EMP042", "details": { "original": 400000.0, "capped": 345000.0 }, "policy": "erisa_compensation_cap" } ``` Company-level summary: ```json theme={null} { "year": 2025, "phase": "allocation", "event": "covered_comp_summary", "entity_type": "company", "inputs": { "max_compensation": 345000.0 }, "outputs": { "total_capped_compensation": 2875000.0, "eligible_employee_count": 45 } } ``` When allocation value exceeds \$69K: ```json theme={null} { "year": 2025, "phase": "allocation", "event": "annual_addition_capped", "entity_type": "employee", "entity_id": "EMP105", "details": { "original_value": 1277500.0, "capped_value": 69000.0 }, "policy": "erisa_annual_addition_cap" } ``` Complete allocation audit trail: ```json theme={null} { "year": 2025, "phase": "allocation", "event": "allocation_computed", "entity_type": "employee", "entity_id": "EMP001", "inputs": { "capped_compensation": 125000.0, "total_eligible_compensation": 2875000.0, "share_pool_by_security": { "CLASS_A": 3000.0, "CLASS_B": 2000.0 }, "price_by_security": { "CLASS_A": 600.0, "CLASS_B": 400.0 }, "max_annual_addition": 69000.0 }, "outputs": { "shares_allocated_by_security": { "CLASS_A": 130.4, "CLASS_B": 86.96 } }, "policy": "erisa_annual_addition_cap" } ``` *** ## Edge Cases If no employees meet eligibility criteria: * Step 3 exits early * Share pool **carries forward** to next year * No allocations made If all eligible employees have zero compensation: * Step 3 exits early * Division by zero avoided * Share pool carries forward In high-share-price scenarios: * Cap may limit ALL allocations * Causes **leftover shares** in pool * Leftover shares carry to next year via forfeitures Employees hired mid-year: * May not meet hours requirement * Excluded from allocation * Will be eligible next year if they meet criteria *** ## Related Steps Provides the shares to allocate Determines how much of allocation becomes vested Eligibility criteria and compliance rules Employee data structure *** ## Summary Step 3 is the **allocation engine** that: * ✅ Determines employee eligibility (age, service, hours) * ✅ Applies ERISA compensation cap (\$345K in 2025) * ✅ Distributes shares pro-rata by eligible compensation * ✅ Enforces annual addition cap (\$69K in 2025) * ✅ Supports multi-class securities with per-security tracking * ✅ Emits comprehensive compliance events **Key Insight:** ERISA caps can **significantly constrain** allocations for highly compensated employees and high-share-price companies, often causing shares to remain unallocated and carry forward to future years. # Step 4: Calculate Contribution Source: https://village-docs.villagelabs.com/simulation/step-4-contribution Determine annual company contribution ## Overview Based on `contribution_policy`, calculate the company's annual contribution. ## Policy Types * Fixed amount * Percentage of payroll * Discretionary formula * Loan payment-based See [Operating Assumptions](/models/operating-assumptions) for configuration details. # Step 5: Update Vesting Source: https://village-docs.villagelabs.com/simulation/step-5-vesting Calculate vested balances and potential forfeitures ## Overview Step 5 applies the plan's vesting schedule to determine what portion of each participant's account is **vested** (owned by the employee) versus **unvested** (subject to forfeiture if they terminate). Vesting is a **critical employee retention mechanism** that gradually transfers ownership of ESOP shares to participants based on years of service. ## Core Responsibilities Apply vesting schedule based on service years Calculate non-vested amounts subject to forfeiture Track vesting per security in multi-class mode Apply vesting to both shares and cash balances *** ## How Vesting Works ### Vesting Schedule Types Ownership increases gradually over time: ```python theme={null} vesting_schedule = { 1: 0.20, # 20% after 1 year 2: 0.40, # 40% after 2 years 3: 0.60, # 60% after 3 years 4: 0.80, # 80% after 4 years 5: 1.00 # 100% after 5 years } ``` **Example:** * Employee has 1,000 allocated shares * Service years: 3.5 years * Vesting: 60% (based on 3 years, rounded down) * **Vested:** 1,000 × 0.60 = 600 shares * **Unvested:** 1,000 × 0.40 = 400 shares (potential forfeiture) Full ownership after single milestone: ```python theme={null} vesting_schedule = { 1: 0.00, # 0% after 1 year 2: 0.00, # 0% after 2 years 3: 1.00 # 100% after 3 years (cliff) } ``` **Example:** * Employee A (2.9 years): 0% vested * Employee B (3.0 years): 100% vested One day can make the difference between 0% and 100% vested! Full ownership upon allocation (rare for ESOPs): ```python theme={null} vesting_schedule = { 0: 1.00 # 100% immediately } ``` All shares are vested the moment they're allocated. *** ## Processing Logic ### Single-Class Mode ```python theme={null} for employee in active_employees: # 1. Determine vesting percentage service_years_int = int(employee.service_years) # Round down: 3.9 → 3 if service_years_int in vesting_schedule: vesting_pct = vesting_schedule[service_years_int] else: # If beyond max schedule year, assume 100% vested max_year = max(vesting_schedule.keys()) vesting_pct = 1.0 if service_years_int > max_year else 0.0 # 2. Calculate total balances total_shares = ( employee.opening_shares + # Beginning balance employee.allocated_shares - # This year's allocation employee.diversified_shares # Minus diversification ) total_cash = ( employee.opening_cash + employee.allocated_cash - employee.diversified_cash ) # 3. Apply vesting employee.vested_shares = total_shares * vesting_pct employee.vested_cash = total_cash * vesting_pct # 4. Calculate potential forfeitures (if terminated) employee.potential_forfeitures = total_shares * (1 - vesting_pct) employee.potential_forfeitures_cash = total_cash * (1 - vesting_pct) ``` ### Multi-Class Mode Vesting is applied **per security**: ```python theme={null} for employee in active_employees: # Determine vesting % vesting_pct = get_vesting_percentage(employee.service_years) total_vested_shares = 0 total_potential_forfeitures = 0 # Apply to each security holding for security_id, holding in employee.holdings.items(): # Total shares in this security shares_in_security = holding.shares # Vested amount vested_in_security = shares_in_security * vesting_pct total_vested_shares += vested_in_security # Potential forfeitures forfeitures_in_security = shares_in_security * (1 - vesting_pct) total_potential_forfeitures += forfeitures_in_security # Set aggregate amounts employee.vested_shares = total_vested_shares employee.potential_forfeitures = total_potential_forfeitures # Cash vesting (aggregate, not per-security) total_cash = employee.opening_cash + employee.allocated_cash - employee.diversified_cash employee.vested_cash = total_cash * vesting_pct employee.potential_forfeitures_cash = total_cash * (1 - vesting_pct) ``` *** ## Vesting Examples **Scenario:** * Service years: 5.2 years * Vesting schedule: 100% at year 5 * Allocated shares: 1,000 * Opening shares: 4,000 * Total: 5,000 shares **Calculation:** * Vesting %: 100% * Vested shares: 5,000 × 1.0 = **5,000 shares** * Potential forfeitures: 5,000 × 0.0 = **0 shares** ✅ Employee owns entire account **Scenario:** * Service years: 2.8 years * Vesting schedule: 40% at year 2, 60% at year 3 * Allocated shares: 500 * Opening shares: 1,500 * Total: 2,000 shares **Calculation:** * Service (rounded): 2 years → 40% vested * Vested shares: 2,000 × 0.40 = **800 shares** * Potential forfeitures: 2,000 × 0.60 = **1,200 shares** ⚠️ If employee terminates, they forfeit 1,200 shares **Scenario:** * Service years: 0.9 years * Vesting schedule: 20% at year 1 * Allocated shares: 200 * Opening shares: 0 * Total: 200 shares **Calculation:** * Service (rounded): 0 years → 0% vested * Vested shares: 200 × 0.0 = **0 shares** * Potential forfeitures: 200 × 1.0 = **200 shares** ❌ If employee terminates, they get nothing **Scenario:** * Service years: 3.2 years → 60% vested * Holdings: * Class A: 800 shares * Class B: 1,200 shares * Total: 2,000 shares **Calculation:** **Class A:** * Vested: 800 × 0.60 = 480 shares * Forfeitures: 800 × 0.40 = 320 shares **Class B:** * Vested: 1,200 × 0.60 = 720 shares * Forfeitures: 1,200 × 0.40 = 480 shares **Aggregates:** * Total vested: 480 + 720 = **1,200 shares** * Total forfeitures: 320 + 480 = **800 shares** *** ## Cash Vesting **New in v0.2:** Cash balances are vested using the **same schedule** as shares. Participants may have cash from: * Company cash contributions * Diversification elections (converted from stock to cash) * Dividends or interest * Opening cash balances **Cash vesting mirrors share vesting:** ```python theme={null} total_cash = opening_cash + allocated_cash - diversified_cash vested_cash = total_cash * vesting_percentage potential_forfeitures_cash = total_cash * (1 - vesting_percentage) ``` **Example:** * Employee has \$10,000 cash in account * Service: 2 years → 40% vested * Vested cash: $10,000 × 0.40 = $4,000 * Potential forfeiture: $10,000 × 0.60 = $6,000 *** ## Potential Forfeitures **"Potential forfeitures"** are NOT actual forfeitures yet. They become **actual forfeitures** only if the employee terminates before becoming fully vested. ### When Forfeitures Occur Forfeitures are realized in **Step 7** when: 1. Employee terminates 2. Employee has `potential_forfeitures > 0` 3. Forfeiture policy is applied **The Flow:** * **Step 5:** Calculate `potential_forfeitures` * **Step 7:** If terminated → convert to `forfeited_shares` * **Step 2 (next year):** Reallocate forfeited shares ### Forfeiture vs. Vested | Metric | Vested | Unvested (Potential Forfeiture) | | ------------- | ------------------- | ------------------------------- | | Ownership | Employee owns | Company owns | | If terminated | Employee keeps | Company reclaims | | If continues | Stays with employee | May vest later | | Distribution | Must be distributed | Never distributed | *** ## Service Year Rounding Service years are **rounded down** (floor) to determine vesting schedule lookup. **Examples:** * 1.0 years → Lookup year 1 * 1.9 years → Lookup year 1 (not 2!) * 2.0 years → Lookup year 2 * 2.999 years → Lookup year 2 * 5.1 years → Lookup year 5 ```python theme={null} service_years_int = int(employee.service_years) # Floor function vesting_pct = vesting_schedule.get(service_years_int, default) ``` This protects the company from prematurely vesting employees who haven't yet completed a full service year. *** ## Data Flow ### Inputs ```python theme={null} { "vesting_schedule": { 1: 0.20, 2: 0.40, 3: 0.60, 4: 0.80, 5: 1.00 } } ``` ```python theme={null} { "employee_id": "EMP001", "service_years": 3.2, "opening_shares": 1500.0, # Beginning balance "allocated_shares": 500.0, # This year's allocation (from Step 3) "diversified_shares": 0.0, # Diversification (from Step 6) "opening_cash": 5000.0, "allocated_cash": 0.0, "diversified_cash": 0.0, "holdings": { # Multi-class mode "CLASS_A": {"shares": 1200.0}, "CLASS_B": {"shares": 800.0} } } ``` ### Outputs ```python theme={null} { "vested_shares": 1200.0, # 60% of 2,000 "vested_cash": 3000.0, # 60% of 5,000 "potential_forfeitures": 800.0, # 40% of 2,000 "potential_forfeitures_cash": 2000.0 # 40% of 5,000 } ``` Per employee: ```json theme={null} { "year": 2025, "phase": "vesting", "event": "vesting_updated", "entity_type": "employee", "entity_id": "EMP001", "details": { "vest_pct": 0.60, "vested_shares": 1200.0, "vested_cash": 3000.0, "potential_forfeitures": 800.0, "potential_forfeitures_cash": 2000.0 } } ``` *** ## Edge Cases If employee service exceeds the max year in vesting schedule: ```python theme={null} max_year = max(vesting_schedule.keys()) # e.g., 5 if service_years_int > max_year: vesting_pct = 1.0 # Assume 100% vested ``` **Example:** * Schedule ends at year 5 * Employee has 12 years service * Vesting: 100% (fully vested) If employee service is less than first schedule year: ```python theme={null} if service_years_int < min(vesting_schedule.keys()): vesting_pct = 0.0 # Not yet vested ``` **Example:** * Schedule starts at year 1 * Employee has 0.5 years service * Vesting: 0% (not vested) In rare cases, diversification or corrections might cause negative balance: ```python theme={null} total_shares = max(0, opening + allocated - diversified) ``` Prevents negative vesting calculations. Shares allocated this year are **immediately subject to vesting**: * Allocated in Step 3: 500 shares * Vesting in Step 5: 40% * Vested: 500 × 0.40 = 200 shares * Unvested: 500 × 0.60 = 300 shares New allocations don't get special treatment—same vesting % applies. *** ## Compliance Events Legacy compliance log format: ```json theme={null} { "year": 2025, "phase": "vesting", "event": "vesting_updated", "entity_type": "employee", "entity_id": "EMP042", "details": { "vest_pct": 0.80, "vested_shares": 4800.0, "vested_cash": 12000.0, "potential_forfeitures": 1200.0, "potential_forfeitures_cash": 3000.0 } } ``` Structured event format: ```json theme={null} { "year": 2025, "phase": "vesting", "event": "vesting_computed", "entity_type": "employee", "entity_id": "EMP042", "inputs": { "vesting_percent": 0.80 }, "outputs": { "vested_shares": 4800.0, "vested_cash": 12000.0, "potential_forfeitures": 1200.0, "potential_forfeitures_cash": 3000.0 } } ``` *** ## Related Steps Provides allocated shares that get vested Reduces share balance before vesting calculation Converts potential forfeitures to actual forfeitures Defines vesting schedule *** ## Vesting Strategy Considerations **Advantages:** * Gradual ownership transfer * Reduces forfeiture shock * Better retention over time * Employees see progress annually **Disadvantages:** * More complex to administer * Partial forfeitures common **Advantages:** * Simpler to administer * Strong retention at cliff point * Clear ownership threshold **Disadvantages:** * "All or nothing" can be demotivating * High forfeiture if employees leave before cliff * May violate DOL regulations if cliff > 3 years for ESOPs Some plans include **accelerated vesting** for: * Death * Disability * Retirement (age 65) * Plan termination * Change of control These triggers can override the normal vesting schedule and grant immediate 100% vesting. *** ## Summary Step 5 is the **vesting calculator** that: * ✅ Applies vesting schedule based on service years * ✅ Calculates vested shares and cash balances * ✅ Identifies potential forfeitures (unvested amounts) * ✅ Supports multi-class securities with per-security tracking * ✅ Handles edge cases (service beyond schedule, negative balances) * ✅ Emits compliance events for audit trail **Key Insight:** Vesting is a **powerful retention tool**. Employees who leave before fully vested forfeit unvested amounts, which are then reallocated to remaining participants—creating an incentive to stay with the company. Vesting calculations in Step 5 are **forward-looking** estimates. Actual forfeitures only occur in Step 7 if the employee terminates. # Step 6: Process Diversification Source: https://village-docs.villagelabs.com/simulation/step-6-diversification Handle statutory diversification elections ## Overview Process diversification elections from eligible participants (age 55+ with 10+ years of participation). ## Eligibility * Age 55+ * 10+ years of plan participation * Can diversify 25% of account * At age 60, can diversify up to 50% See [ESOP Basics](/concepts/esop-basics#diversification-rights) for more details. # Step 7: Process Repurchases Source: https://village-docs.villagelabs.com/simulation/step-7-repurchase Execute share repurchases, distribution schedules, and regulatory compliance ## Overview Step 7 is the **most complex step** in the ESOP projection engine, handling the full lifecycle of repurchase obligations from termination through final distribution. This step processes **9 distinct phases** including QDRO processing, distribution schedules, RMD enforcement, and multi-strategy repurchase execution. ## Why This Matters When employees terminate, the ESOP must: 1. Calculate what they're owed (vested shares + cash) 2. Create a payment schedule (deferred installments or lump sum) 3. Execute repurchases using available cash 4. Apply the company's chosen repurchase strategy This step determines the **cash flow impact** on the company and trust. *** ## Processing Phases Step 7 executes in strict sequential order: Handle divorce settlements and court orders Track non-vested share and cash forfeitures Build payment timelines for new terminations Force distributions for participants age 73+ Process scheduled distributions for current year Convert stock to cash if required by plan rules Removed in v0.3 to focus on core ESOP mechanics Apply recycle/redeem/releverage strategy Reconcile TrustCashLedger draws and balances *** ## Detailed Phase Breakdown ### Phase 1: QDRO Processing **QDRO** = Qualified Domestic Relations Order (divorce/separation settlements) When a divorce decree requires splitting an ESOP account: 1. **Apply Split Percentage** (typically 50%) 2. **Respect Vesting** - Only vested amounts are split 3. **Pro-Rata Across Securities** - In multi-class mode, split proportionally 4. **Reduce Participant Balance** - Deduct from employee account 5. **Create Immediate Repurchase** - Alternate payee is paid immediately 6. **Mark as Processed** - Prevent reprocessing in future years ```python theme={null} # Example QDRO processing for employee in active_employees: if employee.qdro_orders: for order in employee.qdro_orders: if not order.processed_this_year: # Determine vesting vesting_pct = vesting_schedule[employee.service_years] # Apply split (e.g., 50%) split_pct = order.percent # 0.50 for 50% # For each security holding for security_id, holding in employee.holdings: vested_shares = holding.shares * vesting_pct split_shares = vested_shares * split_pct # Reduce employee, add to repurchase holding.shares -= split_shares repurchase_queue[security_id] += split_shares # Mark processed order.processed_year = current_year ``` In multi-class mode, QDROs split proportionally across all securities: **Example:** * Employee holds: 100 Class A shares, 200 Class B shares * Vesting: 80% * QDRO: 50% split **Calculation:** * Class A vested: 100 \* 0.80 = 80 shares * Class A split: 80 \* 0.50 = 40 shares → to alternate payee * Class B vested: 200 \* 0.80 = 160 shares * Class B split: 160 \* 0.50 = 80 shares → to alternate payee Every QDRO generates compliance events: ```json theme={null} { "event": "qdro_processed", "employee_id": "EMP042", "percent": 0.50, "shares_by_security": { "CLASS_A": 40.0, "CLASS_B": 80.0 }, "cash_paid": 2500.00 } ``` *** ### Phase 2: Forfeiture Recording When participants terminate **before fully vested**, non-vested amounts are forfeited. **Two policy options:** 1. **`reallocate_next_year`** (Most Common) * Add forfeitures to next year's share pool * Used to fund next year's allocations * Reduces company cash contribution need 2. **`reallocate_on_payout`** (Less Common) * Hold forfeitures until employee fully paid out * Then reallocate to remaining participants * Used when plan wants to delay forfeiture recognition ```python theme={null} if forfeiture_policy == "reallocate_next_year": carry_over_state.forfeited_shares_for_next_year += forfeited_amount carry_over_state.forfeited_cash_for_next_year += forfeited_cash elif forfeiture_policy == "reallocate_on_payout": carry_over_state.forfeited_shares_from_payout[employee_id] = forfeited_amount carry_over_state.forfeited_cash_from_payout[employee_id] = forfeited_cash ``` **Scenario:** * Employee termination: Service years = 1.0 * Vesting schedule: Year 1 = 20%, Year 5 = 100% * Employee has: 1,000 allocated shares, \$5,000 cash **Vesting:** * Vested: 1,000 × 20% = 200 shares, \$1,000 cash * Forfeited: 1,000 × 80% = 800 shares, \$4,000 cash **If `reallocate_next_year`:** ``` carry_over_state.forfeited_shares_for_next_year += 800 carry_over_state.forfeited_cash_for_next_year += 4000 ``` In Step 2 of next year, these 800 shares will be added to the share pool for allocation. **New in v0.2:** Cash forfeitures mirror share forfeiture policy. Participants may have cash balances from: * Previous diversification elections * Cash contributions from the company * Dividends or interest **Non-vested cash is forfeited using the same policy:** * `reallocate_next_year`: Cash added to next year's contribution * `reallocate_on_payout`: Cash held until final payout *** ### Phase 3: Distribution Schedule Creation When an employee terminates, the engine creates a **multi-year payment schedule**. From `DistributionRule` matched to termination trigger: ```python theme={null} { "trigger": "retirement", # or "death", "disability", "termination" "payment_years": 5, # Installment period "defer_years": 1, # Wait period before first payment "lump_sum_threshold": 5000, # Force lump sum if account < this "installment_frequency": "annual", # or "quarterly", "monthly" "distribution_form": "cash" # or "stock", "stock_with_mandatory_put" } ``` **Regulatory Timing Caps:** | Termination Type | Max Deferral | IRS Rule | | ------------------- | ------------ | --------------- | | Retirement | 1 year | IRC §409(o) | | Death | 1 year | IRC §409(o) | | Disability | 1 year | IRC §409(o) | | Other Termination | 5 years | IRC §409(o) | | Age 65+ & 10+ years | 1 year | IRC §401(a)(14) | **Leveraged ESOP Deferral (Optional):** * IF policy enabled AND loan outstanding * THEN defer start\_year to loan maturity * Protects company cash flow during debt service ```python theme={null} if leveraged_deferral_enabled: latest_loan_maturity = max(loan.maturity_year for loan in loans) if latest_loan_maturity > start_year: start_year = latest_loan_maturity # Push out payment ``` **Small Balance Cashout:** * If vested value ≤ lump\_sum\_threshold (e.g., \$5,000) * Force immediate lump sum payment * Reduces administrative burden ```python theme={null} vested_value = (vested_shares * share_price) + vested_cash if vested_value <= lump_sum_threshold: payment_years = 1 defer_years = 0 start_year = current_year # Immediate ``` **Large Balance Extension:** * If vested value > large\_balance\_threshold (e.g., \$1M) * Add extra installment years * Each increment adds 1 year (up to max) ```python theme={null} if vested_value > large_balance_threshold: increments = (vested_value - threshold) // increment payment_years = min(payment_years + increments, max_installment_years) ``` **Scenario:** Retirement in 2025, \$250,000 vested value ```json theme={null} { "trigger": "retirement", "start_year": 2026, // Year after termination (1-year defer) "years_total": 5, // 5 annual payments "years_paid": 0, // None paid yet "annual_shares": 100, // 100 shares/year "annual_cash": 10000, // $10K cash/year "remaining_shares": 500, // Total to pay "remaining_cash": 50000, // Total to pay "installment_frequency": "annual" } ``` **Payment Timeline:** * 2026: 100 shares + \$10K * 2027: 100 shares + \$10K * 2028: 100 shares + \$10K * 2029: 100 shares + \$10K * 2030: 100 shares + \$10K *** ### Phase 4: RMD Enforcement **RMD** = Required Minimum Distribution (IRS tax rule) Participants **age 73+** must begin receiving distributions, regardless of employment status or deferral preferences. ```python theme={null} RMD_AGE = 73 # As of 2025 (was 72 pre-SECURE Act 2.0) for employee in active_employees: if employee.age >= RMD_AGE: # Check if already has active schedule has_due_schedule = any( sched for sched in employee.pending_distributions if sched.start_year <= current_year ) # If no schedule and has balance, force immediate distribution if not has_due_schedule and (employee.vested_shares > 0 or employee.vested_cash > 0): # Create immediate schedule employee.pending_distributions.append({ "trigger": "rmd", "start_year": current_year, # Immediate "years_total": 1, "annual_shares": employee.vested_shares, "annual_cash": employee.vested_cash, "remaining_shares": employee.vested_shares, "remaining_cash": employee.vested_cash }) ``` **Scenario 1: Active Employee, Age 73** * Still working, no termination * RMD forces distribution of vested balance * Employee remains active, continues accruing **Scenario 2: Terminated with Deferred Schedule** * Terminated at age 65, distribution deferred to 2028 * Reaches age 73 in 2026 * RMD **overrides** deferral, forces payment in 2026 **Scenario 3: Already Receiving Distributions** * RMD check passes (already compliant) * No additional action needed ```json theme={null} { "event": "rmd_schedule_created", "employee_id": "EMP105", "age": 73, "start_year": 2025, "reason": "Regulatory requirement - age 73 reached" } ``` *** ### Phase 5: Execute Due Payments Process all distribution schedules where `current_year >= start_year`. ```python theme={null} for employee in active_employees: for schedule in employee.pending_distributions: # Check if payment due if current_year >= schedule.start_year or employee.age >= RMD_AGE: if schedule.years_paid < schedule.years_total: # Calculate this year's payment payment_shares = min( schedule.annual_shares, schedule.remaining_shares ) payment_cash = min( schedule.annual_cash, schedule.remaining_cash ) # Update schedule schedule.remaining_shares -= payment_shares schedule.remaining_cash -= payment_cash schedule.years_paid += 1 # Add to repurchase queue total_shares_to_repurchase += payment_shares total_payment_value += (payment_shares * share_price) + payment_cash ``` In multi-class mode, payments are distributed **pro-rata across securities**: **Example:** * Employee holds: 80 Class A, 120 Class B (total 200 shares) * Payment due: 50 shares **Pro-Rata Calculation:** * Class A weight: 80 / 200 = 40% * Class B weight: 120 / 200 = 60% **Distribution:** * Class A: 50 × 40% = 20 shares * Class B: 50 × 60% = 30 shares ```python theme={null} total_shares = sum(holding.shares for holding in employee.holdings) for security_id, holding in employee.holdings.items(): weight = holding.shares / total_shares quantity = payment_shares * weight quantity = round(quantity, 4) # Precision rounding # Deduct from employee, add to repurchase holding.shares -= quantity repurchase_by_security[security_id] += quantity ``` Cash payments are funded via the Funding Waterfall using the `TrustCashLedger`: ```python theme={null} if payment_cash > 0: result = trust.cash_ledger.draw_cash( amount=payment_cash, sources=plan_rules.cash_usage_policy ) # result.transactions lists per-source draws; result.shortfall if any ``` See [TrustCashLedger](/models/trust-cash-ledger) for ledger structure and draw behavior. *** ### Phase 6: Distribution Form Conversion If the plan requires **cash-only distributions**, convert remaining stock to cash. Three options per plan rules: 1. **`stock`** - Distribute shares as shares 2. **`cash`** - Convert all shares to cash at current price 3. **`stock_with_mandatory_put`** - Distribute shares with put option (treated as cash in modeling) ```python theme={null} distribution_rule = get_distribution_rule(employee.termination_reason) if distribution_rule.distribution_form == "cash": if employee.remaining_payout_shares > 0: # Convert shares to cash value cash_value = employee.remaining_payout_shares * current_share_price # Update employee account employee.remaining_payout_cash += cash_value employee.remaining_payout_shares = 0 # Add shares to repurchase queue total_shares_to_repurchase += employee.remaining_payout_shares ``` In multi-class mode, convert each security holding: ```python theme={null} for security_id, holding in employee.holdings.items(): security_price = securities[security_id].current_share_price cash_value = holding.shares * security_price employee.vested_cash += cash_value repurchase_by_security[security_id] += holding.shares holding.shares = 0 # Fully converted ``` *** ### Phase 7: (Deprecated) Segregation Policy Segregation is removed in v0.3 to focus on core, high-fidelity ESOP mechanics. The model no longer documents or enforces `segregation_policy`. *** ### Phase 8: Execute Repurchase Strategy The company's **strategic choice** for handling repurchased shares. **Keep shares in the plan** * Add to next year's allocation pool * Shares remain outstanding * Use OIA cash if available * Most cash-efficient **Retire shares permanently** * Reduce outstanding shares * Increases ownership % for remaining participants * Shares cannot be reissued **Create new ESOP loan** * Borrow to fund repurchase * Default term: 10 years * Shares held in suspense * Released as loan paid down **Single Strategy per Year:** ```python theme={null} repurchase_strategy = { 2025: "recycle", 2026: "redeem", 2027: "releverage" } ``` **Weighted Combination:** ```python theme={null} repurchase_strategy = { 2025: { "recycle": 0.60, # 60% recycled "redeem": 0.30, # 30% redeemed "releverage": 0.10 # 10% refinanced } } ``` Weights are normalized if they don't sum to 1.0. **For Weighted Strategy:** ```python theme={null} if isinstance(strategy, dict): # Normalize weights total_weight = sum(strategy.values()) weights = {k: v / total_weight for k, v in strategy.items()} # Apply each strategy for strategy_name, weight in weights.items(): quantity = total_shares_to_repurchase * weight if strategy_name == "recycle": carry_over_state.recycled_shares += quantity # Funding is handled via TrustCashLedger waterfall elif strategy_name == "redeem": company_state.total_outstanding_shares -= quantity elif strategy_name == "releverage": loan_amount = quantity * share_price new_loan = ESOPLoan( loan_id=f"LOAN_{current_year}", original_amount=loan_amount, remaining_balance=loan_amount, annual_payment=loan_amount / 10, # 10-year term shares_released_per_payment=quantity / 10, maturity_year=current_year + 10 ) company_state.loans.append(new_loan) ``` In multi-class mode, strategy is applied **per security**: ```python theme={null} # Example: 60% recycle, 40% redeem for security_id, shares_to_repurchase in repurchase_by_security.items(): # Recycle 60% recycle_qty = shares_to_repurchase * 0.60 carry_over_state.recycled_shares_by_security[security_id] += recycle_qty # Redeem 40% redeem_qty = shares_to_repurchase * 0.40 securities[security_id].total_outstanding_shares -= redeem_qty ``` Each security maintains its own: * Outstanding share count * Recycled share pool * Releverage loans (tagged to security) **Scenario 1: Pure Recycle** * Shares to repurchase: 1,000 * Strategy: `"recycle"` * Result: 1,000 shares added to next year's pool * Outstanding shares: No change **Scenario 2: Pure Redeem** * Shares to repurchase: 1,000 * Strategy: `"redeem"` * Result: Total outstanding shares reduced by 1,000 * Remaining participants' ownership % increases **Scenario 3: Weighted Mix** * Shares to repurchase: 1,000 * Strategy: `{"recycle": 0.7, "redeem": 0.3}` * Result: 700 shares recycled, 300 shares redeemed *** ### Phase 9: Funding Reconciliation Final accounting for the year's cash flows. Reconcile TrustCashLedger movements for the year (no investment earnings in v0.3): ```python theme={null} ledger_summary = { "boy": trust.cash_ledger_snapshot_boy, "draws": result.transactions, # from distributions and repurchases "deposits": company_contributions, "transfers": internal_transfers, "eoy": trust.cash_ledger_snapshot_eoy } ``` Aggregate all loan payments made during the year: ```python theme={null} # Scan compliance events for loan payments principal_paid = 0 interest_paid = 0 for event in compliance_log: if event.event == "loan_payment_made" and event.year == current_year: principal_paid += event.outputs["principal"] interest_paid += event.outputs["interest"] # Track OIA usage total_debt_service = principal_paid + interest_paid carry_over_state.oia_uses_loan_payments += total_debt_service # Deduct from OIA if available if oia_balance >= total_debt_service: oia_balance -= total_debt_service ``` At the end of Step 7, emit comprehensive funding summary: ```json theme={null} { "phase": "repurchase", "event": "repurchase_funding_summary", "inputs": { "shares_to_repurchase": 850.0, "payment_value": 425000.00, "share_price": 500.00 }, "outputs": { "recycled_shares": 510.0, "outstanding_shares": 99150.0, "ledger": { "participant_cash_accounts": 125000.00, "unallocated_company_contributions": 200000.00, "unallocated_forfeiture_cash": 50000.00 } } } ``` This summary provides complete audit trail for cash flow analysis. *** ## Multi-Class Security Support **New in v0.2:** Full multi-class security support with per-security tracking. When `multi_class_mode=True` and `securities` exist: ### Key Differences | Aspect | Single-Class | Multi-Class | | -------------------- | --------------- | ------------------------ | | **Share Tracking** | Aggregate total | Per-security holdings | | **Pricing** | Single price | Security-specific prices | | **Pro-Rata Logic** | N/A | Weighted by holdings | | **Repurchase** | Single queue | Per-security queues | | **Recycled Pool** | Single pool | Per-security pools | | **Releverage Loans** | Generic loan | Security-tagged loans | ### Example: Pro-Rata Distribution ```python theme={null} # Employee has mixed holdings employee.holdings = { "CLASS_A": Holding(shares=100, vested=True), "CLASS_B": Holding(shares=200, vested=True) } # Total: 300 shares # Payment due: 75 shares # Pro-rata calculation total_shares = 300 weight_A = 100 / 300 = 0.333 weight_B = 200 / 300 = 0.667 # Distribute payment_A = 75 * 0.333 = 25 shares payment_B = 75 * 0.667 = 50 shares # Value calculation (different prices) price_A = 500.00 price_B = 450.00 value_A = 25 * 500 = $12,500 value_B = 50 * 450 = $22,500 total_value = $35,000 ``` ### Security-Specific Repurchase ```python theme={null} # Repurchase tracking by security repurchase_by_security = { "CLASS_A": 125.0, "CLASS_B": 250.0 } # Strategy: 60% recycle, 40% redeem for security_id, quantity in repurchase_by_security.items(): recycle_qty = quantity * 0.60 redeem_qty = quantity * 0.40 # Update security-specific pools carry_over_state.recycled_shares_by_security[security_id] += recycle_qty securities[security_id].total_outstanding_shares -= redeem_qty ``` *** ## Configuration Reference Key configuration parameters used in Step 7: ```python theme={null} regulatory_limits = { "rmd_age": 73 # Age when distributions must begin (IRS requirement) } ``` ```python theme={null} distribution_timing_rules = { "retirement_death_disability": { "termination_types": ["retirement", "death", "disability"], "max_deferral_years": 1 # Must start within 1 year }, "termination": { "termination_types": ["termination"], "max_deferral_years": 5 # Can defer up to 5 years }, "latest_commencement": { "min_age": 65, "min_service_years": 10, "max_deferral_years": 1 # Age 65+ with 10+ years: max 1 year defer } } ``` ```python theme={null} default_loan_terms = { "releverage_years": 10 # Default term for releverage loans } ``` ```python theme={null} default_rates = { "oia_yield_rate": 0.03 # 3% annual yield on OIA balance } ``` ```python theme={null} calculation_precision = { "precision_string": "0.0001" # Round to 4 decimal places } ``` ```python theme={null} account_thresholds = { "division_by_zero_default": 1 # Denominator default when total_shares = 0 } ``` *** ## The Funding Waterfall See [Simulation Core](/architecture/simulation-core#funding-waterfall) for complete waterfall explanation. **Quick Summary:** ```python theme={null} cash_usage_policy = [ "unallocated_company_contributions", # 1st priority "unallocated_forfeiture_cash", # 2nd priority "participant_cash_accounts" # 3rd priority ] # Draw cash in specified order for source in cash_usage_policy: if remaining_need > 0: available = trust_cash_ledger[source] amount_to_use = min(available, remaining_need) trust_cash_ledger[source] -= amount_to_use remaining_need -= amount_to_use ``` *** ## Common Scenarios **Setup:** * Employee retires, age 65, 15 years service * Vested: 2,000 shares at $500/share = $1M * Distribution rule: 5-year installment, 1-year defer * Repurchase strategy: 100% recycle **Processing:** 1. **Phase 3:** Create schedule starting 2026, 5 annual payments of 400 shares each 2. **Phase 5:** In 2026, pay first installment of 400 shares 3. **Phase 8:** Recycle 400 shares → added to 2027 allocation pool **Result:** * Employee receives 400 shares in 2026 (valued at current price) * Trust repurchases and recycles shares * Company has 400 shares for next year's allocation **Setup:** * Active employee, age 42, divorce decree * QDRO: 50% split to ex-spouse * Account: 1,500 vested shares, \$25K cash * Repurchase strategy: 100% redeem **Processing:** 1. **Phase 1:** Process QDRO * Split: 750 shares + \$12,500 to ex-spouse * Employee retains: 750 shares + \$12,500 * Immediate payout to ex-spouse 2. **Phase 8:** Redeem 750 shares * Outstanding shares reduced by 750 **Result:** * Ex-spouse paid immediately * Employee continues with reduced account * Company ownership percentages recalculated **Setup:** * Employee terminated at age 68 in 2020 * Distribution deferred to 2025 (5-year max) * Employee reaches age 73 in 2023 * Vested balance: 1,200 shares **Processing:** 1. **Phase 4:** In 2023, RMD check triggers * Age 73 reached, no active distribution * Create immediate RMD schedule 2. **Phase 5:** Force distribution in 2023 (overrides 2025 deferral) **Result:** * Distribution starts in 2023 instead of 2025 * Ensures IRS compliance * Prevents tax penalties **Setup:** * Total repurchase: 3,000 shares * Strategy: 60% recycle, 30% redeem, 10% releverage * Share price: \$500 **Processing:** 1. **Phase 8:** Apply weighted strategy * Recycle: 3,000 × 60% = 1,800 shares * Redeem: 3,000 × 30% = 900 shares * Releverage: 3,000 × 10% = 300 shares **Recycle:** * Add 1,800 shares to next year's pool * Use OIA: \$900K if available **Redeem:** * Reduce outstanding shares by 900 **Releverage:** * Create loan: $150K (300 shares × $500) * Term: 10 years * Annual release: 30 shares/year **Result:** * Mixed strategy provides flexibility * 1,800 shares available for reallocation * 900 shares permanently retired * 300 shares financed via new loan **Setup:** * Employee holds: 500 Class A ($600/share), 1,000 Class B ($400/share) * Payment due: 300 shares total * Strategy: 100% recycle **Processing:** 1. **Phase 5:** Pro-rata distribution * Total shares: 1,500 * Class A weight: 500 / 1,500 = 33.3% * Class B weight: 1,000 / 1,500 = 66.7% **Payment:** * Class A: 300 × 33.3% = 100 shares → value \$60K * Class B: 300 × 66.7% = 200 shares → value \$80K * Total value: \$140K 2. **Phase 8:** Security-specific recycle * Class A: Add 100 to recycled\_shares\_by\_security\["CLASS\_A"] * Class B: Add 200 to recycled\_shares\_by\_security\["CLASS\_B"] **Result:** * Each security maintains separate recycled pools * Next year's allocation can draw from both pools * Preserves security mix in the plan *** ## Data Dependencies ### Inputs Required ```python theme={null} { "employee_id": "EMP042", "age": 65, "service_years": 15.5, "termination_date": "2025-06-30", "termination_reason": "retirement", "vested_shares": 2000.0, "vested_cash": 50000.0, "potential_forfeitures": 0.0, "holdings": { # Multi-class mode "CLASS_A": {"shares": 1200, "vested": True}, "CLASS_B": {"shares": 800, "vested": True} }, "qdro_orders": [ {"percent": 0.50, "processed_year": null} ], "pending_distributions": [] # Schedules created in Phase 3 } ``` ```python theme={null} { "current_share_price": 500.00, "total_outstanding_shares": 100000.0, "oia_balance": 250000.0, "loans": [ { "loan_id": "LOAN_2020", "principal_balance": 2000000.0, "maturity_year": 2028, ... } ], "securities": { # Multi-class mode "CLASS_A": { "security_id": "CLASS_A", "current_share_price": 600.00, "total_outstanding_shares": 60000.0 }, "CLASS_B": { "security_id": "CLASS_B", "current_share_price": 400.00, "total_outstanding_shares": 40000.0 } } } ``` ```python theme={null} { "vesting_schedule": { 1: 0.20, 2: 0.40, 3: 0.60, 4: 0.80, 5: 1.00 }, "distribution_rules": [ { "trigger": "retirement", "payment_years": 5, "defer_years": 1, "lump_sum_threshold": 5000, "large_balance_threshold": 1000000, "large_balance_increment": 250000, "max_installment_years": 10, "installment_frequency": "annual", "distribution_form": "cash" } ] } ``` ```python theme={null} { "forfeiture_policy": "reallocate_next_year", "repurchase_strategy": { 2025: {"recycle": 0.60, "redeem": 0.40} }, "segregation_policy": "on_termination", "distribution_policy": { "leveraged_deferral": True # Defer to loan maturity }, "releverage_years": 10 # Term for releverage loans } ``` ### Outputs Generated ```python theme={null} { "pending_distributions": [ { "trigger": "retirement", "start_year": 2026, "years_total": 5, "years_paid": 1, "annual_shares": 400.0, "remaining_shares": 1600.0, ... } ], "remaining_payout_shares": 1600.0, "remaining_payout_cash": 40000.0, "forfeited_shares": 0.0, "holdings": { # Updated after payment "CLASS_A": {"shares": 1120}, # Reduced by 80 "CLASS_B": {"shares": 680} # Reduced by 120 } } ``` ```python theme={null} { "total_outstanding_shares": 99600.0, # After redemptions "oia_balance": 175000.0, # After uses and earnings "loans": [ ... existing loans ..., { # New releverage loan "loan_id": "LOAN_2025_CLASS_A", "original_amount": 60000.0, "remaining_balance": 60000.0, "annual_payment": 6000.0, "shares_released_per_payment": 10.0, "maturity_year": 2035, "security_id": "CLASS_A" } ], "securities": { "CLASS_A": { "total_outstanding_shares": 59800.0 # After redemptions } } } ``` ```python theme={null} { "recycled_shares": 1200.0, "recycled_shares_by_security": { "CLASS_A": 720.0, "CLASS_B": 480.0 }, "forfeited_shares_for_next_year": 150.0, "forfeited_cash_for_next_year": 7500.0, "oia_uses_distributions": 50000.0, "oia_uses_repurchase": 360000.0, "oia_uses_loan_payments": 120000.0, "oia_earnings": 5250.0 } ``` ```json theme={null} [ { "year": 2025, "phase": "distribution", "event": "distribution_schedule_created", "entity_type": "employee", "entity_id": "EMP042", "inputs": { "vested_shares": 2000.0, "payment_years": 5, "defer_years": 1, "trigger": "retirement" }, "outputs": { "start_year": 2026, "annual_shares": 400.0, "annual_cash": 10000.0 } }, { "year": 2025, "phase": "repurchase", "event": "repurchase_executed_weighted", "entity_type": "company", "inputs": { "strategy_weights": {"recycle": 0.60, "redeem": 0.40}, "shares_to_repurchase_by_security": { "CLASS_A": 200.0, "CLASS_B": 200.0 } }, "outputs": { "recycled_by_security": { "CLASS_A": 120.0, "CLASS_B": 120.0 }, "outstanding_shares_after": 99600.0, "oia_balance": 175000.0 } } ] ``` *** ## Performance Considerations Step 7 is **computationally intensive** due to multiple passes over employee list and complex pro-rata calculations. **Optimization Strategies:** 1. **Index by Termination Status** * Pre-filter terminated employees * Avoid scanning full census each phase 2. **Cache Vesting Calculations** * Vesting percentages calculated multiple times * Cache lookups by service year 3. **Precision Rounding** * Apply rounding at calculation boundaries * Use `Decimal` for financial amounts * Avoid floating-point arithmetic 4. **Multi-Class Overhead** * Pro-rata calculations scale with # securities * Consider performance impact with 5+ securities *** ## Testing Scenarios From `tests/engine/test_engine_step7.py`: 1. **Recycle accumulates recycled shares** * Strategy: `"recycle"` * Verify: `carry_over_state.recycled_shares > 0` 2. **Redeem reduces outstanding shares** * Strategy: `"redeem"` * Verify: `total_outstanding_shares` decreased 3. **Cash forfeitures tracked** * Service: 1 year (20% vested) * Opening cash: \$1,000 * Verify: 80% forfeited to carryover 4. **Reallocate on payout defers forfeiture** * Policy: `"reallocate_on_payout"` * Verify: Forfeitures held until payout complete 5. **Multi-year distribution schedule** * Payment years: 3 * Verify: Payments spread across years 6. **RMD enforcement** * Age: 73 * Verify: Immediate distribution created 7. **Leveraged deferral** * Loan maturity: 2030 * Termination: 2025 * Verify: Start year pushed to 2030 8. **Zero balance protection** * Total shares = 0 * Verify: No divide-by-zero errors 9. **Small balance cashout** * Vested value: \$4,000 * Threshold: \$5,000 * Verify: Lump sum forced 10. **Missing configuration fallbacks** * No RMD age specified * Verify: Defaults to 73 *** ## Related Documentation Ledger structure and cash flow management Why Step 7 is structured this way How Step 7 fits into the annual cycle Releverage loan creation and tracking *** ## Summary Step 7 is the **most complex and critical** step in the ESOP projection engine: **Key Responsibilities:** * ✅ QDRO processing (divorce settlements) * ✅ Forfeiture tracking (non-vested amounts) * ✅ Distribution schedule creation (multi-year installments) * ✅ RMD enforcement (age 73+ compliance) * ✅ Payment execution (scheduled distributions) * ✅ Distribution form conversion (stock → cash) * ❌ Segregation policy (removed in v0.3) * ✅ Repurchase strategy execution (recycle/redeem/releverage) * ✅ Funding reconciliation (TrustCashLedger balances) **Complexity Factors:** * 9 sequential phases * Multi-class security support * Pro-rata calculations across securities * Regulatory compliance checks * Multi-year distribution schedules * Weighted strategy execution * Comprehensive event logging **Performance Profile:** * Most expensive step (1,130 lines of code) * Multiple passes over employee list * Pro-rata calculations scale with # securities * Precision rounding for financial accuracy **For Developers:** Step 7 processes are highly interdependent. Changing one phase may affect downstream phases. Always run full test suite after modifications. # Step 8: Year-End Closing Source: https://village-docs.villagelabs.com/simulation/step-8-year-end Finalize annual results, evolve employee data, and prepare for next year ## Overview Step 8 is the **final step** in the annual processing cycle. It rolls account balances forward, applies yearly evolution to employee data (age, service, compensation), and captures the complete year's results. This step transforms **in-progress allocations** into **opening balances** for the next year and advances the simulation forward in time. ## Core Responsibilities Move allocated/diversified amounts to opening balances Age employees by 1 year, grow compensation, increment service Clean up fully distributed accounts Store year-end snapshots and KPIs *** ## Processing Phases ### Phase 1: Roll Balances Forward For **active employees** (not terminated), consolidate the year's activity: ```python theme={null} for employee in active_employees: if not employee.termination_date: # Active employees only # Roll shares forward employee.opening_shares = ( employee.opening_shares + # What they started with employee.allocated_shares - # Plus this year's allocation employee.diversified_shares # Minus diversification ) # Roll cash forward employee.opening_cash = ( employee.opening_cash + employee.allocated_cash - employee.diversified_cash ) # Reset annual accumulators employee.allocated_shares = 0 employee.allocated_cash = 0 ``` **Example:** | Field | Beginning | Step 3 Allocation | Step 6 Diversification | Year-End | | -------------------- | --------- | ----------------- | ---------------------- | ------------- | | `opening_shares` | 1,500 | N/A | N/A | **2,000** | | `allocated_shares` | 0 | +500 | N/A | **0** (reset) | | `diversified_shares` | 0 | N/A | 0 | 0 | **Result:** Employee starts next year with 2,000 opening shares. **Terminated employees** do NOT roll balances—their accounts are frozen and distributions are handled via `pending_distributions` in Step 7. *** ### Phase 2: Identify Fully Paid-Out Participants Participants who have received all scheduled distributions are marked for removal: ```python theme={null} fully_paid_out_threshold = 0.01 # e.g., $0.01 or 0.01 shares for employee in active_employees: if employee.termination_date: # Only check terminated employees if (employee.remaining_payout_shares < threshold AND employee.remaining_payout_cash < threshold): employee.is_fully_paid_out = True ``` **Cleanup:** At the end of Step 8, fully paid-out employees are **removed from the active list** to improve performance in future years. ```python theme={null} active_employee_list.remove_fully_paid_out() ``` **Example:** * Employee terminated in 2020 * 5-year distribution schedule completed in 2025 * Remaining payout: \$0.00 * **Result:** Removed from active list after 2025 Removing fully paid-out participants keeps the simulation efficient. They're preserved in historical snapshots but don't participate in future processing. *** ### Phase 3: Capture Annual Results Create a comprehensive year-end snapshot: ```python theme={null} annual_results[year] = YearResult( year=year, share_price=current_share_price, total_shares_allocated=sum(emp.allocated_shares for emp in active), total_cash_allocated=sum(emp.allocated_cash for emp in active), total_forfeitures=..., # Aggregated from Step 7 total_distributions=..., # Aggregated from Step 7 participant_count=len([emp for emp in active if not emp.termination_date]), compliance_events=[...] # All events from this year ) ``` **Included Metrics:** * ✅ Share price at year-end * ✅ Total shares allocated this year * ✅ Total cash allocated * ✅ Forfeitures captured * ✅ Distributions paid * ✅ Active participant count * ✅ All compliance events (audit trail) *** ### Phase 4: Apply Yearly Evolution For **remaining active employees**, advance time by one year: ```python theme={null} for employee in active_employees: employee.age = employee.age + 1 ``` **Example:** * Beginning: Age 35 * End: Age 36 This affects eligibility for diversification (age 55+) and RMD (age 73+). ```python theme={null} for employee in active_employees: employee.service_years = employee.service_years + 1.0 ``` **Example:** * Beginning: 3.5 years service * End: 4.5 years service This affects vesting percentage in Step 5 of next year. ```python theme={null} comp_growth_rate = financial_assumptions["combined_comp_growth_rate"] # e.g., 0.03 for 3% for employee in active_employees: employee.compensation = employee.compensation * (1 + comp_growth_rate) ``` **Example:** * Beginning: \$100,000 * Growth: 3% * End: $100,000 * 1.03 = **$103,000\*\* This affects pro-rata allocation in Step 3 of next year. Each employee evolution emits an event: ```json theme={null} { "year": 2025, "phase": "year_end", "event": "yearly_evolution_applied", "entity_type": "employee", "entity_id": "EMP001", "inputs": { "prev_age": 35, "prev_service_years": 3.5, "prev_compensation": 100000.0, "comp_growth_rate": 0.03 }, "outputs": { "age": 36, "service_years": 4.5, "compensation": 103000.0 } } ``` **Timing:** Yearly evolution happens **at year-end** (Step 8), not at the beginning (Step 1). This means that all processing for year N uses the employee data from the **beginning** of year N, and evolution is applied only after all steps complete. *** ### Phase 5: TrustCashLedger Reconciliation Emit a complete reconciliation of the **TrustCashLedger** (no investment earnings in v0.3): ```python theme={null} ledger_summary = { "boy": { "participant_cash_accounts": 150_000, "unallocated_company_contributions": 50_000, "unallocated_forfeiture_cash": 25_000 }, "deposits": { "unallocated_company_contributions": 500_000 }, "draws": [ {"source": "unallocated_company_contributions", "amount": 200_000}, {"source": "unallocated_forfeiture_cash", "amount": 100_000}, {"source": "participant_cash_accounts", "amount": 50_000} ], "transfers": [ {"from": "unallocated_forfeiture_cash", "to": "participant_cash_accounts", "amount": 25_000} ], "eoy": { "participant_cash_accounts": 200_000, "unallocated_company_contributions": 200_000, "unallocated_forfeiture_cash": 0 } } ``` **Formula:** ``` EOY per source = BOY + Deposits - Draws + Transfers(net) ``` After emitting the summary, **reset any year-accumulators** for next year. *** ## Data Flow ### Inputs ```python theme={null} { "employee_id": "EMP001", "age": 35, "service_years": 3.5, "compensation": 100000.0, "opening_shares": 1500.0, "allocated_shares": 500.0, "diversified_shares": 0.0, "opening_cash": 5000.0, "allocated_cash": 0.0, "diversified_cash": 0.0, "termination_date": null } ``` ```python theme={null} { "combined_comp_growth_rate": 0.03 # 3% annual pay increase } ``` ```python theme={null} { "ledger_boy": { "participant_cash_accounts": 150000.0, "unallocated_company_contributions": 50000.0, "unallocated_forfeiture_cash": 25000.0 } } ``` ### Outputs ```python theme={null} { "employee_id": "EMP001", "age": 36, # +1 year "service_years": 4.5, # +1 year "compensation": 103000.0, # Grown by 3% "opening_shares": 2000.0, # Rolled forward "allocated_shares": 0.0, # Reset "diversified_shares": 0.0, "opening_cash": 5000.0, # Rolled forward "allocated_cash": 0.0, # Reset "diversified_cash": 0.0 } ``` ```python theme={null} { "year": 2025, "share_price": 525.00, "total_shares_allocated": 45000.0, "total_cash_allocated": 0.0, "total_forfeitures": 2500.0, "total_distributions": 15000.0, "participant_count": 89, "compliance_events": [...] # Full audit log } ``` ```python theme={null} { "ledger_boy": { "participant_cash_accounts": 200000.0, "unallocated_company_contributions": 200000.0, "unallocated_forfeiture_cash": 0.0 } } ``` *** ## Compliance Events Per employee: ```json theme={null} { "year": 2025, "phase": "year_end", "event": "yearly_evolution_applied", "entity_type": "employee", "entity_id": "EMP042", "inputs": { "prev_age": 45, "prev_service_years": 12.0, "prev_compensation": 150000.0, "comp_growth_rate": 0.03 }, "outputs": { "age": 46, "service_years": 13.0, "compensation": 154500.0 } } ``` Company-level TrustCashLedger reconciliation: ```json theme={null} { "year": 2025, "phase": "ledger", "event": "ledger_reconciliation", "entity_type": "company", "entity_id": null, "inputs": { "boy": { "participant_cash_accounts": 150000.0, "unallocated_company_contributions": 50000.0, "unallocated_forfeiture_cash": 25000.0 }, "deposits": {"unallocated_company_contributions": 500000.0}, "draws": [ {"source": "unallocated_company_contributions", "amount": 200000.0}, {"source": "unallocated_forfeiture_cash", "amount": 100000.0} ] }, "outputs": { "eoy": { "participant_cash_accounts": 200000.0, "unallocated_company_contributions": 200000.0, "unallocated_forfeiture_cash": 0.0 } } } ``` *** ## Edge Cases **Do NOT roll balances or evolve:** * Balances frozen at termination * Age/service/comp don't increment * Distributions handled via `pending_distributions` Only **active** employees are evolved. Employees who terminated during year: * Participated in Steps 1-7 with beginning-of-year data * Do NOT evolve in Step 8 * Marked as terminated for future years In rare cases, corrections might create negative balances: ```python theme={null} opening_shares = max(0, opening + allocated - diversified) ``` Floor at zero to prevent negative opening balances. If no compensation growth assumption: ```python theme={null} comp_growth_rate = financial_assumptions.get("combined_comp_growth_rate", 0.0) employee.compensation = employee.compensation * (1 + comp_growth_rate) ``` Compensation stays flat year-over-year. *** ## Impact on Next Year Step 8 **sets the stage** for the next year's simulation: What was `allocated_shares` this year becomes `opening_shares` next year: **Year 2025 End:** * opening\_shares: 2,000 * allocated\_shares: 0 **Year 2026 Start:** * opening\_shares: 2,000 ← from 2025 rollover * allocated\_shares: 0 ← fresh accumulator Service increment affects vesting: **Year 2025:** * Service: 3.5 years → 60% vested (year 3) **Year 2026:** * Service: 4.5 years → 80% vested (year 4) More shares vest automatically due to service increase. Age increment may trigger eligibility: **Year 2025:** * Age: 54 → Not eligible (need 55+) **Year 2026:** * Age: 55 → **Eligible** for diversification! Age increment may trigger Required Minimum Distributions: **Year 2025:** * Age: 72 → No RMD yet **Year 2026:** * Age: 73 → **RMD enforced** in Step 7! *** ## Performance Optimization **Purpose:** Reduce active employee list size over time **Impact:** * Fewer employees to iterate in Steps 1-8 * Faster projections in later years * No loss of data (preserved in snapshots) **Threshold:** 0.01 shares or \$0.01 cash Clear year-specific accumulators to prepare for next year: * `allocated_shares = 0` * `allocated_cash = 0` * OIA tracking variables reset Prevents carryover of stale data. All employees evolved in single loop for efficiency: ```python theme={null} for emp in active_employees: emp.age += 1 emp.service_years += 1.0 emp.compensation *= (1 + growth_rate) ``` Vectorization opportunities if using NumPy/Pandas. *** ## Related Steps Uses evolved data from Step 8 of previous year Generates distribution data captured in Step 8 How Step 8 fits into the annual cycle Ledger reconciliation details *** ## Summary Step 8 is the **year-end finalization step** that: * ✅ Rolls share/cash balances forward for active employees * ✅ Identifies and removes fully paid-out participants * ✅ Captures comprehensive year-end results and KPIs * ✅ Applies yearly evolution (age +1, service +1, comp growth) * ✅ Reconciles OIA ledger with sources/uses/earnings * ✅ Reconciles TrustCashLedger movements (no earnings in v0.3) * ✅ Resets accumulators for next year * ✅ Emits evolution events for audit trail **Key Insight:** Step 8 is the **bridge between years**. It transforms the current year's processing results into the starting state for the next year, ensuring continuity and accuracy across multi-year projections. After Step 8 completes, the engine is ready to **loop back to Step 1** for the next year, repeating the 8-step cycle until the projection period ends. # API Documentation Source: https://village-docs.villagelabs.com/village-intelligence/api Integrate Village Intelligence into your systems ## Village Intelligence API Programmatic access to ESOP intelligence and insights. ## Overview The Village Intelligence API provides: * Expert ESOP knowledge * Regulatory guidance * Litigation intelligence * Industry benchmarks * Real-time updates ## Use Cases ### Application Integration **Enhance your software:** * Add ESOP expertise * Contextual help * Intelligent features * Real-time guidance ### Automated Research **Programmatic queries:** * Bulk research * Regular monitoring * Automated reports * Data enrichment ### Custom Workflows **Build solutions:** * Tailored processes * Automated compliance * Smart notifications * Custom interfaces ## API Features ### REST API **Standard HTTP:** * Simple integration * Well-documented * Comprehensive * Reliable ### Real-Time Responses **Fast performance:** * Sub-second latency * Scalable infrastructure * High availability * Global distribution ### Webhooks **Event notifications:** * Regulatory updates * New litigation * Content changes * Custom alerts ## Authentication **Secure access:** * API keys * OAuth 2.0 * Rate limiting * Usage tracking ## Rate Limits **Fair use:** * Standard: 100 requests/minute * Professional: 1,000 requests/minute * Enterprise: Custom limits ## Documentation **Complete reference:** * Endpoint documentation * Code examples * Best practices * Error handling * Changelog ## Get API Access Contact us for API access **API launching with platform in 2025** # Benchmarking Source: https://village-docs.villagelabs.com/village-intelligence/benchmarking Compare your ESOP to industry standards ## ESOP Benchmarking Compare your ESOP to industry standards and best practices. ## What is Benchmarking? Understand how your ESOP compares to others: * Plan design features * Contribution levels * Administrative practices * Costs and efficiency * Participant experience ## Key Metrics ### Plan Design * Vesting schedule * Allocation formula * Eligibility requirements * Distribution timing * Diversification provisions ### Financial * Contribution as % of payroll * Administrative costs * Per-participant costs * Repurchase obligations ### Operational * Valuation frequency * Statement delivery * Response times * Compliance approach ## Comparison Groups ### By Size * Similar participant count * Similar company revenue * Similar ESOP age ### By Industry * Same industry sector * Similar business model * Geographic peers ### By Characteristics * Ownership percentage * Leveraged vs. non-leveraged * Growth stage * Maturity ## Benchmarking Reports **Comprehensive analysis:** * Your position vs. industry * Strengths and opportunities * Best practice recommendations * Action items ## Use Cases ### Plan Design Review **Evaluate your features:** * Are we competitive? * Industry standards * Improvement opportunities ### Cost Analysis **Understand your costs:** * Are we efficient? * Where can we improve? * Best practices ### Strategic Planning **Inform decisions:** * What's working elsewhere? * Proven approaches * Avoid common pitfalls **Benchmarking tools launching with platform in 2025** # Platform Features Source: https://village-docs.villagelabs.com/village-intelligence/features Comprehensive capabilities of Village Intelligence ## Village Intelligence Features Deep ESOP expertise accessible through AI-powered intelligence tools. ## Core Features ### Expert Knowledge Base **Comprehensive ESOP knowledge:** * Plan design and mechanics * Regulatory requirements * Fiduciary responsibilities * Industry best practices * Historical context **Coverage includes:** * DOL regulations and guidance * IRS rules and requirements * ERISA compliance * Industry standards * Case law and litigation ### Natural Language Queries **Ask questions naturally:** * No special syntax needed * Conversational interface * Follow-up questions * Context awareness **Example queries:** * "What are the requirements for ESOP diversification?" * "How should we handle repurchase obligations?" * "What litigation involved valuation disputes?" ### Litigation Intelligence **Learn from history:** * Key ESOP litigation cases * Fiduciary breach claims * Valuation disputes * Prohibited transactions * Settlement outcomes * Lessons learned **Search by:** * Topic or issue * Outcome * Parties involved * Time period * Jurisdiction ### Regulatory Monitoring **Stay current:** * DOL guidance updates * IRS rule changes * New legislation * Court decisions * Industry developments **Alerts for:** * Relevant updates * Action required * Compliance changes * Best practice shifts ## Advanced Capabilities ### Benchmarking **Compare to industry:** * Plan design features * Contribution levels * Vesting schedules * Distribution policies * Administrative practices **Insights include:** * Industry averages * Common approaches * Regional variations * Size-based comparisons ### Document Analysis **Analyze plan documents:** * Upload plan documents * Identify key provisions * Flag potential issues * Compare to standards * Suggest improvements ### Scenario Analysis **Test approaches:** * Model different plan designs * Evaluate alternatives * Understand implications * Compare options ### Research Tools **Deep dive capabilities:** * Topic exploration * Related content * Historical analysis * Trend identification ## Integration Features ### API Access **Programmatic access:** * RESTful API * Comprehensive endpoints * Real-time responses * Scalable infrastructure **Use cases:** * Integrate into applications * Automated research * Custom workflows * System enhancement ### Webhooks **Event notifications:** * Regulatory updates * New litigation * Content changes * Custom alerts ### Single Sign-On **Seamless access:** * SAML 2.0 support * OAuth integration * Enterprise authentication * Centralized management ## User Experience ### Intuitive Interface **Easy to use:** * Clean design * Clear navigation * Fast search * Mobile-responsive ### Personalization **Tailored experience:** * Saved searches * Bookmarks * Custom alerts * Usage history ### Collaboration **Team features:** * Share findings * Annotate content * Team workspaces * Activity tracking ### Export & Sharing **Take your insights:** * PDF export * Email sharing * Citation formatting * Link sharing ## Data & Security ### Comprehensive Sources **Built on:** * Regulatory guidance * Court decisions * Industry publications * Expert knowledge * Best practices ### Quality Assurance **Verified information:** * Expert review * Source verification * Regular updates * Accuracy checks ### Security **Enterprise-grade:** * Encryption at rest and in transit * SOC 2 Type II compliance * Access controls * Audit trails * Regular security audits ### Privacy **Your data protected:** * No data sharing * Confidential queries * Secure infrastructure * GDPR compliant ## Platform Architecture ### AI Technology **Powered by:** * Fine-tuned large language models * Deep ESOP domain expertise * Continuous learning * Quality assurance systems ### Performance **Fast and reliable:** * Sub-second responses * 99.9% uptime * Global infrastructure * Automatic scaling ### Updates **Always current:** * Regular content updates * Model improvements * Feature releases * Bug fixes ## Coming Features **Roadmap highlights:** * Document comparison tools * Advanced analytics * Custom reporting * Team collaboration enhancements * Mobile applications ## Pricing (Expected) **Professional** (\$500/month) * Full platform access * Unlimited queries * Standard support * Single user **Team** (\$2,000/month) * Everything in Professional * Up to 10 users * Team workspaces * Priority support **Enterprise** (Custom) * Everything in Team * Unlimited users * API access * Custom integrations * Dedicated support ## Get Early Access Be among the first users # Village Intelligence Source: https://village-docs.villagelabs.com/village-intelligence/index The knowledge core that powers the entire Village Labs ecosystem. A proprietary synthesis of fine-tuned LLMs, structured data, and deep domain expertise. Village Intelligence ## The Knowledge Core for ESOPs Village Intelligence is the centralized brain that powers the Village Labs platform. It is a proprietary, domain-specific knowledge core that gives the **Kelso AI Agent** its deep understanding of the ESOP ecosystem and enables the powerful features within the **Peninsula Operating System**. This is not a general-purpose AI. It is a highly specialized intelligence layer, meticulously curated for the complexities of ESOPs. Explore the data sources and models that make up the core. See how Kelso leverages this knowledge to perform work. ## Components of Village Intelligence We leverage state-of-the-art LLMs (from providers like Google, Anthropic, and OpenAI) and fine-tune them specifically on ESOP legal documents, valuation theory, and administrative best practices. A massive, proprietary knowledge base containing detailed information on every aspect of ESOP mechanics, compliance, and strategy, ensuring Kelso's answers are always accurate and context-aware. Includes comprehensive, queryable datasets such as the Form 5500 database, providing a rich source of industry data for analysis, benchmarking, and insights. # Industry Insights Source: https://village-docs.villagelabs.com/village-intelligence/insights Expert insights and analysis ## ESOP Industry Insights Expert analysis and insights on the ESOP industry. ## Current Topics ### Regulatory Environment **Key developments:** * Recent DOL guidance * IRS rulings and notices * Legislative proposals * Court decisions ### Industry Trends **What's changing:** * Plan design evolution * Technology adoption * Administrative practices * Market dynamics ### Emerging Challenges **What to watch:** * Repurchase obligations * Succession planning * Technology disruption * Regulatory complexity ## Expert Analysis ### Deep Dives **Comprehensive topic analysis:** * Background and context * Current state * Implications * Recommendations * Resources ### Case Studies **Real-world examples:** * Successful approaches * Lessons learned * Best practices * What to avoid ### Thought Leadership **Industry perspectives:** * Expert opinions * Forward-looking analysis * Contrarian views * Provocative questions ## Research Reports **In-depth analysis:** * Industry surveys * Trend reports * Best practice studies * Regulatory analysis ## Stay Informed **Regular updates:** * Weekly insights * Monthly deep dives * Quarterly reports * Annual review **Insights published regularly starting in 2025** # Village Intelligence Source: https://village-docs.villagelabs.com/village-intelligence/overview Enterprise AI platform for financial services # Village Intelligence Our foundational AI platform that powers all Village Labs products with specialized financial domain expertise. ## Platform Features * **Financial Expertise** - Deep knowledge of ESOP, ERISA, and retirement plans * **Multi-Model Architecture** - Orchestrates specialized models for accuracy * **Enterprise Security** - SOC 2 compliant with data residency controls * **API-First** - Integrate AI into any system ## Built for Integration Village Intelligence provides the AI infrastructure that financial services firms can leverage to build custom solutions for their clients. Learn about our complete AI platform # Quick Start Source: https://village-docs.villagelabs.com/village-intelligence/quickstart Get started with Village Intelligence ## Getting Started with Village Intelligence Quick start guide for using Village Intelligence (available upon launch). ## Account Setup Create your account at villagelabs.com/intelligence Confirm your email address Select the plan that fits your needs Tell us about your role and interests ## Your First Query ### Ask a Question Simply type your question in natural language: **Example queries:** * "What are the ESOP diversification requirements?" * "Show me litigation involving repurchase obligations" * "How do most companies structure their vesting?" ### Review Results Get comprehensive answers: * Direct response to your question * Supporting context and details * Related considerations * Citations and sources * Follow-up suggestions ### Explore Further Dig deeper: * Ask follow-up questions * Explore related topics * Save useful findings * Share with your team ## Common Use Cases ### Research a Topic **Goal:** Understand a specific ESOP concept **Example:** "Explain ESOP repurchase obligations" **What you'll get:** * Comprehensive explanation * Regulatory requirements * Common approaches * Best practices * Related resources ### Find Precedent **Goal:** Research litigation history **Example:** "Show me cases about ESOP valuations" **What you'll get:** * Relevant cases * Key issues * Outcomes * Lessons learned * Related cases ### Benchmark Practices **Goal:** Compare to industry standards **Example:** "What's typical for ESOP vesting schedules?" **What you'll get:** * Industry data * Common practices * Variations by size * Regional differences * Recommendations ## Best Practices ### Asking Good Questions **Be specific:** * ✅ "What are the requirements for age 55 diversification?" * ❌ "Tell me about diversification" **Provide context:** * ✅ "For a 100-person manufacturing ESOP, what's typical for contributions?" * ❌ "What about contributions?" **Ask follow-ups:** * Build on previous answers * Clarify uncertainties * Explore related topics ### Organizing Your Work **Save important findings:** * Bookmark useful content * Create collections by topic * Tag for easy retrieval **Share with team:** * Collaborate on research * Share key findings * Build team knowledge base ## Need Help? Get help from our team **Coming 2025** - Platform currently in development # Webhooks Source: https://village-docs.villagelabs.com/village-intelligence/webhooks Real-time notifications from Village Intelligence ## Village Intelligence Webhooks Receive real-time notifications about ESOP intelligence updates. ## What are Webhooks? Webhooks send automated notifications to your systems when events occur: * Regulatory updates * New litigation * Content changes * Custom alerts ## Event Types ### Regulatory Events **Notifications for:** * New DOL guidance * IRS rulings * Legislative changes * Court decisions ### Content Events **Updates about:** * New articles * Updated guidance * Added cases * Revised benchmarks ### Custom Events **Your specific interests:** * Keyword alerts * Topic monitoring * Client-specific * Custom triggers ## Webhook Setup Provide URL to receive notifications Choose which events to monitor Define what triggers notifications Verify and go live ## Payload Format **JSON structure:** ```json theme={null} { "event_type": "regulatory_update", "timestamp": "2025-01-15T10:30:00Z", "data": { "title": "New DOL Guidance on ESOP Valuations", "summary": "...", "url": "...", "priority": "high" } } ``` ## Security **Verified delivery:** * HMAC signatures * HTTPS only * Retry logic * Delivery confirmation ## Get Started Contact us to set up webhooks **Webhooks available with Enterprise plan in 2025**