instmodel 1.3.0__tar.gz → 1.4.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 (39) hide show
  1. instmodel-1.4.0/PKG-INFO +88 -0
  2. instmodel-1.4.0/README.md +66 -0
  3. instmodel-1.4.0/instmodel/__init__.py +16 -0
  4. instmodel-1.4.0/instmodel/_core.py +680 -0
  5. instmodel-1.4.0/instmodel/instruction_model.py +440 -0
  6. instmodel-1.4.0/instmodel/sequence/__init__.py +31 -0
  7. instmodel-1.4.0/instmodel/sequence/_spec.py +305 -0
  8. instmodel-1.4.0/instmodel/sequence/reference.py +70 -0
  9. instmodel-1.4.0/instmodel/sequence/tf.py +331 -0
  10. instmodel-1.4.0/instmodel/sequence/torch.py +283 -0
  11. instmodel-1.4.0/instmodel/tf.py +395 -0
  12. instmodel-1.4.0/instmodel/torch.py +499 -0
  13. {instmodel-1.3.0 → instmodel-1.4.0}/instmodel/training_utils.py +10 -6
  14. instmodel-1.4.0/instmodel.egg-info/PKG-INFO +88 -0
  15. {instmodel-1.3.0 → instmodel-1.4.0}/instmodel.egg-info/SOURCES.txt +11 -5
  16. {instmodel-1.3.0 → instmodel-1.4.0}/instmodel.egg-info/requires.txt +1 -2
  17. instmodel-1.4.0/pyproject.toml +28 -0
  18. instmodel-1.4.0/setup.cfg +4 -0
  19. instmodel-1.4.0/tests/test_backends.py +460 -0
  20. instmodel-1.4.0/tests/test_instruction_model.py +135 -0
  21. instmodel-1.4.0/tests/test_sequence.py +168 -0
  22. instmodel-1.4.0/tests/test_sequence_tf.py +269 -0
  23. instmodel-1.4.0/tests/test_sequence_torch.py +205 -0
  24. instmodel-1.3.0/MANIFEST.in +0 -1
  25. instmodel-1.3.0/PKG-INFO +0 -185
  26. instmodel-1.3.0/README.md +0 -160
  27. instmodel-1.3.0/instmodel/__init__.py +0 -18
  28. instmodel-1.3.0/instmodel/instruction_model.py +0 -479
  29. instmodel-1.3.0/instmodel/tf.py +0 -1752
  30. instmodel-1.3.0/instmodel/torch.py +0 -1613
  31. instmodel-1.3.0/instmodel.egg-info/PKG-INFO +0 -185
  32. instmodel-1.3.0/pyproject.toml +0 -8
  33. instmodel-1.3.0/setup.cfg +0 -35
  34. instmodel-1.3.0/setup.py +0 -6
  35. instmodel-1.3.0/tests/test_tf.py +0 -1216
  36. instmodel-1.3.0/tests/test_torch.py +0 -1166
  37. {instmodel-1.3.0 → instmodel-1.4.0}/LICENSE +0 -0
  38. {instmodel-1.3.0 → instmodel-1.4.0}/instmodel.egg-info/dependency_links.txt +0 -0
  39. {instmodel-1.3.0 → instmodel-1.4.0}/instmodel.egg-info/top_level.txt +0 -0
