{"id":36967341,"url":"https://github.com/afrotech-panther/braid-formula","last_synced_at":"2026-01-13T20:02:41.746Z","repository":{"id":328888469,"uuid":"1117194556","full_name":"afrotech-panther/braid-formula","owner":"afrotech-panther","description":"A settlement engine for collaborative projects. Calculate fair payouts when splitting revenue and expenses.","archived":false,"fork":false,"pushed_at":"2025-12-16T02:10:36.000Z","size":22,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-04T02:50:41.547Z","etag":null,"topics":["calculator","collaboration","expense-splitting","open-source","profit-sharing","python","settlement"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/afrotech-panther.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-16T01:03:38.000Z","updated_at":"2025-12-16T02:10:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/afrotech-panther/braid-formula","commit_stats":null,"previous_names":["afrotech-panther/braid-formula"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/afrotech-panther/braid-formula","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afrotech-panther%2Fbraid-formula","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afrotech-panther%2Fbraid-formula/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afrotech-panther%2Fbraid-formula/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afrotech-panther%2Fbraid-formula/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/afrotech-panther","download_url":"https://codeload.github.com/afrotech-panther/braid-formula/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afrotech-panther%2Fbraid-formula/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28399220,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["calculator","collaboration","expense-splitting","open-source","profit-sharing","python","settlement"],"created_at":"2026-01-13T20:02:40.875Z","updated_at":"2026-01-13T20:02:41.735Z","avatar_url":"https://github.com/afrotech-panther.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Braid Formula\n\n**A settlement engine for collaborative projects.**\n\n[![PyPI version](https://img.shields.io/pypi/v/braid-formula)](https://pypi.org/project/braid-formula/)\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n---\n\n## What is this?\n\nWhen people collaborate on a project—a workshop, an event, a pop-up—someone has to figure out who gets paid what. It's not just \"split the revenue.\" Real collaborations involve:\n\n- Different expense amounts per person\n- Different profit-sharing percentages\n- The need to reimburse everyone for what they spent\n- Handling losses fairly when things don't go as planned\n\n**The Braid Formula handles all of this.**\n\n---\n\n## Installation\n\n```bash\npip install braid-formula\n```\n\n---\n\n## Quick Start\n\n```python\nfrom braid_formula import settle\n\nresult = settle(\n    revenue=120.00,\n    collaborators=[\n        {\"name\": \"J\", \"split_percent\": 50, \"expenses\": 151.15},\n        {\"name\": \"Z\", \"split_percent\": 50, \"expenses\": 90.49},\n    ]\n)\n\nfor c in result.collaborators:\n    print(f\"{c.name} gets ${c.payout}\")\n\n# Output:\n# J gets $90.33\n# Z gets $29.67\n```\n\nEven simpler:\n\n```python\nfrom braid_formula import quick_settle\n\npayouts = quick_settle(\n    revenue=120,\n    splits={\"J\": 50, \"Z\": 50},\n    expenses={\"J\": 151.15, \"Z\": 90.49}\n)\n\nprint(payouts)\n# {'J': 90.33, 'Z': 29.67}\n```\n\n---\n\n## The Math\n\nThe Braid Formula calculates fair settlements in three steps:\n\n### Step 1: Calculate Net Profit (or Loss)\n\n```\nNet Profit = Revenue - Total Expenses\n```\n\n### Step 2: Calculate Each Person's Profit Share\n\n```\nProfit Share = Net Profit × (Split % / 100)\n```\n\n### Step 3: Calculate Payout\n\n```\nPayout = Expenses + Profit Share\n```\n\nThat's it. Everyone gets reimbursed for what they spent, then profit (or loss) is split according to the agreed percentages.\n\n---\n\n## Real Example: The Floral Workshop\n\nJ and Z run a floral arrangement workshop together:\n\n| Person | Split | Expenses |\n|--------|-------|----------|\n| J | 50% | $151.15 |\n| Z | 50% | $90.49 |\n\nThey collect **$120** in revenue.\n\n**Step 1: Net Profit**\n```\nTotal Expenses = $151.15 + $90.49 = $241.64\nNet Profit = $120 - $241.64 = -$121.64 (a loss)\n```\n\n**Step 2: Profit Share (Loss Share)**\n```\nJ's share = -$121.64 × 0.50 = -$60.82\nZ's share = -$121.64 × 0.50 = -$60.82\n```\n\n**Step 3: Payouts**\n```\nJ's payout = $151.15 + (-$60.82) = $90.33\nZ's payout = $90.49 + (-$60.82) = $29.67\n```\n\n**Result:** J gets $90.33, Z gets $29.67. The $120 revenue is distributed, and the loss is shared equally.\n\n---\n\n## Command Line Usage\n\n```bash\n# Simple calculation\nbraid --revenue 120 --collab \"J:50:151.15\" --collab \"Z:50:90.49\"\n\n# Interactive mode\nbraid --interactive\n\n# JSON output\nbraid -r 1000 -c \"Alice:60:500\" -c \"Bob:40:200\" --json\n```\n\n---\n\n## API Reference\n\n### `settle(revenue, collaborators, ...)`\n\nThe main settlement function.\n\n**Parameters:**\n- `revenue` (number): Total revenue from the project\n- `collaborators` (list): List of collaborators, each with:\n  - `name` (str): Person's name\n  - `split_percent` (number): Their percentage share (must sum to 100)\n  - `expenses` (number, optional): What they spent (default 0)\n- `allow_negative_revenue` (bool): Allow refund scenarios (default False)\n- `validate` (bool): Validate inputs (default True)\n\n**Returns:** `SettlementResult` with:\n- `revenue`: Total revenue\n- `total_expenses`: Sum of all expenses\n- `net_profit`: Revenue minus expenses\n- `is_profitable`: True if net_profit \u003e= 0\n- `collaborators`: List of `CollaboratorResult` objects\n\n### `quick_settle(revenue, splits, expenses)`\n\nSimplified interface returning just the payouts.\n\n```python\nquick_settle(\n    revenue=1000,\n    splits={\"Alice\": 60, \"Bob\": 40},\n    expenses={\"Alice\": 200, \"Bob\": 100}\n)\n# Returns: {'Alice': 620.0, 'Bob': 380.0}\n```\n\n---\n\n## Handling Edge Cases\n\n### Negative Payouts\n\nIf someone's share of the loss exceeds their expenses, they'll have a negative payout—meaning they owe money to the other collaborators.\n\n```python\nresult = settle(\n    revenue=100,\n    collaborators=[\n        {\"name\": \"A\", \"split_percent\": 50, \"expenses\": 10},\n        {\"name\": \"B\", \"split_percent\": 50, \"expenses\": 190},\n    ]\n)\n# A's payout: -$40 (owes $40)\n# B's payout: $140\n```\n\n### Zero Revenue\n\n```python\nresult = settle(\n    revenue=0,\n    collaborators=[\n        {\"name\": \"A\", \"split_percent\": 50, \"expenses\": 100},\n        {\"name\": \"B\", \"split_percent\": 50, \"expenses\": 100},\n    ]\n)\n# Both get $0 (nothing to distribute)\n```\n\n### Unequal Splits\n\n```python\nresult = settle(\n    revenue=1000,\n    collaborators=[\n        {\"name\": \"Lead\", \"split_percent\": 70, \"expenses\": 200},\n        {\"name\": \"Support\", \"split_percent\": 30, \"expenses\": 100},\n    ]\n)\n# Net profit: $700\n# Lead: $200 + ($700 × 0.70) = $690\n# Support: $100 + ($700 × 0.30) = $310\n```\n\n---\n\n## Validation\n\nThe formula validates inputs and raises descriptive errors:\n\n```python\nfrom braid_formula import settle, SplitPercentageError\n\ntry:\n    settle(revenue=100, collaborators=[\n        {\"name\": \"A\", \"split_percent\": 60},\n        {\"name\": \"B\", \"split_percent\": 60},  # Total 120%!\n    ])\nexcept SplitPercentageError as e:\n    print(e)  # \"Split percentages must sum to 100%, got 120%\"\n```\n\n**Validation checks:**\n- At least one collaborator required\n- Split percentages must sum to exactly 100\n- Revenue cannot be negative (unless `allow_negative_revenue=True`)\n- Expenses cannot be negative\n- Collaborator names must be unique\n\n---\n\n## Why \"Braid\"?\n\nLike threads woven together, collaborations intertwine different contributions—time, money, skills—into something greater. The Braid Formula weaves these together into fair settlements.\n\n---\n\n## Why Open Source?\n\nThe formula is transparent and auditable. Anyone can verify the math. Trust is built into the code.\n\nThe formula is free. **Braid** (the app) is for people who don't want to run Python scripts after a pottery class.\n\n---\n\n## Contributing\n\nContributions welcome! Please:\n\n1. Fork the repo\n2. Create a feature branch\n3. Add tests for new functionality\n4. Run `pytest tests/` to verify\n5. Submit a PR\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n## Credits\n\nCreated by Afro-Panther.\n\nPart of the **Braid** ecosystem for collaborative economics.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafrotech-panther%2Fbraid-formula","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fafrotech-panther%2Fbraid-formula","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafrotech-panther%2Fbraid-formula/lists"}