ValueLoop AI

ValueLoop AI is a synthetic, local-first prototype for mapping card-member benefits to realistic value, surfacing unclaimed opportunities, and selecting next-best actions without using any real banking data or paid APIs.

What this project does

• Builds a synthetic benefit catalogue for statement credits, lounge visits and protection benefits.
• Generates synthetic member, transaction and event data.
• Evaluates benefit entitlements with a deterministic rule-based engine.
• Calculates face value, eligible value, true unclaimed value and incrementally recoverable value.
• Produces next-best-action recommendations and a simple no-action decision path.
• Offers a Streamlit app with multiple pages for portfolio, member, nudge and QA views.

Synthetic-only disclosure

• All data is fictional.
• The prototype uses representative, configurable rules only.
• It is not an official benefit guide.

Project architecture

• app.py: entry point for the Streamlit app.
• pages/: multipage dashboard views.
• src/: core logic for data generation, entitlement evaluation, value modeling, nudge selection and QA.
• scripts/: scripts for generating data and building processed outputs.
• data/: local synthetic datasets and processed outputs.
• tests/: deterministic tests for the engine.

Windows setup

1. Open PowerShell in the project root.
2. Run python -m venv .venv
3. Run .\.venv\Scripts\Activate.ps1
4. Run python -m pip install -r requirements.txt

macOS/Linux setup

1. Open a terminal in the project root.
2. Run python3 -m venv .venv
3. Run source .venv/bin/activate
4. Run python -m pip install -r requirements.txt

Generate data

Run python scripts/generate_data.py

Build processed outputs

Run python scripts/build_outputs.py

Run tests

Run pytest

Start the app

Run streamlit run app.py

Expected local URL

The app usually opens at http://localhost:8501.

Stop the app

Press Ctrl+C in the terminal.

Common issues

• If Streamlit says the module is missing, reinstall requirements.
• If CSV files are missing, run the build script again.
• If tests fail, read the traceback and fix the smallest relevant component.

Demo recording

Use a screen recorder and show the executive portfolio, one member profile, and the nudge lab.

GitHub upload

1. Initialize git with git init
2. Add files with git add .
3. Commit with git commit -m "Initial ValueLoop AI prototype"
4. Create a repo on GitHub and push with git remote add origin <your-url> and git push -u origin main

Optional deployment

A simple Streamlit Community Cloud deployment is possible after pushing the repository.

Limitations

• This is a prototype and not production-grade.
• Benefit rules are configurable examples, not official terms.
• The nudge engine uses transparent MVP assumptions and simulated outcomes.