@@ -0,0 +1,88 @@
1
+ Metadata-Version: 2.4
2
+ Name: instmodel
3
+ Version: 1.4.0
4
+ Summary: Train TF/PyTorch models and export them to a JSON instruction format with NumPy inference
5
+ Author-email: Joao Ferreira <joaoprcf@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/Joaoprcf/instmodel
8
+ Classifier: Programming Language :: Python :: 3
9
+ Classifier: Operating System :: OS Independent
10
+ Requires-Python: >=3.10
11
+ Description-Content-Type: text/markdown
12
+ License-File: LICENSE
13
+ Requires-Dist: numpy
14
+ Requires-Dist: pandas
15
+ Requires-Dist: scipy
16
+ Provides-Extra: tensorflow
17
+ Requires-Dist: tensorflow>=2.20; extra == "tensorflow"
18
+ Requires-Dist: protobuf>=6.0; extra == "tensorflow"
19
+ Provides-Extra: pytorch
20
+ Requires-Dist: torch>=2.5; extra == "pytorch"
21
+ Dynamic: license-file
22
+
23
+ # instmodel
24
+
25
+ This repo is meant to be used with coding agents, not read manually.
26
+
27
+ Build and train small neural networks with PyTorch or TensorFlow/Keras through one shared graph API,
28
+ then export them to a compact JSON "instruction model" that runs anywhere with plain NumPy (or the
29
+ Rust/C++ inference ports) — no training framework needed at inference time.
30
+
31
+ ## Install
32
+
33
+ ```bash
34
+ pip install instmodel # NumPy inference only
35
+ pip install instmodel[pytorch] # + PyTorch training backend (instmodel.torch)
36
+ pip install instmodel[tensorflow] # + TensorFlow/Keras training backend (instmodel.tf)
37
+ ```
38
+
39
+ ## Example
40
+
41
+ ```python
42
+ import numpy as np
43
+ from instmodel.torch import Dense, InputBuffer, ModelGraph # same API in instmodel.tf
44
+ from instmodel.instruction_model import instruction_model_inference
45
+
46
+ x = InputBuffer(4)
47
+ y = Dense(1, activation="sigmoid")(Dense(8, activation="relu")(x))
48
+ model = ModelGraph(x, y)
49
+ model.compile(optimizer="adam", loss="binary_crossentropy")
50
+ model.fit(np.random.rand(64, 4), np.random.randint(0, 2, (64, 1)), epochs=5, verbose=0)
51
+
52
+ exported = model.create_instruction_model() # JSON-serialisable dict
53
+ print(instruction_model_inference(exported, np.random.rand(3, 4))[-1])
54
+ ```
55
+
56
+ ## Sequence models
57
+
58
+ `instmodel.sequence` trains small causal transformers and exports them as an instruction model
59
+ that processes one token per run. The attention caches are explicit state owned by the caller,
60
+ so any runtime can decode token by token (NumPy here, or `SequenceModel` in the Rust port).
61
+
62
+ ```python
63
+ import numpy as np
64
+ from instmodel import sequence
65
+ from instmodel.sequence import torch as backend # same API in instmodel.sequence.tf
66
+
67
+ config = sequence.TransformerConfig(vocab_size=16, width=16, heads=4, kv_heads=2)
68
+ model = backend.Transformer(config, members=2) # two copies trained in one batch
69
+
70
+ start = np.random.randint(0, 16, (4096, 1))
71
+ tokens = (start + np.arange(13)) % 16 # rows [N, time + 1]; learn "next = token + 1"
72
+ rows = dict(tokens=backend.torch.as_tensor(tokens), groups=backend.torch.zeros(4096, 12, dtype=int))
73
+ trainer = backend.Trainer(model, rows, batch=64, lr=3e-3, ema=0.99)
74
+ for step in range(400):
75
+ trainer.step(backend.schedule(step / 400, 3e-3))
76
+
77
+ exported = sequence.export_step_model(config, trainer.averaged().member_parameters(0))
78
+ session = sequence.SequenceSession(exported) # keeps the key/value cache between steps
79
+ print(session.step([3]).argmax(-1)) # -> [4]
80
+ ```
81
+
82
+ `TransformerConfig` also covers grouped-query attention, looped (weight-shared) passes and
83
+ `SegmentFeatures`; `sequence_loss` takes per-position groups, allowed-token masks and soft targets.
84
+ `add_validation_sequences` stores reference logits in the file for other runtimes to replay.
85
+
86
+ ## License
87
+
88
+ [MIT](LICENSE)
@@ -0,0 +1,66 @@
1
+ # instmodel
2
+
3
+ This repo is meant to be used with coding agents, not read manually.
4
+
5
+ Build and train small neural networks with PyTorch or TensorFlow/Keras through one shared graph API,
6
+ then export them to a compact JSON "instruction model" that runs anywhere with plain NumPy (or the
7
+ Rust/C++ inference ports) — no training framework needed at inference time.
8
+
9
+ ## Install
10
+
11
+ ```bash
12
+ pip install instmodel # NumPy inference only
13
+ pip install instmodel[pytorch] # + PyTorch training backend (instmodel.torch)
14
+ pip install instmodel[tensorflow] # + TensorFlow/Keras training backend (instmodel.tf)
15
+ ```
16
+
17
+ ## Example
18
+
19
+ ```python
20
+ import numpy as np
21
+ from instmodel.torch import Dense, InputBuffer, ModelGraph # same API in instmodel.tf
22
+ from instmodel.instruction_model import instruction_model_inference
23
+
24
+ x = InputBuffer(4)
25
+ y = Dense(1, activation="sigmoid")(Dense(8, activation="relu")(x))
26
+ model = ModelGraph(x, y)
27
+ model.compile(optimizer="adam", loss="binary_crossentropy")
28
+ model.fit(np.random.rand(64, 4), np.random.randint(0, 2, (64, 1)), epochs=5, verbose=0)
29
+
30
+ exported = model.create_instruction_model() # JSON-serialisable dict
31
+ print(instruction_model_inference(exported, np.random.rand(3, 4))[-1])
32
+ ```
33
+
34
+ ## Sequence models
35
+
36
+ `instmodel.sequence` trains small causal transformers and exports them as an instruction model
37
+ that processes one token per run. The attention caches are explicit state owned by the caller,
38
+ so any runtime can decode token by token (NumPy here, or `SequenceModel` in the Rust port).
39
+
40
+ ```python
41
+ import numpy as np
42
+ from instmodel import sequence
43
+ from instmodel.sequence import torch as backend # same API in instmodel.sequence.tf
44
+
45
+ config = sequence.TransformerConfig(vocab_size=16, width=16, heads=4, kv_heads=2)
46
+ model = backend.Transformer(config, members=2) # two copies trained in one batch
47
+
48
+ start = np.random.randint(0, 16, (4096, 1))
49
+ tokens = (start + np.arange(13)) % 16 # rows [N, time + 1]; learn "next = token + 1"
50
+ rows = dict(tokens=backend.torch.as_tensor(tokens), groups=backend.torch.zeros(4096, 12, dtype=int))
51
+ trainer = backend.Trainer(model, rows, batch=64, lr=3e-3, ema=0.99)
52
+ for step in range(400):
53
+ trainer.step(backend.schedule(step / 400, 3e-3))
54
+
55
+ exported = sequence.export_step_model(config, trainer.averaged().member_parameters(0))
56
+ session = sequence.SequenceSession(exported) # keeps the key/value cache between steps
57
+ print(session.step([3]).argmax(-1)) # -> [4]
58
+ ```
59
+
60
+ `TransformerConfig` also covers grouped-query attention, looped (weight-shared) passes and
61
+ `SegmentFeatures`; `sequence_loss` takes per-position groups, allowed-token masks and soft targets.
62
+ `add_validation_sequences` stores reference logits in the file for other runtimes to replay.
63
+
64
+ ## License
65
+
66
+ [MIT](LICENSE)
@@ -0,0 +1,16 @@
1
+ # MIT License
2
+ # Copyright (c) 2025 João Ferreira
3
+ # See LICENSE file for details.
4
+ import importlib
5
+
6
+ from . import instruction_model, training_utils # noqa: F401
7
+
8
+
9
+ def __getattr__(name):
10
+ # Training backends are optional and heavy; import them on first access.
11
+ if name in ("tf", "torch"):
12
+ try:
13
+ return importlib.import_module(f".{name}", __name__)
14
+ except ImportError as e:
15
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r} ({e})") from e
16
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")