AutoSwarm-Shadow-Adapter README

项目的 README,来自 github.com/AhmadHassan-BTed/AutoSwarm-Shadow-Adapter。合并为一个 markdown 文件:README.md。

AutoSwarm-Shadow-Adapter

Non-Blocking Human-in-the-Loop (HITL) & BYOC Infrastructure for AutoSwarm

AI Agent Employees For Your Compan -- The Carbon-Silicon Continuum: Real Humans & Remote PCs as First-Class AutoSwarm Employees

Python 3.10+ PyPI Package MIT License

FastAPI React 19 SQLite WAL JWT Auth Zero Core Modifications AutoSwarm Ecosystem


Built for AutoSwarm | Zero Core Modifications | Production Release v0.1.0


What is AutoSwarm-Shadow-Adapter?

AutoSwarm-shadow-adapter is a high-concurrency Temporal Bridge for AutoSwarm. It allows AutoSwarm agentic DAGs to pause non-blockingly when a role requires human sign-off (Carbon) or remote GPU execution (Silicon BYOC), without causing engine timeouts or stalling parallel branches.

  1. Non-Blocking Intercept: Intercepts AutoSwarm task execution in <50ms, parks the task in an isolated SQLite WAL database, and releases execution threads immediately with AWAITING_HUMAN.
  2. Contractor & Silicon Worker Portal: Provides a dedicated, secure React 19 UI and REST API (shadow-serve) for human reviewers and remote workers (shadow-worker).
  3. Consolidated Corporate Brain: Automatically packages ancestor deliverables, structured markdown briefs (brief_md), and uploaded file artifacts (CorporateArtifacts) for downstream context inheritance.
  4. Canonical State Subordination: Resumes AutoSwarm's native store.db state machine (delegation_work_items.phase) instantly when deliverables are submitted.
  5. Symbiotic Architecture: Functions as an independent, non-invasive extension that plugs into AutoSwarm's external agent registry (ADAPTER_CLASSES["shadow"]) with zero core repository modifications.

Appoint AI Agents & Hybrid Employees to

Automate Freelance & Multiple Jobs (Overemployment Engine)

Juggling multiple client contracts or simultaneous full-time roles? Turn yourself from an individual contributor into an agency of one. Assign the heavy lifting—writing programs, reviewing complex technical architectures, and completing routine software assignments—to your remote silicon employees. You sit at the top of the hierarchy as the sole human reviewer. Deliver 5x the output to multiple clients simultaneously, approving deliverables asynchronously on your own schedule without burning out.

Augment Vacant or Overloaded Roles

Lost a developer? Legal reviewer on leave? Analyst at capacity? AI agents perform 90% of preliminary work (research, code generation, test suite execution, drafting). Shadow Adapter routes only the final approval decision to an available human manager.

Run Your Entire Business on AI Autopilot

One operator with the leverage of a 10-person team. Your AI Research Analyst, Dev Team, Marketing Lead, and Legal Counsel operate 24/7. Shadow Adapter queues strategic checkpoints for your review without stalling non-dependent work streams.

Ensure Enterprise Regulatory Compliance

Feature Comparison

Capability Standard AutoSwarm AutoSwarm + Shadow Adapter
Human response time > 900s Engine crash (timeout failure) Zero timeouts (unlimited duration)
System restart resilience State lost Persisted in isolated SQLite WAL DB
Multi-user access control Local user only Multi-user queue with JWT auth
File attachments Text only Up to 5 files, 50MB payload
Audit log compliance Basic engine log Immutable timeline with user attribution
Iterative rework loop Manual intervention Built-in rework_requested state transition

How It Works

