cedikit 1.0.0__py3-none-any.whl

cedikit/__init__.py

@@ -0,0 +1,35 @@
+"""cedikit - a Python toolkit for Ghanaian phone numbers, cedi amounts and Mobile Money data.
+
+Everything runs offline; no data leaves the device.
+"""
+
+from cedikit import fees, fraud, ids, ledger, money, phone, sms
+from cedikit.exceptions import (
+    CedikitError,
+    CediTypeError,
+    InvalidIdentifier,
+    InvalidPhoneNumber,
+    MoneyParseError,
+    TemplateError,
+)
+from cedikit.money import Cedi
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "Cedi",
+    "CediTypeError",
+    "CedikitError",
+    "InvalidIdentifier",
+    "InvalidPhoneNumber",
+    "MoneyParseError",
+    "TemplateError",
+    "__version__",
+    "fees",
+    "fraud",
+    "ids",
+    "ledger",
+    "money",
+    "phone",
+    "sms",
+]

cedikit/cli.py

@@ -0,0 +1,280 @@
+"""The ``cedikit`` command-line tool.
+
+Examples::
+
+    cedikit phone clean customers.csv --column phone --output cleaned.csv
+    cedikit sms parse inbox.txt --export xlsx
+    cedikit fraud check "You have received GHS 500..." --sender 0551234567
+"""
+
+from __future__ import annotations
+
+import csv
+import sys
+from datetime import date
+from enum import Enum
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from cedikit import __version__, fees, fraud, money, phone
+from cedikit.exceptions import CedikitError
+from cedikit.fees import Kind
+from cedikit.ids import ghana_card, gpgps
+from cedikit.ledger import Ledger
+from cedikit.sms.anonymise import anonymise_many
+
+app = typer.Typer(help="Tools for Ghanaian phone numbers, cedi amounts and Mobile Money SMS.")
+phone_app = typer.Typer(help="Clean, check and format phone numbers.")
+money_app = typer.Typer(help="Parse, format and spell out cedi amounts.")
+sms_app = typer.Typer(help="Parse and anonymise Mobile Money SMS.")
+fraud_app = typer.Typer(help="Check payment SMS for signs of fraud.")
+fees_app = typer.Typer(help="Estimate Mobile Money charges.")
+ids_app = typer.Typer(help="Check Ghana Card numbers and digital addresses.")
+for sub, name in [
+    (phone_app, "phone"),
+    (money_app, "money"),
+    (sms_app, "sms"),
+    (fraud_app, "fraud"),
+    (fees_app, "fees"),
+    (ids_app, "ids"),
+]:
+    app.add_typer(sub, name=name)
+
+
+class ExportFormat(str, Enum):
+    csv = "csv"
+    xlsx = "xlsx"
+    json = "json"
+
+
+class PhoneStyleOption(str, Enum):
+    e164 = "e164"
+    local = "local"
+    pretty = "pretty"
+    international = "international"
+
+
+KindOption = Enum("KindOption", {k: k for k in Kind.__args__}, type=str)  # type: ignore[misc]
+
+
+def _fail(message: str) -> typer.Exit:
+    typer.secho(message, fg=typer.colors.RED, err=True)
+    return typer.Exit(1)
+
+
+def _version(value: bool) -> None:
+    if value:
+        typer.echo(f"cedikit {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        Optional[bool],  # noqa: UP045 - typer needs Optional on Python 3.10
+        typer.Option("--version", callback=_version, is_eager=True, help="Show the version."),
+    ] = None,
+) -> None:
+    """cedikit: built in Ghana, for Ghana. Everything runs offline."""
+
+
+# -- phone --------------------------------------------------------------------
+
+
+@phone_app.command("clean")
+def phone_clean(
+    input: Annotated[Path, typer.Argument(exists=True, dir_okay=False, help="CSV file.")],
+    column: Annotated[str, typer.Option(help="Column holding the phone numbers.")] = "phone",
+    output: Annotated[Optional[Path], typer.Option(help="Where to write the cleaned CSV.")] = None,  # noqa: UP045
+    style: Annotated[PhoneStyleOption, typer.Option(help="Output format.")] = PhoneStyleOption.e164,
+) -> None:
+    """Normalise a column of phone numbers and report what was fixed or invalid."""
+    with input.open(newline="", encoding="utf-8-sig") as fh:
+        reader = csv.DictReader(fh)
+        rows = list(reader)
+        fields = list(reader.fieldnames or [])
+    if column not in fields:
+        raise _fail(f"No column {column!r}. Columns: {', '.join(fields)}")
+
+    report = phone.clean_column(row[column] for row in rows)
+    output = output or input.with_name(f"{input.stem}_cleaned.csv")
+    with output.open("w", newline="", encoding="utf-8") as fh:
+        writer = csv.DictWriter(fh, fieldnames=[*fields, f"{column}_status", f"{column}_note"])
+        writer.writeheader()
+        for row, result in zip(rows, report.results, strict=True):
+            if result.normalised:
+                row[column] = phone.format(result.normalised, style.value)
+            writer.writerow(
+                {**row, f"{column}_status": result.status, f"{column}_note": result.reason or ""}
+            )
+    typer.echo(str(report))
+    for bad in report.invalid[:10]:
+        typer.echo(f"  invalid: {bad.original!r} - {bad.reason}")
+    if report.invalid_count > 10:
+        typer.echo(f"  ... and {report.invalid_count - 10} more (see the _status column)")
+    typer.echo(f"Saved {output}")
+
+
+@phone_app.command("check")
+def phone_check(number: str) -> None:
+    """Validate one number and show its formats and likely network."""
+    try:
+        e164 = phone.normalise(number)
+    except CedikitError as exc:
+        raise _fail(str(exc)) from None
+    guess = phone.likely_network(e164)
+    typer.echo(f"E.164:         {e164}")
+    typer.echo(f"Local:         {phone.format(e164, 'local')}")
+    typer.echo(f"International: {phone.format(e164, 'international')}")
+    typer.echo(f"Network:       {guess.network} (likely - {guess.note})")
+
+
+# -- money --------------------------------------------------------------------
+
+
+@money_app.command("parse")
+def money_parse(text: str) -> None:
+    """Parse text such as "GH₵1.2k" into an exact amount."""
+    try:
+        typer.echo(money.parse(text))
+    except CedikitError as exc:
+        raise _fail(str(exc)) from None
+
+
+@money_app.command("words")
+def money_words(amount: str) -> None:
+    """Spell out an amount, as on a cheque."""
+    try:
+        typer.echo(money.to_words(amount))
+    except (CedikitError, ValueError) as exc:
+        raise _fail(str(exc)) from None
+
+
+# -- sms ----------------------------------------------------------------------
+
+
+def _read_messages(path: Path) -> list[dict[str, str]]:
+    """Messages separated by blank lines (.txt), or a CSV with a ``text`` column and
+    optional ``sender`` and ``received_at`` (ISO date-time) columns."""
+    if path.suffix.lower() == ".csv":
+        with path.open(newline="", encoding="utf-8-sig") as fh:
+            return [row for row in csv.DictReader(fh) if row.get("text")]
+    blocks = path.read_text(encoding="utf-8-sig").replace("\r\n", "\n").split("\n\n")
+    return [{"text": b.strip()} for b in blocks if b.strip()]
+
+
+@sms_app.command("parse")
+def sms_parse(
+    input: Annotated[
+        Path,
+        typer.Argument(
+            exists=True, dir_okay=False, help="Messages separated by blank lines, or a CSV."
+        ),
+    ],
+    sender: Annotated[Optional[str], typer.Option(help="Sender ID of the messages.")] = None,  # noqa: UP045
+    export: Annotated[Optional[ExportFormat], typer.Option(help="Save the ledger.")] = None,  # noqa: UP045
+    output: Annotated[Optional[Path], typer.Option(help="Output file.")] = None,  # noqa: UP045
+) -> None:
+    """Turn a file of MoMo SMS into a ledger and print a summary."""
+    ledger = Ledger.from_messages(_read_messages(input), sender).categorise()
+    typer.echo(str(ledger.summary()))
+    if ledger.notices:
+        typer.echo(f"{len(ledger.notices)} notices (e.g. airtime received) were not counted.")
+    if ledger.unrecognised:
+        typer.secho(
+            f"{len(ledger.unrecognised)} messages were not recognised.", fg=typer.colors.YELLOW
+        )
+    for gap in ledger.balance_gaps():
+        typer.secho(
+            f"Balance gap before {gap.after.transaction_id or 'a transaction'}: expected "
+            f"{money.format(gap.expected)}, message says {money.format(gap.actual)} "
+            "(a message may be missing).",
+            fg=typer.colors.YELLOW,
+        )
+    if export or output:
+        fmt = export.value if export else (output.suffix.lstrip(".") if output else "csv")
+        path = output or input.with_name(f"{input.stem}_ledger.{fmt}")
+        try:
+            ledger.export(path, fmt)  # type: ignore[arg-type]  # validated by export()
+        except (ValueError, ImportError) as exc:
+            raise _fail(str(exc)) from None
+        typer.echo(f"Saved {path}")
+
+
+@sms_app.command("anonymise")
+def sms_anonymise(
+    input: Annotated[Path, typer.Argument(exists=True, dir_okay=False)],
+    seed: Annotated[Optional[int], typer.Option(help="Make the output repeatable.")] = None,  # noqa: UP045
+) -> None:
+    """Replace names, numbers, IDs, amounts and dates (keeps balances consistent)."""
+    messages = [(m["text"], m.get("sender") or None) for m in _read_messages(input)]
+    for result in anonymise_many(messages, seed=seed):
+        if result.needs_review:
+            typer.secho("# CHECK BY HAND: " + " ".join(result.notes), fg=typer.colors.YELLOW)
+        typer.echo(result.text + "\n")
+
+
+# -- fraud --------------------------------------------------------------------
+
+
+@fraud_app.command("check")
+def fraud_check(
+    message: Annotated[str, typer.Argument(help="The SMS text (use - to read from stdin).")],
+    sender: Annotated[Optional[str], typer.Option(help="Who sent it.")] = None,  # noqa: UP045
+) -> None:
+    """Rate how likely a payment SMS is to be fake, and explain why."""
+    text = sys.stdin.read() if message == "-" else message
+    report = fraud.check(text, sender=sender)
+    colour = {"LOW": typer.colors.GREEN, "MEDIUM": typer.colors.YELLOW, "HIGH": typer.colors.RED}
+    lines = str(report).splitlines()
+    typer.secho(lines[0], fg=colour[report.risk], bold=True)
+    typer.echo("\n".join(lines[1:]))
+    if sender is None:
+        typer.echo("Tip: pass --sender; fake alerts almost always come from personal numbers.")
+
+
+# -- fees ---------------------------------------------------------------------
+
+
+@fees_app.command("estimate")
+def fees_estimate(
+    network: str,
+    kind: Annotated[KindOption, typer.Argument()],
+    amount: str,
+    on: Annotated[
+        Optional[str],  # noqa: UP045
+        typer.Option(help="Date YYYY-MM-DD (default today)."),
+    ] = None,
+) -> None:
+    """Estimate the fee and E-Levy for a transaction."""
+    try:
+        day = date.fromisoformat(on) if on else None
+        typer.echo(str(fees.estimate(network, kind.value, amount, day)))
+    except (CedikitError, ValueError) as exc:
+        raise _fail(str(exc)) from None
+
+
+# -- ids ----------------------------------------------------------------------
+
+
+@ids_app.command("check")
+def ids_check(value: str) -> None:
+    """Check a Ghana Card number or GhanaPostGPS address (format only)."""
+    if ghana_card.is_valid_format(value):
+        typer.echo(
+            f"Ghana Card number, valid format: {ghana_card.normalise(value)} "
+            f"({ghana_card.card_type(value)})"
+        )
+    elif gpgps.is_valid_format(value):
+        address = gpgps.parse(value)
+        place = ", ".join(p for p in (address.district, address.region) if p)
+        typer.echo(f"GhanaPostGPS address, valid format: {address.code} ({place})")
+    else:
+        raise _fail(f"{value!r} is neither a Ghana Card number nor a GhanaPostGPS address.")
+    typer.echo("Format check only: this does not confirm that it exists.")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

