jenga-nlp 2.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (121) hide show
  1. jenga_nlp-2.0.0/CHANGELOG.md +52 -0
  2. jenga_nlp-2.0.0/LICENSE +21 -0
  3. jenga_nlp-2.0.0/MANIFEST.in +14 -0
  4. jenga_nlp-2.0.0/PKG-INFO +205 -0
  5. jenga_nlp-2.0.0/README.md +156 -0
  6. jenga_nlp-2.0.0/docs/README.md +53 -0
  7. jenga_nlp-2.0.0/docs/configuration.md +128 -0
  8. jenga_nlp-2.0.0/docs/inference.md +78 -0
  9. jenga_nlp-2.0.0/docs/quickstart.md +110 -0
  10. jenga_nlp-2.0.0/docs/usage-guide.md +1727 -0
  11. jenga_nlp-2.0.0/examples/configs/fixture_logging_mlflow_cpu.yaml +49 -0
  12. jenga_nlp-2.0.0/examples/configs/fixture_logging_tensorboard_cpu.yaml +48 -0
  13. jenga_nlp-2.0.0/examples/configs/fixture_mpesa_fraud_cpu.yaml +49 -0
  14. jenga_nlp-2.0.0/examples/configs/fixture_mpesa_sentiment_cpu.yaml +48 -0
  15. jenga_nlp-2.0.0/examples/configs/fixture_multilabel_cpu.yaml +54 -0
  16. jenga_nlp-2.0.0/examples/configs/fixture_multitask_cpu.yaml +83 -0
  17. jenga_nlp-2.0.0/examples/configs/fixture_ner_cpu.yaml +49 -0
  18. jenga_nlp-2.0.0/examples/configs/fixture_qa_scoring_cpu.yaml +88 -0
  19. jenga_nlp-2.0.0/examples/configs/fixture_regression_cpu.yaml +51 -0
  20. jenga_nlp-2.0.0/examples/configs/jenganlp_cpu_text_smoke.yaml +48 -0
  21. jenga_nlp-2.0.0/examples/configs/jenganlp_hf_demo.yaml +67 -0
  22. jenga_nlp-2.0.0/examples/configs/jenganlp_whisper_somali.yaml +95 -0
  23. jenga_nlp-2.0.0/examples/configs/multi_task_3way_fusion.yaml +135 -0
  24. jenga_nlp-2.0.0/examples/configs/multi_task_classification.yaml +58 -0
  25. jenga_nlp-2.0.0/examples/configs/old_examples_ner_cpu.yaml +50 -0
  26. jenga_nlp-2.0.0/examples/configs/old_examples_qa_scoring_cpu.yaml +89 -0
  27. jenga_nlp-2.0.0/examples/configs/qa_scoring.yaml +106 -0
  28. jenga_nlp-2.0.0/examples/fixtures/sample_classification.jsonl +20 -0
  29. jenga_nlp-2.0.0/examples/fixtures/sample_instructions.jsonl +10 -0
  30. jenga_nlp-2.0.0/examples/fixtures/sample_multilabel.jsonl +12 -0
  31. jenga_nlp-2.0.0/examples/fixtures/sample_ner.jsonl +12 -0
  32. jenga_nlp-2.0.0/examples/fixtures/sample_qa_transcripts.jsonl +10 -0
  33. jenga_nlp-2.0.0/examples/fixtures/sample_regression.jsonl +16 -0
  34. jenga_nlp-2.0.0/examples/fixtures/sample_sentiment.jsonl +15 -0
  35. jenga_nlp-2.0.0/pyproject.toml +92 -0
  36. jenga_nlp-2.0.0/requirements.txt +28 -0
  37. jenga_nlp-2.0.0/setup.cfg +4 -0
  38. jenga_nlp-2.0.0/src/jenga_nlp/__init__.py +126 -0
  39. jenga_nlp-2.0.0/src/jenga_nlp/__main__.py +7 -0
  40. jenga_nlp-2.0.0/src/jenga_nlp/__version__.py +3 -0
  41. jenga_nlp-2.0.0/src/jenga_nlp/asr/__init__.py +66 -0
  42. jenga_nlp-2.0.0/src/jenga_nlp/asr/callbacks.py +103 -0
  43. jenga_nlp-2.0.0/src/jenga_nlp/asr/checkpoints.py +42 -0
  44. jenga_nlp-2.0.0/src/jenga_nlp/asr/collator.py +27 -0
  45. jenga_nlp-2.0.0/src/jenga_nlp/asr/config.py +120 -0
  46. jenga_nlp-2.0.0/src/jenga_nlp/asr/data.py +115 -0
  47. jenga_nlp-2.0.0/src/jenga_nlp/asr/features.py +34 -0
  48. jenga_nlp-2.0.0/src/jenga_nlp/asr/hub.py +59 -0
  49. jenga_nlp-2.0.0/src/jenga_nlp/asr/loaders.py +450 -0
  50. jenga_nlp-2.0.0/src/jenga_nlp/asr/metrics.py +58 -0
  51. jenga_nlp-2.0.0/src/jenga_nlp/asr/pipeline.py +58 -0
  52. jenga_nlp-2.0.0/src/jenga_nlp/asr/serving.py +34 -0
  53. jenga_nlp-2.0.0/src/jenga_nlp/asr/training.py +316 -0
  54. jenga_nlp-2.0.0/src/jenga_nlp/cli.py +398 -0
  55. jenga_nlp-2.0.0/src/jenga_nlp/client/__init__.py +5 -0
  56. jenga_nlp-2.0.0/src/jenga_nlp/client/client.py +73 -0
  57. jenga_nlp-2.0.0/src/jenga_nlp/core/__init__.py +39 -0
  58. jenga_nlp-2.0.0/src/jenga_nlp/core/config.py +513 -0
  59. jenga_nlp-2.0.0/src/jenga_nlp/core/fusion.py +195 -0
  60. jenga_nlp-2.0.0/src/jenga_nlp/core/model.py +302 -0
  61. jenga_nlp-2.0.0/src/jenga_nlp/data/__init__.py +7 -0
  62. jenga_nlp-2.0.0/src/jenga_nlp/data/collators.py +111 -0
  63. jenga_nlp-2.0.0/src/jenga_nlp/data/pii.py +399 -0
  64. jenga_nlp-2.0.0/src/jenga_nlp/data/processor.py +306 -0
  65. jenga_nlp-2.0.0/src/jenga_nlp/export/__init__.py +5 -0
  66. jenga_nlp-2.0.0/src/jenga_nlp/export/huggingface.py +80 -0
  67. jenga_nlp-2.0.0/src/jenga_nlp/inference/__init__.py +18 -0
  68. jenga_nlp-2.0.0/src/jenga_nlp/inference/formatters.py +376 -0
  69. jenga_nlp-2.0.0/src/jenga_nlp/inference/pipeline.py +557 -0
  70. jenga_nlp-2.0.0/src/jenga_nlp/integrations/__init__.py +30 -0
  71. jenga_nlp-2.0.0/src/jenga_nlp/integrations/adapters/__init__.py +16 -0
  72. jenga_nlp-2.0.0/src/jenga_nlp/integrations/adapters/base.py +71 -0
  73. jenga_nlp-2.0.0/src/jenga_nlp/integrations/adapters/labelstudio.py +41 -0
  74. jenga_nlp-2.0.0/src/jenga_nlp/integrations/adapters/mlflow.py +73 -0
  75. jenga_nlp-2.0.0/src/jenga_nlp/integrations/adapters/tensorboard.py +74 -0
  76. jenga_nlp-2.0.0/src/jenga_nlp/integrations/adapters/wandb.py +77 -0
  77. jenga_nlp-2.0.0/src/jenga_nlp/integrations/base.py +5 -0
  78. jenga_nlp-2.0.0/src/jenga_nlp/integrations/callbacks.py +96 -0
  79. jenga_nlp-2.0.0/src/jenga_nlp/integrations/events.py +82 -0
  80. jenga_nlp-2.0.0/src/jenga_nlp/integrations/registry.py +43 -0
  81. jenga_nlp-2.0.0/src/jenga_nlp/integrations/runtime.py +66 -0
  82. jenga_nlp-2.0.0/src/jenga_nlp/integrations/sinks.py +100 -0
  83. jenga_nlp-2.0.0/src/jenga_nlp/resume.py +40 -0
  84. jenga_nlp-2.0.0/src/jenga_nlp/security/audit.py +281 -0
  85. jenga_nlp-2.0.0/src/jenga_nlp/security/explainability.py +311 -0
  86. jenga_nlp-2.0.0/src/jenga_nlp/security/hitl.py +298 -0
  87. jenga_nlp-2.0.0/src/jenga_nlp/tasks/__init__.py +21 -0
  88. jenga_nlp-2.0.0/src/jenga_nlp/tasks/base.py +78 -0
  89. jenga_nlp-2.0.0/src/jenga_nlp/tasks/classification.py +109 -0
  90. jenga_nlp-2.0.0/src/jenga_nlp/tasks/ner.py +67 -0
  91. jenga_nlp-2.0.0/src/jenga_nlp/tasks/qa.py +219 -0
  92. jenga_nlp-2.0.0/src/jenga_nlp/tasks/registry.py +76 -0
  93. jenga_nlp-2.0.0/src/jenga_nlp/tasks/regression.py +85 -0
  94. jenga_nlp-2.0.0/src/jenga_nlp/tasks/sentiment.py +60 -0
  95. jenga_nlp-2.0.0/src/jenga_nlp/training/__init__.py +2 -0
  96. jenga_nlp-2.0.0/src/jenga_nlp/training/callbacks.py +401 -0
  97. jenga_nlp-2.0.0/src/jenga_nlp/training/metrics.py +115 -0
  98. jenga_nlp-2.0.0/src/jenga_nlp/training/trainer.py +700 -0
  99. jenga_nlp-2.0.0/src/jenga_nlp/utils/__init__.py +4 -0
  100. jenga_nlp-2.0.0/src/jenga_nlp/utils/device.py +31 -0
  101. jenga_nlp-2.0.0/src/jenga_nlp/utils/logging.py +18 -0
  102. jenga_nlp-2.0.0/src/jenga_nlp/workflows.py +42 -0
  103. jenga_nlp-2.0.0/src/jenga_nlp.egg-info/PKG-INFO +205 -0
  104. jenga_nlp-2.0.0/src/jenga_nlp.egg-info/SOURCES.txt +119 -0
  105. jenga_nlp-2.0.0/src/jenga_nlp.egg-info/dependency_links.txt +1 -0
  106. jenga_nlp-2.0.0/src/jenga_nlp.egg-info/entry_points.txt +2 -0
  107. jenga_nlp-2.0.0/src/jenga_nlp.egg-info/requires.txt +29 -0
  108. jenga_nlp-2.0.0/src/jenga_nlp.egg-info/top_level.txt +1 -0
  109. jenga_nlp-2.0.0/tests/test_cli.py +167 -0
  110. jenga_nlp-2.0.0/tests/test_config.py +346 -0
  111. jenga_nlp-2.0.0/tests/test_data_processor.py +67 -0
  112. jenga_nlp-2.0.0/tests/test_examples_inference_tmp.py +36 -0
  113. jenga_nlp-2.0.0/tests/test_examples_static.py +65 -0
  114. jenga_nlp-2.0.0/tests/test_fusion_and_sampling.py +272 -0
  115. jenga_nlp-2.0.0/tests/test_import.py +87 -0
  116. jenga_nlp-2.0.0/tests/test_mlflow_logging.py +98 -0
  117. jenga_nlp-2.0.0/tests/test_model_artifacts_end_to_end.py +397 -0
  118. jenga_nlp-2.0.0/tests/test_resume_end_to_end.py +76 -0
  119. jenga_nlp-2.0.0/tests/test_training_callbacks.py +324 -0
  120. jenga_nlp-2.0.0/tests/test_training_metrics.py +246 -0
  121. jenga_nlp-2.0.0/tests/test_wandb_adapter.py +52 -0
