Vesting Program

A command-line program that processes equity vesting events from CSV files and calculates total shares vested for each employee-award combination as of a target date.

How to Build and Run

Prerequisites

• Python 3.6 or higher (no external dependencies required - uses only Python standard library)

Running the Program

The program can be run directly using Python:

python vesting_program.py <filename> <target_date> [precision]

Arguments:

• filename (required): Path to CSV file containing vesting events
• target_date (required): Date to calculate vesting up to, in YYYY-MM-DD format
• precision (optional): Number of decimal places (0-6). Default is 0 if not specified.

Examples:

# Stage 1: Basic vesting with default precision (0)
python vesting_program.py example1.csv 2020-04-01

# Stage 2: With cancellation events
python vesting_program.py example2.csv 2021-02-01

# Stage 3: With fractional shares and precision
python vesting_program.py example3.csv 2021-02-01 1

Making it Executable (Unix-like systems)

On Unix-like systems (Linux, macOS), you can make the script directly executable:

chmod +x vesting_program.py
./vesting_program.py example1.csv 2020-04-01

On Windows, you can create a batch file wrapper if needed, but running with python vesting_program.py works directly.

Design Decisions

1. Architecture and Separation of Concerns

The code is organized into distinct classes with single responsibilities:

• PrecisionHandler: Handles truncation logic for decimal precision
• VestingEvent: Represents a single vesting or cancellation event
• VestingCalculator: Core calculation logic for processing events
• CSVParser: Handles CSV file parsing and validation
• OutputFormatter: Formats and prints results in the required format

This separation makes the code maintainable, testable, and easy to extend.

2. Decimal Precision Handling

To avoid floating-point arithmetic errors (especially with fractional shares), the implementation uses Python's Decimal type for all internal calculations. This ensures precise arithmetic when handling fractional shares and truncation.

The truncation logic:

• Truncates input quantities to the specified precision during parsing
• Uses Decimal.quantize() with ROUND_DOWN to ensure consistent truncation
• Applies precision consistently throughout the calculation pipeline

3. Event Processing Order

Events are processed chronologically, with special handling for events on the same day:

1. All VEST events on a given day are processed first
2. Then all CANCEL events on that day are processed
3. This ensures cancellation validation is done against the vested total that includes vesting events on the same day

4. Cancellation Validation

The program validates that cancellations do not exceed vested shares:

• For each day, the sum of all cancellations must not exceed the total shares vested up to (and including) that day
• The validation is checked incrementally as cancellations are processed
• If validation fails, a descriptive error message is raised

5. Complete Output

The program includes all employee-award combinations in the output, even if 0 shares are vested by the target date. This ensures consistency and completeness of results.

6. Output Ordering

Results are sorted by Employee ID (ascending), then by Award ID (ascending), as required by the specification.

Assumptions

1. CSV Format:

   • CSV files have no header row
   • All rows contain exactly 6 columns
   • Empty rows are skipped

2. Date Format:

   • All dates are in YYYY-MM-DD format
   • Dates are valid calendar dates

3. Event Types:

   • Only 'VEST' and 'CANCEL' event types are valid
   • Event types are case-sensitive

4. Quantities:

   • Quantity values are numeric (integer or decimal)
   • Negative quantities are not explicitly handled (though they would be processed)

5. Data Consistency:

   • Employee names and IDs are consistent across events for the same employee
   • Award IDs are consistent across events for the same award
   • Cancellations will not exceed vested shares (validation catches this)

6. Precision:

   • Precision values are integers between 0 and 6 (inclusive)
   • When precision is 0, all values are treated as integers
   • Truncation happens at both input and output stages

7. Performance:

   • The solution is designed to handle reasonably large datasets efficiently
   • All events are loaded into memory, which should be acceptable for typical use cases

Features Implemented

Stage 1: Basic Vesting

• ✅ Handles VEST events
• ✅ Calculates total shares vested up to target date
• ✅ Includes all employees/awards (even with 0 shares)
• ✅ Outputs in required format with correct ordering

Stage 2: Cancellation Events

• ✅ Handles CANCEL events that subtract from vested total
• ✅ Validates that cancellations do not exceed vested shares
• ✅ Processes cancellations after vesting events on the same day

Stage 3: Fractional Shares & Precision

• ✅ Supports fractional share quantities in input
• ✅ Accepts optional precision argument (0-6, default 0)
• ✅ Truncates inputs and outputs to specified precision
• ✅ Uses Decimal arithmetic for precise calculations

Testing

The program has been tested with the provided examples:

• example1.csv: Basic vesting scenario
• example2.csv: Cancellation scenario
• example3.csv: Fractional shares with precision

All examples produce the expected output as specified in the requirements.

Future Improvements (if time permitted)

1. Performance Optimizations:

   • For very large datasets, could implement streaming CSV parsing
   • Could add progress indicators for large file processing

2. Error Handling:

   • More detailed error messages with line numbers
   • Graceful handling of edge cases (e.g., negative quantities, invalid dates)

3. Testing:

   • Add unit tests for individual components
   • Add integration tests for edge cases
   • Add performance benchmarks

4. Code Organization:

   • Could split into multiple modules for better organization
   • Add type hints more comprehensively

5. Documentation:

   • Add inline documentation for complex algorithms
   • Create user documentation with more examples

6. Features:

   • Support for additional event types if needed
   • Command-line flags for verbose output, error handling modes
   • Support for different date formats

LLM Prompts Used

This solution was developed based on the provided requirements specification. No additional LLM prompts were used beyond understanding and implementing the requirements as specified.