cedikit/data/prefixes.yaml

@@ -0,0 +1,34 @@
+# Ghanaian mobile number prefixes and the network each was ORIGINALLY assigned to.
+#
+# Because of mobile number portability, a prefix only tells you the *likely*
+# network - the subscriber may have ported to another operator.
+#
+# Keys are the two national digits after the trunk "0" (e.g. 024 -> "24").
+#
+# Sources (checked 2026-09-26):
+#   NCA, "Numbering Plan for Ghana" (nca.org.gh, uploaded 2021): 9-digit national
+#     numbers; 20 & 50 Ghana Telecom (now Telecel); 23 Glo; 24, 54, 55 MTN;
+#     26, 56 Airtel and 27, 57 Millicom/Tigo (now AT); 25 mobile broadband.
+#   The plan predates later assignments: MTN received 025 blocks in 2021
+#     (Graphic Online, "MTN releases new network codes") and uses 053 and 059,
+#     which the plan still shows as unassigned.
+#   Not included: 028 (Kasapa/Expresso, which has shut down) and 029 (National
+#   Security, not public numbers).
+
+version: "2026-09-26"
+country_code: "233"
+national_number_length: 9
+
+networks:
+  MTN:
+    display_name: MTN Ghana
+    prefixes: ["24", "25", "53", "54", "55", "59"]
+  TELECEL:
+    display_name: Telecel Ghana
+    prefixes: ["20", "50"]
+  AT:
+    display_name: AT Ghana
+    prefixes: ["26", "27", "56", "57"]
+  GLO:
+    display_name: Glo Mobile Ghana
+    prefixes: ["23"]

