AutoSwarm‑Shadow‑Adapter

개요 – AutoSwarm AI‑에이전트 오케스트레이션 프레임워크용 플러그인으로, DAG 기반 워크플로우가 인간 검토자(“Carbon” 직원) 또는 외부 GPU 워커(“Silicon” BYOC 워커)가 필요한 단계에서 비차단 방식으로 일시 중지할 수 있게 합니다. 일시 중지는 경량 ShadowModeAdapter가 처리하며, 보류 중인 작업을 격리된 SQLite WAL 데이터베이스에 저장하고 즉시 AWAITING_HUMAN 상태를 반환하므로 나머지 병렬 DAG는 계속 실행됩니다.

핵심 기능

기능	설명
비차단 인터셉트	작업을 50ms 이내에 캡처하여 `shadow_tasks.db`에 보관하고 엔진 스레드를 해제합니다.
인간 및 원격 워커 포털	FastAPI 기반 REST API + React 19 + Tailwind UI(`http://localhost:8800`)로, 인간이 작업을 요청하고 마크다운 브리프를 확인하며 최대 5개 파일(총 ≤ 50MB)을 업로드할 수 있습니다.
BYOC 컴퓨트	원격 노드가 `shadow-worker` 데몬을 실행하고, JWT로 인증하며, 작업을 가져와 로컬 모델(Ollama, Anthropic, OpenAI 등)을 실행하고 결과를 다시 푸시합니다.
감사 준비된 영속성	모든 제출물은 타임스탬프, 귀속, 불변 저장되며 SQLite WAL은 크래시 내성과 상태 복구를 보장합니다.
핵심 변경 없음	어댑터는 AutoSwarm의 `ADAPTER_CLASSES["shadow"]` 레지스트리에 자체 등록되며, 기본 AutoSwarm 코드베이스 수정이 필요 없습니다.
기업 산출물 레지스트리	업로드된 산출물은 SHA-256 해시와 함께 `CorporateArtifacts`에 저장되어 다운스트림 에이전트가 검색할 수 있습니다.

작동 방식 (상위 수준 흐름)

AutoSwarm이 작업 항목을 생성하고 해당 역할에 preferred_external_agent: shadow가 있는지 확인합니다.
ShadowModeAdapter가 작업을 인터셉트하여 마크다운 브리프를 작성하고 shadow_tasks.db에 레코드를 기록한 후 AWAITING_HUMAN을 반환합니다.
인간 또는 실리콘 워커가 React 포털(또는 shadow-worker 실행)에 로그인하여 보류 중인 작업을 요청합니다.
워커는 컨텍스트를 검토하고 솔루션 노트를 작성하며 선택적으로 파일을 업로드합니다.
어댑터는 AutoSwarm의 기본 store.db(WAL 모드)에 Phase.APPROVED를 기록하여 기본 DAG 훅을 트리거합니다.
다운스트림 노드는 새로 업로드된 산출물을 입력의 일부로 받으며 자동으로 재개됩니다.

빠른 시작 (Python 3.10+)

# 1️⃣ PyPI에서 패키지 설치
pip install AutoSwarm-shadow-adapter

# 2️⃣ AutoSwarm 진입점에 어댑터 등록
#    (예: AutoSwarm 애플리케이션의 main.py)
from opc.layer3_agent.adapters.registry import ADAPTER_CLASSES
from shadow_adapter import ShadowModeAdapter, start_server_in_thread

ADAPTER_CLASSES["shadow"] = ShadowModeAdapter   # 플러그인 등록
start_server_in_thread(port=8800)               # FastAPI + React UI 시작

# 3️⃣ 평소처럼 일반 AutoSwarm DAG를 실행합니다.

별도 프로세스를 원하면 사이드카 서버를 실행하세요: shadow-serve --port 8800.

원격 실리콘 워커 (BYOC)

# 예: Ollama를 사용하는 원격 GPU 워크스테이션
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

데몬은 API를 지속적으로 폴링하여 자신의 role과 일치하는 작업을 요청하고, 지정된 모델을 로컬에서 실행한 후 결과를 다시 게시합니다.

설정 (환경 변수 / .env)

변수	필수?	기본값	의미
`SHADOW_JWT_SECRET`	예	–	JWT 토큰 서명용 비밀 (≥ 32자).
`SHADOW_DB_PATH`	아니요	`./shadow_tasks.db`	격리된 SQLite WAL DB 경로.
`SHADOW_OPC_STORE_PATH`	아니요	`.opc/projects/default/store.db`	AutoSwarm의 기본 store DB 경로(어댑터가 재개 단계를 기록하는 곳).
`SHADOW_UPLOAD_DIR`	아니요	`./shadow_uploads`	업로드된 파일이 저장되는 디렉토리.
`SHADOW_MAX_FILES_PER_SUBMISSION`	아니요	`5`	작업당 최대 파일 수.
`SHADOW_MAX_FILE_SIZE_MB`	아니요	`10`	파일당 최대 크기.
`SHADOW_MAX_TOTAL_UPLOAD_SIZE_MB`	아니요	`50`	제출당 최대 총 페이로드.
`SHADOW_API_PORT`	아니요	`8800`	FastAPI 서버 및 React SPA용 포트.

누가 사용할까요?

프리랜서 또는 1인 창업자 – 무거운 작업을 원격 GPU 노드에 아웃소싱하면서 최종 인간 승인을 유지하려는 경우.
기업 – 병렬 AI 작업을 중단하지 않으면서 감사 등급의 인간 개입 체크포인트(SOC 2, ISO 27001, GDPR)가 필요한 경우.
팀 – 여러 고객 계약을 동시에 실행하면서 큐 기반의 "인간 서비스" 계층이 필요한 경우.

제한 사항 및 고려 사항

어댑터는 AutoSwarm(대상 DAG 엔진)에서만 작동합니다. 다른 프레임워크용 범용 HITL 계층이 아닙니다.
인간 작업은 별도의 SQLite WAL에 저장됩니다. 장기 보존이 필요하면 shadow_tasks.db를 백업해야 합니다.
파일 업로드는 5 × 10MB(구성 가능)로 제한됩니다. 대용량 바이너리 자산은 외부 저장소가 필요합니다.
보안은 JWT + bcrypt에 의존합니다. SHADOW_JWT_SECRET을 보호하고 프로덕션에서는 TLS 뒤에서 포털을 실행해야 합니다.

개발 및 테스트

# 전체 테스트 스위트(55개 테스트)를 커버리지와 함께 실행
pytest tests/ -v --cov=shadow_adapter --cov-report=term-missing

# 빠른 데모를 위한 AutoSwarm 엔진 시뮬레이션
python tests/mock_AutoSwarm_engine.py

저장소에는 타입 검사된 코드, 속성 기반 퍼즈 테스트, 엔진 재시작 및 동시 작업 부하에서 어댑터가 살아남는지 확인하는 통합 테스트가 포함되어 있습니다.

링크

GitHub: https://github.com/AhmadHassan-BTed/AutoSwarm-shadow-adapter
PyPI: https://pypi.org/project/AutoSwarm-shadow-adapter/
AutoSwarm 코어 저장소: https://github.com/HKUDS/AutoSwarm

AutoSwarm 커뮤니티를 위해 제작 – AI 에이전트와 실제 사람이 워크플로우를 교착 상태에 빠뜨리지 않고 함께 작업할 수 있게 하는 비침습적 인간 개입 브리지입니다.

AhmadHassan-BTed/AutoSwarm-Shadow-Adapter