V 0.1

.gitignore

@@ -0,0 +1,24 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# IDE
+.idea
+.vscode
+
+# Other
+*.DS_Store
+
+# environment variables
+.env
+
+# Rough Work
+/utils
+/poc

.python-version

@@ -0,0 +1 @@
+3.13

app.py

@@ -0,0 +1,222 @@
+import gradio as gr
+import uuid
+import json
+import pandas as pd
+from main import get_graph
+from nodes.foodMatching import getPeople
+
+graph = get_graph()
+MAX_ITEMS = 50
+
+def start_or_resume_graph(image_path, thread_id, updates=None):
+    config = {"configurable": {"thread_id": thread_id}}
+    
+    if updates:
+        graph.update_state(config, updates)
+        # Resume - loop through stream to reach next interrupt
+        for event in graph.stream(None, config, stream_mode="values"):
+            pass
+    elif image_path:
+        # Start new
+        initial_input = {"image_path": image_path}
+        for event in graph.stream(initial_input, config, stream_mode="values"):
+            pass
+            
+    state = graph.get_state(config)
+    return state.values, state.next
+
+def process_upload(image):
+    if not image:
+        return [None, "", "", 0.0, pd.DataFrame(columns=["Name", "Price", "Quantity"]), gr.update(visible=False), gr.update(visible=False), "Please upload an image."]
+    
+    thread_id = str(uuid.uuid4())
+    values, next_steps = start_or_resume_graph(image, thread_id)
+    
+    receipt_data = values.get("receipt_data", {})
+    items = receipt_data.get("items", [])
+    df_items = pd.DataFrame(items)
+    if df_items.empty:
+        df_items = pd.DataFrame(columns=["name", "price", "quantity"])
+    else:
+        # Standardize column names for the UI dataframe
+        df_items = df_items[["name", "price", "quantity"]]
+
+    return [
+        thread_id, 
+        receipt_data.get("restaurant_name", ""), 
+        receipt_data.get("date", ""), 
+        receipt_data.get("total_amount", 0.0),
+        df_items,
+        gr.update(visible=True), 
+        gr.update(visible=False), 
+        "Extracted! Please review and edit the table below if needed."
+    ]
+
+def confirm_receipt(thread_id, res_name, res_date, res_total, items_df):
+    # Convert dataframe back to list of dicts
+    items = items_df.to_dict("records")
+    receipt_data = {
+        "restaurant_name": res_name,
+        "date": res_date,
+        "total_amount": float(res_total),
+        "items": items
+    }
+        
+    values, next_steps = start_or_resume_graph(None, thread_id, updates={"receipt_data": receipt_data})
+    
+    matched_items = values.get("matched_items", [])
+    people = getPeople()
+    
+    # Section visibility updates
+    updates = [gr.update(visible=False), gr.update(visible=True)]
+    
+    # Row container visibility updates
+    row_visibility = []
+    # Component value/choices/visibility updates
+    component_updates = []
+
+    for i in range(MAX_ITEMS):
+        if i < len(matched_items):
+            item = matched_items[i]
+            row_visibility.append(gr.update(visible=True))
+            component_updates.extend([
+                gr.update(value=item.get("name", ""), visible=True),
+                gr.update(value=item.get("price", 0.0), visible=True),
+                gr.update(choices=people, value=[], visible=True)
+            ])
+        else:
+            row_visibility.append(gr.update(visible=False))
+            component_updates.extend([
+                gr.update(visible=False),
+                gr.update(visible=False),
+                gr.update(visible=False)
+            ])
+            
+    final_updates = updates + row_visibility + component_updates + ["Receipt confirmed. Please assign people to each item using the dropdowns."]
+    return final_updates
+
+def update_table_total(items_df):
+    try:
+        total = items_df["price"].astype(float).multiply(items_df["quantity"].astype(int)).sum()
+        return round(float(total), 2)
+    except:
+        return 0.0
+
+def calculate_split_v2(thread_id, final_amount, *args):
+    # args contains (name1, price1, people1, ...)
+    matching_data = args
+    
+    matched_items = []
+    for i in range(0, len(matching_data), 3):
+        name = matching_data[i]
+        price = matching_data[i+1]
+        people = matching_data[i+2]
+        
+        if name and price is not None and str(name).strip() != "":
+            matched_items.append({
+                "name": name,
+                "price": float(price),
+                "quantity": 1,
+                "people": people
+            })
+            
+    # Explicitly update the state so that re-runs use the latest assignments
+    config = {"configurable": {"thread_id": thread_id}}
+    graph.update_state(config, {"matched_items": matched_items, "final_amount_paid": float(final_amount)})
+    
+    # Resume/Re-run the graph
+    for event in graph.stream(None, config, stream_mode="values"):
+        pass
+        
+    state = graph.get_state(config)
+    splits = state.values.get("final_splits", [])
+    
+    if not splits:
+        return pd.DataFrame(columns=["Person", "Items Consumed", "Raw Share ($)", "Ratio (%)", "Final Split ($)"])
+    return pd.DataFrame(splits)
+
+with gr.Blocks(title="Catapult Splitter", theme=gr.themes.Soft()) as demo:
+    gr.Markdown("# 🧾 Catapult Receipt Splitter")
+    gr.Markdown("Split bills fairly based on consumption ratios.")
+    
+    thread_id_state = gr.State()
+    status_msg = gr.Textbox(label="Status", interactive=False)
+    
+    with gr.Row():
+        with gr.Column(scale=1):
+            image_input = gr.Image(type="filepath", label="Upload Receipt Image")
+            upload_btn = gr.Button("1. Extract Content", variant="primary")
+            
+        with gr.Column(scale=2, visible=False) as review_section:
+            gr.Markdown("### 2. Review & Edit Items")
+            with gr.Row():
+                res_name = gr.Textbox(label="Restaurant Name")
+                res_date = gr.Textbox(label="Date")
+            
+            items_df = gr.Dataframe(
+                headers=["name", "price", "quantity"],
+                datatype=["str", "number", "number"],
+                column_count=(3, "fixed"),
+                label="Check item prices and quantities",
+                interactive=True,
+                type="pandas"
+            )
+            
+            with gr.Row():
+                res_total = gr.Number(label="Calculated Items Total ($)", interactive=True)
+                confirm_btn = gr.Button("2. Confirm Items", variant="primary")
+            
+            # Auto-update the total when table changes
+            items_df.change(update_table_total, inputs=[items_df], outputs=[res_total])
+            
+    with gr.Column(visible=False) as matching_section:
+        gr.Markdown("### 3. Food Matching")
+        gr.Markdown("Assign people to each item. You can select multiple people per item.")
+        
+        matching_rows = []
+        matching_row_containers = []
+        with gr.Group():
+            for i in range(MAX_ITEMS):
+                with gr.Row(visible=False) as row:
+                    item_name = gr.Textbox(label=f"Item {i+1}", interactive=False, scale=2)
+                    item_price = gr.Number(label="Price", interactive=False, scale=1)
+                    item_people = gr.Dropdown(label="People", choices=[], multiselect=True, scale=3)
+                    matching_rows.extend([item_name, item_price, item_people])
+                    matching_row_containers.append(row)
+        
+        with gr.Row():
+            final_paid_input = gr.Number(label="Final Amount Paid (Actual Swipe Amount)", value=0)
+            calc_btn = gr.Button("3. Calculate Final Split", variant="primary", size="lg")
+
+    gr.Markdown("### 💰 Result Summary")
+    # Using wrap=True to handle the multi-line "Items Consumed" column
+    result_output = gr.Dataframe(label="Final Breakdown", interactive=False, wrap=True)
+    
+    # Flatten matching rows for inputs
+    matching_inputs = matching_rows
+    
+    # Wire up events with loading bars
+    upload_btn.click(
+        process_upload, 
+        inputs=[image_input], 
+        outputs=[thread_id_state, res_name, res_date, res_total, items_df, review_section, matching_section, status_msg],
+        show_progress=True
+    )
+    
+    confirm_outputs = [review_section, matching_section] + matching_row_containers + matching_rows + [status_msg]
+    confirm_btn.click(
+        confirm_receipt, 
+        inputs=[thread_id_state, res_name, res_date, res_total, items_df], 
+        outputs=confirm_outputs,
+        show_progress=True
+    )
+    
+    calc_btn.click(
+        calculate_split_v2, 
+        inputs=[thread_id_state, final_paid_input] + matching_inputs, 
+        outputs=[result_output],
+        show_progress=True
+    )
+
+if __name__ == "__main__":
+    demo.launch(theme=gr.themes.Soft())