cedikit/evaluation.py

@@ -0,0 +1,197 @@
+"""Measure the parser and fraud checker against labelled, anonymised messages.
+
+The file format is the one used by ``tests/fixtures/sample_messages``: a YAML
+list of entries with ``text``, ``sender`` and (for parser checks) ``expected``
+fields. Keep a held-out set that is never used to tune rules or train models.
+
+Example::
+
+    from cedikit import evaluation
+    genuine = evaluation.load("genuine.yaml")
+    scam = evaluation.load("scam.yaml")
+    print(evaluation.evaluate_fraud(genuine, scam))
+    print(evaluation.evaluate_parser(genuine))
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from decimal import Decimal
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import yaml
+
+from cedikit import fraud, sms
+from cedikit.fraud.rules import FraudReport, Risk
+
+if TYPE_CHECKING:
+    from cedikit.fraud.classifier import ScamClassifier
+
+__all__ = ["FraudEvaluation", "ParserEvaluation", "evaluate_fraud", "evaluate_parser", "load"]
+
+RECALL_TARGET = 0.90
+PRECISION_TARGET = 0.85
+PARSER_TARGET = 0.95
+_MONEY_FIELDS = {"amount", "fee", "tax", "balance", "available_balance"}
+_ORDER: dict[str, int] = {"LOW": 0, "MEDIUM": 1, "HIGH": 2}
+
+
+def load(path: str | Path) -> list[dict[str, Any]]:
+    """Load a labelled YAML file."""
+    data = yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(data, list):
+        raise ValueError(f"{path}: expected a list of messages")
+    return data
+
+
+def _ratio(a: int, b: int) -> float:
+    return a / b if b else 0.0
+
+
+@dataclass(frozen=True)
+class FraudEvaluation:
+    true_positives: int
+    false_positives: int
+    true_negatives: int
+    false_negatives: int
+    flag_at: Risk
+    missed: list[tuple[dict[str, Any], FraudReport]] = field(default_factory=list)
+    false_alarms: list[tuple[dict[str, Any], FraudReport]] = field(default_factory=list)
+
+    @property
+    def recall(self) -> float:
+        """Share of scams that were flagged."""
+        return _ratio(self.true_positives, self.true_positives + self.false_negatives)
+
+    @property
+    def precision(self) -> float:
+        """Share of flagged messages that really were scams."""
+        return _ratio(self.true_positives, self.true_positives + self.false_positives)
+
+    @property
+    def f1(self) -> float:
+        p, r = self.precision, self.recall
+        return 2 * p * r / (p + r) if p + r else 0.0
+
+    def __str__(self) -> str:
+        total = sum(
+            (self.true_positives, self.false_positives, self.true_negatives, self.false_negatives)
+        )
+
+        def mark(value: float, target: float) -> str:
+            return "meets target" if value >= target else f"below target {target:.0%}"
+
+        lines = [
+            f"Fraud detection on {total} messages (flagged at {self.flag_at} or above):",
+            f"  Recall:    {self.recall:.1%} ({mark(self.recall, RECALL_TARGET)})",
+            f"  Precision: {self.precision:.1%} ({mark(self.precision, PRECISION_TARGET)})",
+            f"  F1:        {self.f1:.3f}",
+            f"  Scams caught {self.true_positives}, missed {self.false_negatives}; "
+            f"false alarms {self.false_positives}, correct passes {self.true_negatives}",
+        ]
+        lines += [f"  MISSED: {m.get('id', m['text'][:50])}" for m, _ in self.missed]
+        lines += [f"  FALSE ALARM: {m.get('id', m['text'][:50])}" for m, _ in self.false_alarms]
+        if total < 100:
+            lines.append(f"  Note: {total} messages is too few for reliable percentages.")
+        return "\n".join(lines)
+
+
+def evaluate_fraud(
+    genuine: Sequence[dict[str, Any]],
+    scam: Sequence[dict[str, Any]],
+    *,
+    flag_at: Risk = "MEDIUM",
+    use_sender: bool = True,
+    classifier: ScamClassifier | None = None,
+) -> FraudEvaluation:
+    """Count how many scams are flagged and how many genuine messages are wrongly flagged.
+
+    Args:
+        flag_at: The lowest risk level counted as "flagged".
+        use_sender: Pass each message's sender to the checker. Set False to
+            measure how well the text alone is judged.
+    """
+    tp = fp = tn = fn = 0
+    missed: list[tuple[dict[str, Any], FraudReport]] = []
+    alarms: list[tuple[dict[str, Any], FraudReport]] = []
+    for sample, is_scam in [(g, False) for g in genuine] + [(s, True) for s in scam]:
+        report = fraud.check(
+            sample["text"],
+            sender=sample.get("sender") if use_sender else None,
+            classifier=classifier,
+        )
+        flagged = _ORDER[report.risk] >= _ORDER[flag_at]
+        if is_scam and flagged:
+            tp += 1
+        elif is_scam:
+            fn += 1
+            missed.append((sample, report))
+        elif flagged:
+            fp += 1
+            alarms.append((sample, report))
+        else:
+            tn += 1
+    return FraudEvaluation(tp, fp, tn, fn, flag_at, missed, alarms)
+
+
+def _actual(tx: sms.Transaction, name: str) -> Any:
+    if name.startswith("counterparty_"):
+        return getattr(tx.counterparty, name.removeprefix("counterparty_"), None)
+    if name == "timestamp":
+        return tx.timestamp.isoformat() if tx.timestamp else None
+    if name == "type":
+        return tx.type.value
+    return getattr(tx, name)
+
+
+def field_mismatches(tx: sms.Transaction, expected: dict[str, Any]) -> list[str]:
+    """Fields of ``tx`` that differ from ``expected``, as readable strings."""
+    problems = []
+    for name, want in expected.items():
+        if name in _MONEY_FIELDS and want is not None:
+            want = Decimal(str(want))
+        got = _actual(tx, name)
+        if got != want:
+            problems.append(f"{name}: expected {want!r}, got {got!r}")
+    return problems
+
+
+@dataclass(frozen=True)
+class ParserEvaluation:
+    total: int
+    fully_correct: int
+    failures: dict[str, list[str]] = field(default_factory=dict)
+
+    @property
+    def accuracy(self) -> float:
+        return _ratio(self.fully_correct, self.total)
+
+    def __str__(self) -> str:
+        status = "meets" if self.accuracy >= PARSER_TARGET else "below"
+        lines = [
+            f"Parser: {self.fully_correct}/{self.total} messages with every expected field "
+            f"correct ({self.accuracy:.1%}, {status} target {PARSER_TARGET:.0%})"
+        ]
+        for sample_id, problems in self.failures.items():
+            lines.append(f"  {sample_id}: " + "; ".join(problems))
+        return "\n".join(lines)
+
+
+def evaluate_parser(samples: Sequence[dict[str, Any]]) -> ParserEvaluation:
+    """Check that each sample parses with all its ``expected`` fields correct."""
+    correct = 0
+    failures: dict[str, list[str]] = {}
+    for i, sample in enumerate(samples):
+        sample_id = str(sample.get("id", i))
+        result = sms.parse(sample["text"], sender=sample.get("sender"))
+        if result.transaction is None:
+            failures[sample_id] = ["not recognised"]
+            continue
+        problems = field_mismatches(result.transaction, sample.get("expected", {}))
+        if problems:
+            failures[sample_id] = problems
+        else:
+            correct += 1
+    return ParserEvaluation(len(samples), correct, failures)

cedikit/exceptions.py

@@ -0,0 +1,42 @@
+"""Exceptions raised by cedikit."""
+
+from __future__ import annotations
+
+
+class CedikitError(Exception):
+    """Base class for all cedikit errors."""
+
+
+class InvalidPhoneNumber(CedikitError, ValueError):
+    """Raised when a phone number cannot be normalised to a valid Ghanaian mobile number."""
+
+    def __init__(self, value: object, reason: str) -> None:
+        self.value = value
+        self.reason = reason
+        super().__init__(f"Invalid Ghanaian phone number {value!r}: {reason}")
+
+
+class CediTypeError(CedikitError, TypeError):
+    """Raised when a float (or other unsafe type) is used as a money value."""
+
+
+class InvalidIdentifier(CedikitError, ValueError):
+    """Raised when a Ghana Card number or digital address has the wrong format."""
+
+    def __init__(self, value: object, reason: str) -> None:
+        self.value = value
+        self.reason = reason
+        super().__init__(f"Invalid identifier {value!r}: {reason}")
+
+
+class TemplateError(CedikitError):
+    """Raised when an SMS template file is malformed."""
+
+
+class MoneyParseError(CedikitError, ValueError):
+    """Raised when text cannot be parsed as a cedi amount."""
+
+    def __init__(self, value: object, reason: str) -> None:
+        self.value = value
+        self.reason = reason
+        super().__init__(f"Cannot parse {value!r} as a cedi amount: {reason}")

cedikit/fees/__init__.py

@@ -0,0 +1,15 @@
+"""Estimate Mobile Money fees and the E-Levy from dated, sourced tables.
+
+Results are always *estimates*: charges change, and the tables record only
+what has been observed or published. Unknown values are ``None``, never guessed.
+
+Example:
+    >>> from datetime import date
+    >>> from cedikit import fees
+    >>> fees.estimate("MTN", "cash_out", "50.00").fee
+    Decimal('0.50')
+"""
+
+from cedikit.fees.calculator import FeeEstimate, Kind, estimate
+
+__all__ = ["FeeEstimate", "Kind", "estimate"]