shadow-tools 0.4.0__tar.gz → 0.4.2__tar.gz

{shadow_tools-0.4.0 → shadow_tools-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: shadow-tools
-Version: 0.4.0
+Version: 0.4.2
 Summary: A practical all-in-one Python toolkit for HTTP, WebSockets, files, data, validation, async work, and CLIs.
 Project-URL: Homepage, https://github.com/WilliamLaurento/shadow-tools
 Project-URL: Issues, https://github.com/WilliamLaurento/shadow-tools/issues
@@ -145,6 +145,19 @@ trainer = Trainer(config)
 history = trainer.fit(train_loader, validation_loader)
 ```
 
+For normal lists, use the short root-level API—no PyTorch imports or loaders:
+
+```python
+from shadowtools import train
+
+model, history = train(
+    features=[[0, 1], [1, 1], [0, 0], [1, 0]],
+    labels=[1, 1, 0, 0],
+    epochs=10,
+)
+print(history)
+```
+
 ```bash
 shadow get https://api.github.com --json
 shadow json-format settings.json

{shadow_tools-0.4.0 → shadow_tools-0.4.2}/README.md

@@ -119,6 +119,19 @@ trainer = Trainer(config)
 history = trainer.fit(train_loader, validation_loader)
 ```
 
+For normal lists, use the short root-level API—no PyTorch imports or loaders:
+
+```python
+from shadowtools import train
+
+model, history = train(
+    features=[[0, 1], [1, 1], [0, 0], [1, 0]],
+    labels=[1, 1, 0, 0],
+    epochs=10,
+)
+print(history)
+```
+
 ```bash
 shadow get https://api.github.com --json
 shadow json-format settings.json

{shadow_tools-0.4.0 → shadow_tools-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "shadow-tools"
-version = "0.4.0"
+version = "0.4.2"
 description = "A practical all-in-one Python toolkit for HTTP, WebSockets, files, data, validation, async work, and CLIs."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -35,5 +35,8 @@ Issues = "https://github.com/WilliamLaurento/shadow-tools/issues"
 [tool.hatch.build.targets.wheel]
 packages = ["src/shadowtools"]
 
+[tool.hatch.build]
+exclude = ["*.zip", "release-*", "dist", "build", ".pytest_cache"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{shadow_tools-0.4.0 → shadow_tools-0.4.2}/src/shadowtools/__init__.py

@@ -10,12 +10,13 @@ from .network import generate_random_ips, generate_test_ips, is_subdomain_of, ma
 from .retry import retry
 from .security import audit_headers, make_password, redact_secrets, verify_file_hash
 from .text import chunks, slugify, to_camel, to_snake
+from .training import fine_tune, make_loaders, train
 from .validation import is_email, is_url, require_keys
 
-__version__ = "0.4.0"
+__version__ = "0.4.2"
 
 __all__ = [
     "append_text", "audit_headers", "chunks", "ensure_dir", "env", "file_hash", "generate_random_ips", "generate_test_ips", "get", "hash_text", "is_email", "is_subdomain_of", "is_url", "make_password", "make_subdomain", "random_token", "read_csv",
-    "read_json", "read_text", "request", "require_env", "require_keys", "retry", "reverse_dns", "resolve_dns", "slugify", "timestamp_id", "to_bool", "to_camel", "to_snake", "uuid4", "write_csv",
+    "read_json", "read_text", "request", "require_env", "require_keys", "retry", "reverse_dns", "resolve_dns", "slugify", "timestamp_id", "to_bool", "to_camel", "to_snake", "train", "fine_tune", "make_loaders", "uuid4", "write_csv",
     "write_json", "write_text", "redact_secrets", "verify_file_hash",
 ]

{shadow_tools-0.4.0 → shadow_tools-0.4.2}/src/shadowtools/training.py

@@ -168,3 +168,63 @@ class Trainer:
 def run_training(config: TrainingConfig | Mapping[str, Any], train_data: Iterable[Any], validation_data: Iterable[Any] | None = None) -> tuple[Trainer, list[dict[str, float]]]:
     trainer = Trainer(config)
     return trainer, trainer.fit(train_data, validation_data)
+
+
+def make_loaders(features: Any, labels: Any, *, batch_size: int = 32,
+                 validation_split: float = 0.2, shuffle: bool = True) -> tuple[Any, Any]:
+    """Turn ordinary lists or tensors into PyTorch training and validation loaders."""
+    torch = Trainer._torch()
+    if not 0 < validation_split < 1:
+        raise ValueError("validation_split must be between 0 and 1.")
+    x = torch.as_tensor(features, dtype=torch.float32)
+    y = torch.as_tensor(labels, dtype=torch.long).flatten()
+    if x.ndim != 2:
+        raise ValueError("features must be a 2D list or tensor: rows by input values.")
+    if len(x) != len(y) or len(x) < 2:
+        raise ValueError("features and labels must have the same length of at least 2.")
+    if int(y.min()) < 0:
+        raise ValueError("labels must be zero or positive integer class IDs.")
+    order = torch.randperm(len(x)) if shuffle else torch.arange(len(x))
+    split = max(1, min(len(x) - 1, round(len(x) * (1 - validation_split))))
+    train_set = torch.utils.data.TensorDataset(x[order[:split]], y[order[:split]])
+    validation_set = torch.utils.data.TensorDataset(x[order[split:]], y[order[split:]])
+    return (
+        torch.utils.data.DataLoader(train_set, batch_size=batch_size, shuffle=shuffle),
+        torch.utils.data.DataLoader(validation_set, batch_size=batch_size),
+    )
+
+
+def train(features: Any, labels: Any, *, hidden_sizes: list[int] | None = None,
+          epochs: int = 5, learning_rate: float = 1e-3, batch_size: int = 32,
+          validation_split: float = 0.2, device: str = "auto",
+          checkpoint_path: str | Path | None = None) -> tuple[Trainer, list[dict[str, float]]]:
+    """Train a classifier from regular Python lists or tensors in one call."""
+    torch = Trainer._torch()
+    x = torch.as_tensor(features)
+    y = torch.as_tensor(labels).flatten()
+    if x.ndim != 2 or not len(y):
+        raise ValueError("features must be 2D and labels must not be empty.")
+    train_loader, validation_loader = make_loaders(features, labels, batch_size=batch_size, validation_split=validation_split)
+    config = TrainingConfig(
+        mode="from_scratch", epochs=epochs, learning_rate=learning_rate, batch_size=batch_size,
+        device=device, checkpoint_path=checkpoint_path,
+        architecture={"type": "mlp", "input_size": int(x.shape[1]),
+                      "hidden_sizes": hidden_sizes or [64, 32],
+                      "num_classes": int(y.max().item()) + 1},
+    )
+    return run_training(config, train_loader, validation_loader)
+
+
+def fine_tune(model: Any, features: Any, labels: Any, *, epochs: int = 3,
+              learning_rate: float = 1e-4, batch_size: int = 32,
+              validation_split: float = 0.2, freeze_layers: tuple[str, ...] = (),
+              head_attr: str | None = None, num_classes: int | None = None,
+              device: str = "auto", checkpoint_path: str | Path | None = None) -> tuple[Trainer, list[dict[str, float]]]:
+    """Fine-tune a supplied PyTorch classifier from regular lists or tensors."""
+    train_loader, validation_loader = make_loaders(features, labels, batch_size=batch_size, validation_split=validation_split)
+    config = TrainingConfig(
+        mode="fine_tune", model=model, epochs=epochs, learning_rate=learning_rate,
+        batch_size=batch_size, device=device, checkpoint_path=checkpoint_path,
+        freeze_layers=freeze_layers, head_attr=head_attr, num_classes=num_classes,
+    )
+    return run_training(config, train_loader, validation_loader)