@@ -0,0 +1,52 @@
1
+ # Changelog
2
+
3
+ All notable changes to **JengaNLP** will be documented in this file.
4
+
5
+ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
6
+ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ---
9
+
10
+ ## [2.0.0] — 2026-11-11
11
+
12
+ ### Added
13
+ - Full multi-task text NLP framework with shared encoder + pluggable task heads
14
+ - Task types: `single_label_classification`, `multi_label_classification`, `sentiment`, `ner`, `regression`, `qa_scoring`
15
+ - `ExperimentConfig` — Pydantic v2 YAML-driven configuration system
16
+ - `MultiTaskModel` — shared encoder with independent task heads and optional fusion layers
17
+ - `InferencePipeline` — load-once, predict-many production inference with formatters
18
+ - `JengaClient` — high-level Python API for train / evaluate / predict
19
+ - CLI: `python -m jenga_nlp train | evaluate | predict | resume | backends | asr`
20
+ - Pluggable integrations layer: MLflow, TensorBoard, Weights & Biases, Label Studio
21
+ - Activity event system: typed events, sinks (Console, JSONL, Multi), callbacks
22
+ - ASR module: Whisper fine-tuning (`WhisperTrainer`), local serving (`WhisperServer`), manifest-based dataset loaders, WER/CER metrics, HuggingFace Hub push
23
+ - PII redaction in `data/pii.py`
24
+ - Security module: audit logging, explainability, HITL review
25
+ - Training resume: `find_latest_training_state`, `resume_training`
26
+ - `ship_model` workflow: train → evaluate → push to Hub
27
+ - PyPI packaging with `jenga-nlp` CLI entry point
28
+ - Unknown config keys now raise an `UnknownConfigKeyWarning` naming the section and the closest
29
+ valid key (they are still ignored), so typos such as `fussion:` no longer fail silently
30
+
31
+ ### Changed
32
+ - Attention fusion redesigned: each task's embedding now attends over the tokens (padding masked,
33
+ `num_attention_heads` honoured) and the task context is gated into every token. The previous
34
+ version had no task-specific effect; models trained with it must be retrained.
35
+ - New `model.fusion.lr_multiplier`: fusion trains faster than the pretrained encoder (default 10 for attention
36
+ fusion, 1 for concatenation)
37
+ - `training.task_sampling` now implements `proportional` and `temperature` (previously always round-robin)
38
+ - CLI: `predict` accepts `--device`; `evaluate` writes its activity log to the evaluated model folder
39
+ - Crashed or interrupted runs end as `FAILED` / `KILLED` in MLflow (they were recorded as `FINISHED`), and
40
+ `evaluate` always closes its tracker run; the MLflow integration adapter no longer passes an invalid status
41
+ - Resuming a run whose optimizer layout changed restarts the optimizer cleanly instead of crashing
42
+ - Attention fusion always uses its residual connection: `use_residual: false` is rejected for
43
+ `type: attention` (still supported for concatenation). Custom callbacks with an
44
+ `on_train_end(self, model)` signature keep working.
45
+ - Refactored from monolithic codebase into modular sub-packages
46
+ - Config parsing migrated to Pydantic v2
47
+
48
+ ---
49
+
50
+ ## [1.x.x] — Prior releases (internal / JengaAI backend)
51
+
52
+ Earlier versions were part of the JengaAI backend monorepo and not published to PyPI.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 JengaNLP Team
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,14 @@
1
+ # MANIFEST.in — controls which non-Python files are included in the sdist
2
+
3
+ include LICENSE
4
+ include CHANGELOG.md
5
+ include README.md
6
+ include requirements.txt
7
+
8
+ recursive-include docs *.md *.rst *.txt
9
+ recursive-include examples/configs *.yaml *.yml
10
+ recursive-include examples/fixtures *.jsonl *.json *.csv
11
+
12
+ global-exclude __pycache__
13
+ global-exclude *.py[co]
14
+ global-exclude *.egg-info
@@ -0,0 +1,205 @@
1
+ Metadata-Version: 2.4
2
+ Name: jenga-nlp
3
+ Version: 2.0.0
4
+ Summary: Config-driven multi-task NLP: one shared transformer encoder, many task heads, load-once production inference
5
+ Author: JengaNLP Team
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/Rogendo/JengaNLP
8
+ Project-URL: Repository, https://github.com/Rogendo/JengaNLP
9
+ Project-URL: Bug Tracker, https://github.com/Rogendo/JengaNLP/issues
10
+ Keywords: nlp,multi-task-learning,african-languages,transformers,jenga-nlp
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
19
+ Requires-Python: >=3.10
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: setuptools<81,>=68.0
23
+ Requires-Dist: torch>=2.2.0
24
+ Requires-Dist: transformers>=4.40.0
25
+ Requires-Dist: datasets>=2.18.0
26
+ Requires-Dist: pydantic>=2.5.0
27
+ Requires-Dist: pyyaml>=6.0
28
+ Requires-Dist: scikit-learn>=1.4.0
29
+ Requires-Dist: scipy>=1.11.0
30
+ Requires-Dist: numpy>=1.26.0
31
+ Requires-Dist: pandas>=2.2.0
32
+ Requires-Dist: tqdm>=4.66.0
33
+ Requires-Dist: mlflow>=2.10.0
34
+ Requires-Dist: tensorboard>=2.15.0
35
+ Provides-Extra: asr
36
+ Requires-Dist: accelerate>=0.28.0; extra == "asr"
37
+ Requires-Dist: peft>=0.10.0; extra == "asr"
38
+ Requires-Dist: librosa>=0.10.0; extra == "asr"
39
+ Requires-Dist: soundfile>=0.12.0; extra == "asr"
40
+ Provides-Extra: wandb
41
+ Requires-Dist: wandb>=0.16.0; extra == "wandb"
42
+ Provides-Extra: dev
43
+ Requires-Dist: pytest>=8.0.0; extra == "dev"
44
+ Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
45
+ Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
46
+ Requires-Dist: ruff>=0.3.0; extra == "dev"
47
+ Requires-Dist: mypy>=1.8.0; extra == "dev"
48
+ Dynamic: license-file
49
+
50
+ # JengaNLP
51
+
52
+ **Config-driven multi-task NLP.** Train one shared transformer encoder with many task heads — classification, sentiment, NER, regression and checklist-style QA scoring — from a single YAML file, then serve it with a load-once inference pipeline.
53
+
54
+ > **Status: alpha (2.0.0).** The core text workflow — config → train → evaluate → predict → `InferencePipeline` — is tested and is the supported path. Everything else is marked experimental below.
55
+
56
+ ## What JengaNLP is, honestly
57
+
58
+ JengaNLP is built on PyTorch and Hugging Face Transformers. For a single classifier, the Hugging Face `Trainer` is a fine choice, and JengaNLP is mostly a convenience layer on top of the same ideas.
59
+
60
+ Where JengaNLP does more than a training wrapper:
61
+
62
+ - **Multi-task models are the default, not a research project.** One encoder, several tasks, several heads per task, per-head loss weights, and task sampling strategies (`round_robin`, `proportional`, `temperature`) — all declared in YAML.
63
+ - **Checklist QA scoring (`qa_scoring`).** Score call-centre transcripts against weighted rubric sections (opening, listening, resolution, …) as multi-head binary checklists — a task type you would otherwise hand-build.
64
+ - **Production inference included.** `InferencePipeline` loads once, predicts single or batch, returns structured per-head results with confidences, and flags PII in inputs.
65
+ - **One artefact layout.** Training, evaluation, resume, checkpoints and inference all read the same saved config and model directory.
66
+
67
+ **What is not here yet:** pretrained JengaNLP checkpoints, published benchmarks, and African-language base models and datasets. Those are the roadmap, not current features — see [Roadmap](#roadmap).
68
+
69
+ ## Install
70
+
71
+ ```bash
72
+ pip install jenga-nlp
73
+ ```
74
+
75
+ Requires Python 3.10+. Optional extras:
76
+
77
+ | Extra | Installs | When you need it |
78
+ |---|---|---|
79
+ | `jenga-nlp[asr]` | accelerate, peft, librosa, soundfile | Whisper ASR workflows (experimental) |
80
+ | `jenga-nlp[wandb]` | `wandb` | Weights & Biases experiment tracking |
81
+ | `jenga-nlp[dev]` | pytest, ruff, mypy | Working on JengaNLP itself |
82
+
83
+ From source:
84
+
85
+ ```bash
86
+ git clone https://github.com/Rogendo/JengaNLP.git
87
+ cd JengaNLP
88
+ pip install -e ".[dev]"
89
+ ```
90
+
91
+ ## Quickstart (5 minutes, CPU)
92
+
93
+ **1. Data** — JSONL, JSON or CSV with a text column and a label column:
94
+
95
+ ```bash
96
+ mkdir -p jenganlp_demo
97
+ cat > jenganlp_demo/messages.jsonl <<'JSONL'
98
+ {"text":"Urgent M-PESA reversal request. Share your PIN now.","label":1}
99
+ {"text":"Your payment has been received successfully.","label":0}
100
+ {"text":"Congratulations, send your PIN to claim the prize.","label":1}
101
+ {"text":"Please visit the nearest branch for help.","label":0}
102
+ {"text":"Account blocked. Reply with your secret code.","label":1}
103
+ {"text":"Your statement is ready for download.","label":0}
104
+ JSONL
105
+ ```
106
+
107
+ **2. Config** — run every command from the folder that contains `jenganlp_demo/`:
108
+
109
+ ```bash
110
+ cat > jenganlp_demo/config.yaml <<'YAML'
111
+ project_name: demo_mpesa_fraud
112
+ model:
113
+ base_model: distilbert-base-uncased
114
+ tokenizer:
115
+ max_length: 64
116
+ tasks:
117
+ - name: mpesa_fraud_detection
118
+ type: single_label_classification
119
+ data_path: jenganlp_demo/messages.jsonl
120
+ text_column: text
121
+ label_column: label
122
+ heads:
123
+ - name: fraud_head
124
+ num_labels: 2
125
+ training:
126
+ output_dir: jenganlp_demo/model
127
+ batch_size: 2
128
+ num_epochs: 3
129
+ device: cpu
130
+ logging:
131
+ service: none
132
+ data:
133
+ test_size: 0.33
134
+ YAML
135
+ ```
136
+
137
+ **3. Train, evaluate, predict:**
138
+
139
+ ```bash
140
+ jenga-nlp train --config jenganlp_demo/config.yaml
141
+ jenga-nlp evaluate --config jenganlp_demo/config.yaml --model-dir jenganlp_demo/model
142
+ jenga-nlp predict --config jenganlp_demo/config.yaml --model-dir jenganlp_demo/model \
143
+ --task-name mpesa_fraud_detection --text "Urgent M-PESA reversal request asking for PIN"
144
+ ```
145
+
146
+ **4. Load once in Python** (notebooks, batch jobs, services):
147
+
148
+ ```python
149
+ from jenga_nlp.inference.pipeline import InferencePipeline
150
+
151
+ pipeline = InferencePipeline.from_checkpoint(
152
+ model_dir="jenganlp_demo/model",
153
+ config_path="jenganlp_demo/config.yaml",
154
+ device="cpu",
155
+ )
156
+ print(pipeline.predict(text="Urgent M-PESA reversal request asking for PIN",
157
+ task_name="mpesa_fraud_detection").to_dict())
158
+ ```
159
+
160
+ > Six examples prove the pipeline works, not that the model is good. A perfect score on a handful of eval samples is meaningless — use hundreds of labelled examples per class before trusting predictions.
161
+
162
+ ## Task types
163
+
164
+ | `type` | Labels look like | Example use |
165
+ |---|---|---|
166
+ | `single_label_classification` | `1` | Fraud vs legitimate message |
167
+ | `multi_label_classification` | `{"risk_tags": [1, 1, 0, 1]}` | Several risk tags per message |
168
+ | `sentiment` | `2` | Negative / neutral / positive |
169
+ | `ner` | entity spans | Names, amounts, phone numbers |
170
+ | `regression` | `0.73` | Risk or quality score |
171
+ | `qa_scoring` | `{"opening": [1], "resolution": [1, 0, 1, 1, 0]}` | Call-centre QA checklists |
172
+
173
+ Multi-task: list several tasks under `tasks:` — they share the encoder. See [`examples/configs/fixture_multitask_cpu.yaml`](https://github.com/Rogendo/JengaNLP/blob/main/examples/configs/fixture_multitask_cpu.yaml).
174
+
175
+ ## Stable vs experimental
176
+
177
+ | Area | Status |
178
+ |---|---|
179
+ | YAML config, text training, evaluation, resume, checkpoints | **Stable** — covered by tests |
180
+ | `InferencePipeline` (single + batch), CLI predict | **Stable** — covered by tests |
181
+ | MLflow / TensorBoard logging | **Stable** |
182
+ | Hugging Face Hub export | Experimental |
183
+ | Whisper ASR fine-tuning and serving | Experimental — not yet validated on real audio/GPU; needs `ffmpeg` installed to read audio files |
184
+ | Weights & Biases, Label Studio adapters | Experimental |
185
+ | Explainability, human-in-the-loop routing, audit logging | Experimental |
186
+
187
+ Experimental features may change or move out of the core package.
188
+
189
+ ## Documentation
190
+
191
+ - [Quickstart](https://github.com/Rogendo/JengaNLP/blob/main/docs/quickstart.md)
192
+ - [Configuration reference](https://github.com/Rogendo/JengaNLP/blob/main/docs/configuration.md)
193
+ - [Inference and production serving](https://github.com/Rogendo/JengaNLP/blob/main/docs/inference.md)
194
+ - [Full usage guide](https://github.com/Rogendo/JengaNLP/blob/main/docs/usage-guide.md) — every workflow, including experimental ones
195
+ - [Example configs](https://github.com/Rogendo/JengaNLP/blob/main/examples/configs/) and [fixtures](https://github.com/Rogendo/JengaNLP/blob/main/examples/fixtures/)
196
+
197
+ ## Roadmap
198
+
199
+ 1. **African-language base models** — adapt an African-language encoder (AfriBERTa / AfroXLMR) to Swahili, Sheng and Swahili–English code-switched text.
200
+ 2. **Benchmarks** — public results on African-language datasets, including multi-task vs single-task baselines.
201
+ 3. **Ready-made templates with pretrained checkpoints** — mobile-money fraud, call-centre QA, Swahili sentiment, on the Hugging Face Hub.
202
+
203
+ ## License
204
+
205
+ MIT — see [LICENSE](https://github.com/Rogendo/JengaNLP/blob/main/LICENSE).
@@ -0,0 +1,156 @@
1
+ # JengaNLP
2
+
3
+ **Config-driven multi-task NLP.** Train one shared transformer encoder with many task heads — classification, sentiment, NER, regression and checklist-style QA scoring — from a single YAML file, then serve it with a load-once inference pipeline.
4
+
5
+ > **Status: alpha (2.0.0).** The core text workflow — config → train → evaluate → predict → `InferencePipeline` — is tested and is the supported path. Everything else is marked experimental below.
6
+
7
+ ## What JengaNLP is, honestly
8
+
9
+ JengaNLP is built on PyTorch and Hugging Face Transformers. For a single classifier, the Hugging Face `Trainer` is a fine choice, and JengaNLP is mostly a convenience layer on top of the same ideas.
10
+
11
+ Where JengaNLP does more than a training wrapper:
12
+
13
+ - **Multi-task models are the default, not a research project.** One encoder, several tasks, several heads per task, per-head loss weights, and task sampling strategies (`round_robin`, `proportional`, `temperature`) — all declared in YAML.
14
+ - **Checklist QA scoring (`qa_scoring`).** Score call-centre transcripts against weighted rubric sections (opening, listening, resolution, …) as multi-head binary checklists — a task type you would otherwise hand-build.
15
+ - **Production inference included.** `InferencePipeline` loads once, predicts single or batch, returns structured per-head results with confidences, and flags PII in inputs.
16
+ - **One artefact layout.** Training, evaluation, resume, checkpoints and inference all read the same saved config and model directory.
17
+
18
+ **What is not here yet:** pretrained JengaNLP checkpoints, published benchmarks, and African-language base models and datasets. Those are the roadmap, not current features — see [Roadmap](#roadmap).
19
+
20
+ ## Install
21
+
22
+ ```bash
23
+ pip install jenga-nlp
24
+ ```
25
+
26
+ Requires Python 3.10+. Optional extras:
27
+
28
+ | Extra | Installs | When you need it |
29
+ |---|---|---|
30
+ | `jenga-nlp[asr]` | accelerate, peft, librosa, soundfile | Whisper ASR workflows (experimental) |
31
+ | `jenga-nlp[wandb]` | `wandb` | Weights & Biases experiment tracking |
32
+ | `jenga-nlp[dev]` | pytest, ruff, mypy | Working on JengaNLP itself |
33
+
34
+ From source:
35
+
36
+ ```bash
37
+ git clone https://github.com/Rogendo/JengaNLP.git
38
+ cd JengaNLP
39
+ pip install -e ".[dev]"
40
+ ```
41
+
42
+ ## Quickstart (5 minutes, CPU)
43
+
44
+ **1. Data** — JSONL, JSON or CSV with a text column and a label column:
45
+
46
+ ```bash
47
+ mkdir -p jenganlp_demo
48
+ cat > jenganlp_demo/messages.jsonl <<'JSONL'
49
+ {"text":"Urgent M-PESA reversal request. Share your PIN now.","label":1}
50
+ {"text":"Your payment has been received successfully.","label":0}
51
+ {"text":"Congratulations, send your PIN to claim the prize.","label":1}
52
+ {"text":"Please visit the nearest branch for help.","label":0}
53
+ {"text":"Account blocked. Reply with your secret code.","label":1}
54
+ {"text":"Your statement is ready for download.","label":0}
55
+ JSONL
56
+ ```
57
+
58
+ **2. Config** — run every command from the folder that contains `jenganlp_demo/`:
59
+
60
+ ```bash
61
+ cat > jenganlp_demo/config.yaml <<'YAML'
62
+ project_name: demo_mpesa_fraud
63
+ model:
64
+ base_model: distilbert-base-uncased
65
+ tokenizer:
66
+ max_length: 64
67
+ tasks:
68
+ - name: mpesa_fraud_detection
69
+ type: single_label_classification
70
+ data_path: jenganlp_demo/messages.jsonl
71
+ text_column: text
72
+ label_column: label
73
+ heads:
74
+ - name: fraud_head
75
+ num_labels: 2
76
+ training:
77
+ output_dir: jenganlp_demo/model
78
+ batch_size: 2
79
+ num_epochs: 3
80
+ device: cpu
81
+ logging:
82
+ service: none
83
+ data:
84
+ test_size: 0.33
85
+ YAML
86
+ ```
87
+
88
+ **3. Train, evaluate, predict:**
89
+
90
+ ```bash
91
+ jenga-nlp train --config jenganlp_demo/config.yaml
92
+ jenga-nlp evaluate --config jenganlp_demo/config.yaml --model-dir jenganlp_demo/model
93
+ jenga-nlp predict --config jenganlp_demo/config.yaml --model-dir jenganlp_demo/model \
94
+ --task-name mpesa_fraud_detection --text "Urgent M-PESA reversal request asking for PIN"
95
+ ```
96
+
97
+ **4. Load once in Python** (notebooks, batch jobs, services):
98
+
99
+ ```python
100
+ from jenga_nlp.inference.pipeline import InferencePipeline
101
+
102
+ pipeline = InferencePipeline.from_checkpoint(
103
+ model_dir="jenganlp_demo/model",
104
+ config_path="jenganlp_demo/config.yaml",
105
+ device="cpu",
106
+ )
107
+ print(pipeline.predict(text="Urgent M-PESA reversal request asking for PIN",
108
+ task_name="mpesa_fraud_detection").to_dict())
109
+ ```
110
+
111
+ > Six examples prove the pipeline works, not that the model is good. A perfect score on a handful of eval samples is meaningless — use hundreds of labelled examples per class before trusting predictions.
112
+
113
+ ## Task types
114
+
115
+ | `type` | Labels look like | Example use |
116
+ |---|---|---|
117
+ | `single_label_classification` | `1` | Fraud vs legitimate message |
118
+ | `multi_label_classification` | `{"risk_tags": [1, 1, 0, 1]}` | Several risk tags per message |
119
+ | `sentiment` | `2` | Negative / neutral / positive |
120
+ | `ner` | entity spans | Names, amounts, phone numbers |
121
+ | `regression` | `0.73` | Risk or quality score |
122
+ | `qa_scoring` | `{"opening": [1], "resolution": [1, 0, 1, 1, 0]}` | Call-centre QA checklists |
123
+
124
+ Multi-task: list several tasks under `tasks:` — they share the encoder. See [`examples/configs/fixture_multitask_cpu.yaml`](https://github.com/Rogendo/JengaNLP/blob/main/examples/configs/fixture_multitask_cpu.yaml).
125
+
126
+ ## Stable vs experimental
127
+
128
+ | Area | Status |
129
+ |---|---|
130
+ | YAML config, text training, evaluation, resume, checkpoints | **Stable** — covered by tests |
131
+ | `InferencePipeline` (single + batch), CLI predict | **Stable** — covered by tests |
132
+ | MLflow / TensorBoard logging | **Stable** |
133
+ | Hugging Face Hub export | Experimental |
134
+ | Whisper ASR fine-tuning and serving | Experimental — not yet validated on real audio/GPU; needs `ffmpeg` installed to read audio files |
135
+ | Weights & Biases, Label Studio adapters | Experimental |
136
+ | Explainability, human-in-the-loop routing, audit logging | Experimental |
137
+
138
+ Experimental features may change or move out of the core package.
139
+
140
+ ## Documentation
141
+
142
+ - [Quickstart](https://github.com/Rogendo/JengaNLP/blob/main/docs/quickstart.md)
143
+ - [Configuration reference](https://github.com/Rogendo/JengaNLP/blob/main/docs/configuration.md)
144
+ - [Inference and production serving](https://github.com/Rogendo/JengaNLP/blob/main/docs/inference.md)
145
+ - [Full usage guide](https://github.com/Rogendo/JengaNLP/blob/main/docs/usage-guide.md) — every workflow, including experimental ones
146
+ - [Example configs](https://github.com/Rogendo/JengaNLP/blob/main/examples/configs/) and [fixtures](https://github.com/Rogendo/JengaNLP/blob/main/examples/fixtures/)
147
+
148
+ ## Roadmap
149
+
150
+ 1. **African-language base models** — adapt an African-language encoder (AfriBERTa / AfroXLMR) to Swahili, Sheng and Swahili–English code-switched text.
151
+ 2. **Benchmarks** — public results on African-language datasets, including multi-task vs single-task baselines.
152
+ 3. **Ready-made templates with pretrained checkpoints** — mobile-money fraud, call-centre QA, Swahili sentiment, on the Hugging Face Hub.
153
+
154
+ ## License
155
+
156
+ MIT — see [LICENSE](https://github.com/Rogendo/JengaNLP/blob/main/LICENSE).
@@ -0,0 +1,53 @@
1
+ # JengaNLP Framework Documentation
2
+
3
+ This folder documents the `jenga_nlp` Python framework from the perspective of a user who installed or cloned the package.
4
+
5
+ Start here if you want to train, evaluate, monitor, export, or run inference with JengaNLP models.
6
+
7
+ ## Guides
8
+
9
+ | Guide | Purpose |
10
+ |---|---|
11
+ | [quickstart.md](quickstart.md) | Smallest local train -> evaluate -> predict workflow. |
12
+ | [configuration.md](configuration.md) | Explains the YAML config and how it maps to core modules. |
13
+ | [inference.md](inference.md) | Explains CLI inference, Python inference, batch inference, and production loading. |
14
+
15
+ ## Package Boundary
16
+
17
+ JengaNLP is the new package namespace:
18
+
19
+ ```python
20
+ from jenga_nlp import JengaClient
21
+ from jenga_nlp.inference.pipeline import InferencePipeline
22
+ ```
23
+
24
+ Do not use old `jenga_ai` imports for the new framework docs.
25
+
26
+ The old JengaAI platform/product story has been moved to:
27
+
28
+ ```text
29
+ docs/jenga-ai-platform-story.md
30
+ ```
31
+
32
+ ## Core Runtime Map
33
+
34
+ ```text
35
+ jenga_nlp/core/config.py YAML schema and Pydantic config models
36
+ jenga_nlp/data/processor.py CSV/JSON/JSONL loading and task preprocessing
37
+ jenga_nlp/tasks/registry.py Task type -> task class resolution
38
+ jenga_nlp/core/model.py Shared encoder + task heads
39
+ jenga_nlp/training/trainer.py Training loop, metrics, callbacks, checkpoints
40
+ jenga_nlp/inference/pipeline.py Load once and predict
41
+ jenga_nlp/client/client.py Thin convenience client
42
+ jenga_nlp/cli.py Command line entrypoint
43
+ ```
44
+
45
+ ## Current Stable Path
46
+
47
+ The most stable path today is text NLP:
48
+
49
+ ```text
50
+ config.yaml -> train -> evaluate -> predict -> InferencePipeline
51
+ ```
52
+
53
+ ASR/Whisper is present but should be treated as experimental until real audio/GPU validation is complete.
@@ -0,0 +1,128 @@
1
+ # Configuration Guide
2
+
3
+ JengaNLP uses YAML configs so training can be reproduced from a file.
4
+
5
+ A config becomes an `ExperimentConfig` object, then flows into data processing, model creation, training, checkpoints, and inference.
6
+
7
+ ## Minimal Shape
8
+
9
+ ```yaml
10
+ project_name: my_project
11
+
12
+ model:
13
+ base_model: bert-base-multilingual-cased
14
+
15
+ tokenizer:
16
+ max_length: 128
17
+ padding: max_length
18
+ truncation: true
19
+
20
+ tasks:
21
+ - name: my_task
22
+ type: single_label_classification
23
+ data_path: data/train.jsonl
24
+ text_column: text
25
+ label_column: label
26
+ heads:
27
+ - name: classifier
28
+ num_labels: 2
29
+
30
+ training:
31
+ output_dir: ./results/my_project
32
+ learning_rate: 0.00002
33
+ batch_size: 16
34
+ num_epochs: 3
35
+ device: auto
36
+ ```
37
+
38
+ ## Core Sections
39
+
40
+ | Section | Consumed By | Purpose |
41
+ |---|---|---|
42
+ | `project_name` | CLI, logs, integrations | Human-readable run name. |
43
+ | `model` | `MultiTaskModel` | Base encoder and model behavior. |
44
+ | `tokenizer` | `DataProcessor`, `InferencePipeline` | Token length, padding, truncation. |
45
+ | `tasks` | `DataProcessor`, `TaskRegistry`, formatters | Defines task type, data, columns, heads. |
46
+ | `training` | `Trainer` | Optimizer, batch size, epochs, output, callbacks. |
47
+ | `integrations` | `IntegrationRuntime` | MLflow, TensorBoard, W&B, Label Studio artifact adapters. |
48
+
49
+ ## Task Types
50
+
51
+ | Type | Label Shape | Use Case |
52
+ |---|---|---|
53
+ | `single_label_classification` | integer class id | topic, fraud, spam |
54
+ | `multi_label_classification` | list/vector of 0/1 labels | multiple flags per text |
55
+ | `sentiment` | integer class id | negative/neutral/positive |
56
+ | `ner` | entity span list | names, places, organizations |
57
+ | `regression` | float | risk, severity, quality score |
58
+ | `qa_scoring` | dict of checklist vectors | call-center QA/compliance |
59
+
60
+ `question_answering` currently maps to `qa_scoring` for backward compatibility. It is not extractive question answering yet.
61
+
62
+ ## Data Formats
63
+
64
+ Supported text dataset files:
65
+
66
+ - `.jsonl`
67
+ - `.json`
68
+ - `.csv`
69
+
70
+ Single-label example:
71
+
72
+ ```json
73
+ {"text":"Share your PIN now","label":1}
74
+ ```
75
+
76
+ Multi-label example:
77
+
78
+ ```json
79
+ {"text":"Threatening scam message","labels":[1,1,0]}
80
+ ```
81
+
82
+ QA scoring example:
83
+
84
+ ```json
85
+ {
86
+ "text":"Thank you for calling. How can I help?",
87
+ "labels": {
88
+ "opening": [1],
89
+ "listening": [1, 0, 1],
90
+ "closing": [0]
91
+ }
92
+ }
93
+ ```
94
+
95
+ ## Bounded Regression
96
+
97
+ Use bounded regression when the target is a constrained score, for example `0.0` to `1.0`.
98
+
99
+ ```yaml
100
+ heads:
101
+ - name: risk
102
+ num_labels: 1
103
+ activation: sigmoid
104
+ output_min: 0.0
105
+ output_max: 1.0
106
+ ```
107
+
108
+ ## Logging
109
+
110
+ Simple direct logging:
111
+
112
+ ```yaml
113
+ training:
114
+ logging:
115
+ service: mlflow
116
+ experiment_name: my_project
117
+ tracking_uri: sqlite:///mlflow.db
118
+ ```
119
+
120
+ Adapter logging:
121
+
122
+ ```yaml
123
+ integrations:
124
+ - type: tensorboard
125
+ enabled: true
126
+ params:
127
+ log_dir: /tmp/jenganlp_tensorboard
128
+ ```