owo-parse 0.1.0__tar.gz

owo_parse-0.1.0/LICENSE

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

owo_parse-0.1.0/PKG-INFO

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: owo-parse
+Version: 0.1.0
+Summary: Nigerian-language financial intent parser
+Author: owo contributors
+License: MIT License
+        
+        Copyright (c) 2026 owo contributors
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/LPMatrix/owo
+Project-URL: Repository, https://github.com/LPMatrix/owo
+Project-URL: Issues, https://github.com/LPMatrix/owo/issues
+Project-URL: Changelog, https://github.com/LPMatrix/owo/blob/main/CHANGELOG.md
+Keywords: nlp,fintech,nigeria,pidgin,yoruba,hausa,igbo,intent-parsing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Provides-Extra: eval
+Requires-Dist: pyyaml>=6; extra == "eval"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: openrouter
+Requires-Dist: openai>=1.0; extra == "openrouter"
+Dynamic: license-file
+
+# owo
+
+**Nigerian-language financial intent parser.**
+
+`owo` takes a free-form financial instruction in English, Pidgin, Yoruba, Hausa, or Igbo — and returns structured JSON that any payment backend can consume.
+
+```python
+from owo import parse
+
+result = parse("Send 20k to Mama")
+
+# OwoResult(intent='transfer', amount=20000.0, currency='NGN',
+#           recipient='Mama', confidence=0.85, flags=[], ...)
+```
+
+---
+
+## Why owo?
+
+Nigerian fintech products that want a conversational layer have to solve the same hard problem: users don't speak in structured commands. They say *"abeg send 5k to Chidi"*, or *"jẹ kí n san owo ina mi"*, or *"biya wutar lantarki"*. Most NLU libraries weren't built for this. `owo` was.
+
+It handles:
+
+- **Code-switching** — mid-sentence language mixing ("Send am 5k abeg, GTBank")
+- **Naija numerics** — `5k`, `2 bags`, `half a milli`
+- **Intent ambiguity** — flags underspecified fields rather than guessing
+- **Backend agnosticism** — plug in your own LLM provider
+
+---
+
+## Installation
+
+```bash
+pip install owo-parse
+```
+
+Requires Python 3.10+.
+
+---
+
+## Quickstart
+
+```python
+from owo import parse
+
+# English
+parse("Buy 2GB data for 08012345678 on MTN")
+
+# Pidgin
+parse("Abeg top up my light, meter number 4512345678")
+
+# Yoruba
+parse("Jẹ kí n san ₦5,000 fún DSTV mi")
+
+# Hausa
+parse("Aika dubu goma zuwa ga Ahmad")
+
+# Igbo
+parse("Zipụ ego nde ise nye Emeka")
+```
+
+Every call returns an `OwoResult`:
+
+```python
+@dataclass
+class OwoResult:
+    intent: str                    # transfer | bill_pay | buy_airtime | buy_data | crypto_sell | balance_check | unknown
+    amount: float | None
+    currency: str                  # always "NGN" for now
+    recipient: str | None
+    account_number: str | None
+    bank: str | None
+    service: str | None            # MTN | DSTV | EKEDC | ...
+    language_detected: str         # en | pcm | yo | ha | ig
+    confidence: float              # 0.0 – 1.0
+    flags: list[str]               # ["missing_amount", "ambiguous_recipient", ...]
+    raw: dict                      # parser metadata for debugging
+```
+
+---
+
+## Configuration
+
+By default, `parse()` runs an **offline heuristic** covering common transfer and
+balance patterns across all five supported languages (English, Pidgin, Yoruba,
+Hausa, and Igbo). No API key needed. Inputs that fall outside the heuristic's
+rule set return `intent: "unknown"` with `needs_llm_provider` in `flags` — pass
+a provider to handle those cases.
+
+```python
+# Offline — works for common patterns in all five languages
+parse("Abeg send 5k to Chidi, GTBank")
+parse("Aika dubu goma zuwa ga Ahmad")
+parse("Send half a milli to Kemi")
+```
+
+To handle complex or ambiguous inputs, plug in an LLM provider. Three providers
+ship with the package:
+
+```bash
+pip install 'owo-parse[anthropic]'   # Anthropic
+pip install 'owo-parse[openai]'      # OpenAI
+pip install 'owo-parse[openrouter]'  # OpenRouter (access to 200+ models)
+```
+
+```python
+from owo import parse
+from owo.providers.anthropic import AnthropicProvider   # ANTHROPIC_API_KEY
+from owo.providers.openai import OpenAIProvider         # OPENAI_API_KEY
+from owo.providers.openrouter import OpenRouterProvider # OPENROUTER_API_KEY
+
+result = parse(
+    "Buy 2GB data for 08012345678 on MTN",
+    provider=AnthropicProvider(),  # or OpenAIProvider() / OpenRouterProvider()
+)
+```
+
+The heuristic always runs first — the provider is only called when the input falls
+outside the rule set (i.e. `needs_llm_provider` is in `result.flags`). This keeps
+costs low for common transfer and balance patterns.
+
+Or bring your own by subclassing `BaseProvider`:
+
+```python
+from owo import BaseProvider
+
+class MyProvider(BaseProvider):
+    def complete(self, prompt: str) -> str:
+        # Fallback — called when complete_messages() is not overridden.
+        # Receives the full system + user prompt as a single string.
+        ...
+
+    def complete_messages(self, user_text: str) -> str:
+        # Preferred override — gives you the user text directly so you can
+        # pass the system prompt via your SDK's native system-message field.
+        response = my_llm_client.chat(
+            system=MY_SYSTEM_PROMPT,   # use owo._prompt.SYSTEM_PROMPT
+            user=user_text,
+        )
+        return response.text
+```
+
+`SYSTEM_PROMPT` from `owo._prompt` contains the full instruction block with few-shot examples across all five languages — use it as-is or extend it.
+
+---
+
+## Handling ambiguity
+
+`owo` never silently fills in missing fields. If it can't determine the amount, it says so:
+
+```python
+result = parse("Send money to Tunde")
+
+result.amount        # None
+result.flags         # ["missing_amount"]
+result.confidence    # 0.61
+```
+
+Use `confidence` and `flags` to decide whether to ask the user for clarification before passing the result downstream.
+
+---
+
+## Supported intents
+
+
+| Intent          | Example                           |
+| --------------- | --------------------------------- |
+| `transfer`      | "Send 20k to Mama"                |
+| `bill_pay`      | "Pay my DSTV, smart card 1234567" |
+| `buy_airtime`   | "Recharge 500 naira on Airtel"    |
+| `buy_data`      | "Buy 5GB MTN data for my line"    |
+| `crypto_sell`   | "Sell 50 USDT"                    |
+| `balance_check` | "How much I get?"                 |
+| `unknown`       | Heuristic could not classify; use `flags` (`needs_llm_provider`) or an LLM provider |
+
+
+---
+
+## Supported languages
+
+
+| Code  | Language        |
+| ----- | --------------- |
+| `en`  | English         |
+| `pcm` | Nigerian Pidgin |
+| `yo`  | Yoruba          |
+| `ha`  | Hausa           |
+| `ig`  | Igbo            |
+
+
+Mixed-language input (code-switching) is handled automatically — `owo` detects the dominant language and resolves cross-language entities.
+
+---
+
+## Running the eval suite
+
+`owo` ships with a benchmark suite of curated test fixtures across all five languages:
+
+```bash
+pip install owo-parse[eval]
+python -m owo.eval
+```
+
+Results are printed per-language, per-intent, with a breakdown of field-level accuracy.
+
+---
+
+## Roadmap
+
+
+| Version | Focus                                                 |
+| ------- | ----------------------------------------------------- |
+| `v0.1`  | Core intent + entity extraction (English + Pidgin)    |
+| `v0.2`  | Full multilingual support (Yoruba, Hausa, Igbo)       |
+| `v0.3`  | Confidence scores, ambiguity flags, graceful fallback |
+| `v1.0`  | Provider abstraction, eval suite, docs, OSS-ready     |
+
+
+---
+
+## Contributing
+
+Contributions welcome — especially test fixtures in Yoruba, Hausa, and Igbo, which are the hardest to source.
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the fixture format and how to add a new language normalization map.
+
+This project follows the [Contributor Covenant](./CODE_OF_CONDUCT.md). Security
+disclosures: [SECURITY.md](./SECURITY.md). Changes are summarized in
+[CHANGELOG.md](./CHANGELOG.md).
+
+---
+
+## License
+
+[MIT](./LICENSE)

