# Synaptopus

![Synaptopus mascot](artwork/synaptopus_mascot_multi_brains_2.png)

Many minds, one workbench.

Synaptopus is a multi-architecture artificial neural systems lab for composing, comparing, and teaching interacting network models.

The repository is intended as a broader home for reusable artificial neural system components, pedagogical tooling, and hybrid systems that combine unlike architectures into a single executable process. The thesis-derived composition system developed in the neighboring repository is one important origin point, but it is not the boundary of the idea.

## What Synaptopus Is For

- Building systems in which different neural architectures play different roles
- Comparing architecture families under a common execution model
- Teaching artificial neural systems through inspectable, stepwise behavior
- Supporting both domain-specific applications and cross-domain experiments
- Providing a basis for future graphical and browser-based experimentation tools

## Design Direction

Synaptopus is meant to support systems built from cooperating components such as:

- generators
- critics
- categorizers
- controllers
- analyzers

The emphasis is on explicit interaction among heterogeneous models rather than a single monolithic network.

## Initial Provenance

The immediate historical provenance of this repository is a 1989 master's thesis project by Wesley Royce Elsberry, implemented in Turbo Pascal, which combined Hopfield-style generation, backpropagation-based evaluation, and ART-style categorization in a hybrid musical composition system.

That work has already been reconstructed in Python elsewhere as a thesis-focused project. Synaptopus is the next abstraction layer: a more general repository for multi-architecture artificial neural systems, their interfaces, their orchestration, and their pedagogical presentation.

See [docs/HISTORY.md](docs/HISTORY.md) for the longer provenance note.
See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the current execution and serialization model.
See [docs/FORMATS.md](docs/FORMATS.md) for the current JSON artifact contracts and examples.
See [docs/ROADMAP.md](docs/ROADMAP.md) for the broader project plan.
See [typescript/README.md](typescript/README.md) for the first TypeScript-side contract layer.
See [viewer/index.html](viewer/index.html) for the minimal browser-based trace viewer.

For the smoothest viewer workflow:

```bash
PYTHONPATH=src python -m synaptopus ./artifacts --demo parity_pressure
python -m http.server 8000
```

Then load `http://127.0.0.1:8000/artifacts/manifest.json` in the viewer's manifest URL field.

If you want a checkpointable run artifact as well:

```bash
PYTHONPATH=src python -m synaptopus ./artifacts \
  --demo parity_pressure \
  --accepted-count 4 \
  --snapshot-after-accepted 2
```

That writes `snapshot.json` alongside the graph, trace, report, and manifest artifacts. The snapshot captures the demo state plus mutable network internals so the run can be resumed later rather than replayed from scratch.

## Planned Scope

- reusable architecture interfaces
- generic network implementations
- mixed-family example systems
- domain adapters and example tasks
- execution tracing and information-theoretic analysis
- visual tooling for inspecting interacting systems
- a future JavaScript and web-based driver

## Repository Layout

```text
src/synaptopus/   package code
docs/             project notes, provenance, and architecture documents
```

## Status

This repository is now past the pure-scaffold stage. It contains the first generic runtime, reporting, serialization, graph, backpropagation, ART1, and Hopfield layers, plus internal mixed-family demos built on the generic orchestration model. The exporter can emit artifacts for more than one internal demo and can now save checkpointable snapshot artifacts for later resume, while the thesis-derived Python implementation remains the historical reference for the first complete hybrid system.