data/catapult.csv

@@ -0,0 +1,9 @@
+s.no,name,email
+1,Sarath Rajan S,sarathrajansk@gmail.com
+2,Vidhula, 
+3,Gayathri,
+4,Anuradha,
+5,Neha,
+6,Srinithi,
+7,Krishna,
+8,Shuvrdip,

main.py

@@ -0,0 +1,84 @@
+"""
+Langgraph logic for Receipt Splitting
+Author: Sarath Rajan S
+Date: 26-01-2026
+"""
+
+import os
+import json
+from typing import TypedDict, List, Optional, Dict
+from langgraph.graph import StateGraph, START, END
+from langgraph.checkpoint.memory import MemorySaver
+from nodes.pydanticGenerator import pydanticGenerator
+from nodes.foodMatching import foodMatching, getPeople
+from nodes.splitCalculator import splitCalculator
+from nodes.receiptOCR import receiptOCR
+
+# Define the state shape
+class GraphState(TypedDict):
+    image_path: str
+    receipt_text: Optional[str]
+    receipt_data: Optional[Dict]
+    matched_items: Optional[List[dict]]
+    final_amount_paid: Optional[float]
+    final_splits: Optional[List[Dict]]
+
+def ocr_node(state: GraphState):
+    print("--- OCR Node ---")
+    text = receiptOCR(state["image_path"])
+    return {"receipt_text": text}
+
+def pydantic_node(state: GraphState):
+    print("--- Pydantic Generator Node ---")
+    json_res = pydanticGenerator(state["receipt_text"])
+    try:
+        data = json.loads(json_res)
+    except Exception as e:
+        print(f"Error parsing JSON: {e}")
+        data = {"items": [], "total_amount": 0}
+    
+    return {"receipt_data": data}
+
+def review_node(state: GraphState):
+    print("--- Review Node ---")
+    # Initialize matched items here after potential edits to receipt_data
+    matches = foodMatching(state["receipt_data"], None)
+    return {"matched_items": matches}
+
+def calculator_node(state: GraphState):
+    print("--- Split Calculator Node ---")
+    splits = splitCalculator(
+        state["receipt_data"], 
+        state.get("matched_items", []), 
+        state.get("final_amount_paid")
+    )
+    return {"final_splits": splits}
+
+# Define the Graph
+workflow = StateGraph(GraphState)
+
+workflow.add_node("ocr", ocr_node)
+workflow.add_node("pydantic", pydantic_node)
+workflow.add_node("review", review_node)
+workflow.add_node("calculator", calculator_node)
+
+workflow.add_edge(START, "ocr")
+workflow.add_edge("ocr", "pydantic")
+workflow.add_edge("pydantic", "review")
+workflow.add_edge("review", "calculator")
+workflow.add_edge("calculator", END)
+
+# Set up checkpointer
+memory = MemorySaver()
+
+# Compile with interrupts
+# interrupt_before review: let user edit receipt_data (Step 3: Make changes)
+# interrupt_before matching: move to food matching (Step 4)
+# interrupt_before calculator: let user check/edit matched_items and discount (Step 5)
+app = workflow.compile(
+    checkpointer=memory,
+    interrupt_before=["review", "calculator"]
+)
+
+def get_graph():
+    return app

