cedikit 1.0.0__tar.gz

cedikit-1.0.0/.gitattributes

@@ -0,0 +1,3 @@
+* text=auto eol=lf
+*.png binary
+*.xlsx binary

cedikit-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,87 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy
+      - run: pytest
+      - run: pytest --no-cov --doctest-modules src
+      - name: Demo commands still work
+        run: |
+          cedikit phone clean examples/customers.csv --column phone --output /tmp/cleaned.csv
+          cedikit sms parse examples/inbox.csv --output /tmp/ledger.xlsx
+
+  core-only:
+    # The core package must work without any optional extras installed.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install . pytest hypothesis
+      - run: >-
+          pytest -p no:cacheprovider --no-cov -o addopts=""
+          tests/test_phone.py tests/test_money.py tests/test_sms_parser.py tests/test_fraud.py
+          tests/test_fees.py tests/test_ids.py tests/test_anonymise.py
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[docs]"
+      # Only checks the docs build; the site itself is hosted on Read the Docs.
+      - run: mkdocs build --strict
+
+  build:
+    needs: [test, core-only, docs]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    # Publishes to PyPI on version tags using trusted publishing.
+    # One-time setup: add this repo as a trusted publisher on pypi.org.
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+

cedikit-1.0.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+coverage.xml
+htmlcov/
+site/
+.ipynb_checkpoints/

cedikit-1.0.0/.readthedocs.yaml

@@ -0,0 +1,19 @@
+# Read the Docs build configuration: https://docs.readthedocs.io/en/stable/config-file/v2.html
+# Builds the MkDocs site at https://cedikit.readthedocs.io/ on every push to main.
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: true
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

cedikit-1.0.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/). Data-file updates (prefixes, templates, fee tables)
+are released as patch versions.
+
+## [1.0.0] - Unreleased
+
+First complete release. Everything runs offline.
+
+### Added
+- **`cedikit.phone`**: `normalise`, `is_valid`, `format` (e164 / local / pretty /
+  international), `likely_network`, `mask`, `clean_column`. Prefix data in `data/prefixes.yaml`.
+- **`cedikit.money`**: `parse`, `format` (symbol / code / compact), `to_words`,
+  `round_pesewas` and the float-proof `Cedi` type.
+- **`cedikit.sms`**: template-driven parser for MTN MoMo and Telecel Cash returning a
+  `ParseResult` with a `Transaction` and confidence score; unrecognised messages never raise.
+  12 templates built from real messages: Telecel send (same / other network), receive (same /
+  other network), cash in, airtime purchase, airtime notice; MTN payment received, payment to
+  merchants and loans, cash in, cash out, send to another network, data bundle.
+  `Transaction.affects_wallet` marks notices that repeat a transaction. `sms.Parser` loads extra
+  template files at runtime.
+- **`cedikit.sms.anonymise`**: replaces names, numbers, IDs, amounts, dates and links while
+  keeping wording and keeping balances consistent across a batch.
+- **`cedikit.fraud`**: `check()` returns a `FraudReport` (risk, score, reasons, per-check
+  results, advice). Checks: sender ID, genuine format, spelling, scam phrases, accented-letter
+  disguises, transaction ID length, balance consistency; optional `ScamClassifier` (scikit-learn).
+  Signals combine with a noisy-OR. Scam phrases live in `fraud/scam_phrases.yaml`.
+- **`cedikit.ledger`**: `Ledger.from_messages` / `from_csv`, `summary`, `cash_flow`,
+  `top_counterparties`, rule-based `categorise`, `category_totals`, `balance_gaps`, export to
+  CSV / Excel / JSON, `to_dataframe`, `plot`.
+- **`cedikit.fees`**: fee and E-Levy estimates from dated tables in which every rule cites its
+  evidence; unknown values are `None`.
+- **`cedikit.ids`**: Ghana Card format checks for `GHA` (citizens) and `FGN` (foreign
+  nationals) with `card_type()`; GhanaPostGPS parsing with region and district names (218
+  district codes, including digit codes such as `A2`), sourced from ghanapostgps.com and the
+  Wikipedia postcode table.
+- **`cedikit.evaluation`**: parser accuracy and fraud precision / recall on labelled files.
+- **Integrations**: pandas `.cedikit` accessor, Pydantic types, Django validators, WTForms
+  validators.
+- **CLI** (`cedikit`): `phone clean|check`, `money parse|words`, `sms parse|anonymise`,
+  `fraud check`, `fees estimate`, `ids check`.
+- Docs site (MkDocs, hosted on Read the Docs), demo notebook, demo data generator,
+  anonymised fixtures.
+
+### Notes
+- AT Money is out of scope (little used); AT numbers are still handled by `cedikit.phone`.
+- Data checked against sources on 2026-09-26: E-Levy repeal date (2 April 2025, GRA);
+  network prefixes (NCA numbering plan + later MTN assignments; Glo 023 added); MTN cash-out
+  and same-network send schedules (third-party tracker, consistent with real messages).
+- Still unconfirmed: MTN cross-network fee, Telecel cash-out fee (the only published table
+  contradicts real messages), and district names against GhanaPostGPS's official table.
+- The Ghana Card check digit is not validated: its algorithm is not published.

