Fund Load Adjudication Engine

Overview

A Python-based rule evaluation system for determining the validity of fund load attempts under velocity and regulatory constraints. When a batch of transactions is received, each attempting to load funds into a customer’s account, the system must evaluate whether each one meets the required constraints. These constraints determine which transactions are permitted to proceed. This program replicates that decision-making process: assigning an acceptance status to each load attempt, and producing an output file that guides which transactions should be executed. This program processes fund load attempts and determines whether each should be accepted or declined based on the following business rules:

Velocity Limits

• Daily Limit: A customer may load a maximum of $5000 per day
• Weekly Limit: A customer may load a maximum of $20000 per week
• Daily Load Count: A customer may perform at most 3 load attempts per day

Special Sanctions

• Prime ID: If a customer's ID is a prime number, they may:
  • Perform only 1 load attempt per day
  • Load a maximum of $9999 per day
• Monday Penalty: Loads performed on a Monday are counted at double their value for all limit evaluations (e.g. $4000 counts as $8000 toward limits)

How the Solution Works

1. The input is parsed by services.parser line-by-line from input.txt, and each line (considered a load attempt) is converted into a LoadAttempt object (defined in models.load_attempt) with standardized fields (amount, timestamp, etc.).
2. services.evaluator then processes the list of LoadAttempt objects in chronological order (by the "time" field in input) to ensure logical evaluation (i.e. constraint application) order, regardless of the LoadAttempt line order in the input file.
3. Each load attempt is evaluated (in services.evaluator) against the constraints defined under Velocity Limits and Special Sanctions.
4. Accepted ("accepted":true) load attempts are tracked using a CustomerFund object (defined in models.customer_fund), which maintains per-day and per-week histories for each customer.
5. After constraint evaluation (services.evaluator), each LoadAttempt is updated with an accepted: true/false flag to reflect the decision.
6. services.writer serializes the updated LoadAttempt objects to output.txt (in the same directory as main.py), one JSON object per line (JSON Lines format), matching the required output schema.

The program is fully modular, with separate folders for models, services, utilities, and tests. All core logic is covered by targeted unit tests and can be run manually for verification.

---

Assumptions

• Week starts on Monday (ISO 8601)
• All currency values are in USD
• All "id" fields in the input file are unique
• "id" in the input refers to the load attempt ID
• id in the Extra Credit - Special Sanctions of the restrictions refers only to customer_id
• "customer_id" in the input file is used to apply sanctions and velocity limits
• For Prime ID sanctions, customer_id is treated as an integer
• Each fund load is either fully accepted ("accepted":true) or fully declined ("accepted":false). Partial acceptance is not allowed
• Load amounts are formatted as strings and may include currency symbols or prefixes (e.g., "$" or "USD"), but do not contain commas

---

How to Run

Make sure you are using Python 3.9 or later.

1. Install dependencies:

pip install python-dateutil

2. Place your input.txt in the same directory as main.py.
3. Then run the program:

python main.py

4. The program will generate output.txt(will be created in the same directory as main.py) with results in JSON Lines format.

Output Format

The program outputs one JSON object per line in output.txt:

{"id":"15337","customer_id":"999","accepted":false}

Each object includes:

• "id": the load attempt ID (string)
• "customer_id": the ID of the customer attempting the load (string)
• "accepted": whether the attempt passed all constraints (true) or not (false)

---

Tests

Unit tests are included for all key components. Each test file can be run independently using python.

To run a specific test file:

python tests/test_<feature>.py

Where <feature> is one of:

• time_utils
• prime_utils
• parser
• evaluator

---

Files

File	Description
main.py	Entrypoint script that runs the full pipeline with process logs
config.py	Contains global configuration values (limits)
requirements.txt	Python dependency list
input.txt	Input data file (use file to generate output.txt)
output.txt	Output results file (generated by running main.py)

Directory Structure

fund-load-restriction-check/
├── main.py                # Entrypoint script
├── config.py              # Velocity/sanction limits
├── requirements.txt       # Dependencies
├── input.txt              # Sample input data
├── README.md              # Explains solution and any assumptions
|
├── models/                # Data class module
│   ├── load_attempt.py    # LoadAttempt dataclass and helpers
│   ├── customer_fund.py   # Tracks accepted attempts per customer
│   └── __init__.py
│
├── services/              # Business & Processing logic module
│   ├── parser.py          # Parses input file into LoadAttempt objects
│   ├── evaluator.py       # Applies business rules and constraints
│   ├── writer.py          # Serializes result to output file
│   └── __init__.py
│
├── utils/                 # Helper module
│   ├── time_utils.py      # Monday/week key/date logic
│   ├── prime_utils.py     # Prime number checking
│   └── __init__.py
|
├── tests/                 # Unit tests (run manually)
│   ├── test_time_utils.py
│   ├── test_prime_utils.py
│   ├── test_parser.py
│   ├── test_evaluator.py
│   └── __init__.py

---

Notes

• This submission does not include generated __pycache__ folders
• The output is written in JSON Lines format for scalability and clarity
• All constraints (daily limits, weekly limits, prime restrictions, etc.) are enforced only against only prior attempts that were accepted (accepted: true)
• Certain print statements for debugging and evaluation tracing remain commented out in evaluator.py and customer_fund.py. These can be uncommented for additional visibility during review or testing.