daggr는 Gradio 앱, ML 모델 (Hugging Face Inference Providers를 통해), 그리고 커스텀 Python 함수들을 연결하여 강력한 AI workflow를 구축하기 위한 Python 라이브러리입니다. 이는 workflow를 코드로 정의하면 시각적 캔버스(visual canvas)를 자동으로 생성하여, 사용자에게 중간 결과 검사, 개별 단계 재실행, 복잡하거나 장기 실행 workflow의 상태 보존, 그리고 provenance 추적 기능을 제공합니다.

핵심 방법론 (Core Methodology)

daggr workflow는 노드(node)들이 연결된 Directed Acyclic Graph (DAG) 형태로 구성됩니다. 각 노드는 연산(computation)을 나타내며, input ports와 output ports를 통해 데이터가 흐릅니다.

1. 노드 유형 (Node Types)
   • GradioNode: Gradio Space의 API endpoint를 호출하는 데 사용됩니다. space_or_url 매개변수로 Hugging Face Space ID 또는 URL을, api_name으로 호출할 API 엔드포인트 이름을 지정합니다. inputs 딕셔너리의 키는 대상 API의 매개변수 이름과 일치해야 하며, outputs 딕셔너리는 API 반환 값의 순서에 매핑됩니다. GradioNode는 외부 API 호출이므로 기본적으로 동시(concurrent) 실행됩니다.
   • FnNode: Python 함수를 실행합니다. fn 매개변수에 호출할 함수를 전달합니다. inputs 딕셔너리의 키는 함수의 매개변수 이름과 일치해야 하며, outputs 딕셔너리는 함수의 반환 값 순서에 매핑됩니다. 단일 값을 반환하거나, 여러 값을 tuple 형태로 반환하여 여러 output port에 매핑할 수 있습니다. FnNode는 기본적으로 세션(session)당 순차(sequential)적으로 실행되어 리소스 경합을 방지하지만, $concurrent=True$ 설정 또는 concurrency_group 및 max_concurrent 설정을 통해 동시 실행을 명시적으로 허용할 수 있습니다.
   • InferenceNode: Hugging Face Inference Providers를 통해 호스팅된 모델을 호출합니다. model 매개변수에 모델 ID를 지정합니다. inputs와 outputs 정의 방식은 GradioNode와 유사하며, InferenceNode 또한 외부 API 호출이므로 기본적으로 동시 실행됩니다.

2. 입력 및 출력 포트 (Input & Output Ports)
   • Input ports:
     • Gradio component (gr.Textbox, gr.Image 등): UI에 독립적인 입력 필드를 생성합니다.
     • Port reference (other_node.output_name): 이전 노드의 출력 포트에 연결하여 데이터를 자동으로 전달합니다.
     • Fixed value: 상수로 직접 전달되며 UI에 나타나지 않습니다.
     • Callable: workflow가 실행될 때마다 호출되는 함수입니다 (예: random.random for seed).
   • Output ports:
     • Gradio component: 노드 카드에 해당 결과를 표시합니다.
     • None: 출력은 UI에서 숨겨지지만, 다음 노드에 연결될 수 있습니다.

3. 특수 기능 (Special Features)
   • Scatter / Gather (분산/집합): 노드가 리스트를 출력하고 각 항목을 개별적으로 처리하고자 할 때 .{output_port_name}.each를 사용하여 분산(scatter)시킬 수 있습니다. 이후 .{output_port_name}.all()을 사용하여 분산된 항목들의 결과를 하나의 리스트로 집합(gather)할 수 있습니다.
   • Choice Nodes (선택 노드): | 연산자를 사용하여 여러 대안 노드를 정의하고, 런타임에 UI에서 사용자가 선택할 수 있도록 합니다. 모든 대안은 동일한 output ports를 가져야 하지만, input ports는 다를 수 있습니다.

주요 기능 및 특징

