LetsANN 0.1.0__py3-none-any.whl

letsann/__init__.py

@@ -0,0 +1,44 @@
+"""LetsANN — A beginner-friendly ANN library on top of TensorFlow.
+
+Public API:
+    - Model: thin wrapper around ``tf.keras.Sequential`` that builds a network
+      from a simple JSON-like list of layer specs.
+    - build_model: convenience factory for spec-based model construction.
+    - LAYER_REGISTRY: mapping of supported layer types to Keras classes
+      together with the metadata used by the web UI.
+
+Importing ``letsann`` does *not* start the web server. The web UI has its own
+console script (``letsann-web``) and must be started explicitly.
+"""
+
+from ._version import __version__
+
+__all__ = [
+    "Model",
+    "build_model",
+    "load_dataset",
+    "LAYER_REGISTRY",
+    "layer_catalog",
+    "__version__",
+]
+
+
+def __getattr__(name):
+    """Lazily import the heavy (TensorFlow-backed) public API.
+
+    This keeps ``python -m letsann.cli version`` and similar tooling usable
+    even when TensorFlow has not been imported yet (or is not installed).
+    """
+    if name in {"Model", "build_model"}:
+        from .model import Model, build_model
+
+        return {"Model": Model, "build_model": build_model}[name]
+    if name in {"LAYER_REGISTRY", "layer_catalog"}:
+        from .layers import LAYER_REGISTRY, layer_catalog
+
+        return {"LAYER_REGISTRY": LAYER_REGISTRY, "layer_catalog": layer_catalog}[name]
+    if name == "load_dataset":
+        from .data import load_dataset
+
+        return load_dataset
+    raise AttributeError(f"module 'letsann' has no attribute {name!r}")

letsann/_version.py

@@ -0,0 +1,7 @@
+"""Version constant kept in a dependency-free module.
+
+Keeping ``__version__`` isolated means ``letsann.cli`` and tooling can read
+it without triggering the TensorFlow import chain.
+"""
+
+__version__ = "0.1.0"

letsann/cli.py