flowchart LR
    subgraph Engine ["AutoSwarm Agentic DAG Engine"]
        DAG["Multi-Agent DAG Execution\n(Parallel AI Tasks)"]
    end

    subgraph Adapter ["Shadow Mode Plugin"]
        SA["ShadowModeAdapter\n(Non-blocking Intercept < 50ms)"]
    end

    subgraph Store ["Isolated Persistence"]
        DB[("SQLite WAL Store\nshadow_tasks.db")]
    end

    subgraph Portal ["Human Operations"]
        ReactApp["React 19 Human Portal\n(JWT Authenticated)"]
        HumanReviewer["Human Contractor / Reviewer"]
    end

    subgraph ResumeLayer ["DAG Unblock & Resume"]
        OPCStore[("AutoSwarm Engine Store\nstore.db (WAL Mode)")]
        UnblockNode(["Downstream DAG Nodes\nResume Automatically"])
    end

    DAG -->|1. Intercept human-backed task| SA
    SA -->|2. Park task record| DB
    SA -->|3. Return AWAITING_HUMAN and release thread| DAG
    DB <-->|4. Query pending queue & Submit deliverable| ReactApp
    HumanReviewer <-->|5. Review brief & attach files| ReactApp
    ReactApp -->|6. Submit deliverable via REST API| SA
    SA -->|7. Write Phase.APPROVED to store| OPCStore
    OPCStore -->|8. Native Phase Hooks Trigger| UnblockNode

User Workflow & Execution Pipeline

  1. Task Decomposing & Assignment: When a user launches an AutoSwarm session (e.g. opc chat --mode company "Build feature X"), AutoSwarm's Manager AI creates work items and assigns them to configured role seats (e.g., senior_developer, legal_counsel).
  2. Shadow Intercept (<50ms): Any role assigned preferred_external_agent: shadow is intercepted by ShadowModeAdapter. The adapter parses project goals, compiles a markdown task brief (TaskBriefBuilder), parks a record in shadow_tasks.db, and returns AWAITING_HUMAN to AutoSwarm. Execution threads release immediately so parallel DAG tasks continue without timing out.
  3. Task Claiming:
    • Human Contractor: Logs into the Contractor Portal at http://localhost:8800, claims the pending task, and opens the interactive TaskWorkspace.
    • Silicon BYOC Worker: A remote GPU node running shadow-worker --role senior_developer polls the API, claims the task, and executes inference on its local model.
  4. Deliverable Submission: The worker reviews upstream subagent context, writes solution notes, and attaches deliverable files (up to 5 files / 50MB payload cap). Files are indexed into CorporateArtifacts with SHA-256 integrity hashes.
  5. DAG Resumption: OpcResumeRepository updates delegation_work_items.phase in AutoSwarm's host store.db. AutoSwarm wakes downstream DAG nodes, passing the uploaded artifacts forward.

For complete documentation:


Symbiotic Integration & Quick Start

AutoSwarm-shadow-adapter is built to run as a true symbiont with AutoSwarm. You can run the portal server embedded in your main Python process or as a standalone CLI sidecar.

Step 1: Install Package

pip install AutoSwarm-shadow-adapter

Step 2: Register & Launch Embedded (Zero Extra Commands)

In your main AutoSwarm application entry point (e.g., main.py), register the adapter and launch the Human Portal server concurrently in a background thread:

# main.py (Your AutoSwarm application entry point)
from opc.layer3_agent.adapters.registry import ADAPTER_CLASSES
from shadow_adapter import ShadowModeAdapter, start_server_in_thread

# 1. Register "shadow" mode into AutoSwarm's adapter registry
ADAPTER_CLASSES["shadow"] = ShadowModeAdapter

# 2. Launch Human Web Portal concurrently on port 8800 (single process)
start_server_in_thread(port=8800)

# 3. Launch your AutoSwarm DAG pipeline as normal!

Step 3: Configure Target Roles

In your AutoSwarm organization config (.opc/config/company_orgs/company_config.yaml), set preferred_external_agent: shadow for human-backed roles:

# .opc/config/company_orgs/company_config.yaml
roles:
  legal_counsel:
    title: "Human Legal Counsel"
    execution_strategy: external
    preferred_external_agent: shadow  # <-- Intercepted by Shadow Adapter

  senior_architect:
    title: "Human Senior Architect"
    execution_strategy: external
    preferred_external_agent: shadow  # <-- Intercepted by Shadow Adapter