• 시각적 캔버스 (Visual Canvas): Python 코드로 workflow를 정의하면, daggr가 이를 해석하여 사용자 친화적인 시각적 인터페이스를 자동으로 생성합니다.
• 상태 보존 및 시트 (Persistence & Sheets): 입력 값, 노드 결과, 캔버스 위치 등 workflow 상태를 자동으로 저장합니다. "시트(sheets)" 기능을 통해 단일 앱 내에서 여러 개의 분리된 작업 공간을 가질 수 있으며, 각 시트는 독립적인 입력 값과 캐시된 결과를 유지합니다.
• 결과 이력 및 Provenance 추적 (Result History & Provenance Tracking): 노드가 실행될 때마다 해당 시점의 모든 입력 값 스냅샷과 함께 결과를 저장합니다.
  • 이전 결과 탐색: 노드 푸터의 화살표를 통해 캐시된 이전 결과를 탐색할 수 있습니다.
  • 자동 입력 복원: 이전 결과를 선택하면, 해당 결과를 생성했던 정확한 입력 값이 자동으로 복원됩니다.
  • 시각적 노후화 지표 (Visual Staleness Indicators): 엣지(edge) 색상으로 workflow의 어떤 부분이 최신(orange)이고 어떤 부분이 노후화(stale, gray)되었는지 시각적으로 보여줍니다. 상위 노드의 값이 변경되거나 하위 노드가 아직 실행되지 않았을 때 엣지가 노후화 상태가 됩니다.
• 배포 (Deployment):
  • 로컬 실행: graph.launch()를 통해 로컬에서 실행하거나, daggr app.py 명령어로 핫 리로딩(hot reloading)을 지원합니다.
  • Hugging Face Spaces 배포: daggr deploy CLI 명령어를 사용하여 workflow를 Hugging Face Spaces에 손쉽게 배포할 수 있습니다. 필요한 의존성, requirements.txt, README.md 등을 자동으로 관리하며, private Space, 하드웨어 티어, 시크릿(secret) 설정 등을 지원합니다.
  • 자동 로컬 실행 (Automatic Local Execution): GradioNode에 $run_locally=True$를 설정하면, daggr가 해당 Gradio Space를 로컬에 클론하고 가상 환경에 의존성을 설치하여 자동으로 실행합니다. 로컬 실행 실패 시 원격 API로 자동 폴백(fallback)하는 기능을 제공합니다.
• API 접근 (API Access): daggr workflow는 REST API를 통해 프로그래밍 방식으로 호출될 수 있습니다. /api/schema 엔드포인트를 통해 workflow의 입력/출력 스키마를 확인하고, /api/call 엔드포인트에 JSON 페이로드로 입력을 POST하여 workflow를 실행할 수 있습니다.
• LLM 친화적 기능 (LLM-Friendly Features):
  • 상세한 에러 메시지: 잘못된 API 엔드포인트, 매개변수 오타, 누락된 필수 매개변수 등 흔한 오류에 대해 상세하고 실행 가능한 에러 메시지를 제공하여 LLM이 코드를 더 쉽게 수정할 수 있도록 돕습니다.
  • .test() 메서드: 각 노드의 .test() 메서드를 사용하여 특정 입력으로 노드를 개별적으로 실행하고 실제 출력 형식을 확인할 수 있습니다. 이는 LLM이 노드의 데이터 흐름과 변환 로직을 이해하는 데 유용합니다.
• Hugging Face 인증 (Authentication): 로컬 Hugging Face 토큰을 자동으로 사용하여 ZeroGPU 할당량 추적, Private Space 접근, Gate 모델 접근 등을 지원합니다.

다른 도구들과의 비교

• ComfyUI: ComfyUI가 시각적 노드 편집기인 반면, daggr는 Python 코드로 workflow를 정의하고 시각적 캔버스를 자동으로 생성하는 코드-퍼스트(code-first) 접근 방식을 취합니다. Gradio Spaces 및 Hugging Face 모델과 직접 연동됩니다.
• Airflow/Prefect: 이들 오케스트레이션 플랫폼이 대규모 파이프라인의 스케줄링, 모니터링, 관리에 초점을 맞추는 것과 달리, daggr는 실시간 시각적 피드백과 즉각적인 실행을 제공하는 대화형 AI/ML workflow에 중점을 둡니다. 프로토타이핑, 데모, 중간 결과 검사 및 개별 단계 재실행에 적합합니다.
• Gradio: Gradio는 단일 ML 모델 또는 데모를 위한 웹 UI를 생성하는 데 사용됩니다. daggr는 여러 Gradio 앱, 커스텀 Python 함수, 그리고 Inference Providers를 투명하고 쉽게 검사할 수 있는 방식으로 연결하여 복잡한 workflow를 구축합니다.