Add screenshots, README and LICENSE; with some code cleanups

.idea/workspace.xml

@@ -5,8 +5,15 @@
   </component>
   <component name="ChangeListManager">
     <list default="true" id="b6145d7e-32b4-4917-b6ec-19187eb432a7" name="Changes" comment="">
+      <change afterPath="$PROJECT_DIR$/LICENSE" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/assets/images/Screenshot_1.jpg" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/assets/images/Screenshot_2.jpg" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/assets/images/Screenshot_3.jpg" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/.idea/workspace.xml" beforeDir="false" afterPath="$PROJECT_DIR$/.idea/workspace.xml" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/README.md" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/src/app/gradio_ui.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/app/gradio_ui.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/app/split_ai.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/app/split_ai.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/llm/ollama.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/llm/ollama.py" afterDir="false" />
     </list>
     <option name="SHOW_DIALOG" value="false" />
     <option name="HIGHLIGHT_CONFLICTS" value="true" />

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Avinash Mallya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,58 @@
+# IRS: The Intelligent Receipt Splitter
+
+Tired of overpaying just because splitting the bill equally was easier? Now, pay only your fair share with this app! Snap a photo of your receipt, specify who had what, and let the app handle the rest. Handle tips, taxes, and if you're feeling a little charitable, credit card cashback as well!
+
+Know Python? Then read on to run it locally.
+
+Don't know Python? Watch this space.
+
+## Screenshots
+
+<img src="/assets/images/screenshot_1.jpg" width=15%>
+<img src="/assets/images/screenshot_2.jpg" width=15%>
+<img src="/assets/images/screenshot_3.jpg" width=15%>
+
+## Setup environment
+
+### Prerequisites
+
+You will need [`ollama`](https://ollama.com/) installed and running with a model of your choice available. The default is `qwen2.5:7b`, while this is easily configurable.
+
+### Python virtual environment
+
+Use `uv` from the folks over at [astral.sh](https://github.com/astral-sh/uv). After cloning the repository, do:
+
+```bash
+uv sync --extra dev
+source .venv/bin/activate # On MacOS/Linux, venv\Scripts\activate on Windows
+export PYTHONPATH=$(pwd)
+```
+
+If you don't have `uv` or don't care for it, then create a virtual environment and install the package itself. Below is an example using `pyvenv`.
+
+```bash
+python3 -m venv venv # Python 3.6+
+source .venv/bin/activate # On MacOS/Linux, venv\Scripts\activate on Windows
+pip install .
+export PYTHONPATH=$(pwd)
+```
+
+## Start the Gradio app
+
+If everything's setup properly in the virtual environment, run:
+
+```bash
+python src/app/gradio_ui.py
+```
+
+By default, it should run at `0.0.0.0:7860`. If you want to run this on a mobile device while processing on your local machine, you will need to identify the IP address of your machine and be connected to the same network the machine is on. Then, in your mobile browser, navigate to:
+
+```commandline
+http://<machine-ip-address>:7860/
+```
+
+## Other stuff
+
+> Did you know that the abbreviation IRS conflicts with the Internal Revenue Service?
+
+Yes.

src/app/gradio_ui.py

@@ -1,6 +1,7 @@
 from datetime import datetime
 from typing import Literal, TypedDict, TypeVar
 
+import argparse as agp
 import gradio as gr
 import polars as pl
 from PIL.Image import Image
@@ -526,22 +527,20 @@ class SplitAIApp:
         image: Image,
         items: gr.State,
     ):  # -> gr.State:
-        # gr.Info("Running OCR on image of receipt.")
-        # receipt_string = self.receipt_reader.get_ordered_text(image)
-        # gr.Info("Extracting components. Please be patient.")
-        # receipt_extracted = self.receipt_reader.extract_components(receipt_string)
-        receipt_extracted = {
-            "merchant": "FUBAR",
-            "receipt_date": datetime.now(),
-            "total": {"amount": 15},
-            "tip": {"amount": 0},
-            "tax": {"amount": 3},
-            "item_amounts": [
-                {"name": "PET TOY", "currency": "$", "amount": 2},
-                {"name": "FLOPPY PUPPY", "currency": "$", "amount": 4},
-                {"name": "SSSUPREME S", "currency": "$", "amount": 6},
-            ],
-        }
+        receipt_string = self.receipt_reader.get_ordered_text(image)
+        receipt_extracted = self.receipt_reader.extract_components(receipt_string)
+        # receipt_extracted = {
+        #     "merchant": "FUBAR",
+        #     "receipt_date": datetime.now(),
+        #     "total": {"amount": 15},
+        #     "tip": {"amount": 0},
+        #     "tax": {"amount": 3},
+        #     "item_amounts": [
+        #         {"name": "PET TOY", "currency": "$", "amount": 2},
+        #         {"name": "FLOPPY PUPPY", "currency": "$", "amount": 4},
+        #         {"name": "SSSUPREME S", "currency": "$", "amount": 6},
+        #     ],
+        # }
         key_value_updates = [
             {
                 "component": self.merchant,
@@ -593,7 +592,13 @@ class SplitAIApp:
         else:
             self.demo.queue().launch()
 
+def arg_parser() -> agp.ArgumentParser:
+    ag = agp.ArgumentParser()
+    ag.add_argument("-m", "--model", type=str, default="qwen2.5:7b", help="Choose the LLM model used.")
+    return ag
+
 
 if __name__ == "__main__":
-    demo = SplitAIApp("qwen2.5")
+    args = arg_parser().parse_args()
+    demo = SplitAIApp(args.model)
     demo.launch(True)

src/app/split_ai.py

@@ -1,7 +1,6 @@
 from src.llm.ollama import LLMExtractor, ReceiptExtracted
 from src.ocr.surya import SuryaOCR
 from PIL.Image import Image
-from PIL.Image import open as PIL_open
 
 
 class ReceiptReader:
@@ -13,10 +12,4 @@ class ReceiptReader:
         return self.ocr_model.ordered_ocr_text(image)
 
     def extract_components(self, receipt_string: str) -> ReceiptExtracted:
-        return self.llm_model.forward(receipt_string, enable_alerts=False)
-
-
-if __name__ == "__main__":
-    image = PIL_open("data/pytest/image_upload_test.png")
-    sr = ReceiptReader()
-    print(sr.extract_components(image))
+        return self.llm_model.forward(receipt_string)

src/llm/ollama.py

@@ -46,9 +46,9 @@ class ItemizedAmounts(TypedDict):
 class ReceiptExtracted(TypedDict):
     merchant: str
     receipt_date: datetime
-    total_amount: Amount
-    tip_amount: Amount
-    tax_amount: Amount
+    total: Amount
+    tip: Amount
+    tax: Amount
     item_amounts: list[ItemizedAmounts]
 
 class LLMExtractor:
@@ -165,19 +165,13 @@ class LLMExtractor:
         itemized_amounts = self.get_chat_response(messages, ReceiptItemized)['ItemizedReceipt']
         return itemized_amounts
 
-    def forward(self, receipt_string, enable_alerts:bool=False) -> ReceiptExtracted:
+    def forward(self, receipt_string) -> ReceiptExtracted:
         merchant = self.extract_merchant_name(receipt_string)
-        # gr.Info("Extracted merchant name.")
         receipt_date = self.extract_receipt_date(receipt_string)
-        # gr.Info("Extracted receipt date.")
         total_amount = self.extract_receipt_total_amount(receipt_string)
-        # gr.Info("Extracted total amount.")
         tip_amount = self.extract_receipt_tip_amount(receipt_string)
-        # gr.Info("Extracted tip amount.")
         tax_amount = self.extract_receipt_tax_amount(receipt_string)
-        # gr.Info("Extracted tax amount. Extracting individual items - this will take time.")
         item_amounts = self.extract_receipt_items(receipt_string)
-        # gr.Info("Extracted individual items. Populating items now!")
         return {
             "merchant": merchant,
             "receipt_date": receipt_date,
@@ -186,11 +180,3 @@ class LLMExtractor:
             "tax": tax_amount,
             "item_amounts": item_amounts
         }
-        # return {
-        #     "merchant": self.extract_merchant_name(receipt_string),
-        #     "receipt_date": self.extract_receipt_date(receipt_string),
-        #     "total": self.extract_receipt_total_amount(receipt_string),
-        #     "tip": self.extract_receipt_tip_amount(receipt_string),
-        #     "tax": self.extract_receipt_tax_amount(receipt_string),
-        #     "item_amounts": self.extract_receipt_items(receipt_string)
-        # }