nodes/__init__.py

@@ -0,0 +1,12 @@
+from .receiptOCR import receiptOCR
+from .pydanticGenerator import pydanticGenerator
+from .foodMatching import foodMatching
+from .splitCalculator import splitCalculator
+
+__all__ = [
+    "receiptOCR",
+    "pydanticGenerator",
+    "foodMatching",
+    "splitCalculator",
+]
+

nodes/foodMatching.py

@@ -0,0 +1,60 @@
+"""
+Used to assign who ate which food item for easier splitting of bills
+
+Author: Sarath Rajan S
+Date: 26-01-2026
+"""
+from nodes.models.models import Receipt
+
+import csv
+
+def getPeople():
+    """
+    Gets the list of people from the CSV file.
+    """
+    people = []
+    try:
+        with open("data/catapult.csv", "r") as f:
+            reader = csv.DictReader(f)
+            people = [row["name"] for row in reader]
+    except Exception as e:
+        print(f"Error reading people: {e}")
+    return people
+
+def foodMatching(receipt_data: dict, matched_items: list = None):
+    """
+    Assigns food items to people based on the receipt.
+    If matched_items is already provided (resumed), returns it.
+    Otherwise, explodes items with qty > 1 into individual rows.
+    """
+    if matched_items:
+        return matched_items
+    
+    # Initialize matched items from receipt items
+    items = receipt_data.get("items", [])
+    new_matches = []
+    for item in items:
+        try:
+            price = float(item.get("price", 0))
+            total_qty = int(item.get("quantity", 1))
+        except:
+            price = 0.0
+            total_qty = 1
+            
+        # Explode quantity: if qty is 3, create 3 rows
+        unit_price = price # Assuming price in receipt_data is per-unit
+        # Check if the AI provided total price instead of unit price
+        # (models often fluctuate here, but standard schema is per-item)
+        
+        for q in range(total_qty):
+            display_name = item.get("name", "Unknown")
+            if total_qty > 1:
+                display_name = f"{display_name} ({q+1}/{total_qty})"
+                
+            new_matches.append({
+                "name": display_name,
+                "price": unit_price,
+                "quantity": 1, # Each row represents 1 unit
+                "people": []
+            })
+    return new_matches