@@ -0,0 +1,35 @@
+"""LetsANN 命令行工具。
+
+只做一件事：查版本号。
+Web 界面已拆到独立的 ``letsann-web`` 项目，本包不再附带。
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from ._version import __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="letsann",
+        description="LetsANN —— 基于 TensorFlow 的极简 ANN 库。",
+    )
+    sub = parser.add_subparsers(dest="command")
+    sub.required = True
+
+    ver = sub.add_parser("version", help="打印 LetsANN 版本。")
+    ver.set_defaults(func=lambda _a: (print(f"LetsANN {__version__}") or 0))
+
+    return parser
+
+
+def main(argv=None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args) or 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

letsann/data.py

@@ -0,0 +1,197 @@
+"""Dataset helpers for LetsANN.
+
+Users can:
+    * point LetsANN at a local CSV/NPZ file via :func:`load_dataset`;
+    * load the same way from uploaded files in the web UI.
+
+Datasets are kept intentionally simple: tabular data in CSV (with a target
+column) or NPZ archives that contain ``X`` / ``y`` arrays.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Tuple, Union
+
+import numpy as np
+import pandas as pd
+from sklearn.model_selection import train_test_split
+from sklearn.preprocessing import StandardScaler
+
+
+@dataclass
+class Dataset:
+    X_train: np.ndarray
+    X_val: np.ndarray
+    y_train: np.ndarray
+    y_val: np.ndarray
+    feature_names: Optional[list] = None
+    target_name: Optional[str] = None
+    n_classes: Optional[int] = None
+
+    @property
+    def input_shape(self) -> Tuple[int, ...]:
+        return self.X_train.shape[1:]
+
+    @property
+    def task_type(self) -> str:
+        """Heuristic classification-vs-regression detection."""
+        if self.n_classes and self.n_classes > 1:
+            return "classification"
+        return "regression"
+
+    def summary(self) -> Dict[str, Any]:
+        return {
+            "n_train": int(self.X_train.shape[0]),
+            "n_val": int(self.X_val.shape[0]),
+            "input_shape": list(self.input_shape),
+            "task_type": self.task_type,
+            "n_classes": self.n_classes,
+            "feature_names": self.feature_names,
+            "target_name": self.target_name,
+        }
+
+
+def _infer_classes(y: np.ndarray) -> Optional[int]:
+    if y.ndim > 1 and y.shape[-1] > 1:
+        return int(y.shape[-1])
+    if np.issubdtype(y.dtype, np.integer):
+        uniq = np.unique(y)
+        if uniq.size <= max(50, int(np.sqrt(y.size))):
+            return int(uniq.size)
+    return None
+
+
+def _from_dataframe(
+    df: pd.DataFrame,
+    target: Optional[str],
+    test_size: float,
+    normalize: bool,
+    random_state: int,
+) -> Dataset:
+    if target is None:
+        target = df.columns[-1]
+    if target not in df.columns:
+        raise ValueError(f"Target column {target!r} not in dataset. Columns: {list(df.columns)}")
+
+    features = [c for c in df.columns if c != target]
+    X = df[features].to_numpy(dtype=np.float32)
+    y_raw = df[target].to_numpy()
+
+    # If target is non-numeric, label-encode it.
+    if y_raw.dtype.kind in {"O", "U", "S"}:
+        classes, y = np.unique(y_raw, return_inverse=True)
+        y = y.astype(np.int64)
+        n_classes = int(classes.size)
+    else:
+        y = y_raw
+        n_classes = _infer_classes(y)
+        if n_classes is None:
+            y = y.astype(np.float32)
+
+    if normalize:
+        scaler = StandardScaler()
+        X = scaler.fit_transform(X).astype(np.float32)
+
+    X_train, X_val, y_train, y_val = train_test_split(
+        X, y, test_size=test_size, random_state=random_state,
+        stratify=y if n_classes else None,
+    )
+
+    return Dataset(
+        X_train=X_train,
+        X_val=X_val,
+        y_train=y_train,
+        y_val=y_val,
+        feature_names=features,
+        target_name=target,
+        n_classes=n_classes,
+    )
+
+
+def load_dataset(
+    source: Union[str, bytes, io.BytesIO, pd.DataFrame],
+    *,
+    target: Optional[str] = None,
+    test_size: float = 0.2,
+    normalize: bool = True,
+    random_state: int = 42,
+    file_name: Optional[str] = None,
+) -> Dataset:
+    """Load a dataset from a path, bytes buffer, or DataFrame.
+
+    Parameters
+    ----------
+    source:
+        Path to a CSV/NPZ file, a bytes buffer (e.g. uploaded file), or a
+        pandas DataFrame.
+    target:
+        Target column name. When ``None`` the last column is used.
+    test_size:
+        Fraction kept for the validation split.
+    normalize:
+        Whether to StandardScaler-normalise the features.
+    file_name:
+        Optional hint used when ``source`` is raw bytes and its extension is
+        otherwise unknown.
+    """
+
+    if isinstance(source, pd.DataFrame):
+        return _from_dataframe(source, target, test_size, normalize, random_state)
+
+    if isinstance(source, (bytes, bytearray)):
+        buf = io.BytesIO(source)
+        ext = os.path.splitext(file_name or "")[1].lower()
+        return _load_from_buffer(buf, ext, target, test_size, normalize, random_state)
+
+    if isinstance(source, io.IOBase):
+        ext = os.path.splitext(file_name or getattr(source, "name", ""))[1].lower()
+        return _load_from_buffer(source, ext, target, test_size, normalize, random_state)
+
+    # assume string path
+    path = str(source)
+    ext = os.path.splitext(path)[1].lower()
+    if ext in {".csv", ".tsv", ".txt"}:
+        sep = "\t" if ext == ".tsv" else ","
+        df = pd.read_csv(path, sep=sep)
+        return _from_dataframe(df, target, test_size, normalize, random_state)
+    if ext in {".npz"}:
+        return _load_npz(np.load(path), test_size, normalize, random_state)
+    raise ValueError(f"Unsupported file extension: {ext!r}")
+
+
+def _load_from_buffer(buf, ext, target, test_size, normalize, random_state) -> Dataset:
+    if ext in {".csv", ".tsv", ".txt", ""}:
+        sep = "\t" if ext == ".tsv" else ","
+        df = pd.read_csv(buf, sep=sep)
+        return _from_dataframe(df, target, test_size, normalize, random_state)
+    if ext == ".npz":
+        return _load_npz(np.load(buf), test_size, normalize, random_state)
+    raise ValueError(f"Unsupported upload extension: {ext!r}")
+
+
+def _load_npz(npz, test_size: float, normalize: bool, random_state: int) -> Dataset:
+    if "X" not in npz or "y" not in npz:
+        raise ValueError("NPZ file must contain 'X' and 'y' arrays.")
+    X = np.asarray(npz["X"], dtype=np.float32)
+    y = np.asarray(npz["y"])
+    n_classes = _infer_classes(y)
+    if n_classes is None:
+        y = y.astype(np.float32)
+
+    if normalize and X.ndim == 2:
+        X = StandardScaler().fit_transform(X).astype(np.float32)
+
+    X_train, X_val, y_train, y_val = train_test_split(
+        X, y, test_size=test_size, random_state=random_state,
+        stratify=y if n_classes else None,
+    )
+    return Dataset(
+        X_train=X_train,
+        X_val=X_val,
+        y_train=y_train,
+        y_val=y_val,
+        n_classes=n_classes,
+    )

