Wactorz — Architecture Reference

┌────────────────────────────────────────────────────────────────────┐
│  Browser                                                           │
│  Babylon.js SPA  ←──WebSocket──►  nginx  ←─── /ws  ──►           │
│                  ←──REST──────►          ←─── /api/ ──►           │
│                  ←──MQTT/WS───►          ←─── /mqtt ──►           │
└────────────────────────────────────────────────────────────────────┘
                                    │
                             nginx  │  (single public entry point)
                              :80   │
                                    │
          ┌─────────────────────────┼──────────────────────────────┐
          │                         │                              │
          ▼                         ▼                              ▼
  wactorz (Python)        Mosquitto (MQTT)              Fuseki (RDF)
  :8080 REST                :1883 TCP / :9001 WS          :3030 SPARQL
  :8081 WS bridge
  ┆ Rust in-sync ┆
          │
          │  pub/sub via MQTT
          ├── MainActor         (LLM orchestrator)
          ├── MonitorAgent      (health watchdog)
          ├── IOAgent           (UI gateway)
          ├── QAAgent           (safety observer)
          ├── NautilusAgent     (SSH / rsync bridge)
          ├── UDXAgent          (built-in knowledge base)
          ├── PlannerAgent      (task planning + pipeline builder)
          ├── CatalogAgent      (pre-built recipe library)
          ├── InstallerAgent    (pip + SSH deployment)
          ├── ManualAgent       (PDF search & extraction)
          ├── HomeAssistantAgent (HA automation CRUD)
          └── DynamicAgent*    (LLM-generated scripts, spawned at runtime)

# Windows
mosquitto -v

# Docker
docker run -it -p 1883:1883 eclipse-mosquitto

Message flow:

  Actor A                Registry              Actor B
  ───────               ──────────             ───────
  send(B_id, TASK, {…}) ──────────────────►  mailbox.put(msg)
                                              message_loop picks it up
                                              handle_message(msg) fires
                        ◄─────────────────── send(A_id, RESULT, {…})
  handle_message fires
  future.set_result(…)

CREATED → RUNNING → PAUSED → STOPPED
                  ↘ FAILED

#[async_trait]
pub trait Actor: Send {
    fn id(&self)       -> String;
    fn name(&self)     -> &str;
    fn state(&self)    -> ActorState;
    fn mailbox(&self)  -> mpsc::Sender<Message>;

    async fn on_start(&mut self)                     -> Result<()>;
    async fn handle_message(&mut self, msg: Message) -> Result<()>;
    async fn on_heartbeat(&mut self)                 -> Result<()>;
    async fn on_stop(&mut self)                      -> Result<()> { Ok(()) }
    async fn run(&mut self)                          -> Result<()>;
}

coordinate: get the weather and search AI news, then combine them  → PlannerAgent (task mode)
if the door opens send me a Discord message                        → PlannerAgent (pipeline mode)
@home-assistant-agent turn on the lights                           → HA direct
what is the capital of France?                                     → main LLM

Browser IO bar
  │  publishes  io/chat  { from: "user", content: "@agent-name text" }
  ▼
Mosquitto
  │  subscribed by wactorz backend
  ▼
MQTT event loop  →  IOAgent mailbox
  │
  ▼
IOAgent.handle_message()
  │  parses @mention, looks up registry
  ▼
target actor mailbox  →  handle_message()  →  LLM call (if needed)
  │
  ▼
actor publishes  agents/{id}/chat  { from: actor, to: "user", content: … }
  │
  ▼
Mosquitto  →  WebSocket bridge  →  Browser

async def handle_task(agent, payload):
    # Ask another agent and wait for the result
    weather = await agent.delegate('weather-agent', {'city': 'Athens'})

    # Fan-out to multiple agents in parallel
    results = await agent.send_to_many([
        ('weather-agent', {'city': 'Athens'}),
        ('news-agent',    {'query': 'AI today'}),
    ])

    # List all running agents
    workers = agent.agents()