nodes/models/models.py

@@ -0,0 +1,14 @@
+from pydantic import BaseModel
+from typing import List
+
+class items(BaseModel):
+    name: str
+    price: float
+    quantity: int
+
+class Receipt(BaseModel):
+    restaurant_name: str
+    date: str
+    time: str
+    items: List[items]
+    total_amount: float

nodes/pydanticGenerator.py

@@ -0,0 +1,64 @@
+"""
+This module is used to generate structured information from the receipt text.
+
+Author: Sarath Rajan S
+Date: 26-01-2026
+"""
+
+from google import genai
+from google.genai import types
+from nodes.models.models import Receipt
+from dotenv import load_dotenv
+load_dotenv()
+
+client = genai.Client()
+
+
+
+def pydanticGenerator(receipt_text):
+    response = client.models.generate_content(
+    model='gemini-2.5-flash',
+    contents=receipt_text,
+    config=types.GenerateContentConfig(
+        response_mime_type='application/json',
+        response_schema=Receipt,
+    ),
+    )
+    return response.text
+
+
+if __name__ == "__main__":
+    receipt_text = """
+    1 25/01/26 Dine In: $3
+    Bill No.; 1147
+    Bhier: cashier
+    [Note] No Mushroom
+    Chicken Classic 1 365.00 365.00
+    Hot & Sour Soup
+    [Note] No Mushroom
+    Crumbs 1 415.00 415.00
+    Mushroom
+    Croquette
+    Fire Cracker Ebi 1 395.00 395.00
+    Uramaki (4 Pcs)
+    Xo Garlic Sauce 1 595.00 595.00
+    Prawn |
+    Kaki-Age Uramaki 1 625.00 625.00 |
+    (8 Pes)
+    Peri-peri Crispy 1 215.00 215.00
+    1 195.00 195.00 |
+    Vietnamese Crispy 1 595.00 595.00
+    Lambs
+    a cence on eee ci SS
+    Total Qty: 9 oe 3795.00
+    vice Charge 379.50
+    GEST 2E% 94.88
+    CGST 2.5% 94.88
+    | Round off 0,26
+    | Grand Total 4364.00
+    Paid Via Other [Pending]
+    OO
+    | Service Charge is Optional
+    Thank You...! & Visit Us Again...!
+    """
+    print(pydanticGenerator(receipt_text))