cedikit-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing to cedikit
+
+Thanks for helping! A few ground rules keep the library trustworthy.
+
+## Setup
+
+```bash
+python -m venv .venv
+.venv/Scripts/activate        # Windows; use `source .venv/bin/activate` elsewhere
+pip install -e ".[dev]"
+```
+
+Before opening a pull request, all of these must pass:
+
+```bash
+pytest
+pytest --no-cov --doctest-modules src
+ruff check . && ruff format --check .
+mypy
+mkdocs build --strict         # needs pip install -e ".[docs]"
+```
+
+## Rules
+
+- **Never commit real personal data.** Phone numbers, names, transaction IDs and balances in tests
+  and fixtures must be fake. Anonymise SMS samples *before* they enter the repository with
+  `cedikit sms anonymise messages.txt`, then read the output: anything marked `CHECK BY HAND`
+  may still contain names.
+- **Money is `Decimal`, never `float`.**
+- **Data lives in data files.** Network prefixes, SMS templates, fee tables and scam phrases belong
+  in YAML under `src/cedikit/`, not hard-coded in Python.
+- **Be honest in outputs.** Network guesses are *likely*, fees are *estimates*, fraud results are
+  *risk indicators*.
+- Public functions get type hints and a Google-style docstring with an example.
+
+## Updating fee tables and scam phrases
+
+- Fee rules (`src/cedikit/fees/tables/*.yaml`) must cite their evidence in `source`: an official
+  tariff or real (anonymised) messages. When charges change, add a new rule with a `from:` date
+  rather than editing the old one, so historical transactions keep the old rate.
+- New scam phrases (`src/cedikit/fraud/scam_phrases.yaml`) need a scam sample in
+  `tests/fixtures/sample_messages/scam.yaml`, and all genuine fixtures must still score LOW.
+  Check with `cedikit.evaluation.evaluate_fraud`.
+
+## Updating network prefixes
+
+Edit `src/cedikit/data/prefixes.yaml`, bump its `version` date, cite your source (e.g. the NCA
+numbering plan) in the pull request, and add a test for the new prefix.

cedikit-1.0.0/LICENSE

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