owo_parse-0.1.0/README.md

@@ -0,0 +1,235 @@
+# owo
+
+**Nigerian-language financial intent parser.**
+
+`owo` takes a free-form financial instruction in English, Pidgin, Yoruba, Hausa, or Igbo — and returns structured JSON that any payment backend can consume.
+
+```python
+from owo import parse
+
+result = parse("Send 20k to Mama")
+
+# OwoResult(intent='transfer', amount=20000.0, currency='NGN',
+#           recipient='Mama', confidence=0.85, flags=[], ...)
+```
+
+---
+
+## Why owo?
+
+Nigerian fintech products that want a conversational layer have to solve the same hard problem: users don't speak in structured commands. They say *"abeg send 5k to Chidi"*, or *"jẹ kí n san owo ina mi"*, or *"biya wutar lantarki"*. Most NLU libraries weren't built for this. `owo` was.
+
+It handles:
+
+- **Code-switching** — mid-sentence language mixing ("Send am 5k abeg, GTBank")
+- **Naija numerics** — `5k`, `2 bags`, `half a milli`
+- **Intent ambiguity** — flags underspecified fields rather than guessing
+- **Backend agnosticism** — plug in your own LLM provider
+
+---
+
+## Installation
+
+```bash
+pip install owo-parse
+```
+
+Requires Python 3.10+.
+
+---
+
+## Quickstart
+
+```python
+from owo import parse
+
+# English
+parse("Buy 2GB data for 08012345678 on MTN")
+
+# Pidgin
+parse("Abeg top up my light, meter number 4512345678")
+
+# Yoruba
+parse("Jẹ kí n san ₦5,000 fún DSTV mi")
+
+# Hausa
+parse("Aika dubu goma zuwa ga Ahmad")
+
+# Igbo
+parse("Zipụ ego nde ise nye Emeka")
+```
+
+Every call returns an `OwoResult`:
+
+```python
+@dataclass
+class OwoResult:
+    intent: str                    # transfer | bill_pay | buy_airtime | buy_data | crypto_sell | balance_check | unknown
+    amount: float | None
+    currency: str                  # always "NGN" for now
+    recipient: str | None
+    account_number: str | None
+    bank: str | None
+    service: str | None            # MTN | DSTV | EKEDC | ...
+    language_detected: str         # en | pcm | yo | ha | ig
+    confidence: float              # 0.0 – 1.0
+    flags: list[str]               # ["missing_amount", "ambiguous_recipient", ...]
+    raw: dict                      # parser metadata for debugging
+```
+
+---
+
+## Configuration
+
+By default, `parse()` runs an **offline heuristic** covering common transfer and
+balance patterns across all five supported languages (English, Pidgin, Yoruba,
+Hausa, and Igbo). No API key needed. Inputs that fall outside the heuristic's
+rule set return `intent: "unknown"` with `needs_llm_provider` in `flags` — pass
+a provider to handle those cases.
+
+```python
+# Offline — works for common patterns in all five languages
+parse("Abeg send 5k to Chidi, GTBank")
+parse("Aika dubu goma zuwa ga Ahmad")
+parse("Send half a milli to Kemi")
+```
+
+To handle complex or ambiguous inputs, plug in an LLM provider. Three providers
+ship with the package:
+
+```bash
+pip install 'owo-parse[anthropic]'   # Anthropic
+pip install 'owo-parse[openai]'      # OpenAI
+pip install 'owo-parse[openrouter]'  # OpenRouter (access to 200+ models)
+```
+
+```python
+from owo import parse
+from owo.providers.anthropic import AnthropicProvider   # ANTHROPIC_API_KEY
+from owo.providers.openai import OpenAIProvider         # OPENAI_API_KEY
+from owo.providers.openrouter import OpenRouterProvider # OPENROUTER_API_KEY
+
+result = parse(
+    "Buy 2GB data for 08012345678 on MTN",
+    provider=AnthropicProvider(),  # or OpenAIProvider() / OpenRouterProvider()
+)
+```
+
+The heuristic always runs first — the provider is only called when the input falls
+outside the rule set (i.e. `needs_llm_provider` is in `result.flags`). This keeps
+costs low for common transfer and balance patterns.
+
+Or bring your own by subclassing `BaseProvider`:
+
+```python
+from owo import BaseProvider
+
+class MyProvider(BaseProvider):
+    def complete(self, prompt: str) -> str:
+        # Fallback — called when complete_messages() is not overridden.
+        # Receives the full system + user prompt as a single string.
+        ...
+
+    def complete_messages(self, user_text: str) -> str:
+        # Preferred override — gives you the user text directly so you can
+        # pass the system prompt via your SDK's native system-message field.
+        response = my_llm_client.chat(
+            system=MY_SYSTEM_PROMPT,   # use owo._prompt.SYSTEM_PROMPT
+            user=user_text,
+        )
+        return response.text
+```
+
+`SYSTEM_PROMPT` from `owo._prompt` contains the full instruction block with few-shot examples across all five languages — use it as-is or extend it.
+
+---
+
+## Handling ambiguity
+
+`owo` never silently fills in missing fields. If it can't determine the amount, it says so:
+
+```python
+result = parse("Send money to Tunde")
+
+result.amount        # None
+result.flags         # ["missing_amount"]
+result.confidence    # 0.61
+```
+
+Use `confidence` and `flags` to decide whether to ask the user for clarification before passing the result downstream.
+
+---
+
+## Supported intents
+
+
+| Intent          | Example                           |
+| --------------- | --------------------------------- |
+| `transfer`      | "Send 20k to Mama"                |
+| `bill_pay`      | "Pay my DSTV, smart card 1234567" |
+| `buy_airtime`   | "Recharge 500 naira on Airtel"    |
+| `buy_data`      | "Buy 5GB MTN data for my line"    |
+| `crypto_sell`   | "Sell 50 USDT"                    |
+| `balance_check` | "How much I get?"                 |
+| `unknown`       | Heuristic could not classify; use `flags` (`needs_llm_provider`) or an LLM provider |
+
+
+---
+
+## Supported languages
+
+
+| Code  | Language        |
+| ----- | --------------- |
+| `en`  | English         |
+| `pcm` | Nigerian Pidgin |
+| `yo`  | Yoruba          |
+| `ha`  | Hausa           |
+| `ig`  | Igbo            |
+
+
+Mixed-language input (code-switching) is handled automatically — `owo` detects the dominant language and resolves cross-language entities.
+
+---
+
+## Running the eval suite
+
+`owo` ships with a benchmark suite of curated test fixtures across all five languages:
+
+```bash
+pip install owo-parse[eval]
+python -m owo.eval
+```
+
+Results are printed per-language, per-intent, with a breakdown of field-level accuracy.
+
+---
+
+## Roadmap
+
+
+| Version | Focus                                                 |
+| ------- | ----------------------------------------------------- |
+| `v0.1`  | Core intent + entity extraction (English + Pidgin)    |
+| `v0.2`  | Full multilingual support (Yoruba, Hausa, Igbo)       |
+| `v0.3`  | Confidence scores, ambiguity flags, graceful fallback |
+| `v1.0`  | Provider abstraction, eval suite, docs, OSS-ready     |
+
+
+---
+
+## Contributing
+
+Contributions welcome — especially test fixtures in Yoruba, Hausa, and Igbo, which are the hardest to source.
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the fixture format and how to add a new language normalization map.
+
+This project follows the [Contributor Covenant](./CODE_OF_CONDUCT.md). Security
+disclosures: [SECURITY.md](./SECURITY.md). Changes are summarized in
+[CHANGELOG.md](./CHANGELOG.md).
+
+---
+
+## License
+
+[MIT](./LICENSE)

