Update README with Nubank case study and expanded repo structure

README.md

@@ -18,6 +18,17 @@ Text LLM:      "The cat sat on the mat" → [The] [cat] [sat] [on] [the] [mat]
 domainTokenizer: Customer purchase history → [HighEndElectronics] [WeekdayCredit] [Accessory+SameDay] → Transformer → next purchase
 ```
 
+## 🏦 Industry Validation: Nubank's nuFormer
+
+This isn't just theory. **Nubank** (100M+ customers, Latin America's largest digital bank) built exactly this and published the full recipe:
+
+- **Paper:** ["Your spending needs attention: Modeling financial habits with transformers"](https://arxiv.org/abs/2507.23267) (arXiv: 2507.23267)
+- **Blog series:** [Building Nubank — Foundation Models](https://building.nubank.com/unlocking-financial-insights-how-nubank-powers-personalized-experiences-with-foundation-models/)
+
+**Their approach:** 97 special tokens for structured fields (amount bins, calendar features, credit/debit sign) + BPE for merchant descriptions → **~14 tokens per transaction** → GPT-style Transformer (24M-330M params) → **+1.25% relative AUC over LightGBM** (3× their production launch threshold).
+
+📄 **Full reverse-engineering:** [`docs/nubank_nuformer_analysis.md`](docs/nubank_nuformer_analysis.md) — complete pipeline reconstruction with code patterns, scaling laws, and adaptation guides for e-commerce and healthcare.
+
 ## Why This Matters
 
 | Problem | Text Tokenizer | Domain Tokenizer |
@@ -29,7 +40,7 @@ domainTokenizer: Customer purchase history → [HighEndElectronics] [WeekdayCred
 
 ## Research Foundation
 
-This project is grounded in 30+ papers from Google, Google DeepMind, and the broader research community. The key finding: **any sequential domain data can be tokenized and modeled with the LLM paradigm** — the challenge is *how* to tokenize.
+This project is grounded in 35+ papers from Google, Google DeepMind, Nubank, Yandex, and the broader research community. The key finding: **any sequential domain data can be tokenized and modeled with the LLM paradigm** — the challenge is *how* to tokenize.
 
 Five paradigms have emerged:
 
@@ -37,35 +48,42 @@ Five paradigms have emerged:
 |----------|--------|-----------|
 | **Semantic IDs** | RQ-VAE quantization of item embeddings | [TIGER](https://arxiv.org/abs/2305.05065) (Google, 2023) |
 | **Action Tokenization** | BPE-like merging of feature patterns | [ActionPiece](https://arxiv.org/abs/2502.13581) (DeepMind, 2025) |
-| **Transaction Tokenization** | Composite (date + amount + text) encoding | [Banking TF](https://arxiv.org/abs/2410.08243) (2024) |
-| **Tabular Tokenization** | Relative magnitude encoding for numbers | [TP-BERTa](https://arxiv.org/abs/2403.01841) (2024) |
+| **Transaction Tokenization** | Special tokens + BPE hybrid | [nuFormer](https://arxiv.org/abs/2507.23267) (Nubank, 2025) |
+| **Tabular Tokenization** | Periodic embeddings for numbers | [PLR](https://arxiv.org/abs/2203.05556) (Yandex, 2022) |
 | **Universal Tokenization** | All modalities → shared discrete space | [Meta-Transformer](https://arxiv.org/abs/2307.10802) (2023) |
 
-📄 **Full research report:** [`docs/research_report.md`](docs/research_report.md)
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [`docs/research_report.md`](docs/research_report.md) | **Comprehensive research survey** — 31 papers across 5 paradigms, technical taxonomy of tokenization methods, full blueprint for building domain tokenizers |
+| [`docs/nubank_nuformer_analysis.md`](docs/nubank_nuformer_analysis.md) | **Nubank reverse-engineering** — complete pipeline reconstruction (tokenizer → pre-training → joint fusion), all 4 academic pillars explained, adaptation playbooks for finance/e-commerce/healthcare |
 
 ## Project Vision
 
-### Phase 1: Research & Survey (✅ Current)
-- Literature survey of domain tokenization methods
-- Analysis of tokenization strategies across recommendation, finance, tabular, and universal domains
+### Phase 1: Research & Survey ✅
+- Literature survey of domain tokenization methods (31+ papers)
+- Nubank nuFormer full reverse-engineering
 - Blueprint for a general-purpose domain tokenizer
 
-### Phase 2: Core Tokenizer Library
+### Phase 2: Core Tokenizer Library (Next)
 - Implement per-field tokenizers:
-  - `SemanticIDTokenizer` — RQ-VAE for entity encoding
-  - `MagnitudeTokenizer` — relative magnitude binning for numerical values
-  - `TemporalTokenizer` — calendar + relative delta encoding
+  - `SignBucketTokenizer` — sign + magnitude bins for monetary values (Nubank-style)
+  - `CalendarTokenizer` — month/dow/dom/hour decomposition
+  - `SemanticIDTokenizer` — RQ-VAE for entity encoding (TIGER-style)
+  - `PLREmbedding` — periodic linear representation for numerical tabular features
   - `CompositeTokenizer` — BPE-like merging of multi-field patterns (ActionPiece-style)
 - Schema-driven automatic tokenizer selection
 
 ### Phase 3: Pre-training Framework
-- Self-supervised objectives: Masked Event Prediction, Next Event Prediction
-- Small Transformer backbone (10M–350M parameters)
-- Domain-agnostic training loop that works with any tokenizer configuration
+- GPT-style causal LM with NoPE (no positional encoding)
+- Small Transformer backbone (24M–350M parameters, following Nubank's sizes)
+- Joint fusion with DCNv2 + PLR for tabular features
+- Domain-agnostic training loop
 
 ### Phase 4: Domain Demos
+- Finance: transaction recommendation, fraud detection, credit scoring
 - E-commerce: next purchase prediction, customer segmentation
-- Finance: fraud detection, credit scoring
 - Healthcare: clinical event prediction
 
 ## Repo Structure
@@ -73,12 +91,13 @@ Five paradigms have emerged:
 ```
 domainTokenizer/
 ├── docs/