nodes/receiptOCR.py

@@ -0,0 +1,15 @@
+"""
+Used to extract the receipt data from the receipt image
+
+Author: Sarath Rajan S
+Date: 26-01-2026
+"""
+
+from tools.ocr import extract_text_from_receipt,extract_raw_text
+
+def receiptOCR(image_path: str) -> str:
+    """
+    Uses OCR to extract the text from the image
+    """
+    text = extract_raw_text(image_path)
+    return text if text else ""

nodes/splitCalculator.py

@@ -0,0 +1,69 @@
+"""
+This module is used to calculate the split of the bill among people.
+
+Author: Sarath Rajan S
+Date: 26-01-2026
+"""
+
+def splitCalculator(receipt_data: dict, matched_items: list, final_amount_paid: float = None):
+    """
+    Calculates the split of the bill.
+    1. Calculate Raw Individual Total
+    2. Ratio = Individual Total / Raw Receipt Total
+    3. Final Split = Ratio * Final Amount Paid
+    """
+    # Use the total confirmed by the user in the UI as the base for the ratio
+    # This allows users to manualy override the "original amount" if needed.
+    raw_receipt_total = receipt_data.get("total_amount", 0)
+    
+    # Fallback to sum of items if total_amount is not set/valid
+    if raw_receipt_total <= 0:
+        raw_receipt_total = sum(float(item.get("price", 0)) * int(item.get("quantity", 1)) for item in matched_items)
+    
+    # If final_amount_paid is not provided or zero, assume no discount/tax
+    if final_amount_paid is None or final_amount_paid <= 0:
+        final_amount_paid = raw_receipt_total
+        
+    person_data = {} # {name: {"items": [], "raw_sum": 0}}
+    
+    for item in matched_items:
+        iname = item.get("name", "Unknown")
+        iprice = float(item.get("price", 0))
+        iqty = int(item.get("quantity", 1))
+        item_total = iprice * iqty
+        people = item.get("people", [])
+        
+        if not people:
+            people = ["Unassigned"]
+            
+        share = item_total / len(people)
+        
+        for person in people:
+            if person not in person_data:
+                person_data[person] = {"items": [], "raw_sum": 0}
+            
+            # Since items are now exploded in the matching phase, iqty is usually 1 here
+            item_display = f"{iname} @ ${iprice}"
+            if iqty > 1:
+                item_display = f"{iname} (x{iqty}) @ ${iprice}"
+                
+            person_data[person]["items"].append(item_display)
+            person_data[person]["raw_sum"] += share
+            
+    table_data = []
+    for person, data in person_data.items():
+        # Step: Ratio of person raw total vs original raw total
+        ratio = data["raw_sum"] / raw_receipt_total if raw_receipt_total > 0 else 0
+        
+        # Step: Apply final amount paid based on that ratio
+        final_cost = ratio * final_amount_paid
+        
+        table_data.append({
+            "Person": person,
+            "Items Consumed": "\n".join(data["items"]), # Multi-line string for "nested" look
+            "Raw Share ($)": round(data["raw_sum"], 2),
+            "Ratio (%)": f"{round(ratio * 100, 1)}%",
+            "Final Split ($)": round(final_cost, 2)
+        })
+        
+    return table_data

pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "catapultsplit"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "google-genai>=1.60.0",
+    "langgraph>=1.0.7",
+    "pydantic>=2.12.5",
+    "pytesseract>=0.3.13",
+    "streamlit>=1.53.1",
+    "Pillow>=11.1.0",
+    "python-dotenv>=1.2.1",
+    "gradio>=6.4.0",
+]
+
+[dependency-groups]
+dev = [
+    "pyrefly>=0.49.0",
+]

