ihatebaselines commited on
Commit
79ca052
·
verified ·
1 Parent(s): 6d13da1

Update README: full API table + unified model.* usage

Browse files
Files changed (1) hide show
  1. README.md +76 -39
README.md CHANGED
@@ -24,21 +24,16 @@ Built with the **SocrateX** library — a modular, easy-to-use training framewor
24
  ## Quick Start — Use the Pre-trained Model
25
 
26
  ```python
 
27
  from huggingface_hub import hf_hub_download
28
- from tokenizers import Tokenizer
29
- import torch
30
-
31
- # Download model files
32
- model_path = hf_hub_download("ihatebaselines/Socrate", "pytorch_model.bin")
33
- tok_path = hf_hub_download("ihatebaselines/Socrate", "ocr_bpe_tokenizer.json")
34
 
35
- # Load tokenizer
36
- tokenizer = Tokenizer.from_file(tok_path)
37
-
38
- # Load model with AutoModel (requires trust_remote_code=True)
39
- from transformers import AutoModel
40
  model = AutoModel.from_pretrained("ihatebaselines/Socrate", trust_remote_code=True)
41
 
 
 
 
 
42
  # Run OCR on an image
43
  results = model.predict(["your_image.jpg"], function="generate", max_iter=64)
44
  print(results)
@@ -48,18 +43,16 @@ print(results)
48
 
49
  ## Quick Start — Build Your Own Custom Model (no pretrained weights)
50
 
51
- You can use the **SocrateX** library to define your own architecture from scratch using `sx.Config()`.
52
- No pretrained weights required — full control over every parameter.
53
 
54
  ```python
55
- import SocrateX as sx
56
- import torch
57
 
58
- # 1. Load tokenizer
59
- tokenizer = sx.load_tokenizer(hf_hub_download("ihatebaselines/Socrate", "ocr_bpe_tokenizer.json"))
60
 
