splitkaro 0.1.0__tar.gz

splitkaro-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kanhaiya Kumar
+
+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.

splitkaro-0.1.0/PKG-INFO

@@ -0,0 +1,323 @@
+Metadata-Version: 2.4
+Name: splitkaro
+Version: 0.1.0
+Summary: Bill splitter for friends, flatmates and trips: split shared expenses, see who owes whom, and settle up with the fewest payments and UPI links.
+Author: Kanhaiya Kumar
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/K70281095/splitkaro
+Project-URL: Issues, https://github.com/K70281095/splitkaro/issues
+Project-URL: Changelog, https://github.com/K70281095/splitkaro/blob/main/CHANGELOG.md
+Keywords: bill-splitter,split-expenses,expense-splitter,group-expenses,settle-up,splitwise-alternative,upi,india,roommates,travel,personal-finance,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# splitkaro: split expenses & settle up with UPI
+
+**A bill splitter for friends, flatmates and trips: track shared expenses, see who owes whom, and settle up with the fewest payments and one-tap UPI links.**
+
+[![CI](https://github.com/K70281095/splitkaro/actions/workflows/ci.yml/badge.svg)](https://github.com/K70281095/splitkaro/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.9%20%E2%80%93%203.13-blue)
+![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+*Split karo* is Hinglish for "split it". It is the phrase every group says at the end of a trip,
+right before the *hisaab* (the accounts) gets complicated.
+
+Every trip, every shared flat and every office lunch ends with the same questions:
+
+- Who paid for what, and who still owes whom?
+- The hotel was ₹9,000, but a couple shared one room. How do we split that fairly?
+- Five people owe each other money. Do we really need ten transfers?
+- Somebody paid in dollars. What is that in rupees?
+
+`splitkaro` answers all of them from your terminal. It keeps the group's records in one readable
+JSON file, does every calculation with exact decimal arithmetic so the totals always add up to
+the paisa, and works out the smallest set of payments that settles everyone, with UPI links you
+can open in GPay, PhonePe, Paytm or BHIM.
+
+```console
+$ splitkaro balances
+Asha             gets back ₹2,618.00
+Ravi             owes ₹682.00
+Meera            owes ₹1,936.00
+
+$ splitkaro settle --upi
+2 payment(s) settle everything:
+  Meera pays Asha ₹1,936.00
+    upi://pay?pa=asha%40okbank&pn=Asha&am=1936.00&cu=INR&tn=splitkaro%3A+Goa+trip
+  Ravi pays Asha ₹682.00
+    upi://pay?pa=asha%40okbank&pn=Asha&am=682.00&cu=INR&tn=splitkaro%3A+Goa+trip
+```
+
+---
+
+## Contents
+
+- [Features](#features)
+- [Install](#install)
+- [A full example: a Goa trip](#a-full-example-a-goa-trip)
+- [Ways to split](#ways-to-split)
+- [Command reference](#command-reference)
+- [Your data](#your-data)
+- [Using splitkaro from Python](#using-splitkaro-from-python)
+- [How it works](#how-it-works)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+| | |
+|---|---|
+| **Four ways to split** | Equally, by exact amounts, by percentage, or by shares (a couple counts as 2). |
+| **Several payers** | "I paid ₹1,000 and you paid ₹500" for the same bill works naturally. |
+| **Fewest payments** | Suggests at most *n − 1* transfers for *n* people, and pairs up exact matches first. |
+| **UPI links** | One `upi://pay` link per payment; the payer just confirms it in their app. |
+| **Exact to the paisa** | Decimal arithmetic and fair rounding: ₹100 split three ways is 33.34 + 33.33 + 33.33. |
+| **Foreign currency** | Record an expense in USD or EUR; it is converted with the rate you set. |
+| **Reports** | Spending by category and month, and who paid vs. who consumed. |
+| **Statements** | A running, line-by-line history of one person's balance. |
+| **CSV import/export** | Move data to and from spreadsheets. Imports are all-or-nothing. |
+| **Your data, your file** | Plain JSON you can read, back up, sync or put under git. No account, no server, no ads. |
+| **Zero dependencies** | Pure Python standard library, Python 3.9+. |
+
+## Install
+
+```bash
+pip install splitkaro
+```
+
+Or straight from GitHub:
+
+```bash
+pip install git+https://github.com/K70281095/splitkaro.git
+```
+
+Check it works:
+
+```bash
+splitkaro --version
+```
+
+## A full example: a Goa trip
+
+Asha, Ravi and Meera go to Goa. Asha travels with her partner, so on the hotel she counts as two.
+
+```bash
+splitkaro init "Goa trip"
+splitkaro member add Asha Ravi Meera
+splitkaro member upi Asha asha@okbank          # so others can pay her with one tap
+
+# Hotel: Asha paid, split by shares (Asha 2, Ravi 1, Meera 1)
+splitkaro add "Hotel (2 nights)" 9000 --paid-by Asha --shares Asha=2,Ravi=1,Meera=1 --category stay
+
+# Dinner: Ravi paid, split equally among everyone (the default)
+splitkaro add "Dinner at the shack" 2400 --paid-by Ravi --category food
+
+# Scooters: two people paid, and only they used them
+splitkaro add "Scooter rental" 1500 --paid-by Asha=1000 --paid-by Meera=500 --among Asha,Meera --category travel
+
+# Parasailing was paid in dollars
+splitkaro rate USD 83.20
+splitkaro add "Parasailing" 30 --currency USD --paid-by Meera --category fun
+
+# Groceries: everyone took different things
+splitkaro add "Groceries" 1260 --paid-by Ravi --exact Asha=500,Ravi=460,Meera=300 --category food
+```
+
+Where does everyone stand, and how do they square up?
+
+```console
+$ splitkaro settle
+2 payment(s) settle everything:
+  Meera pays Asha ₹1,936.00
+  Ravi pays Asha ₹682.00
+```
+
+Where did the money go?
+
+```console
+$ splitkaro report
+Goa trip: 5 expense(s), ₹16,656.00 in total
+
+By category
+  stay                  ₹9,000.00  54%
+  food                  ₹3,660.00  22%
+  fun                   ₹2,496.00  15%
+  travel                ₹1,500.00  9%
+
+By month
+  2026-11              ₹16,656.00
+
+  member                     paid          share
+  Asha                 ₹10,000.00      ₹7,382.00
+  Ravi                  ₹3,660.00      ₹4,342.00
+  Meera                 ₹2,996.00      ₹4,932.00
+```
+
+Meera wants to see exactly how she ended up owing ₹1,936:
+
+```console
+$ splitkaro statement meera
+2026-11-01      -₹2,250.00      -₹2,250.00  #1 Hotel (2 nights)
+2026-11-01        -₹800.00      -₹3,050.00  #2 Dinner at the shack
+2026-11-02        -₹250.00      -₹3,300.00  #3 Scooter rental
+2026-11-02       ₹1,664.00      -₹1,636.00  #4 Parasailing
+2026-11-03        -₹300.00      -₹1,936.00  #5 Groceries
+
+Meera owes ₹1,936.00
+```
+
+Once the money has moved, record it, and everyone is back to zero:
+
+```bash
+splitkaro pay Meera Asha 1936
+splitkaro pay Ravi Asha 682
+splitkaro settle      # Everyone is settled up. 🎉
+```
+
+The same trip is available as [`examples/goa-trip.csv`](examples/goa-trip.csv), which you can
+load with `splitkaro import examples/goa-trip.csv`.
+
+## Ways to split
+
+| Option | Example | Meaning |
+|---|---|---|
+| *(none)* | `--paid-by Ravi` | Equally among **all** members. |
+| `--among` | `--among Asha,Meera` | Equally among the listed members. |
+| `--exact` | `--exact Asha=500,Ravi=460,Meera=300` | Fixed amounts; must add up to the total. |
+| `--percent` | `--percent Asha=50,Ravi=25,Meera=25` | Percentages; must add up to 100. |
+| `--shares` | `--shares Asha=2,Ravi=1,Meera=1` | Proportional weights, e.g. couples, or nights stayed. |
+
+Whoever paid is given with `--paid-by NAME`, or `--paid-by NAME=AMOUNT` repeated when several
+people paid the same bill. Names are case-insensitive.
+
+## Command reference
+
+| Command | What it does |
+|---|---|
+| `splitkaro init NAME [--currency INR]` | Start a group (creates `splitkaro.json`). |
+| `splitkaro member add NAME... [--upi ID]` | Add members. |
+| `splitkaro member upi NAME ID` | Set a member's UPI ID. |
+| `splitkaro member list` / `remove NAME` | List members, or remove one who has no history. |
+| `splitkaro add DESC AMOUNT --paid-by ...` | Record an expense (`--category`, `--date`, `--currency`, `--note`). |
+| `splitkaro list [--month YYYY-MM] [--category C] [--member M]` | List expenses. |
+| `splitkaro delete ID` | Delete an expense. |
+| `splitkaro balances [--json]` | Who gets money back, who owes. |
+| `splitkaro settle [--upi] [--json]` | Fewest payments to settle everything. |
+| `splitkaro pay FROM TO AMOUNT` | Record a payment between members. |
+| `splitkaro statement NAME` | Running history of one member's balance. |
+| `splitkaro report [filters] [--json]` | Totals by category, month and member. |
+| `splitkaro rate CUR VALUE` | Exchange rate: 1 CUR = VALUE in the group currency. |
+| `splitkaro export FILE` / `import FILE` | CSV out and in (`-` for stdout/stdin). |
+
+Every command accepts `--file PATH` (or the `SPLITKARO_FILE` environment variable) to work with
+more than one group, for example `splitkaro -f flat.json balances`.
+
+Errors are printed as `splitkaro: <message>` with exit code `1`, and nothing is saved when a command
+fails.
+
+## Your data
+
+A group lives in a single JSON file, `splitkaro.json` by default (shortened here):
+
+```json
+{
+  "version": 1,
+  "name": "Goa trip",
+  "currency": "INR",
+  "members": [{ "name": "Asha", "upi": "asha@okbank" }, { "name": "Ravi", "upi": null }],
+  "expenses": [
+    {
+      "id": 2,
+      "date": "2026-11-01",
+      "description": "Dinner at the shack",
+      "amount": "2400.00",
+      "paid_by": { "Ravi": "2400.00" },
+      "split": { "kind": "equal", "among": ["Asha", "Ravi", "Meera"], "values": {} }
+    }
+  ]
+}
+```
+
+- Amounts are stored as strings, never floats, so nothing is ever rounded away.
+- Files are written atomically: a crash or a full disk cannot leave a half-written file.
+- There is no account, server or tracking. Share the file however your group likes.
+
+The CSV format is documented in [docs/csv-format.md](docs/csv-format.md).
+
+## Using splitkaro from Python
+
+```python
+import datetime as dt
+from decimal import Decimal
+
+from splitkaro import Expense, Group, Split, balances, settle
+
+group = Group("Flat 302")
+for name in ("Asha", "Ravi", "Meera"):
+    group.add_member(name)
+
+group.add_expense(Expense(
+    id=0, description="Electricity", amount=Decimal("3120"),
+    paid_by={"Ravi": Decimal("3120")}, split=Split.equal(["Asha", "Ravi", "Meera"]),
+    date=dt.date(2026, 11, 5), currency="INR", category="bills",
+))
+
+for t in settle(balances(group)):
+    print(f"{t.sender} pays {t.receiver} {t.amount}")
+```
+
+## How it works
+
+- **Rounding:** amounts are split with the largest-remainder method on whole paise, so the parts
+  always add up to the exact total and nobody is ever short-changed by more than one paisa.
+- **Balances:** each member's balance is what they paid minus their share, plus payments made
+  minus payments received. Balances always add up to exactly zero.
+- **Settling:** exact matches (someone owes exactly what someone else is owed) are paired first;
+  the rest is settled greedily between the largest debtor and the largest creditor. This never
+  needs more than *n − 1* payments.
+
+The details, with worked examples, are in [docs/how-it-works.md](docs/how-it-works.md).
+
+## Roadmap
+
+- [ ] Recurring expenses (rent, Wi-Fi, maid) added automatically each month
+- [ ] UPI QR codes in the terminal
+- [ ] Simplify across groups (one payment per pair of people for several trips)
+- [ ] Budgets per category with warnings
+- [ ] Hindi and other Indian language output
+- [ ] A small web or mobile front end on top of the same file format
+
+Ideas and pull requests are welcome, see the [issues](https://github.com/K70281095/splitkaro/issues).
+
+## Contributing
+
+Bug reports, ideas, translations and code are all welcome. Please read
+[CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md). To report a
+security problem, see [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) © 2026 Kanhaiya Kumar
+
+*UPI is a system of the National Payments Corporation of India. splitkaro only creates standard
+`upi://pay` links and never handles money, bank details or PINs.*

splitkaro-0.1.0/README.md

@@ -0,0 +1,292 @@
+# splitkaro: split expenses & settle up with UPI
+
+**A bill splitter for friends, flatmates and trips: track shared expenses, see who owes whom, and settle up with the fewest payments and one-tap UPI links.**
+
+[![CI](https://github.com/K70281095/splitkaro/actions/workflows/ci.yml/badge.svg)](https://github.com/K70281095/splitkaro/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.9%20%E2%80%93%203.13-blue)
+![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+*Split karo* is Hinglish for "split it". It is the phrase every group says at the end of a trip,
+right before the *hisaab* (the accounts) gets complicated.
+
+Every trip, every shared flat and every office lunch ends with the same questions:
+
+- Who paid for what, and who still owes whom?
+- The hotel was ₹9,000, but a couple shared one room. How do we split that fairly?
+- Five people owe each other money. Do we really need ten transfers?
+- Somebody paid in dollars. What is that in rupees?
+
+`splitkaro` answers all of them from your terminal. It keeps the group's records in one readable
+JSON file, does every calculation with exact decimal arithmetic so the totals always add up to
+the paisa, and works out the smallest set of payments that settles everyone, with UPI links you
+can open in GPay, PhonePe, Paytm or BHIM.
+
+```console
+$ splitkaro balances
+Asha             gets back ₹2,618.00
+Ravi             owes ₹682.00
+Meera            owes ₹1,936.00
+
+$ splitkaro settle --upi
+2 payment(s) settle everything:
+  Meera pays Asha ₹1,936.00
+    upi://pay?pa=asha%40okbank&pn=Asha&am=1936.00&cu=INR&tn=splitkaro%3A+Goa+trip
+  Ravi pays Asha ₹682.00
+    upi://pay?pa=asha%40okbank&pn=Asha&am=682.00&cu=INR&tn=splitkaro%3A+Goa+trip
+```
+
+---
+
+## Contents
+
+- [Features](#features)
+- [Install](#install)
+- [A full example: a Goa trip](#a-full-example-a-goa-trip)
+- [Ways to split](#ways-to-split)
+- [Command reference](#command-reference)
+- [Your data](#your-data)
+- [Using splitkaro from Python](#using-splitkaro-from-python)
+- [How it works](#how-it-works)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+| | |
+|---|---|
+| **Four ways to split** | Equally, by exact amounts, by percentage, or by shares (a couple counts as 2). |
+| **Several payers** | "I paid ₹1,000 and you paid ₹500" for the same bill works naturally. |
+| **Fewest payments** | Suggests at most *n − 1* transfers for *n* people, and pairs up exact matches first. |
+| **UPI links** | One `upi://pay` link per payment; the payer just confirms it in their app. |
+| **Exact to the paisa** | Decimal arithmetic and fair rounding: ₹100 split three ways is 33.34 + 33.33 + 33.33. |
+| **Foreign currency** | Record an expense in USD or EUR; it is converted with the rate you set. |
+| **Reports** | Spending by category and month, and who paid vs. who consumed. |
+| **Statements** | A running, line-by-line history of one person's balance. |
+| **CSV import/export** | Move data to and from spreadsheets. Imports are all-or-nothing. |
+| **Your data, your file** | Plain JSON you can read, back up, sync or put under git. No account, no server, no ads. |
+| **Zero dependencies** | Pure Python standard library, Python 3.9+. |
+
+## Install
+
+```bash
+pip install splitkaro
+```
+
+Or straight from GitHub:
+
+```bash
+pip install git+https://github.com/K70281095/splitkaro.git
+```
+
+Check it works:
+
+```bash
+splitkaro --version
+```
+
+## A full example: a Goa trip
+
+Asha, Ravi and Meera go to Goa. Asha travels with her partner, so on the hotel she counts as two.
+
+```bash
+splitkaro init "Goa trip"
+splitkaro member add Asha Ravi Meera
+splitkaro member upi Asha asha@okbank          # so others can pay her with one tap
+
+# Hotel: Asha paid, split by shares (Asha 2, Ravi 1, Meera 1)
+splitkaro add "Hotel (2 nights)" 9000 --paid-by Asha --shares Asha=2,Ravi=1,Meera=1 --category stay
+
+# Dinner: Ravi paid, split equally among everyone (the default)
+splitkaro add "Dinner at the shack" 2400 --paid-by Ravi --category food
+
+# Scooters: two people paid, and only they used them
+splitkaro add "Scooter rental" 1500 --paid-by Asha=1000 --paid-by Meera=500 --among Asha,Meera --category travel
+
+# Parasailing was paid in dollars
+splitkaro rate USD 83.20
+splitkaro add "Parasailing" 30 --currency USD --paid-by Meera --category fun
+
+# Groceries: everyone took different things
+splitkaro add "Groceries" 1260 --paid-by Ravi --exact Asha=500,Ravi=460,Meera=300 --category food
+```
+
+Where does everyone stand, and how do they square up?
+
+```console
+$ splitkaro settle
+2 payment(s) settle everything:
+  Meera pays Asha ₹1,936.00
+  Ravi pays Asha ₹682.00
+```
+
+Where did the money go?
+
+```console
+$ splitkaro report
+Goa trip: 5 expense(s), ₹16,656.00 in total
+
+By category
+  stay                  ₹9,000.00  54%
+  food                  ₹3,660.00  22%
+  fun                   ₹2,496.00  15%
+  travel                ₹1,500.00  9%
+
+By month
+  2026-11              ₹16,656.00
+
+  member                     paid          share
+  Asha                 ₹10,000.00      ₹7,382.00
+  Ravi                  ₹3,660.00      ₹4,342.00
+  Meera                 ₹2,996.00      ₹4,932.00
+```
+
+Meera wants to see exactly how she ended up owing ₹1,936:
+
+```console
+$ splitkaro statement meera
+2026-11-01      -₹2,250.00      -₹2,250.00  #1 Hotel (2 nights)
+2026-11-01        -₹800.00      -₹3,050.00  #2 Dinner at the shack
+2026-11-02        -₹250.00      -₹3,300.00  #3 Scooter rental
+2026-11-02       ₹1,664.00      -₹1,636.00  #4 Parasailing
+2026-11-03        -₹300.00      -₹1,936.00  #5 Groceries
+
+Meera owes ₹1,936.00
+```
+
+Once the money has moved, record it, and everyone is back to zero:
+
+```bash
+splitkaro pay Meera Asha 1936
+splitkaro pay Ravi Asha 682
+splitkaro settle      # Everyone is settled up. 🎉
+```
+
+The same trip is available as [`examples/goa-trip.csv`](examples/goa-trip.csv), which you can
+load with `splitkaro import examples/goa-trip.csv`.
+
+## Ways to split
+
+| Option | Example | Meaning |
+|---|---|---|
+| *(none)* | `--paid-by Ravi` | Equally among **all** members. |
+| `--among` | `--among Asha,Meera` | Equally among the listed members. |
+| `--exact` | `--exact Asha=500,Ravi=460,Meera=300` | Fixed amounts; must add up to the total. |
+| `--percent` | `--percent Asha=50,Ravi=25,Meera=25` | Percentages; must add up to 100. |
+| `--shares` | `--shares Asha=2,Ravi=1,Meera=1` | Proportional weights, e.g. couples, or nights stayed. |
+
+Whoever paid is given with `--paid-by NAME`, or `--paid-by NAME=AMOUNT` repeated when several
+people paid the same bill. Names are case-insensitive.
+
+## Command reference
+
+| Command | What it does |
+|---|---|
+| `splitkaro init NAME [--currency INR]` | Start a group (creates `splitkaro.json`). |
+| `splitkaro member add NAME... [--upi ID]` | Add members. |
+| `splitkaro member upi NAME ID` | Set a member's UPI ID. |
+| `splitkaro member list` / `remove NAME` | List members, or remove one who has no history. |
+| `splitkaro add DESC AMOUNT --paid-by ...` | Record an expense (`--category`, `--date`, `--currency`, `--note`). |
+| `splitkaro list [--month YYYY-MM] [--category C] [--member M]` | List expenses. |
+| `splitkaro delete ID` | Delete an expense. |
+| `splitkaro balances [--json]` | Who gets money back, who owes. |
+| `splitkaro settle [--upi] [--json]` | Fewest payments to settle everything. |
+| `splitkaro pay FROM TO AMOUNT` | Record a payment between members. |
+| `splitkaro statement NAME` | Running history of one member's balance. |
+| `splitkaro report [filters] [--json]` | Totals by category, month and member. |
+| `splitkaro rate CUR VALUE` | Exchange rate: 1 CUR = VALUE in the group currency. |
+| `splitkaro export FILE` / `import FILE` | CSV out and in (`-` for stdout/stdin). |
+
+Every command accepts `--file PATH` (or the `SPLITKARO_FILE` environment variable) to work with
+more than one group, for example `splitkaro -f flat.json balances`.
+
+Errors are printed as `splitkaro: <message>` with exit code `1`, and nothing is saved when a command
+fails.
+
+## Your data
+
+A group lives in a single JSON file, `splitkaro.json` by default (shortened here):
+
+```json
+{
+  "version": 1,
+  "name": "Goa trip",
+  "currency": "INR",
+  "members": [{ "name": "Asha", "upi": "asha@okbank" }, { "name": "Ravi", "upi": null }],
+  "expenses": [
+    {
+      "id": 2,
+      "date": "2026-11-01",
+      "description": "Dinner at the shack",
+      "amount": "2400.00",
+      "paid_by": { "Ravi": "2400.00" },
+      "split": { "kind": "equal", "among": ["Asha", "Ravi", "Meera"], "values": {} }
+    }
+  ]
+}
+```
+
+- Amounts are stored as strings, never floats, so nothing is ever rounded away.
+- Files are written atomically: a crash or a full disk cannot leave a half-written file.
+- There is no account, server or tracking. Share the file however your group likes.
+
+The CSV format is documented in [docs/csv-format.md](docs/csv-format.md).
+
+## Using splitkaro from Python
+
+```python
+import datetime as dt
+from decimal import Decimal
+
+from splitkaro import Expense, Group, Split, balances, settle
+
+group = Group("Flat 302")
+for name in ("Asha", "Ravi", "Meera"):
+    group.add_member(name)
+
+group.add_expense(Expense(
+    id=0, description="Electricity", amount=Decimal("3120"),
+    paid_by={"Ravi": Decimal("3120")}, split=Split.equal(["Asha", "Ravi", "Meera"]),
+    date=dt.date(2026, 11, 5), currency="INR", category="bills",
+))
+
+for t in settle(balances(group)):
+    print(f"{t.sender} pays {t.receiver} {t.amount}")
+```
+
+## How it works
+
+- **Rounding:** amounts are split with the largest-remainder method on whole paise, so the parts
+  always add up to the exact total and nobody is ever short-changed by more than one paisa.
+- **Balances:** each member's balance is what they paid minus their share, plus payments made
+  minus payments received. Balances always add up to exactly zero.
+- **Settling:** exact matches (someone owes exactly what someone else is owed) are paired first;
+  the rest is settled greedily between the largest debtor and the largest creditor. This never
+  needs more than *n − 1* payments.
+
+The details, with worked examples, are in [docs/how-it-works.md](docs/how-it-works.md).
+
+## Roadmap
+
+- [ ] Recurring expenses (rent, Wi-Fi, maid) added automatically each month
+- [ ] UPI QR codes in the terminal
+- [ ] Simplify across groups (one payment per pair of people for several trips)
+- [ ] Budgets per category with warnings
+- [ ] Hindi and other Indian language output
+- [ ] A small web or mobile front end on top of the same file format
+
+Ideas and pull requests are welcome, see the [issues](https://github.com/K70281095/splitkaro/issues).
+
+## Contributing
+
+Bug reports, ideas, translations and code are all welcome. Please read
+[CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md). To report a
+security problem, see [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) © 2026 Kanhaiya Kumar
+
+*UPI is a system of the National Payments Corporation of India. splitkaro only creates standard
+`upi://pay` links and never handles money, bank details or PINs.*

splitkaro-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "splitkaro"
+version = "0.1.0"
+description = "Bill splitter for friends, flatmates and trips: split shared expenses, see who owes whom, and settle up with the fewest payments and UPI links."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kanhaiya Kumar" }]
+keywords = ["bill-splitter", "split-expenses", "expense-splitter", "group-expenses", "settle-up", "splitwise-alternative", "upi", "india", "roommates", "travel", "personal-finance", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["ruff>=0.6"]
+
+[project.scripts]
+splitkaro = "splitkaro.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/K70281095/splitkaro"
+Issues = "https://github.com/K70281095/splitkaro/issues"
+Changelog = "https://github.com/K70281095/splitkaro/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py39"
+src = ["src", "tests"]
+
+[tool.ruff.format]
+# Code samples in the docs are laid out for reading, not by the formatter.
+exclude = ["*.md"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["splitkaro", "helpers"]