Add SocrateX library section + module reference table

README.md

@@ -173,3 +173,88 @@ model.generate_data(
 )
 images, labels = model.load_data("my_train_data/labels.csv")
 ```
+
+---
+
+## Using the SocrateX Library Directly
+
+If you prefer to use SocrateX as a standalone library (e.g. in a training script), the API is identical — just `import SocrateX as sx`.
+
+```python
+import SocrateX as sx
+import torch
+from torch.utils.data import DataLoader
+
+# ─── 1. Tokenizer ────────────────────────────────────────────────────────────
+tokenizer = sx.load_tokenizer("ocr_bpe_tokenizer.json")
+# or build a fresh one:
+# tokenizer = sx.init_tokenizer()
+
+# ─── 2. Config ───────────────────────────────────────────────────────────────
+config = sx.Config(
+    d_model=640,
+    nhead=10,
+    num_layers=12,
+    dim_feedforward=2560,
+    pool_height=4
+)
+
+# ─── 3. Model ────────────────────────────────────────────────────────────────
+model = sx.init(config=config, tokenizer=tokenizer, device="cuda")
+# or use a preset:
+# model = sx.cat(tokenizer=tokenizer, weights="previous.pt", device="cuda")
+# model = sx.rat(tokenizer=tokenizer, device="cuda")
+# model = sx.mice(tokenizer=tokenizer, device="cuda")
+
+# ─── 4. Dataset ──────────────────────────────────────────────────────────────
+images, labels = sx.load_dataset("label.csv")
+dataset = sx.Makeset(images, labels, tokenizer=tokenizer)
+sampler = sx.SmartBatchSampler(labels, batch_size=32)
+loader  = DataLoader(dataset, batch_sampler=sampler)
+
+# ─── 5. Train ────────────────────────────────────────────────────────────────
+optimizer = torch.optim.AdamW(model.parameters(), lr=1e-4)
+criterion = torch.nn.CrossEntropyLoss(ignore_index=tokenizer.token_to_id("<pad>"))
+
+trainer = sx.Trainer(model, loader, optimizer, criterion, device="cuda")
+for epoch in range(50):
+    loss = trainer.train_epoch()
+    print(f"Epoch {epoch} | Loss: {loss:.4f}")
+
+# ─── 6. Inference ────────────────────────────────────────────────────────────
+results = model.predict(
+    image_paths=["receipt.jpg", "document.png"],
+    function="generate",
+    max_iter=64,
+    temp=0.5,
+    top_k=5,
+    penalty=1.15
+)
+print(results)
+
+# ─── 7. Synthetic Data ───────────────────────────────────────────────────────
+sx.generate_silly_training_set(
+    source="https://raw.githubusercontent.com/first20hours/google-10000-english/master/google-10000-english-no-swears.txt",
+    count=1000,
+    output_dir="train_data"
+)
+```
+
+### SocrateX Module Reference
+
+| Module | What it does |
+|--------|-------------|
+| `sx.Config(...)` | Define custom architecture |
+| `sx.init(config, tokenizer)` | Build model from scratch |
+| `sx.cat / sx.rat / sx.mice` | Preset-sized models |
+| `sx.load_tokenizer(path)` | Load BPE tokenizer from file |
+| `sx.init_tokenizer()` | Build a fresh tokenizer |
+| `sx.load_dataset(path)` | Load CSV/JSON/TXT → (images, labels) |
+| `sx.Makeset(images, labels, ...)` | Create a PyTorch Dataset |
+| `sx.SmartBatchSampler(labels, batch_size)` | Length-sorted batch sampler |
+| `sx.Trainer(model, loader, opt, crit)` | Training loop wrapper |
+| `sx.predict(...)` | Run inference on image list |
+| `sx.generate(...)` | Greedy autoregressive generation |
+| `sx.beam_search(...)` | Beam search decoding |
+| `sx.generate_silly_training_set(...)` | Generate synthetic word images |
+