Alternative: Launch via CLI Sidecar

If you prefer running the Web Portal in a separate terminal or Docker container:

shadow-serve --port 8800

Distributed Silicon Workforce (Bring Your Own Compute - BYOC)

The shadow-worker daemon allows remote PCs, GPU workstations, and dedicated cloud nodes to act as specialized silicon employees. Each remote node runs its assigned role on its own local model or API key without modifying the central AutoSwarm engine.

Launch Remote Compute Nodes (3-PC Distributed Example)

1. Remote GPU Workstation (Role: Senior Developer -> Local Ollama)

export OLLAMA_HOST="http://localhost:11434"
shadow-worker \
  --server-url "[http://192.168.1.100:8800](http://192.168.1.100:8800)" \
  --username "dev_node_1" \
  --password "secure_pass_1" \
  --role "senior_developer" \
  --provider "ollama" \
  --model "llama3.3:70b"
export LOCAL_ANTHROPIC_KEY="sk-ant-api03-enterprise-key..."
shadow-worker \
  --server-url "[http://192.168.1.100:8800](http://192.168.1.100:8800)" \
  --username "legal_node_2" \
  --password "secure_pass_2" \
  --role "legal_counsel" \
  --provider "anthropic" \
  --model "claude-3-5-sonnet-20241022"

3. Remote Tester Machine (Role: QA Tester -> OpenAI GPT-4o)

export LOCAL_OPENAI_API_KEY="sk-proj-openai-key..."
shadow-worker \
  --server-url "[http://192.168.1.100:8800](http://192.168.1.100:8800)" \
  --username "qa_node_3" \
  --password "secure_pass_3" \
  --role "qa_tester" \
  --provider "openai" \
  --model "gpt-4o"

Programmatic Python SDK Usage

You can also embed ShadowWorker into custom Python pipelines on remote nodes:

import asyncio
from shadow_adapter import ShadowWorker

# Custom task handler executing local agent pipeline
async def my_local_agent(task: dict) -> str:
    # Query your local GPU, private database, or custom agent model
    return f"Processed task '{task['title']}' on local node."

worker = ShadowWorker(
    server_url="[http://192.168.1.100:8800](http://192.168.1.100:8800)",
    username="custom_node_01",
    password="password123",
    role="legal_counsel",
    custom_handler=my_local_agent,
)

asyncio.run(worker.run_forever())

The Consolidated Corporate Brain (Knowledge Graph)

A real company doesn't just pass text strings—employees share documents, reports, and data. AutoSwarm-shadow-adapter acts as the Central Nervous System for your AI and Human workforce by maintaining a centralized artifact registry.

1. The Shared Artifact Registry

When a Silicon or Carbon employee finishes a task, their deliverables (PDFs, CSVs, code files) are saved to the centralized CorporateArtifacts registry. This creates an indexed, searchable corporate memory for your entire DAG.

2. Hierarchical Context Injection

The adapter dynamically parses your AutoSwarm company_config.yaml to understand your corporate hierarchy. When a downstream Manager receives a task to "Review the Analyst's work," the adapter automatically packages and injects the Analyst's upstream artifacts directly into the Manager's workspace (via the React Portal or the ShadowWorker API payload).

3. Role-Based Inheritance

Employees natively inherit the context of the workers below them. A Human Legal Director reviewing a contract doesn't just get a text summary—they are handed the exact .docx file the remote AI Drafter uploaded 5 minutes prior.


Architecture Deep-Dive

All detailed technical specifications are decoupled from this overview:


Configuration Reference

