Metadata-Version: 2.4
Name: laysnet
Version: 0.2.0
Summary: LaysNet: a graph-theoretic Markov memory network prototype.
Author: Ahmad Shajahan
License: MIT
Project-URL: Homepage, https://github.com/ahmadshajahan2000-commits/LaysNet
Project-URL: Repository, https://github.com/ahmadshajahan2000-commits/LaysNet
Project-URL: Documentation, https://github.com/ahmadshajahan2000-commits/LaysNet/tree/main/docs
Keywords: graph learning,markov chain,stochastic process,classifier,research
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: datasets
Requires-Dist: scikit-learn>=1.4; extra == "datasets"
Requires-Dist: pillow>=10.0; extra == "datasets"
Provides-Extra: torch
Requires-Dist: torch>=2.0; extra == "torch"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# LaysNet

LaysNet is a research prototype for a graph-based, Markov-memory classifier. It is intentionally not a conventional neural network: it does not use backpropagation, dense layers, convolution kernels, or brain-inspired neurons. It stores learned evidence in graph nodes and directed edges, then predicts by routing an encoded input through the graph.

## Core idea

Each input is converted into a sequence of numerical symbols. LaysNet stores those symbols as graph nodes and stores observed transitions as weighted directed edges. During prediction, the model walks the graph, uses a semaphore-like router to pick the exact or nearest known node at each step, and scores each class with:

- class prior probability,
- node-label memory probability,
- Markov transition probability,
- optional route regularity diagnostics inspired by Eulerian graph balance.

This makes the model closer to a stochastic graph memory machine than to a standard neural network.

## Install

```bash
python3 -m venv .venv
. .venv/bin/activate
pip install -e .
```

For dataset examples:

```bash
pip install -e ".[datasets]"
```

Smoke test:

```bash
python3 -m laysnet
```

## Quick CPU Test

```bash
python3 examples/train_toy.py
```

The toy example uses a deterministic local dataset so the model can be tested without GPU or internet.

## Real Small Dataset Comparison

The repo bundles the classic UCI Iris dataset inside `laysnet/data/iris.csv` and keeps a copy at `datasets/iris.csv` for easy inspection. Run:

```bash
python3 examples/compare_iris.py
```

Current measured local result on the default split:

```text
| model | accuracy |
|---|---:|
| GaussianNB | 1.0000 |
| LaysNet | 1.0000 |
| LaysNetEnsemble | 0.9778 |
| kNN-k3 | 0.9778 |
| Majority | 0.3333 |
```

Full generated report: `reports/iris_comparison.md`.

## Image/Dataset Pipeline

For real image work, prepare a folder like:

```text
data/animals/
  train/
    cat/
    dog/
  test/
    cat/
    dog/
```

Then run:

```bash
python3 examples/train_image_folder.py --data data/animals --image-size 16
```

You can download a Kaggle cats/dogs dataset manually with your Kaggle token, place it in this folder structure, and run the same script. The repo does not include Kaggle credentials or fabricated benchmark numbers.

## Minimal API

```python
from laysnet import LaysNetClassifier

model = LaysNetClassifier(steps=12, bins=17, seed=7)
model.fit(X_train, y_train)
print(model.score(X_test, y_test))
print(model.predict_one(X_test[0]))
```

## Layer-Style API

```python
import laysnet.nn as lnn

model = lnn.SequentialGraphNetwork(
    lnn.GraphEncoder(steps=24, bins=11, seed=5),
    lnn.SemaphoreRouter(),
    lnn.MarkovMemory(smoothing=0.5, transition_weight=1.7),
)
model.fit(X_train, y_train)
print(model.forward(X_test[0]).label)
```

Inspect the graph route:

```python
trace = model.trace_one(X_test[0])
print(trace.encoded)
print(trace.route)
print(trace.scores)
```

## Research Artifacts

- Paper draft: `paper/laysnet_paper.md`
- Generated PDF: `paper/laysnet_paper.pdf`
- Architecture diagram: `docs/architecture.md`
- Graph math notes: `docs/math.md`
- Pipeline guide: `docs/pipeline.md`
- PyPI release guide: `docs/pypi_release.md`
- User guide: `docs/user_guide.md`
- Colab quickstart: `docs/colab_quickstart.md`
- Research concept: `docs/research_concept.md`

## Publish to PyPI

```bash
python3 -m pip install --upgrade build twine
rm -rf dist/
python3 -m build
python3 -m twine check dist/*
python3 -m twine upload --repository testpypi dist/*
```

Use `docs/pypi_release.md` for the full checklist and the safer Trusted Publisher path.

## Honest Status

LaysNet is a new research prototype and implementation scaffold. It is suitable for experimentation, ablations, and small CPU tests. It should not be described as state of the art until it has been benchmarked against strong baselines on many public datasets.
