LetsANN 0.1.0__tar.gz

letsann-0.1.0/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/LetsANN.egg-info/PKG-INFO

@@ -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/LetsANN.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+LetsANN.egg-info/PKG-INFO
+LetsANN.egg-info/SOURCES.txt
+LetsANN.egg-info/dependency_links.txt
+LetsANN.egg-info/entry_points.txt
+LetsANN.egg-info/requires.txt
+LetsANN.egg-info/top_level.txt
+letsann/__init__.py
+letsann/_version.py
+letsann/cli.py
+letsann/data.py
+letsann/layers.py
+letsann/model.py
+letsann/trainer.py
+tests/test_model.py

letsann-0.1.0/LetsANN.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

letsann-0.1.0/LetsANN.egg-info/entry_points.txt

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

letsann-0.1.0/LetsANN.egg-info/requires.txt

@@ -0,0 +1,9 @@
+tensorflow>=2.8
+numpy>=1.19
+pandas>=1.2
+scikit-learn>=1.0
+
+[dev]
+pytest>=7.0
+build
+twine

letsann-0.1.0/LetsANN.egg-info/top_level.txt

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

letsann-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+include LICENSE

letsann-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,84 @@
+# 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/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-0.1.0/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-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-0.1.0/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,
+    )