owo_parse-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "owo-parse"
+version = "0.1.0"
+description = "Nigerian-language financial intent parser"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "owo contributors" }]
+keywords = [
+  "nlp",
+  "fintech",
+  "nigeria",
+  "pidgin",
+  "yoruba",
+  "hausa",
+  "igbo",
+  "intent-parsing",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Typing :: Typed",
+]
+
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.8"]
+eval = ["pyyaml>=6"]
+anthropic = ["anthropic>=0.40"]
+openai = ["openai>=1.0"]
+openrouter = ["openai>=1.0"]
+
+[project.urls]
+Homepage = "https://github.com/LPMatrix/owo"
+Repository = "https://github.com/LPMatrix/owo"
+Issues = "https://github.com/LPMatrix/owo/issues"
+Changelog = "https://github.com/LPMatrix/owo/blob/main/CHANGELOG.md"
+
+[project.scripts]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+owo = ["py.typed", "eval/fixtures/*.yaml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["E501"]

owo_parse-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

owo_parse-0.1.0/src/owo/__init__.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from owo._heuristic import heuristic_parse as _heuristic_parse
+from owo._heuristic import result_from_provider_json as _result_from_provider_json
+from owo.providers import BaseProvider
+from owo.schema import Intent, Language, OwoResult
+
+
+def parse(text: str, *, provider: BaseProvider | None = None) -> OwoResult:
+    """
+    Parse a free-form financial instruction into structured fields.
+
+    The heuristic runs first in all cases. When a *provider* is supplied,
+    it is called only for inputs the heuristic cannot confidently handle
+    (i.e. the result carries a ``needs_llm_provider`` flag).
+    """
+    result = _heuristic_parse(text)
+    if provider is None or "needs_llm_provider" not in result.flags:
+        return result
+    out = provider.complete_messages(text)
+    return _result_from_provider_json(out, text)
+
+
+__all__ = [
+    "BaseProvider",
+    "Intent",
+    "Language",
+    "OwoResult",
+    "parse",
+]