Budget Meals: Deterministic Resource Allocation Engine

Budget Meals is a local-first, offline Streamlit application designed for precise meal planning and resource management. Unlike probabilistic assistants, this application uses linear algebra to manage inventory, forecast resources, and generate automated procurement lists with 100% mathematical accuracy.

The "Deterministic Agent" Philosophy

This application is built on the philosophy that resource allocation should be handled by a math engine rather than a Large Language Model (LLM). By using a deterministic approach, the app ensures precision, privacy, and zero operational costs.

Feature	LLM-Based Agent	This Matrix-Based Agent
Accuracy	Probabilistic (May hallucinate quantities)	Mathematical (100% Precise)
Privacy	Data sent to Cloud	100% Local / Offline
Cost	API Fees per request	$0 (Runs on local CPU)
Logic	Natural Language Processing	Linear Algebra ($Ax = b$)

Core Features (The Pipeline)

The application follows a structured data pipeline to ensure reliable resource forecasting:

1. Local State Management: All data is stored in local JSON files (`inventory.json`, `recipes.json`). The system employs automatic string normalization (e.g., de-pluralization) and data type coercion via regex to handle units and ensure consistency.
2. Dynamic Matrix Editor: A Pandas-driven UI allows users to define and modify the Recipe Matrix ($A$) and current inventory levels directly through interactive data editors.
3. The Math Engine: Leveraging NumPy-powered calculations, the engine performs a dot product ($b = Ax$) to instantly compute the total resources required for a specific meal plan and compare them against current inventory.
4. Procurement Automation: The system identifies deficits and provides an interactive budgeting tool where users can input estimated costs and export a final shopping list as a CSV file.

The Math Explained

At its core, the application solves the fundamental resource allocation equation:

$$b = Ax$$

• $A$ (Recipe Matrix): A matrix representing the required ingredients per unit of output (e.g., amount of flour per plate).
• $x$ (Target Vector): A vector containing the user's requested number of plates for each recipe.
• $b$ (Required Resources): The resulting dot product, representing the total quantity needed for every ingredient.

The application then calculates the Deficit Vector by subtracting the Inventory Vector from $b$. Any positive values in the result represent the exact items and quantities needed for the shopping list.

Tech Stack

• Python: Core logic and processing.
• Streamlit: Interactive web interface.
• Pandas: Data manipulation and matrix operations.
• NumPy: High-performance numerical computing (backend for Pandas ops).
• Standard Libraries: `json` (storage), `re` (data normalization/extraction), `os`.

Installation and Usage

To run Budget Meals locally, follow these steps:

1. Clone the repository: ```bash git clone cd budget-meals ```

2. Install the required dependencies: ```bash pip install streamlit pandas numpy ```

3. Run the application: ```bash streamlit run app.py ```

Once the app is running, use the sidebar to set your meal goals and navigate through the tabs to manage your inventory, recipes, and view your feasibility report.