-│   └── research_report.md    # Detailed research findings (30+ papers)
-├── src/                       # (coming) Core library
-│   ├── tokenizers/            # Per-field tokenizer implementations
-│   ├── models/                # Small Transformer backbones
-│   └── training/              # Pre-training and fine-tuning
-├── examples/                  # (coming) Domain-specific demos
+│   ├── research_report.md          # 51KB — Full research survey (31+ papers)
+│   └── nubank_nuformer_analysis.md # Nubank pipeline reverse-engineering
+├── src/                             # (Phase 2) Core library
+│   ├── tokenizers/                  # Per-field tokenizer implementations
+│   ├── models/                      # Small Transformer backbones
+│   └── training/                    # Pre-training and fine-tuning
+├── examples/                        # (Phase 4) Domain-specific demos
 └── README.md
 ```
 
@@ -86,16 +105,19 @@ domainTokenizer/
 
 | Paper | Year | What It Does | Link |
 |-------|------|-------------|------|
-| TIGER | 2023 | Semantic IDs for products via RQ-VAE | [arXiv](https://arxiv.org/abs/2305.05065) |
-| ActionPiece | 2025 | BPE for user action sequences | [arXiv](https://arxiv.org/abs/2502.13581) |
-| Banking TF | 2024 | Tokenizer for financial transactions | [arXiv](https://arxiv.org/abs/2410.08243) |
-| LETTER | 2024 | Learnable item tokenization | [arXiv](https://arxiv.org/abs/2405.07314) |
-| TP-BERTa | 2024 | Numerical value tokenization | [arXiv](https://arxiv.org/abs/2403.01841) |
+| **nuFormer** (Nubank) | 2025 | Transaction foundation model at production scale | [arXiv](https://arxiv.org/abs/2507.23267) |
+| TIGER (Google) | 2023 | Semantic IDs for products via RQ-VAE | [arXiv](https://arxiv.org/abs/2305.05065) |
+| ActionPiece (DeepMind) | 2025 | BPE for user action sequences | [arXiv](https://arxiv.org/abs/2502.13581) |
+| RecFormer | 2023 | Items as key-value text representations | [arXiv](https://arxiv.org/abs/2305.13731) |
+| PLR Embeddings (Yandex) | 2022 | Periodic embeddings for numerical features | [arXiv](https://arxiv.org/abs/2203.05556) |
+| DCN V2 (Google) | 2021 | Feature crossing for tabular data | [arXiv](https://arxiv.org/abs/2008.13535) |
+| NoPE | 2023 | No positional encoding beats RoPE/ALiBi | [arXiv](https://arxiv.org/abs/2305.19466) |
+| Banking TF | 2024 | Transaction tokenizer for French banking | [arXiv](https://arxiv.org/abs/2410.08243) |
 | Meta-Transformer | 2023 | 12 modalities, one token space | [arXiv](https://arxiv.org/abs/2307.10802) |
 | NTP Survey | 2024 | Comprehensive multimodal NTP taxonomy | [arXiv](https://arxiv.org/abs/2412.18619) |
 | Nested Learning (HOPE) | 2025 | Continual learning via multi-timescale memory | [arXiv](https://arxiv.org/abs/2512.24695) |
 
-See the [full reference table](docs/research_report.md#10-complete-paper-reference-table) with 31 papers in the research report.
+See the [full reference table](docs/research_report.md#10-complete-paper-reference-table) with 35+ papers in the research report.
 
 ## License