AutoSwarm‑Shadow‑Adapter

What it is – A plug‑in for the AutoSwarm AI‑agent orchestration framework that lets a DAG‑based workflow pause non‑blocking when a step needs a human reviewer (the “Carbon” employee) or an external GPU worker (the “Silicon” BYOC worker). The pause is handled by a lightweight ShadowModeAdapter that stores the pending task in an isolated SQLite WAL database and immediately returns an AWAITING_HUMAN state, so the rest of the parallel DAG keeps running.

---

Core capabilities

Feature	What it does
Non‑blocking intercept	Captures a task in < 50 ms, parks it in shadow_tasks.db, and frees the engine thread.
Human & remote‑worker portal	FastAPI‑backed REST API + React 19 + Tailwind UI (http://localhost:8800) where humans can claim tasks, view markdown briefs, and upload up to 5 files (≤ 50 MB total).
BYOC compute	Remote nodes run shadow‑worker daemon, authenticate via JWT, pull tasks, execute a local model (Ollama, Anthropic, OpenAI, etc.) and push results back.
Audit‑ready persistence	All submissions are timestamped, attributed, and stored immutably; the SQLite WAL ensures crash‑resilience and state‑recovery.
Zero core changes	The adapter registers itself in AutoSwarm’s ADAPTER_CLASSES["shadow"] registry; no modifications to the main AutoSwarm codebase are required.
Corporate artifact registry	Uploaded deliverables are saved under CorporateArtifacts with SHA‑256 hashes, making them searchable for downstream agents.

---

How it works (high‑level flow)

1. AutoSwarm creates a work item and sees preferred_external_agent: shadow for the role.
2. ShadowModeAdapter intercepts the task, builds a markdown brief, writes a record to shadow_tasks.db, and returns AWAITING_HUMAN.
3. Human or silicon worker logs into the React portal (or runs shadow‑worker) and claims the pending task.
4. The worker reviews the context, writes a solution note, and optionally uploads files.
5. The adapter writes Phase.APPROVED into AutoSwarm’s native store.db (WAL mode), triggering the native DAG hooks.
6. Downstream nodes resume automatically, receiving the newly‑uploaded artifacts as part of their input.

---

Quick start (Python 3.10+)

# 1️⃣ Install the package from PyPI
pip install AutoSwarm-shadow-adapter

# 2️⃣ Register the adapter in your AutoSwarm entry point
#    (e.g. main.py of your AutoSwarm application)
from opc.layer3_agent.adapters.registry import ADAPTER_CLASSES
from shadow_adapter import ShadowModeAdapter, start_server_in_thread

ADAPTER_CLASSES["shadow"] = ShadowModeAdapter   # plug‑in registration
start_server_in_thread(port=8800)               # launch the FastAPI + React UI

# 3️⃣ Run your normal AutoSwarm DAG as you would normally.

If you prefer a separate process, just run the side‑car server: shadow-serve --port 8800.

---

Remote silicon workers (BYOC)

# Example: a remote GPU workstation using Ollama
export OLLAMA_HOST="http://localhost:11434"
shadow-worker \
  --server-url http://192.168.1.100:8800 \
  --username dev_node_1 \
  --password secret123 \
  --role senior_developer \
  --provider ollama \
  --model llama3.3:70b

The daemon continuously polls the API, claims tasks matching its role, runs the specified model locally, and posts the result back.

---

Configuration (environment variables / .env)

Variable	Required?	Default	Meaning
SHADOW_JWT_SECRET	Yes	–	Secret for signing JWT tokens (≥ 32 chars).
SHADOW_DB_PATH	No	./shadow_tasks.db	Path to the isolated SQLite WAL DB.
SHADOW_OPC_STORE_PATH	No	.opc/projects/default/store.db	Path to AutoSwarm’s main store DB (where the adapter writes the resume phase).
SHADOW_UPLOAD_DIR	No	./shadow_uploads	Directory where uploaded files are stored.
SHADOW_MAX_FILES_PER_SUBMISSION	No	5	Max number of files per task.
SHADOW_MAX_FILE_SIZE_MB	No	10	Max size per file.
SHADOW_MAX_TOTAL_UPLOAD_SIZE_MB	No	50	Max total payload per submission.
SHADOW_API_PORT	No	8800	Port for the FastAPI server and React SPA.

---

Who would use this?

• Freelancers or solo founders who want to outsource heavy‑lifting to remote GPU nodes while retaining final human sign‑off.
• Enterprises needing audit‑grade human‑in‑the‑loop checkpoints (SOC 2, ISO 27001, GDPR) without halting parallel AI work.
• Teams that run multiple client contracts simultaneously and need a queue‑based “human‑as‑service” layer.

---

Limitations & considerations

• The adapter only works with AutoSwarm (the specific DAG engine it targets). It is not a generic HITL layer for other frameworks.
• Human tasks are stored in a separate SQLite WAL; you must back up shadow_tasks.db if long‑term retention is required.
• File uploads are capped at 5 × 10 MB (configurable) – large binary assets need external storage.
• Security relies on JWT + bcrypt; you must protect SHADOW_JWT_SECRET and run the portal behind TLS in production.

---

Development & testing

# Run the full test suite (55 tests) with coverage
pytest tests/ -v --cov=shadow_adapter --cov-report=term-missing

# Simulate an AutoSwarm engine for quick demos
python tests/mock_AutoSwarm_engine.py

The repository includes type‑checked code, property‑based fuzz tests, and integration tests that verify the adapter survives engine restarts and concurrent task loads.

---

Links

• GitHub: https://github.com/AhmadHassan-BTed/AutoSwarm-shadow-adapter
• PyPI: https://pypi.org/project/AutoSwarm-shadow-adapter/
• AutoSwarm core repo: https://github.com/HKUDS/AutoSwarm

---

Built for the AutoSwarm community – a non‑invasive, human‑in‑the‑loop bridge that lets AI agents and real people work together without dead‑locking the workflow.