Variable Default Value Required Description
SHADOW_JWT_SECRET None Yes Secret key for signing JWT tokens (min 32 chars).
SHADOW_DB_PATH ./shadow_tasks.db No Path for the isolated Shadow SQLite database.
SHADOW_OPC_STORE_PATH .opc/projects/default/store.db No Path to AutoSwarm's store.db for WAL resume writes.
SHADOW_UPLOAD_DIR ./shadow_uploads No Directory for storing deliverable attachments.
SHADOW_MAX_FILES_PER_SUBMISSION 5 No Max files permitted per submission.
SHADOW_MAX_FILE_SIZE_MB 10 No Max allowed size per file in MB.
SHADOW_MAX_TOTAL_UPLOAD_SIZE_MB 50 No Max total upload payload per submission in MB.
SHADOW_API_PORT 8800 No Network port for FastAPI server and React SPA.

Development & Testing

# Run full anti-fragility & host integration test suite (55 tests)
# Enforces Concurrency, Property-Based Fuzzing, Black Hole Exception Trapping, and AutoSwarm Host Mutation Survival
pytest tests/ -v --cov=shadow_adapter --cov-report=term-missing

# Run engine simulator demo
python tests/mock_AutoSwarm_engine.py

AutoSwarm-Shadow-Adapter | Non-Blocking Human-in-the-Loop Layer for AutoSwarm

GitHub Repository | PyPI Package | Issue Tracker | Architecture Spec


Thanks for visiting 🖤 Build for AutoSwarm Community

Views

AutoSwarm-Shadow-Adapter (AhmadHassan-BTed/AutoSwarm-Shadow-Adapter)

正在搜索数据库…

这是做什么的?OpenOPC-Shadow-Adapter 是 OpenOPC 智能体 DAG 运行时的非阻塞式人在回路(HITL)桥接器。它可以让 AI 智能体工作流暂停,等待人工签核或远程 GPU(BYOC)执行,而不会冻结引擎或导致超时。
它会修改 OpenOPC 本身,还是和它一起运行?它是一个独立的适配层(FastAPI 后端加 React 门户),用于拦截 OpenOPC 的任务执行,而不修改 OpenOPC 自身的代码。
怎样才能在我现有的 OpenOPC 环境中运行它?设置必需的环境变量 SHADOW_JWT_SECRET(至少 32 个字符),然后启动服务器。默认情况下,它在 8800 端口同时提供 FastAPI 接口和 React SPA,也可以通过 PyPI 包安装。
使用它之前,我需要已经安装好 OpenOPC 吗?需要。它设计为接入 OpenOPC 的智能体 DAG 运行时,并会解析其 companyconfig.yaml。角色席位可以切换到本地 Ollama,或远程 API,比如 Claude 或 GPT-4o。
等待人工回应时,整个 DAG 会停住吗?不会。如果没有这个适配器,OpenOPC 的引擎会在等待某个角色 900 秒后因超时而崩溃。这个适配器去掉了该限制,使人工或远程机器可以用任意长的时间来完成工作,而不会阻塞并行分支。
这是为谁设计的?面向在企业式架构中运行 OpenOPC 的团队:由管理者 AI 把工作项分配给“高级开发者”“法务顾问”等角色席位,并需要可审计的人工签核或远程执行追踪。
README 里提到的“碳硅连续体”是什么?这是项目的术语,指把真人(“碳基”)和由远程 GPU 驱动的 AI 工作者(“硅基 BYOC”)都视为 OpenOPC 的一级“员工”,DAG 可以为他们暂停执行。
什么是企业产物注册表?它是一个集中的、可搜索的存储库,每位员工的交付物(PDF、CSV、代码)都保存在其中。这样,像管理者这样的下游智能体可以自动获取同事的实际文件,而不只是文字摘要。
被驳回的工作能否无需人工干预就自动重做?可以。内置了 'rework_requested' 状态转换,用于迭代返工循环,而不必手动重启任务。
我能否不通过 React 门户,而在自己的 Python 代码中使用它?可以。ShadowWorker 类可以直接嵌入到运行在远程节点上的自定义 Python 流水线中。
大小
0.3 MB
星标
5.2K
时长
3个月
提交 · 90 天