letsann/layers.py

@@ -0,0 +1,217 @@
+"""层注册表：同时被 Python API 与 Web UI 使用。
+
+每一项描述了 LetsANN 所支持的一种层。``params`` 列表会驱动 Web 界面
+的表单生成，因此 UI 展示始终与后端可实例化的参数保持一致。
+
+UI 中展示的 ``description`` / ``label`` 使用中文，便于教学场景。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+import tensorflow as tf
+
+# ---------------------------------------------------------------------------
+# 每个条目的字段：
+#   keras_cls     : 创建该层所用的 Keras 类
+#   params        : Web 表单使用的参数描述
+#                   { name, label, type, default, options?, min?, max?, step? }
+#   description   : 在层列表中展示的一句话说明（中文）
+# ---------------------------------------------------------------------------
+
+ACTIVATIONS = ["relu", "sigmoid", "tanh", "softmax", "linear", "elu", "selu"]
+INITIALIZERS = [
+    "glorot_uniform",
+    "glorot_normal",
+    "he_uniform",
+    "he_normal",
+    "random_normal",
+    "zeros",
+]
+
+LAYER_REGISTRY: Dict[str, Dict[str, Any]] = {
+    "Input": {
+        "keras_cls": tf.keras.layers.InputLayer,
+        "description": "输入层：指定单个样本的形状。",
+        "params": [
+            {
+                "name": "shape",
+                "label": "输入形状",
+                "type": "shape",
+                "default": "4",
+                "help": "用英文逗号分隔，例如 4 或 28,28,1",
+            }
+        ],
+    },
+    "Dense": {
+        "keras_cls": tf.keras.layers.Dense,
+        "description": "全连接层（Dense）。",
+        "params": [
+            {"name": "units", "label": "神经元数", "type": "int", "default": 32, "min": 1},
+            {
+                "name": "activation",
+                "label": "激活函数",
+                "type": "select",
+                "default": "relu",
+                "options": ACTIVATIONS,
+            },
+            {
+                "name": "use_bias",
+                "label": "是否使用偏置",
+                "type": "bool",
+                "default": True,
+                "advanced": True,
+            },
+            {
+                "name": "kernel_initializer",
+                "label": "权重初始化",
+                "type": "select",
+                "default": "glorot_uniform",
+                "options": INITIALIZERS,
+                "advanced": True,
+            },
+        ],
+    },
+
+    "Dropout": {
+        "keras_cls": tf.keras.layers.Dropout,
+        "description": "Dropout：训练时按比例随机丢弃神经元。",
+        "params": [
+            {
+                "name": "rate",
+                "label": "丢弃比例",
+                "type": "float",
+                "default": 0.2,
+                "min": 0.0,
+                "max": 0.95,
+                "step": 0.05,
+            }
+        ],
+    },
+    "BatchNormalization": {
+        "keras_cls": tf.keras.layers.BatchNormalization,
+        "description": "批归一化（BatchNormalization）。",
+        "params": [],
+    },
+    "Flatten": {
+        "keras_cls": tf.keras.layers.Flatten,
+        "description": "展平：将多维输入拉平成一维向量。",
+        "params": [],
+    },
+    "Activation": {
+        "keras_cls": tf.keras.layers.Activation,
+        "description": "独立的激活函数层。",
+        "params": [
+            {
+                "name": "activation",
+                "label": "激活函数",
+                "type": "select",
+                "default": "relu",
+                "options": ACTIVATIONS,
+            }
+        ],
+    },
+    "Conv2D": {
+        "keras_cls": tf.keras.layers.Conv2D,
+        "description": "二维卷积层（输入需要是 3 维，如图像）。",
+        "params": [
+            {"name": "filters", "label": "卷积核数量", "type": "int", "default": 16, "min": 1},
+            {
+                "name": "kernel_size",
+                "label": "卷积核大小",
+                "type": "shape",
+                "default": "3,3",
+            },
+            {
+                "name": "activation",
+                "label": "激活函数",
+                "type": "select",
+                "default": "relu",
+                "options": ACTIVATIONS,
+            },
+            {
+                "name": "padding",
+                "label": "填充方式",
+                "type": "select",
+                "default": "valid",
+                "options": ["valid", "same"],
+                "advanced": True,
+            },
+        ],
+    },
+    "MaxPooling2D": {
+        "keras_cls": tf.keras.layers.MaxPooling2D,
+        "description": "二维最大池化（MaxPooling2D）。",
+        "params": [
+            {
+                "name": "pool_size",
+                "label": "池化窗口",
+                "type": "shape",
+                "default": "2,2",
+            }
+        ],
+    },
+}
+
+
+def _parse_shape(value: Any) -> Any:
+    """把诸如 ``"28,28,1"`` 的字符串转成整数元组。"""
+    if value is None or value == "":
+        return None
+    if isinstance(value, (list, tuple)):
+        return tuple(int(v) for v in value)
+    if isinstance(value, int):
+        return (value,)
+    parts = [p.strip() for p in str(value).split(",") if p.strip()]
+    if len(parts) == 1:
+        return (int(parts[0]),)
+    return tuple(int(p) for p in parts)
+
+
+def _coerce(param_spec: Dict[str, Any], value: Any) -> Any:
+    ptype = param_spec.get("type")
+    if value is None:
+        return param_spec.get("default")
+    if ptype == "int":
+        return int(value)
+    if ptype == "float":
+        return float(value)
+    if ptype == "bool":
+        if isinstance(value, bool):
+            return value
+        return str(value).lower() in {"1", "true", "yes", "on"}
+    if ptype == "shape":
+        return _parse_shape(value)
+    return value
+
+
+def build_keras_layer(layer_type: str, params: Dict[str, Any]) -> tf.keras.layers.Layer:
+    """按 ``layer_type`` / ``params`` 创建一个 Keras 层实例。"""
+    if layer_type not in LAYER_REGISTRY:
+        raise ValueError(f"未知的层类型：{layer_type!r}")
+
+    spec = LAYER_REGISTRY[layer_type]
+    coerced: Dict[str, Any] = {}
+    for p in spec["params"]:
+        name = p["name"]
+        coerced[name] = _coerce(p, params.get(name, p.get("default")))
+
+    if layer_type == "Input":
+        return tf.keras.layers.InputLayer(input_shape=coerced["shape"])
+
+    return spec["keras_cls"](**coerced)
+
+
+def layer_catalog() -> List[Dict[str, Any]]:
+    """返回可 JSON 序列化的层目录，供 Web UI 使用。"""
+    catalog = []
+    for name, spec in LAYER_REGISTRY.items():
+        catalog.append(
+            {
+                "type": name,
+                "description": spec["description"],
+                "params": spec["params"],
+            }
+        )
+    return catalog

letsann/model.py

@@ -0,0 +1,132 @@
+"""High level wrapper around ``tf.keras.Sequential``.
+
+The :class:`Model` class lets users describe a network with a list of simple
+Python dicts and then train / evaluate / predict with the usual methods.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Union
+
+import numpy as np
+import tensorflow as tf
+
+from .layers import build_keras_layer
+
+LayerSpec = Dict[str, Any]  # {"type": "Dense", "params": {...}}
+
+
+class Model:
+    """A thin, beginner-friendly wrapper over ``tf.keras.Sequential``.
+
+    Example::
+
+        model = Model([
+            {"type": "Input", "params": {"shape": "4"}},
+            {"type": "Dense", "params": {"units": 16, "activation": "relu"}},
+            {"type": "Dense", "params": {"units": 3, "activation": "softmax"}},
+        ])
+        model.compile(loss="sparse_categorical_crossentropy",
+                      optimizer="adam", metrics=["accuracy"])
+        model.fit(X, y, epochs=20, batch_size=16)
+    """
+
+    def __init__(self, layers: Sequence[LayerSpec]):
+        self.layer_specs: List[LayerSpec] = [dict(s) for s in layers]
+        self.keras_model: tf.keras.Sequential = self._build()
+
+    # ------------------------------------------------------------------
+    # Construction
+    # ------------------------------------------------------------------
+    def _build(self) -> tf.keras.Sequential:
+        if not self.layer_specs:
+            raise ValueError("At least one layer is required.")
+        model = tf.keras.Sequential()
+        for idx, spec in enumerate(self.layer_specs):
+            ltype = spec.get("type")
+            params = spec.get("params", {}) or {}
+            if ltype is None:
+                raise ValueError(f"Layer {idx} has no 'type'.")
+            model.add(build_keras_layer(ltype, params))
+        return model
+
+    # ------------------------------------------------------------------
+    # Training / inference API — thin pass-through with helpful defaults
+    # ------------------------------------------------------------------
+    def compile(
+        self,
+        optimizer: Union[str, tf.keras.optimizers.Optimizer] = "adam",
+        loss: str = "mse",
+        metrics: Optional[Iterable[str]] = None,
+        learning_rate: Optional[float] = None,
+    ) -> "Model":
+        if learning_rate is not None and isinstance(optimizer, str):
+            optimizer = tf.keras.optimizers.get(
+                {"class_name": optimizer, "config": {"learning_rate": learning_rate}}
+            )
+        self.keras_model.compile(
+            optimizer=optimizer,
+            loss=loss,
+            metrics=list(metrics) if metrics else None,
+        )
+        return self
+
+    def fit(self, X, y=None, **kwargs):
+        return self.keras_model.fit(X, y, **kwargs)
+
+    def evaluate(self, X, y=None, **kwargs):
+        return self.keras_model.evaluate(X, y, **kwargs)
+
+    def predict(self, X, **kwargs) -> np.ndarray:
+        return self.keras_model.predict(X, **kwargs)
+
+    # ------------------------------------------------------------------
+    # Introspection
+    # ------------------------------------------------------------------
+    def summary(self) -> str:
+        lines: List[str] = []
+        self.keras_model.summary(print_fn=lines.append)
+        return "\n".join(lines)
+
+    def describe(self) -> List[Dict[str, Any]]:
+        """Return a JSON-friendly description of the built Keras layers."""
+        info: List[Dict[str, Any]] = []
+        for layer in self.keras_model.layers:
+            try:
+                out_shape = layer.output_shape
+            except Exception:
+                out_shape = None
+            info.append(
+                {
+                    "name": layer.name,
+                    "class": layer.__class__.__name__,
+                    "output_shape": out_shape,
+                    "params": int(layer.count_params()),
+                }
+            )
+        return info
+
+    @property
+    def total_params(self) -> int:
+        return int(self.keras_model.count_params())
+
+    # ------------------------------------------------------------------
+    # Persistence
+    # ------------------------------------------------------------------
+    def save(self, path: str) -> None:
+        """Save the underlying Keras model plus the LetsANN spec."""
+        self.keras_model.save(path)
+        spec_path = os.path.join(path, "letsann_spec.json") if os.path.isdir(path) else path + ".letsann.json"
+        with open(spec_path, "w", encoding="utf-8") as f:
+            json.dump(self.layer_specs, f, ensure_ascii=False, indent=2)
+
+    @classmethod
+    def from_spec(cls, spec: Sequence[LayerSpec]) -> "Model":
+        return cls(spec)
+
+
+def build_model(spec: Sequence[LayerSpec]) -> Model:
+    """Convenience factory — mirror of :meth:`Model.from_spec`."""
+    return Model.from_spec(spec)