61
- # 2. Define your own architecture — these give ~15M params
62
- config = sx.Config(
63
  d_model=256,
64
  nhead=4,
65
  num_layers=4,
@@ -67,50 +60,80 @@ config = sx.Config(
67
  pool_height=4
68
  )
69
 
70
- # 3. Build model from scratch — no weights loaded
71
- model = sx.init(config=config, tokenizer=tokenizer, device="cuda")
 
 
72
 
73
- total_params = sum(p.numel() for p in model.parameters())
 
 
 
74
  print(f"Your model has {total_params:,} parameters")
75
 
76
- # 4. Build a dataset and train
77
- images, labels = sx.load_dataset("your_label.csv")
78
- dataset = sx.Makeset(images, labels, tokenizer=tokenizer)
79
- sampler = sx.SmartBatchSampler(labels, batch_size=16)
80
 
 
 
81
  from torch.utils.data import DataLoader
82
- loader = DataLoader(dataset, batch_sampler=sampler)
83
 
84
- optimizer = torch.optim.AdamW(model.parameters(), lr=1e-4)
85
- criterion = torch.nn.CrossEntropyLoss(ignore_index=tokenizer.token_to_id("<pad>"))
86
 
87
- trainer = sx.Trainer(model, loader, optimizer, criterion, device="cuda")
 
 
 
 
88
  for epoch in range(50):
89
  loss = trainer.train_epoch()
90
  print(f"Epoch {epoch} | Loss: {loss:.4f}")
91
 
92
- # 5. Run inference
93
- results = model.predict(["test.jpg"], function="generate", max_iter=64)
94
  print(results)
95
  ```
96
 
97
  ---
98
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
99
  ## Architecture Presets
100
 
101
  | Model | Params | Notes |
102
  |-------|--------|-------|
103
- | `sx.cat` | 159M | This checkpoint (d_model=640, 12 layers) |
104
- | `sx.rat` | ~80M | d_model=512, 8 layers |
105
- | `sx.mice` | ~40M | d_model=384, 6 layers |
106
- | Custom via `sx.Config` | Your choice | Full control |
107
 
108
  ---
109
 
110
- ## `sx.Config` — All Parameters
111
 
112
  ```python
113
- config = sx.Config(
114
  d_model=640, # Transformer hidden dimension
115
  nhead=10, # Multi-head attention heads
116
  num_layers=12, # Number of Transformer layers
@@ -127,7 +150,7 @@ config = sx.Config(
127
  ## Inference Functions
128
 
129
  ```python
130
- # Simple greedy generation
131
  results = model.predict(images, function="generate", max_iter=64, temp=0.7, top_k=5, penalty=1.15)
132
 
133
  # Faster generation (less accurate but quicker)
@@ -136,3 +159,17 @@ results = model.predict(images, function="generate_fast", max_iter=64)
136
  # Beam search (most accurate)
137
  results = model.predict(images, function="beam_search", max_iter=64, beam_width=4)
138
  ```
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
24
  ## Quick Start — Use the Pre-trained Model
25
 
26
  ```python
27
+ from transformers import AutoModel
28
  from huggingface_hub import hf_hub_download
 
 
 
 
 
 
29
 
30
+ # Load pre-trained Socrate (159M) directly from HuggingFace
 
 
 
 
31
  model = AutoModel.from_pretrained("ihatebaselines/Socrate", trust_remote_code=True)
32
 
33
+ # Load the tokenizer
34
+ tok_path = hf_hub_download("ihatebaselines/Socrate", "ocr_bpe_tokenizer.json")
35
+ tokenizer = model.make_tokenizer(tok_path)
36
+
37
  # Run OCR on an image
38
  results = model.predict(["your_image.jpg"], function="generate", max_iter=64)
39
  print(results)
 
43
 
44
  ## Quick Start — Build Your Own Custom Model (no pretrained weights)
45
 
46
+ No need to install SocrateX separately. Everything is built into the model object.
 
47
 
48
  ```python
49
+ from transformers import AutoModel
 
50
 
51
+ # Load model from HuggingFace (only needed to access the class + tokenizer)
52
+ model = AutoModel.from_pretrained("ihatebaselines/Socrate", trust_remote_code=True)
53
 
54
+ # 1. Create your own architecture config
55
+ cfg = model.create_config(
56
  d_model=256,
57
  nhead=4,
58
  num_layers=4,
 
60
  pool_height=4
61
  )
62
 
63
+ # 2. Create a tokenizer
64
+ tok = model.make_tokenizer() # fresh tokenizer
65
+ # or load an existing one:
66
+ # tok = model.make_tokenizer("ocr_bpe_tokenizer.json")
67
 
68
+ # 3. Build a brand-new model from your config (no pretrained weights)
69
+ my_model = model.new(config=cfg, tokenizer=tok, device="cuda")
70
+
71
+ total_params = sum(p.numel() for p in my_model.parameters())
72
  print(f"Your model has {total_params:,} parameters")
73
 
74
+ # 4. Load your dataset
75
+ images, labels = my_model.load_data("your_label.csv")
 
 
76
 
77
+ # 5. Build a dataset + DataLoader
78
+ import torch
79
  from torch.utils.data import DataLoader
 
80
 
81
+ dataset = my_model.make_dataset(images, labels)
82
+ loader = DataLoader(dataset, batch_size=16, shuffle=True)
83
 
84
+ # 6. Train
85
+ optimizer = torch.optim.AdamW(my_model.parameters(), lr=1e-4)
86
+ criterion = torch.nn.CrossEntropyLoss(ignore_index=tok.token_to_id("<pad>"))
87
+
88
+ trainer = my_model.make_trainer(loader, optimizer, criterion)
89
  for epoch in range(50):
90
  loss = trainer.train_epoch()
91
  print(f"Epoch {epoch} | Loss: {loss:.4f}")
92
 
93
+ # 7. Run inference
94
+ results = my_model.predict(["test.jpg"], function="generate", max_iter=64)
95
  print(results)
96
  ```
97
 
98
  ---
99
 
100
+ ## Full API — All Methods on the Model Object
101
+
102
+ Once loaded with `AutoModel.from_pretrained`, the model exposes the entire SocrateX API:
103
+
104
+ | Method | Description |
105
+ |--------|-------------|
106
+ | `model.predict(images, ...)` | Run OCR inference on a list of image paths |
107
+ | `model.fit(dataloader, optimizer, criterion, ...)` | Train the model for N epochs |
108
+ | `model.make_dataset(images, labels, ...)` | Create a `Makeset` dataset object |
109
+ | `model.create_config(d_model, nhead, ...)` | Create a custom architecture config |
110
+ | `model.new(config, tokenizer, device)` | Build a new model from scratch with your config |
111
+ | `model.make_tokenizer(path=None)` | Load or create a BPE tokenizer |
112
+ | `model.make_trainer(loader, optimizer, criterion)` | Returns a `Trainer` wired to this model |
113
+ | `model.load_data(path)` | Load images + labels from CSV/JSON/TXT |
114
+ | `model.generate_data(source, count, output_dir, mode)` | Generate synthetic training data |
115
+ | `model.freeze_encoder()` | Freeze CNN + Encoder weights (fine-tuning) |
116
+ | `model.unfreeze_encoder()` | Unfreeze encoder weights |
117
+ | `model.load_parameters(path)` | Load weights from a `.pt` checkpoint |
118
+ | `model.summary()` | Print total/trainable parameter counts |
119
+
120
+ ---
121
+
122
  ## Architecture Presets
123
 
124
  | Model | Params | Notes |
125
  |-------|--------|-------|
126
+ | `cat` | 159M | This checkpoint (d_model=640, 12 layers) |
127
+ | `rat` | ~80M | d_model=512, 8 layers |
128
+ | `mice` | ~40M | d_model=384, 6 layers |
129
+ | Custom via `create_config` | Your choice | Full control |
130
 
131
  ---
132
 
133
+ ## `create_config` — All Parameters
134
 
135
  ```python
136
+ cfg = model.create_config(
137
  d_model=640, # Transformer hidden dimension
138
  nhead=10, # Multi-head attention heads
139
  num_layers=12, # Number of Transformer layers
 
150
  ## Inference Functions
151
 
152
  ```python
153
+ # Simple greedy generation (fast, good quality)
154
  results = model.predict(images, function="generate", max_iter=64, temp=0.7, top_k=5, penalty=1.15)
155
 
156
  # Faster generation (less accurate but quicker)
 
159
  # Beam search (most accurate)
160
  results = model.predict(images, function="beam_search", max_iter=64, beam_width=4)
161
  ```
162
+
163
+ ---
164
+
165
+ ## Generate Synthetic Training Data
166
+
167
+ ```python
168
+ model.generate_data(
169
+ source="https://raw.githubusercontent.com/first20hours/google-10000-english/master/google-10000-english-no-swears.txt",
170
+ count=1000,
171
+ output_dir="my_train_data",
172
+ mode="train" # or "test"
173
+ )
174
+ images, labels = model.load_data("my_train_data/labels.csv")
175
+ ```