README.md

metadata

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 ("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.

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)

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):

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:

cd backend
.\dev.ps1            # Windows

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):

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:

{
  "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

# 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 — minimal settings (CORS_ORIGINS).
• 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 — 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 (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):

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.