cedikit-1.0.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.5
+Name: cedikit
+Version: 1.0.0
+Summary: A Python toolkit for Ghanaian phone numbers, cedi amounts, and Mobile Money transactions
+Project-URL: Homepage, https://github.com/brainiacweb-tech/cedikit
+Project-URL: Issues, https://github.com/brainiacweb-tech/cedikit/issues
+Project-URL: Documentation, https://cedikit.readthedocs.io/
+Project-URL: Changelog, https://github.com/brainiacweb-tech/cedikit/blob/main/CHANGELOG.md
+Author: Francis Kusi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cedi,fintech,ghana,mobile money,momo,phone numbers
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Provides-Extra: all
+Requires-Dist: django>=4.2; extra == 'all'
+Requires-Dist: joblib>=1.3; extra == 'all'
+Requires-Dist: matplotlib>=3.7; extra == 'all'
+Requires-Dist: openpyxl>=3.1; extra == 'all'
+Requires-Dist: pandas>=2.0; extra == 'all'
+Requires-Dist: pydantic>=2.0; extra == 'all'
+Requires-Dist: scikit-learn>=1.3; extra == 'all'
+Requires-Dist: wtforms>=3.0; extra == 'all'
+Provides-Extra: charts
+Requires-Dist: matplotlib>=3.7; extra == 'charts'
+Provides-Extra: dev
+Requires-Dist: django>=4.2; extra == 'dev'
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: joblib>=1.3; extra == 'dev'
+Requires-Dist: matplotlib>=3.7; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: openpyxl>=3.1; extra == 'dev'
+Requires-Dist: pandas-stubs; extra == 'dev'
+Requires-Dist: pandas>=2.0; extra == 'dev'
+Requires-Dist: pydantic>=2.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: scikit-learn>=1.3; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Requires-Dist: wtforms>=3.0; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == 'django'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.1; extra == 'excel'
+Provides-Extra: flask
+Requires-Dist: wtforms>=3.0; extra == 'flask'
+Provides-Extra: ml
+Requires-Dist: joblib>=1.3; extra == 'ml'
+Requires-Dist: scikit-learn>=1.3; extra == 'ml'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.0; extra == 'pydantic'
+Description-Content-Type: text/markdown
+
+# cedikit
+
+**A Python toolkit for Ghanaian phone numbers, cedi amounts, and Mobile Money transactions.**
+
+[![PyPI](https://img.shields.io/pypi/v/cedikit)](https://pypi.org/project/cedikit/)
+[![Docs](https://readthedocs.org/projects/cedikit/badge/?version=latest)](https://cedikit.readthedocs.io/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/brainiacweb-tech/cedikit/blob/main/LICENSE)
+
+Every Ghanaian app ends up writing the same code: cleaning phone numbers typed five different
+ways, adding up cedi amounts without floating-point errors, and making sense of MoMo SMS
+alerts. cedikit does this once, carefully, with tests.
+
+Everything runs **offline**. No user data leaves the device.
+
+## Install
+
+```bash
+pip install cedikit            # core + the `cedikit` command
+pip install "cedikit[all]"     # + pandas, Excel export, charts, ML, Pydantic, Django, Flask
+```
+
+Requires Python 3.10+.
+
+## 30-second tour
+
+```python
+from cedikit import phone, money, sms, fraud, Cedi
+from cedikit.ledger import Ledger
+
+phone.normalise("024 412 3456")  # '+233244123456'
+phone.likely_network("0244123456").network  # 'MTN' (likely - numbers can be ported)
+
+money.parse("GH₵1.2k")  # Decimal('1200.00')
+money.to_words("1200.50")  # 'One thousand two hundred Ghana cedis and fifty pesewas'
+sum([Cedi("1.10"), Cedi("2.20")])  # Cedi('3.30') - exact, unlike 1.1 + 2.2
+
+tx = sms.parse(message_text, sender="MobileMoney").transaction
+tx.type, tx.amount, tx.counterparty, tx.balance
+
+ledger = Ledger.from_messages(inbox, sender="MobileMoney").categorise()
+print(ledger.summary())
+ledger.export("september.xlsx")  # Transactions, Summary, Cash flow, Categories
+
+print(fraud.check(suspicious_text, sender="+233591234567", history=ledger.transactions))
+# Risk: HIGH (score 0.99)
+# Reasons:
+#   - Sent from a personal phone number (+233 59 123 4567), not an official sender ID ...
+#   - Claimed balance GHS 640.35 does not follow from your last genuine balance ...
+```
+
+From the command line:
+
+```bash
+cedikit phone clean customers.csv --column phone
+cedikit sms parse inbox.csv --export xlsx
+cedikit fraud check "Cash receive for 200.00 ..." --sender 0543268728
+```
+
+## Modules
+
+| Module | What it does |
+|---|---|
+| `cedikit.phone` | Normalise, validate, format, mask, likely network, bulk clean |
+| `cedikit.money` | `Decimal` parsing, formatting, words, rounding, the `Cedi` type |
+| `cedikit.sms` | MTN MoMo and Telecel Cash SMS → transactions (12 formats); anonymiser |
+| `cedikit.fraud` | Fake-alert detection with reasons; optional ML classifier |
+| `cedikit.ledger` | Summary, cash flow, categories, balance gaps, CSV/Excel/JSON, charts |
+| `cedikit.fees` | Fee and E-Levy estimates from dated, sourced tables |
+| `cedikit.ids` | Ghana Card and GhanaPostGPS format checks |
+| `cedikit.evaluation` | Parser accuracy and fraud precision/recall on labelled data |
+| Integrations | pandas accessor, Pydantic types, Django and Flask validators |
+
+Full documentation: [the docs site](https://cedikit.readthedocs.io/). The end-to-end demo is
+[notebooks/demo.ipynb](https://github.com/brainiacweb-tech/cedikit/blob/main/notebooks/demo.ipynb), using the data in [examples/](https://github.com/brainiacweb-tech/cedikit/tree/main/examples).
+
+## Honest outputs
+
+- **Network detection is only "likely".** Mobile number portability lets people keep their number
+  when they switch networks.
+- **Fees are estimates.** The tables record only charges seen in real messages or published
+  rules, each with its source. Unknown charges are reported as unknown, never guessed.
+- **Fraud results are risk indicators, not guarantees.** Always confirm a payment in the official
+  Mobile Money app before releasing goods.
+- **Money is never a float.**
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/Scripts/activate        # Windows; use `source .venv/bin/activate` elsewhere
+pip install -e ".[dev,docs]"
+pytest                        # tests + coverage (>= 90%)
+pytest --no-cov --doctest-modules src
+ruff check . && ruff format --check .
+mypy
+mkdocs serve                  # docs at http://127.0.0.1:8000
+```
+
+See [CONTRIBUTING.md](https://github.com/brainiacweb-tech/cedikit/blob/main/CONTRIBUTING.md) and [Adding an SMS template](https://github.com/brainiacweb-tech/cedikit/blob/main/docs/contributing-templates.md).
+
+## Licence
+
+MIT © Francis Kusi. Built in Ghana, for Ghana.

cedikit-1.0.0/README.md

@@ -0,0 +1,103 @@
+# cedikit
+
+**A Python toolkit for Ghanaian phone numbers, cedi amounts, and Mobile Money transactions.**
+
+[![PyPI](https://img.shields.io/pypi/v/cedikit)](https://pypi.org/project/cedikit/)
+[![Docs](https://readthedocs.org/projects/cedikit/badge/?version=latest)](https://cedikit.readthedocs.io/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/brainiacweb-tech/cedikit/blob/main/LICENSE)
+
+Every Ghanaian app ends up writing the same code: cleaning phone numbers typed five different
+ways, adding up cedi amounts without floating-point errors, and making sense of MoMo SMS
+alerts. cedikit does this once, carefully, with tests.
+
+Everything runs **offline**. No user data leaves the device.
+
+## Install
+
+```bash
+pip install cedikit            # core + the `cedikit` command
+pip install "cedikit[all]"     # + pandas, Excel export, charts, ML, Pydantic, Django, Flask
+```
+
+Requires Python 3.10+.
+
+## 30-second tour
+
+```python
+from cedikit import phone, money, sms, fraud, Cedi
+from cedikit.ledger import Ledger
+
+phone.normalise("024 412 3456")  # '+233244123456'
+phone.likely_network("0244123456").network  # 'MTN' (likely - numbers can be ported)
+
+money.parse("GH₵1.2k")  # Decimal('1200.00')
+money.to_words("1200.50")  # 'One thousand two hundred Ghana cedis and fifty pesewas'
+sum([Cedi("1.10"), Cedi("2.20")])  # Cedi('3.30') - exact, unlike 1.1 + 2.2
+
+tx = sms.parse(message_text, sender="MobileMoney").transaction
+tx.type, tx.amount, tx.counterparty, tx.balance
+
+ledger = Ledger.from_messages(inbox, sender="MobileMoney").categorise()
+print(ledger.summary())
+ledger.export("september.xlsx")  # Transactions, Summary, Cash flow, Categories
+
+print(fraud.check(suspicious_text, sender="+233591234567", history=ledger.transactions))
+# Risk: HIGH (score 0.99)
+# Reasons:
+#   - Sent from a personal phone number (+233 59 123 4567), not an official sender ID ...
+#   - Claimed balance GHS 640.35 does not follow from your last genuine balance ...
+```
+
+From the command line:
+
+```bash
+cedikit phone clean customers.csv --column phone
+cedikit sms parse inbox.csv --export xlsx
+cedikit fraud check "Cash receive for 200.00 ..." --sender 0543268728
+```
+
+## Modules
+
+| Module | What it does |
+|---|---|
+| `cedikit.phone` | Normalise, validate, format, mask, likely network, bulk clean |
+| `cedikit.money` | `Decimal` parsing, formatting, words, rounding, the `Cedi` type |
+| `cedikit.sms` | MTN MoMo and Telecel Cash SMS → transactions (12 formats); anonymiser |
+| `cedikit.fraud` | Fake-alert detection with reasons; optional ML classifier |
+| `cedikit.ledger` | Summary, cash flow, categories, balance gaps, CSV/Excel/JSON, charts |
+| `cedikit.fees` | Fee and E-Levy estimates from dated, sourced tables |
+| `cedikit.ids` | Ghana Card and GhanaPostGPS format checks |
+| `cedikit.evaluation` | Parser accuracy and fraud precision/recall on labelled data |
+| Integrations | pandas accessor, Pydantic types, Django and Flask validators |
+
+Full documentation: [the docs site](https://cedikit.readthedocs.io/). The end-to-end demo is
+[notebooks/demo.ipynb](https://github.com/brainiacweb-tech/cedikit/blob/main/notebooks/demo.ipynb), using the data in [examples/](https://github.com/brainiacweb-tech/cedikit/tree/main/examples).
+
+## Honest outputs
+
+- **Network detection is only "likely".** Mobile number portability lets people keep their number
+  when they switch networks.
+- **Fees are estimates.** The tables record only charges seen in real messages or published
+  rules, each with its source. Unknown charges are reported as unknown, never guessed.
+- **Fraud results are risk indicators, not guarantees.** Always confirm a payment in the official
+  Mobile Money app before releasing goods.
+- **Money is never a float.**
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/Scripts/activate        # Windows; use `source .venv/bin/activate` elsewhere
+pip install -e ".[dev,docs]"
+pytest                        # tests + coverage (>= 90%)
+pytest --no-cov --doctest-modules src
+ruff check . && ruff format --check .
+mypy
+mkdocs serve                  # docs at http://127.0.0.1:8000
+```
+
+See [CONTRIBUTING.md](https://github.com/brainiacweb-tech/cedikit/blob/main/CONTRIBUTING.md) and [Adding an SMS template](https://github.com/brainiacweb-tech/cedikit/blob/main/docs/contributing-templates.md).
+
+## Licence
+
+MIT © Francis Kusi. Built in Ghana, for Ghana.

cedikit-1.0.0/docs/cli.md

@@ -0,0 +1,25 @@
+# Command line
+
+Installing cedikit adds a `cedikit` command. Run `cedikit --help` or `cedikit <group> --help`.
+
+| Command | What it does |
+|---|---|
+| `cedikit phone clean FILE.csv --column phone [--style pretty] [--output OUT.csv]` | Normalise a column; adds `_status` and `_note` columns |
+| `cedikit phone check NUMBER` | Formats and likely network of one number |
+| `cedikit money parse TEXT` | `GH₵1.2k` → `1200.00` |
+| `cedikit money words AMOUNT` | Amount in words |
+| `cedikit sms parse FILE [--sender ID] [--export csv\|xlsx\|json] [--output PATH]` | Messages → ledger summary, balance gaps, export |
+| `cedikit sms anonymise FILE [--seed N]` | Anonymise messages before sharing them |
+| `cedikit fraud check TEXT [--sender ID]` | Risk rating with reasons (`-` reads the text from stdin) |
+| `cedikit fees estimate NETWORK KIND AMOUNT [--on YYYY-MM-DD]` | Fee and E-Levy estimate |
+| `cedikit ids check VALUE` | Ghana Card or GhanaPostGPS format check |
+
+**Message files** for `sms parse` and `sms anonymise` are either plain text with one message per
+paragraph (messages separated by a blank line), or a CSV with a `text` column.
+
+Try it on the demo data in `examples/`:
+
+```bash
+cedikit phone clean examples/customers.csv --column phone
+cedikit sms parse examples/inbox.txt --export xlsx
+```

cedikit-1.0.0/docs/contributing-templates.md

@@ -0,0 +1,78 @@
+# Adding an SMS template
+
+Telcos change their message wording from time to time. When that happens, cedikit needs a new
+template, not new code. Templates live in `src/cedikit/sms/templates/<network>.yaml`.
+
+## 1. Anonymise the sample first
+
+Before a message goes anywhere in the repository, replace **every** name, phone number, transaction
+ID, amount, balance, reference and date with fake values. Keep everything else exactly as it is:
+the wording, capital letters, punctuation, and even odd spacing like `NAME .` or double spaces.
+Those quirks are what the template has to match.
+
+## 2. Add a fixture
+
+Append the anonymised message to `tests/fixtures/sample_messages/genuine.yaml` with the fields you
+expect the parser to extract:
+
+```yaml
+- id: mtn_cash_out
+  sender: MobileMoney
+  text: |-
+    Cash Out made for GHS40.00 to ADOM ELECTRICALS . Current Balance: GHS22.10 ...
+  expected:
+    template: mtn_cash_out
+    type: CASH_OUT
+    amount: "40.00"
+    counterparty_name: ADOM ELECTRICALS
+```
+
+Run `pytest tests/test_sms_parser.py`. The new fixture should fail.
+
+## 3. Write the template
+
+```yaml
+  - name: mtn_cash_out
+    type: CASH_OUT            # RECEIVED SENT CASH_OUT CASH_IN MERCHANT AIRTIME BILL REVERSAL
+    source: sample 2026-09    # where the format was seen
+    pattern: >-
+      Cash Out made for {{amount}} to {{counterparty_name}} ?\.
+      Current Balance:? {{balance}}
+      Financial Transaction Id: {{transaction_id}}\.
+      .*?Fee charged: {{fee}}
+    fields:
+      transaction_id: '\d{11}'  # optional: tighter regex for one placeholder
+```
+
+How matching works:
+
+- The message is **cleaned** first: whitespace (including line breaks) collapses to single spaces,
+  and `GH₵`, `GH¢`, `GHC` and `₵` all become `GHS`. The `>-` block joins your lines with single
+  spaces too, so write the pattern the way the cleaned message reads.
+- **Keep optional groups on the same line as the text before them.** Each line break adds a
+  space, so an optional group on its own line leaves a double space when it's absent. Write
+  `Balance: {{balance}}\.(?: Reference: {{reference}}\.)?`, not the group on a new line.
+- `pattern` is a regular expression that must match from the **start** of the message. Any text
+  after it (adverts, safety tips) is ignored. Escape literal dots as `\.`.
+- `{{placeholders}}` become named capture groups. Money placeholders (`amount`, `fee`, `tax`,
+  `balance`, `available_balance`) already include the `GHS ?` prefix. The full list is
+  `FIELD_PATTERNS` in `src/cedikit/sms/parser.py`.
+- `extras` are fields that can appear anywhere, e.g. a `Reference:` after an advert:
+  `reference: 'Reference: {{reference}} ?\.'`
+- `affects_wallet: false` marks notices that repeat another transaction without moving wallet
+  money, e.g. Telecel's "you have received airtime" after an airtime purchase (same transaction
+  ID). They still parse, but ledgers and balance checks skip them.
+- `optional` lists fields that are sometimes missing. Missing optional fields don't lower
+  confidence.
+- Confidence = (required fields found and valid ÷ required fields) × `weight`. Below 0.8, the
+  transaction's `needs_review` is True.
+
+## 4. Check
+
+```bash
+pytest
+ruff check . && mypy
+```
+
+If you can't release yet, apps can load a template file at runtime:
+`sms.Parser(extra_template_files=["my_templates.yaml"])`.