letsann/trainer.py

@@ -0,0 +1,215 @@
+"""Training orchestration used by both the Python API and the web UI.
+
+The :class:`TrainingJob` runs a Keras fit loop in a background thread and
+streams live metrics into an in-memory queue so the web UI can poll or
+stream them via Server-Sent Events.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+import uuid
+from collections import deque
+from typing import Any, Deque, Dict, List, Optional
+
+import numpy as np
+import tensorflow as tf
+
+from .data import Dataset
+from .model import Model
+
+
+class _StreamCallback(tf.keras.callbacks.Callback):
+    """Keras callback that pushes every epoch/batch event into a job."""
+
+    def __init__(self, job: "TrainingJob") -> None:
+        super().__init__()
+        self.job = job
+
+    def on_train_begin(self, logs=None):
+        self.job._push({"event": "train_begin", "time": time.time()})
+
+    def on_epoch_begin(self, epoch, logs=None):
+        self.job._push({"event": "epoch_begin", "epoch": int(epoch)})
+
+    def on_epoch_end(self, epoch, logs=None):
+        payload = {"event": "epoch_end", "epoch": int(epoch)}
+        payload.update(_clean_logs(logs))
+        self.job._record_epoch(payload)
+        self.job._push(payload)
+
+    def on_train_end(self, logs=None):
+        self.job._push({"event": "train_end", "time": time.time()})
+        self.job.status = "finished"
+
+
+def _clean_logs(logs: Optional[Dict[str, Any]]) -> Dict[str, float]:
+    if not logs:
+        return {}
+    out: Dict[str, float] = {}
+    for k, v in logs.items():
+        try:
+            out[k] = float(v)
+        except (TypeError, ValueError):
+            continue
+    return out
+
+
+class TrainingJob:
+    """In-process training job with live event streaming."""
+
+    def __init__(
+        self,
+        model: Model,
+        dataset: Dataset,
+        *,
+        epochs: int = 10,
+        batch_size: int = 32,
+        optimizer: str = "adam",
+        loss: Optional[str] = None,
+        learning_rate: float = 1e-3,
+        metrics: Optional[List[str]] = None,
+    ) -> None:
+        self.id = uuid.uuid4().hex[:12]
+        self.model = model
+        self.dataset = dataset
+        self.epochs = int(epochs)
+        self.batch_size = int(batch_size)
+        self.optimizer = optimizer
+        self.loss = loss or _default_loss(dataset)
+        self.learning_rate = float(learning_rate)
+        self.metrics = metrics or _default_metrics(dataset)
+
+        self.status: str = "pending"  # pending | running | finished | error
+        self.error: Optional[str] = None
+        self.history: List[Dict[str, Any]] = []
+        self.final_eval: Optional[Dict[str, float]] = None
+
+        self._events: Deque[Dict[str, Any]] = deque(maxlen=1024)
+        self._lock = threading.Lock()
+        self._thread: Optional[threading.Thread] = None
+
+    # ------------------------------------------------------------------
+    # Public control
+    # ------------------------------------------------------------------
+    def start(self) -> None:
+        if self._thread and self._thread.is_alive():
+            return
+        self.status = "running"
+        self._thread = threading.Thread(target=self._run, name=f"letsann-train-{self.id}", daemon=True)
+        self._thread.start()
+
+    # ------------------------------------------------------------------
+    # Event helpers (used by the callback and API)
+    # ------------------------------------------------------------------
+    def _push(self, event: Dict[str, Any]) -> None:
+        with self._lock:
+            self._events.append(event)
+
+    def _record_epoch(self, event: Dict[str, Any]) -> None:
+        self.history.append({k: v for k, v in event.items() if k != "event"})
+
+    def drain_events(self) -> List[Dict[str, Any]]:
+        with self._lock:
+            events = list(self._events)
+            self._events.clear()
+        return events
+
+    def snapshot(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "status": self.status,
+            "error": self.error,
+            "epochs": self.epochs,
+            "batch_size": self.batch_size,
+            "optimizer": self.optimizer,
+            "loss": self.loss,
+            "metrics": self.metrics,
+            "history": list(self.history),
+            "final_eval": self.final_eval,
+            "dataset": self.dataset.summary(),
+            "model": self.model.describe(),
+            "total_params": self.model.total_params,
+        }
+
+    # ------------------------------------------------------------------
+    # Internal worker
+    # ------------------------------------------------------------------
+    def _run(self) -> None:
+        try:
+            self.model.compile(
+                optimizer=self.optimizer,
+                loss=self.loss,
+                metrics=self.metrics,
+                learning_rate=self.learning_rate,
+            )
+
+            self.model.fit(
+                self.dataset.X_train,
+                self.dataset.y_train,
+                validation_data=(self.dataset.X_val, self.dataset.y_val),
+                epochs=self.epochs,
+                batch_size=self.batch_size,
+                verbose=0,
+                callbacks=[_StreamCallback(self)],
+            )
+
+            results = self.model.evaluate(
+                self.dataset.X_val, self.dataset.y_val, verbose=0, return_dict=True
+            )
+            self.final_eval = {k: float(v) for k, v in results.items()}
+            self._push({"event": "final_eval", **self.final_eval})
+            self.status = "finished"
+        except Exception as exc:  # pragma: no cover
+            self.status = "error"
+            self.error = str(exc)
+            self._push({"event": "error", "message": str(exc)})
+
+    # ------------------------------------------------------------------
+    # Prediction on validation sample
+    # ------------------------------------------------------------------
+    def sample_predictions(self, n: int = 10) -> Dict[str, Any]:
+        if self.status != "finished":
+            return {"ready": False}
+
+        n = int(min(n, self.dataset.X_val.shape[0]))
+        X = self.dataset.X_val[:n]
+        y_true = self.dataset.y_val[:n]
+        y_pred = self.model.predict(X, verbose=0)
+
+        if self.dataset.task_type == "classification":
+            if y_pred.ndim == 2 and y_pred.shape[1] > 1:
+                preds = y_pred.argmax(axis=1).tolist()
+                confidences = y_pred.max(axis=1).tolist()
+            else:
+                preds = (y_pred.ravel() > 0.5).astype(int).tolist()
+                confidences = y_pred.ravel().tolist()
+            return {
+                "ready": True,
+                "task": "classification",
+                "y_true": np.asarray(y_true).ravel().tolist(),
+                "y_pred": preds,
+                "confidence": confidences,
+            }
+
+        return {
+            "ready": True,
+            "task": "regression",
+            "y_true": np.asarray(y_true).ravel().tolist(),
+            "y_pred": np.asarray(y_pred).ravel().tolist(),
+        }
+
+
+def _default_loss(dataset: Dataset) -> str:
+    if dataset.task_type == "classification":
+        if dataset.n_classes and dataset.n_classes > 2:
+            return "sparse_categorical_crossentropy"
+        return "binary_crossentropy"
+    return "mse"
+
+
+def _default_metrics(dataset: Dataset) -> List[str]:
+    if dataset.task_type == "classification":
+        return ["accuracy"]
+    return ["mae"]

letsann-0.1.0.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: LetsANN
+Version: 0.1.0
+Summary: 基于 TensorFlow 的零基础 ANN 库：用简单的 Python 字典就能描述网络。
+Author: LetsANN Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/letsann/letsann
+Project-URL: Documentation, https://github.com/letsann/letsann#readme
+Project-URL: Issues, https://github.com/letsann/letsann/issues
+Keywords: tensorflow,keras,neural network,ann,deep learning,education
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tensorflow>=2.8
+Requires-Dist: numpy>=1.19
+Requires-Dist: pandas>=1.2
+Requires-Dist: scikit-learn>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# LetsANN
+
+**LetsANN** 是一个基于 TensorFlow / Keras 的零基础 ANN 库。  
+用最简单的 Python 列表描述网络，像搭积木一样训练模型。
+
+> 需要可视化拖拽界面？请看配套的独立项目 [`letsann-web`](https://github.com/letsann/letsann-web)。
+
+## 安装
+
+```bash
+pip install LetsANN
+```
+
+要求 Python **3.8 及以上**。
+
+## 最小示例
+
+```python
+from letsann import Model, load_dataset
+
+# 用 DataFrame 或 CSV 路径都行，最后一列默认为标签
+ds = load_dataset("iris.csv", target="species")
+
+# 用列表描述网络
+model = Model([
+    {"type": "Input",  "params": {"shape": "4"}},
+    {"type": "Dense",  "params": {"units": 16, "activation": "relu"}},
+    {"type": "Dense",  "params": {"units": 3,  "activation": "softmax"}},
+])
+
+# 和 Keras 一样编译、训练
+model.compile(optimizer="adam",
+              loss="sparse_categorical_crossentropy",
+              metrics=["accuracy"])
+model.fit(ds.X_train, ds.y_train,
+          validation_data=(ds.X_val, ds.y_val),
+          epochs=20, batch_size=16)
+
+print(model.summary())
+```
+
+更多示例见 `examples/quickstart.py`。
+
+## 支持的层
+
+`Input`、`Dense`、`Dropout`、`BatchNormalization`、`Flatten`、`Activation`、
+`Conv2D`、`MaxPooling2D`。全部在 `letsann/layers.py` 中注册，想扩展就
+往 `LAYER_REGISTRY` 里加一条即可。
+
+## 数据集格式
+
+- **CSV / TSV**：默认最后一列为标签；用 `target="col"` 指定其它列。
+- **NPZ**：需要包含 `X` 和 `y` 两个数组。
+
+## 发布到 PyPI
+
+```bash
+# 1. 安装打包工具
+pip install build twine
+
+# 2. 打包（在本目录运行）
+python -m build         # 会生成 dist/LetsANN-0.1.0.tar.gz 和 .whl
+
+# 3. 先上传到 TestPyPI 验证
+twine upload --repository testpypi dist/*
+
+# 4. 确认没问题后，正式上传 PyPI
+twine upload dist/*
+```
+
+上传需要在 <https://pypi.org> 先创建账号并生成 API Token，放进
+`~/.pypirc` 或设置环境变量 `TWINE_USERNAME=__token__`、
+`TWINE_PASSWORD=<你的 token>`。
+
+## 开发
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

letsann-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+letsann/__init__.py,sha256=wmJiZCoLBsLuGHXGoHkae0w9d_eVkFkHTAMOhi2x_Vs,1538
+letsann/_version.py,sha256=rBxpUCL_QmUlcUTrpvNt4WqmVZZMX4xqlGYZMVWEpZU,216
+letsann/cli.py,sha256=5glGNHWYlf3wvvgKv0x3ecdz0vcwksZZYlVDHjwqqSk,903
+letsann/data.py,sha256=xw4DEL3SfskhBY2LWXhHR2vNeqJm-q1mmAZf2bVhgy8,6424
+letsann/layers.py,sha256=kQtbbfkyk0Wb2FsapVK18T91yoW6ARRxHdgtKbJnZ34,7088
+letsann/model.py,sha256=joDLd26p7KIyjkpO7M4sx26RTgPRI2flphtphxWeLJU,5020
+letsann/trainer.py,sha256=1FWySQxwRgWwLkdxTrw-Y_QdpsEawlvHJ2gZcBXL1qM,7634
+letsann-0.1.0.dist-info/licenses/LICENSE,sha256=w3SbG5R22PYPf3Z3O6bgCXchLfh_TEE8SA64YsHgE8k,1098
+letsann-0.1.0.dist-info/METADATA,sha256=icZlk_IitVkLQ6Gx14Y2aI8j9tuLiQkqik1gIy1zXL8,3584
+letsann-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+letsann-0.1.0.dist-info/entry_points.txt,sha256=u3P6q5bQ6oJ307hSLwLZcTL2OSBf4Ir7rBItkUVe-8E,45
+letsann-0.1.0.dist-info/top_level.txt,sha256=Tf524tX4l7BvnwZeemrDEUKpY1rNqeVz8GnEe2wLB2E,8
+letsann-0.1.0.dist-info/RECORD,,

letsann-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

letsann-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+letsann = letsann.cli:main

letsann-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 LetsANN Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

letsann-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+letsann