agent.persist('my_key', {'count': 42, 'data': [...]})   # immediate disk write
value = agent.recall('my_key', default={})               # read

if the door opens, send me a Discord message
when the kitchen temperature goes above 28 degrees, turn on the air conditioner
if a person is detected on my webcam, turn on the living room lights
whenever the lamp in the living room turns on, notify me on Discord

DynamicAgent (sensor/filter) → MQTT topic → HomeAssistantActuatorAgent → HA service call

[Main machine]                        [Raspberry Pi / Edge node]
main_actor ──MQTT──► nodes/{name}/spawn ──► remote_runner.py
                                               │  compiles + runs agent
                                               │  heartbeats every 10s
dashboard  ◄──MQTT── agents/{id}/heartbeat ◄───┘

pip install aiomqtt --break-system-packages
python3 remote_runner.py --broker 192.168.1.10 --name rpi-kitchen

/deploy rpi-kitchen

/nodes

  local                online   @main @monitor @installer @home-assistant-agent
  rpi-kitchen          online   @temp-sensor
  rpi-bedroom          OFFLINE  (no agents)

/migrate temp-sensor rpi-bedroom

wactorz/
├── main.py                                    Entry point — CLI args, actor system setup, supervision tree
├── remote_runner.py                           Self-contained edge node runner
├── monitor_server.py                          MQTT → WebSocket bridge for dashboard
├── monitor.html                               Live web dashboard
├── fix_history.py                             One-time corrupted history cleanup utility
├── requirements.txt
│
├── core/
│   ├── actor.py                               Base Actor — mailbox, lifecycle, heartbeat, spawn, supervisor
│   └── registry.py                            ActorSystem, ActorRegistry, Supervisor — routing & OTP restarts
│
├── agents/
│   ├── llm_agent.py                           LLMAgent — 5 providers, rolling summarization, cost tracking
│   ├── main_actor.py                          MainActor — intent routing, memory, user facts, pipeline rules
│   ├── dynamic_agent.py                       DynamicAgent — runtime code executor, error events
│   ├── planner_agent.py                       PlannerAgent — task planning + reactive pipeline builder
│   ├── monitor_agent.py                       MonitorAgent — heartbeat, error registry, recovery
│   ├── installer_agent.py                     InstallerAgent — pip install locally + SSH deploy to remote nodes
│   ├── catalog_agent.py                       CatalogAgent — pre-built recipe library
│   ├── manual_agent.py                        ManualAgent — 3-layer PDF search and extraction
│   ├── home_assistant_agent.py                HomeAssistantAgent — HA automation CRUD (LLM-backed)
│   ├── home_assistant_map_agent.py            HomeAssistantMapAgent — live entity/location map
│   ├── home_assistant_state_bridge_agent.py   HomeAssistantStateBridgeAgent — state_changed → MQTT
│   ├── home_assistant_actuator_agent.py       HomeAssistantActuatorAgent — reactive MQTT→HA actuator
│   ├── code_agent.py                          CodeAgent — sandboxed Python execution
│   └── ml_agent.py                            MLAgent, YOLOAgent, AnomalyDetectorAgent
│
├── interfaces/
│   └── chat_interfaces.py                     CLI, REST, Discord, Telegram, WhatsApp
│
└── rust/                                      Optional Rust in-sync mirror
    └── crates/
        ├── wactorz-core/
        ├── wactorz-agents/
        ├── wactorz-mqtt/
        ├── wactorz-interfaces/
        └── wactorz-server/

catalogue_agents/                              Pre-built agent recipe files (loaded by CatalogAgent)
├── __init__.py
├── image_gen_agent.py                         NIM FLUX.1-dev image generation
└── doc_to_pptx_agent.py                      PDF/TXT → PowerPoint conversion

state/                                         Persisted agent state (auto-created, never commit to git)
├── main/state.pkl
├── planner/state.pkl
└── {agent-name}/state.pkl