updated workflow

.github/workflows/hf_sync.yml

@@ -17,4 +17,4 @@ jobs:
         env:
           HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
-          git push https://Sarathrsk03:$HF_TOKEN@huggingface.co/spaces/Sarathrsk03/Catapult-Splitter main
+          git push --force https://Sarathrsk03:$HF_TOKEN@huggingface.co/spaces/Sarathrsk03/Catapult-Splitter main

README.md

@@ -9,5 +9,115 @@ app_file: app.py
 pinned: false
 ---
 
-# Catapult Splitter
-Split bills fairly based on consumption ratios.
+# 🧾 Catapult Receipt Splitter
+
+Catapult Splitter is an AI-powered receipt splitting application that uses **LangGraph**, **Gemini 2.5 Flash**, and **Tesseract OCR** to help friends split bills fairly based on actual consumption ratios. Unlike simple equal-split apps, Catapult handles complex scenarios like unshared items, taxes, and service charges proportionally.
+
+## 🚀 Features
+
+- **AI-Powered OCR**: Automatically extracts restaurant names, dates, items, and prices from receipt images.
+- **Smart Pydantic Extraction**: Uses Gemini to structure messy OCR text into valid JSON.
+- **Human-in-the-Loop**: Interrupts the workflow to allow users to verify extracted items and assign people.
+- **Proportional Splitting**: Automatically distributes non-itemized costs (tax, tips, service charges) based on each person's consumption ratio.
+- **Export to CSV/Table**: Provides a clear breakdown of who owes what and why.
+
+## 🏗️ Architecture
+
+The application is built using a state-machine approach with **LangGraph**.
+
+### LangGraph Workflow
+
+```mermaid
+graph TD
+    START((Start)) --> OCR[OCR Node]
+    OCR --> PYD[Pydantic Generator]
+    PYD -->|Interrupt: Review| REVIEW[Review Node]
+    REVIEW -->|Interrupt: Matching| CALC[Calculator Node]
+    CALC --> END((End))
+    
+    subgraph "Nodes"
+    OCR -.- |pytesseract| OCR
+    PYD -.- |Google Gemini| PYD
+    CALC -.- |Proportional Logic| CALC
+    end
+```
+
+### Logical Data Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI as Gradio Frontend
+    participant LG as LangGraph Workflow
+    participant LLM as Gemini 2.5 Flash
+
+    User->>UI: Upload Receipt
+    UI->>LG: Start Workflow
+    LG->>LG: Extract Raw Text (OCR)
+    LG->>LLM: Structure Text to JSON
+    LG-->>UI: Interrupt (Review Items)
+    User->>UI: Confirm/Edit Items
+    UI->>LG: Resume (Update State)
+    LG-->>UI: Interrupt (Match People)
+    User->>UI: Assign People to Items
+    UI->>LG: Resume (Calculate)
+    LG->>LG: Run Proportional Split
+    LG-->>User: Display Final Breakdown
+```
+
+## 🛠️ Tech Stack
+
+- **Framework**: [LangGraph](https://github.com/langchain-ai/langgraph)
+- **UI**: [Gradio](https://gradio.app/)
+- **LLM**: Google Gemini 2.5 Flash
+- **OCR**: Pytesseract (Tesseract OCR)
+- **Data Handling**: Pandas & Pydantic
+- **Environment**: Managed with `uv`
+
+## 📦 Installation & Local Setup
+
+### Prerequisites
+- Python 3.13+
+- Tesseract OCR installed on your system (`brew install tesseract` on Mac, `apt install tesseract-ocr` on Linux)
+- A Google Gemini API Key
+
+### Setup
+1. **Clone the repository**:
+   ```bash
+   git clone <your-repo-url>
+   cd catapultSplit
+   ```
+
+2. **Install dependencies**:
+   Using `uv` (recommended):
+   ```bash
+   uv sync
+   ```
+
+3. **Configure Environment**:
+   Create a `.env` file:
+   ```env
+   GOOGLE_API_KEY=your_gemini_api_key_here
+   ```
+
+4. **Run the app**:
+   ```bash
+   python app.py
+   ```
+
+## 🚢 Deployment (Hugging Face Spaces)
+
+This project is configured for automatic deployment via GitHub Actions.
+
+1. **GitHub Secret**: Add `HF_TOKEN` to your GitHub repository secrets.
+2. **Hugging Face Secret**: Add `GOOGLE_API_KEY` to your Space's variables.
+3. **Trigger**: Any push to the `main` branch will automatically sync to the Hugging Face Space.
+
+## 📝 How the Split Logic Works
+
+The "Fair Split" is calculated in three steps:
+1. **Individual Raw Total**: Sum of items assigned to a person (shared items are divided equally among sharers).
+2. **Ratio**: `Person's Raw Total / Sum of All Items`.
+3. **Final Result**: `Ratio * Final Amount Paid (swipe amount)`.
+
+This ensures that taxes, discounts, and tips are distributed according to how much value each person actually received.