pyrefly.toml

@@ -0,0 +1,63 @@
+# Pyrefly configuration for catapultSplit
+
+###### configuring what to type check and where to import from
+
+# check all Python files under the containing directory
+project-includes = ["**/*.py*"]
+
+# exclude some uninteresting files
+project-excludes = [
+    "**/node_modules",
+    "**/__pycache__",
+    "**/.venv/**",
+    "**/.[!/.]*/**",
+    "**/poc/**"  # Excluding POC if it's just experimental
+]
+
+# perform an upward search for `.gitignore`, `.ignore`, and `.git/info/exclude`, and
+# add those to `project-excludes` automatically
+use-ignore-files = true
+
+# import project files from "."
+search-path = ["."]
+
+# let Pyrefly try to guess your search path
+disable-search-path-heuristics = false
+
+###### configuring your python environment
+
+# assume we're running on mac (darwin) as per user environment
+python-platform = "darwin"
+
+# assume the Python version we're using is 3.13
+python-version = "3.13"
+
+# is Pyrefly disallowed from querying for an interpreter?
+skip-interpreter-query = false
+
+#### configuring your type check settings
+
+# wildcards for which Pyrefly will unconditionally replace the import with `typing.Any`
+replace-imports-with-any = []
+
+# wildcards for which Pyrefly will replace the import with `typing.Any` if it can't be found
+ignore-missing-imports = [
+    "google.genai.*",
+    "langgraph.*",
+    "pytesseract.*",
+    "streamlit.*",
+    "PIL.*"
+]
+
+# should Pyrefly skip type checking if we find a generated file?
+ignore-errors-in-generated-code = true
+
+# what should Pyrefly do when it encounters a function that is untyped?
+untyped-def-behavior = "check-and-infer-return-type"
+
+# can Pyrefly recognize ignore directives other than `# pyrefly: ignore` and `# type: ignore`
+permissive-ignores = true
+
+[errors]
+# You can disable specific error codes here if needed, for example:
+# "unused-expression" = false

tools/ocr.py

@@ -0,0 +1,52 @@
+"""
+Uses OCR to extract the raw text from a given image, optimized for receipts.
+
+Author: Sarath Rajan S
+Date: 26-01-2026
+"""
+
+import pytesseract
+from typing import Optional
+from PIL import Image, ImageOps, ImageFilter
+
+def extract_raw_text(image_path: str) -> Optional[str]:
+    """
+    Uses pytesseract to extract the raw text from the image.
+    Includes basic preprocessing to improve OCR accuracy for receipts.
+    """
+    try:
+        # Open the image using PIL
+        with Image.open(image_path) as img:
+            # 1. Convert to grayscale to reduce noise
+            img = ImageOps.grayscale(img)
+            
+            # 2. Enhance contrast and sharpen for better character definition
+            img = img.filter(ImageFilter.SHARPEN)
+            
+            # 3. Use custom Tesseract config
+            # --psm 4: Assume a single column of text of variable sizes (common in receipts)
+            # --oem 3: Default, based on what is available
+            custom_config = r'--oem 3 --psm 4'
+            
+            text = pytesseract.image_to_string(img, config=custom_config)
+            return str(text).strip() if text else None
+            
+    except Exception as e:
+        print(f"Error extracting text from {image_path}: {e}")
+        return None
+
+def extract_text_from_receipt(image_path: str) -> Optional[str]:
+    """
+    Alias for extract_raw_text, specifically intended for receipt processing.
+    Ensures the text is cleaned up before returning.
+    """
+    text = extract_raw_text(image_path)
+    if text:
+        # Basic cleanup: remove excessive empty lines
+        lines = [line.strip() for line in text.split('\n') if line.strip()]
+        return '\n'.join(lines)
+    return None
+
+
+if __name__ == "__main__":
+    print(extract_text_from_receipt("/Users/sarathrajan/Desktop/catapultSplit/utils/architecture/receipts/receipt-1.jpeg"))