Imported from abhay2212-hub/Buy-Wait (AGENTS.md). Install upstream with npx skills add abhay2212-hub/Buy-Wait. Copyright stays with the author.

Buy or Wait AI — Agent Guidelines

Overview

AI-powered financial affordability and payment-planning engine.

Architecture

• app.py — Entry point for the CLI
• code/ — Core logic modules (config, data, evidence, ledger, simulator, planner, validator, explanations, llm)
• prompts/ — LLM prompt templates for evidence extraction and explanation writing
• evaluation/ — Scoring, validation, and usage reporting
• dataset/ — CSV data files

Coding Conventions

• Python 3.9+ typing throughout
• All LLM interactions go through code/llm.py
• Data loading is handled exclusively by code/data_loader.py
• The ledger (code/ledger.py) maintains financial state reconstruction
• The simulator (code/simulator.py) implements the 90-day safety check
• The planner (code/planner.py) explores counterfactual spending changes
• The validator (code/validator.py) enforces hard constraints
• Validation rules are defined in code/validator.py

90-Day Safety Check

Every recommended payment plan must pass the 90-day minimum-balance safety test:

• For each day in the 90-day forecast, projected balance >= minimum_balance_to_keep
• Binary search is used to find the maximum safe payment amount

Prompt Engineering

• Prompts are stored as .txt files in prompts/
• Each prompt must be loaded via code/llm.py at runtime
• Keep prompt instructions deterministic and reproducible

Running

pip install -r requirements.txt
cp .env.example .env
python app.py --product REQUEST_ID --days 90

Evaluation

python evaluation/check_output.py <output_file.json>
python evaluation/score_sample.py <sample_file.json>

Environment Setup

pip install -r requirements.txt
cp .env.example .env