Metadata-Version: 2.1
Name: momoparse
Version: 0.1.0
Summary: Transaction intelligence API for Mobile Money SMS — the Plaid Enrich for MoMo markets
Keywords: mobile money,momo,sms,fintech,ghana,africa,parser
Author: Alex Marfo Appiah
Requires-Python: >=3.12,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Requires-Dist: fastapi (>=0.115.0,<0.116.0)
Requires-Dist: httpx (>=0.27.0,<0.28.0)
Requires-Dist: pydantic (>=2.9.0,<3.0.0)
Requires-Dist: pydantic-settings (>=2.6.0,<3.0.0)
Requires-Dist: python-dotenv (>=1.0.0,<2.0.0)
Requires-Dist: sentry-sdk[fastapi] (>=2.0.0,<3.0.0)
Requires-Dist: slowapi (>=0.1.9,<0.2.0)
Requires-Dist: uvicorn[standard] (>=0.32.0,<0.33.0)
Description-Content-Type: text/markdown

# MomoParse

**Transaction Intelligence API for Mobile Money SMS**

MomoParse transforms raw MoMo SMS messages into structured, categorized financial data. It is the "Plaid Enrich" for mobile money markets — an infrastructure layer that fintechs, banks, and developers plug into to understand a user's MoMo financial life.

**Launch market:** Ghana → West Africa → Pan-African
**Status:** Phase 1 — Parser Engine (Weeks 1–4)

---

## What It Does

**Input:** Raw MoMo SMS text from any Ghanaian telco (MTN MoMo, Telecel Cash)

**Output:** Structured JSON

```json
POST /v1/parse
{
  "sms_text": "Payment made for GHS 150.00 to KWAME ASANTE. Current Balance: GHS 1,230.50. Reference: rent. Transaction ID: 76664093335. Fee charged: GHS 1.12 TAX charged: GHS 0.00.",
  "sender_id": "MobileMoney"
}
```

```json
{
  "telco": "mtn",
  "tx_type": "transfer_sent",
  "template_id": "mtn_transfer_sent_v2",
  "confidence": 1.0,
  "amount": 150.00,
  "currency": "GHS",
  "balance": 1230.50,
  "fee": 1.12,
  "counterparty": {
    "name": "KWAME ASANTE",
    "phone": null
  },
  "tx_id": "76664093335",
  "reference": "rent",
  "date": null,
  "time": null
}
```

---

## Architecture

The parser runs as a **3-stage pipeline**:

```
Raw SMS
   │
   ▼
┌─────────────────────┐
│  Stage 1            │  TelcoDetector
│  Telco Detection    │  sender_id → content patterns
│                     │  confidence: 1.0 (sender) / 0.9 (content)
└────────┬────────────┘
         │ telco name
         ▼
┌─────────────────────┐
│  Stage 2            │  TemplateMatcher
│  Template Matching  │  loads configs/{telco}_templates.json
│                     │  scores each regex template → best match
└────────┬────────────┘
         │ template + match object
         ▼
┌─────────────────────┐
│  Stage 3            │  FieldExtractor
│  Field Extraction   │  applies field rules from template
│                     │  normalizes amounts, phones, names
└────────┬────────────┘
         │
         ▼
     ParseResult
```

**Adding a new telco = add one JSON file to `configs/`. No code changes.**

---

## Project Structure

```
momoparse/
├── parser/               # Core parsing engine (Phase 1)
│   ├── pipeline.py       # MoMoParser — orchestrates all 3 stages
│   ├── detector.py       # Stage 1: telco detection
│   ├── matcher.py        # Stage 2: template matching + confidence scoring
│   ├── extractor.py      # Stage 3: field extraction + normalization
│   ├── models.py         # ParseResult dataclass
│   ├── config_loader.py  # JSON template loader with caching
│   └── normalizers.py    # Amount / phone / name normalization
│
├── api/                  # FastAPI server (Phase 1, Week 3)
│
├── configs/              # Telco template registries (pluggable)
│   ├── mtn_templates.json
│   └── telecel_templates.json
│
├── corpus/               # SMS dataset
│   ├── real_sms_corpus.csv     # Ground truth (92 real annotated SMS)
│   └── synthetic_sms_corpus.csv
│
├── tests/                # Test suite (Week 2)
│
├── docs/                 # API documentation (Week 3)
│
└── pyproject.toml        # Poetry dependency management
```

---

## Supported Transaction Types

| Type | MTN | Telecel |
|------|-----|---------|
| Transfer sent | ✅ (v1 + v2 + with_phone) | ✅ |
| Transfer received | ✅ | ✅ |
| Cash in (deposit) | ✅ | — |
| Cash out / withdrawal | ✅ | ✅ |
| Airtime purchase | ✅ | ✅ |
| Airtime received | — | ✅ |
| Merchant payment | ✅ | ✅ |
| Bill / service payment | ✅ | — |
| Bank transfer | — | ✅ |
| Deposit received | — | ✅ |
| Loan repayment | — | ✅ |
| Interest received | — | ✅ |
| Wallet balance | — | ✅ |

---

## Quick Start

```bash
# Install dependencies
poetry install

# Run the parser directly
python -c "
import parser as p
result = p.parse('Payment made for GHS 50.00 to KOFI MENSAH. Current Balance: GHS 200.00. Reference: food. Transaction ID: 76289975115. Fee charged: GHS 0.00 TAX charged: GHS 0.00.', 'MobileMoney')
print(result.to_dict())
"
```

---

## Tech Stack

| Layer | Technology |
|-------|------------|
| Language | Python 3.12 |
| API Framework | FastAPI + Pydantic |
| Database | PostgreSQL 16 |
| Cache / Rate limiting | Redis |
| Testing | pytest + hypothesis |
| Docs | Mintlify |
| Hosting | Railway / Fly.io |
| CI/CD | GitHub Actions |

---

## Roadmap

- **Phase 1 (Weeks 1–4):** Parser engine + FastAPI server + Python SDK
- **Phase 2 (Weeks 5–8):** ML categorization + enrichment + first customers
- **Phase 3 (Weeks 9–12):** Scale, multi-country, enterprise features

