README.md

---
title: Decidron Network Simulator
emoji: 🔗
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
---

# Decidron Network Simulator

A deterministic, browser-based simulator for **Decidron networks** — the
coupled machine-learning decision units described in US Patent
[US11989636B1](https://patents.google.com/patent/US11989636B1/en)
("System and method for persuadable collaborative conversational AI",
Gasper & Leeds).

You define simulated **sensor inputs** and **processing commands**
(IF a sensor matches THEN emit an output / drive an actuator / modify the
network), run the simulation, and watch the **network diagram**,
**performance statistics**, and **topology-change history** update live.

> This project started from Neon.ai's private `CCAI-Vibe-Demo` app and
> reuses its FastAPI + React scaffold, Docker setup, and visual branding.
> The CCAI multi-LLM orchestration was intentionally removed — v1 of the
> simulator is purely rule-based and needs no API keys or LLM. See
> [Relationship to CCAI](#relationship-to-ccai-and-the-patent).

## Patent context (brief)

A **Decidron** is a machine-learning unit (MLU) with collaborative
protocols that can be **coupled/networked** with other Decidrons. The
patent highlights that "a MLU network coupled with real-time sensors and
actuators can operate industrial controls ... and increased reliability
through parallel pathways." A Decidron records its **experience**, fires
**actions**, scores **results**, and can **modify its own topology**.

This simulator models those concepts deterministically:

| Patent concept | Simulator |
| --- | --- |
| Coupled MLU node / coupling | `decidron` node / directed edge |
| Sensors and actuators | `sensor` / `actuator` nodes |
| Experience Chains (ECDS) | per-node experience log (sensor received → rule fired → actuator acted) |
| Select & perform action, results scored | command output (+ optional actuator) + performance stats |
| Dynamic/extensible topology | `network_ops` applied when a command fires |
| Parallel pathways / reliability | redundant couplings in the seed network |

## Prerequisites

- **Docker** (recommended), or
- **Python 3.12+** and **Node 22+** for local dev.

## Start the application

### Docker (recommended)

```bash
cp .env.example .env        # no secrets needed; defaults are fine
docker compose up --build
# open http://localhost:7860
```

The container builds the React frontend, serves it as static files from
FastAPI, and listens on port 7860. Override the host port with
`CCAI_HOST_PORT` in `.env` if 7860 is taken.

### Local development

Backend (FastAPI on :7860):

```bash
cd backend
python -m venv .venv
.venv/Scripts/activate      # Windows; use source .venv/bin/activate on macOS/Linux
pip install -r requirements.txt
uvicorn app.main:app --port 7860
```

#### Hot reload (development)

Do **not** rely on `uvicorn --reload` on Windows: it detects file changes
but frequently fails to actually restart the worker, so it silently keeps
serving stale code. Instead use the bundled dev scripts, which wrap
uvicorn in `watchfiles` for a clean full restart on every change:

```powershell
cd backend
.\dev.ps1            # Windows
```

```bash
cd backend
./dev.sh             # macOS/Linux/Git Bash
```

Both default to `app.main:app` on `127.0.0.1:7860`, watching `./app`.
`watchfiles` ships with `uvicorn[standard]`. (On non-Windows hosts plain
`uvicorn --reload` works too, but the scripts behave identically.)

Frontend (CRA dev server on :3000, proxying to the backend):

```bash
cd frontend
npm install
# point the dev server at the backend:
echo "REACT_APP_API_URL=http://localhost:7860" > .env.development
npm start
```

## Web UI workflow

1. **View the initial network diagram** — sensors (blue boxes) feed
   coupled Decidrons (purple hexagons) that drive actuators (green
   triangles).
2. **Enter a simulated sensor input** — pick a channel (e.g.
   `Temperature Sensor`), enter a value (e.g. `97`), and click **Queue**.
3. **Create processing commands** — define IF (sensor + match) THEN
   (output, optional actuator). The match is an `operator:value` rule.
4. **Run the simulation** — click **Run Simulation**; queued inputs are
   evaluated against all commands.
5. **Read the results and statistics** — matched commands, emitted
   outputs, and per-sensor/command/output metrics appear on the right.
6. **Review the network-change diagram** — if a command applied
   `network_ops`, a new version is snapshotted; select any version in the
   **Network Modification History** to view that topology in the diagram.

## Processing command format

A command is JSON:

```json
{
  "name": "HighTempAlert",
  "sensor": "temperature",
  "match": "gte:85",
  "output": "Trigger failsafe review",
  "actuator": "actuator-1",
  "network_ops": [
    { "op": "add_node", "node": { "id": "D3", "label": "Decidron D3", "type": "decidron" } },
    { "op": "add_edge", "from": "temperature", "to": "D3" },
    { "op": "remove_edge", "from": "D1", "to": "D2" }
  ]
}
```

- `sensor` — the sensor channel/node id this command listens to.
- `match` — `operator:value`, where operator is one of `contains`,
  `equals`, `startswith`, `endswith`, `regex`, `gt`, `gte`, `lt`, `lte`.
  A bare value (no operator) is treated as `contains`.
- `output` — text emitted when the rule fires.
- `actuator` *(optional)* — id of an actuator node to drive.
- `network_ops` *(optional)* — topology changes: `add_node`, `add_edge`,
  `remove_edge` (edges use `from`/`to`).

## API reference

All endpoints are under `/api/decidron`.

| Method | Path | Purpose |
| --- | --- | --- |
| GET | `/api/decidron/network` | Current network + vis-network diagram JSON |
| POST | `/api/decidron/sensors/input` | Queue a simulated sensor input |
| GET | `/api/decidron/commands` | List processing commands |
| POST | `/api/decidron/commands` | Create a processing command |
| POST | `/api/decidron/run` | Process queued (or supplied) inputs |
| GET | `/api/decidron/stats` | Performance statistics |
| GET | `/api/decidron/history` | Topology-change snapshots |
| POST | `/api/decidron/reset` | Reset to the seed network |

### curl examples

```bash
# View the initial network
curl http://localhost:7860/api/decidron/network

# Queue a sensor reading and run
curl -X POST http://localhost:7860/api/decidron/sensors/input \
  -H 'Content-Type: application/json' \
  -d '{"channel":"temperature","value":"97"}'

curl -X POST http://localhost:7860/api/decidron/run \
  -H 'Content-Type: application/json' -d '{}'

# Create a command
curl -X POST http://localhost:7860/api/decidron/commands \
  -H 'Content-Type: application/json' \
  -d '{"name":"LowTemp","sensor":"temperature","match":"lt:0","output":"Freeze warning"}'

# Run with inline inputs (bypasses the queue)
curl -X POST http://localhost:7860/api/decidron/run \
  -H 'Content-Type: application/json' \
  -d '{"inputs":[{"channel":"temperature","value":"-5"}]}'

# Stats and history
curl http://localhost:7860/api/decidron/stats
curl http://localhost:7860/api/decidron/history
```

## Config & seed files

- [`backend/app/config.py`](backend/app/config.py) — minimal settings
  (`CORS_ORIGINS`).
- [`backend/app/data/decidron/default_network.json`](backend/app/data/decidron/default_network.json)
  — the starter network (sensor → coupled Decidrons → actuator, with a
  redundant coupling).
- [`backend/app/data/decidron/sample_commands.json`](backend/app/data/decidron/sample_commands.json)
  — example commands (one drives an actuator, one reconfigures the
  topology). Edit these to change the simulation's starting state.

## Adding files in Cursor

- **Open the repo as a workspace**: File → Open Folder → `decidron-simulator`.
- **New file**: right-click a folder in the Explorer → New File.
- **Drag & drop** files from your file manager into the Explorer.
- **Ask Cursor in chat**: e.g. "Add `backend/app/decidron/alerts.py`".
- **Terminal**: `New-Item backend/app/decidron/alerts.py` (PowerShell) or
  `touch backend/app/decidron/alerts.py` (bash).

## Relationship to CCAI and the patent

v1 deliberately omits the patent's full pipeline: ECDS context/memory
augmentation, the embedded CCAI per Decidron, Theory-of-Mind,
persuadability, and action-reinforcement learning. A future version
could make Decidrons LLM-driven by porting the orchestration and LLM
clients from the `CCAI-Vibe-Demo` reference app. The simulator's logic is
isolated under `backend/app/decidron/` and
`frontend/src/components/decidron/` to keep that door open.

## Project layout

```
backend/
  app/
    main.py                 # FastAPI app: CORS, /api/health, SPA serving
    config.py               # minimal settings
    api/decidron.py         # REST router
    decidron/               # simulation engine (models, network, engine, stats, diagrams)
    data/decidron/          # seed network + sample commands
frontend/
  src/
    App.js                  # shell
    components/Header.js     # branded header
    components/decidron/     # simulator UI (diagram, forms, tables, history)
    utils/api.js             # API client
    styles/                  # branding + simulator CSS
Dockerfile, docker-compose.yml
```

## Hugging Face Space (BrainForge)

Hosted as a Docker Space on [BrainForge/decidron-simulator](https://huggingface.co/spaces/BrainForge/decidron-simulator) (`app_port: 7860`, `cpu-basic`). No API keys or secrets are required.

Deploy from the **`master`** branch (merge `dev-cursor` into `master` on GitHub first):

```bash
git remote add hf https://huggingface.co/spaces/BrainForge/decidron-simulator
git checkout master && git pull origin master
git push hf master:main
```

The Space builds from the root `Dockerfile` (React frontend → `backend/static`, FastAPI on port 7860).

## Troubleshooting

- **Port 7860 in use** — set `CCAI_HOST_PORT` in `.env`, or run uvicorn
  on another port.
- **Frontend can't reach the API in dev** — ensure
  `REACT_APP_API_URL=http://localhost:7860` is set in
  `frontend/.env.development` and the backend is running.
- **CORS errors** — add your origin to `CORS_ORIGINS` in `.env`.
- **Diagram doesn't render** — vis-network needs the bundled assets from
  `npm install`; re-run it if you cloned without building.