process-gpt-agent-sdk 0.3.10__py3-none-any.whl → 0.3.12__py3-none-any.whl

process_gpt_agent_sdk-0.3.12.dist-info/METADATA

@@ -0,0 +1,410 @@
+Metadata-Version: 2.4
+Name: process-gpt-agent-sdk
+Version: 0.3.12
+Summary: Supabase 기반 이벤트/작업 폴링으로 A2A AgentExecutor를 실행하는 SDK
+License: MIT
+Project-URL: Homepage, https://github.com/your-org/process-gpt-agent-sdk
+Project-URL: Issues, https://github.com/your-org/process-gpt-agent-sdk/issues
+Keywords: agent,a2a,supabase,workflow,sdk,processgpt
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: supabase>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: asyncio-mqtt>=0.13.0
+Requires-Dist: jsonschema>=4.0.0
+Requires-Dist: structlog>=23.0.0
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: python-dateutil>=2.8.0
+Requires-Dist: a2a-sdk==0.3.0
+
+# ProcessGPT Agent Framework
+## A2A SDK 연동을 위한 경량 에이전트 서버 프레임워크
+
+Supabase 기반의 프로세스 작업(Todolist)을 폴링하고, A2A 규격 이벤트를 통해 작업 상태/결과를 기록하는 **경량 에이전트 서버 프레임워크**입니다.
+
+### 📋 요구사항
+- **런타임**: Python 3.9+ (권장: Python 3.11)
+- **데이터베이스**: Supabase (PostgreSQL) + 제공된 RPC/테이블
+- **이벤트 규격**: A2A `TaskStatusUpdateEvent` / `TaskArtifactUpdateEvent`
+
+## 📊 이벤트 타입별 저장 테이블 및 특징
+
+### 1. TaskStatusUpdateEvent (작업 상태 이벤트)
+- **저장 테이블**: `events`
+- **용도**: 작업 진행 상황, 사용자 입력 요청, 에러 알림 등
+- **저장 데이터**: 메시지 래퍼를 제거한 순수 payload만 `data` 컬럼에 JSON으로 저장
+
+```python
+# 예시 코드
+event_queue.enqueue_event(
+    TaskStatusUpdateEvent(
+        status={
+            "state": TaskState.working,  # working, input_required, completed 등
+            "message": new_agent_text_message("진행 중입니다", context_id, task_id),
+        },
+        final=False,
+        contextId=context_id,
+        taskId=task_id,
+        metadata={"event_type": "task_started"}  # events.event_type에 저장
+    )
+)
+```
+
+**특별 규칙**:
+- `state=input_required`일 때는 자동으로 `event_type=human_asked`로 저장됨
+- 메시지는 `new_agent_text_message()` 유틸 함수로 생성
+
+### 2. TaskArtifactUpdateEvent (작업 결과 이벤트)
+- **저장 테이블**: `todolist` (output 컬럼)
+- **용도**: 최종 작업 결과물 전송
+- **저장 데이터**: 아티팩트 래퍼를 제거한 순수 payload만 `output` 컬럼에 JSON으로 저장
+
+```python
+# 예시 코드
+artifact = new_text_artifact(
+    name="처리결과",
+    description="작업 완료 결과",
+    text="실제 결과 데이터"
+)
+event_queue.enqueue_event(
+    TaskArtifactUpdateEvent(
+        artifact=artifact,
+        lastChunk=True,  # 최종 결과면 True
+        contextId=context_id,
+        taskId=task_id,
+    )
+)
+```
+
+**특별 규칙**:
+- `lastChunk=True` 또는 `final=True`일 때만 최종 저장됨 (`p_final=true`)
+- 아티팩트는 `new_text_artifact()` 유틸 함수로 생성
+
+## 🔄 데이터 흐름과 값 전달 방식
+
+### 전체 흐름
+1. **작업 폴링**: 서버가 Supabase `todolist` 테이블에서 새 작업을 가져옴
+2. **컨텍스트 준비**: `RequestContext`에 작업 정보와 사용자 입력을 담음
+3. **익스큐터 실행**: 사용자가 구현한 `AgentExecutor.execute()` 메서드 호출
+4. **이벤트 전송**: 익스큐터에서 진행 상황과 결과를 이벤트로 전송
+5. **데이터 저장**: 이벤트 타입에 따라 적절한 테이블에 저장
+
+### 값 전달 과정
+```python
+# 1. 서버에서 작업 정보 가져오기
+row = context.get_context_data()["row"]  # todolist 테이블의 한 행
+context_id = row.get("root_proc_inst_id") or row.get("proc_inst_id")  # 프로세스 ID
+task_id = row.get("id")  # 작업 ID
+user_input = context.get_user_input()  # 사용자가 입력한 내용
+
+# 2. 메시지/아티팩트 생성시 JSON 문자열로 변환
+payload = {"result": "처리 완료"}
+message_text = json.dumps(payload, ensure_ascii=False)  # 중요: JSON 문자열로!
+
+# 3. 서버가 자동으로 래퍼 제거 후 순수 payload만 저장
+# events.data 또는 todolist.output에 {"result": "처리 완료"}만 저장됨
+```
+
+## 🚀 빠른 시작 가이드
+
+### 1단계: 설치
+```bash
+# 패키지 설치
+pip install -e .
+
+# 또는 requirements.txt 사용
+pip install -r requirements.txt
+```
+
+### 2단계: 환경 설정
+`.env` 파일 생성:
+```env
+SUPABASE_URL=your_supabase_project_url
+SUPABASE_KEY=your_supabase_anon_key
+ENV=dev
+```
+
+### 3단계: 서버 구현 방법
+서버는 이렇게 만드세요:
+
+```python
+# my_server.py
+import asyncio
+from dotenv import load_dotenv
+from processgpt_agent_sdk.processgpt_agent_framework import ProcessGPTAgentServer
+from my_executor import MyExecutor  # 아래에서 구현할 익스큐터
+
+async def main():
+    load_dotenv()
+    
+    server = ProcessGPTAgentServer(
+        agent_executor=MyExecutor(),  # 여러분이 구현할 익스큐터
+        agent_type="my-agent"  # Supabase todolist.agent_orch와 매칭되어야 함
+    )
+    server.polling_interval = 3  # 3초마다 새 작업 확인
+    
+    print("서버 시작!")
+    await server.run()
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        print("서버 종료")
+```
+
+### 4단계: 익스큐터 구현 방법
+익스큐터는 이렇게 만드세요:
+
+```python
+# my_executor.py
+import asyncio
+import json
+from typing_extensions import override
+from a2a.server.agent_execution import AgentExecutor, RequestContext
+from a2a.server.events import EventQueue
+from a2a.types import TaskStatusUpdateEvent, TaskState, TaskArtifactUpdateEvent
+from a2a.utils import new_agent_text_message, new_text_artifact
+
+class MyExecutor(AgentExecutor):
+    @override
+    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
+        # 1. 작업 정보 가져오기
+        row = context.get_context_data()["row"]
+        context_id = row.get("root_proc_inst_id") or row.get("proc_inst_id")
+        task_id = row.get("id")
+        user_input = context.get_user_input()  # 사용자가 입력한 내용
+        
+        print(f"처리할 작업: {user_input}")
+        
+        # 2. 작업 시작 알림 (events 테이블에 저장됨)
+        event_queue.enqueue_event(
+            TaskStatusUpdateEvent(
+                status={
+                    "state": TaskState.working,
+                    "message": new_agent_text_message("작업 시작", context_id, task_id),
+                },
+                final=False,
+                contextId=context_id,
+                taskId=task_id,
+                metadata={"event_type": "task_started"}
+            )
+        )
+        
+        # 3. 실제 작업 수행 (여기에 여러분의 로직 작성)
+        await asyncio.sleep(2)
+        result_data = {"status": "완료", "input": user_input, "output": "처리 결과"}
+        
+        # 4. 최종 결과 전송 (todolist.output에 저장됨)
+        artifact = new_text_artifact(
+            name="처리결과",
+            description="작업 완료 결과",
+            text=json.dumps(result_data, ensure_ascii=False)  # JSON 문자열로!
+        )
+        event_queue.enqueue_event(
+            TaskArtifactUpdateEvent(
+                artifact=artifact,
+                lastChunk=True,  # 중요: 최종 결과면 True
+                contextId=context_id,
+                taskId=task_id,
+            )
+        )
+
+    @override
+    async def cancel(self, context: RequestContext, event_queue: EventQueue) -> None:
+        pass  # 취소 로직 (필요시 구현)
+```
+
+### 5단계: 실행
+```bash
+python my_server.py
+```
+
+## 🤝 Human-in-the-Loop (사용자 입력 요청) 패턴
+
+사용자 입력이 필요할 때:
+
+```python
+# 사용자 입력 요청
+question_data = {
+    "question": "어떤 방식으로 처리할까요?",
+    "options": ["방식A", "방식B", "방식C"]
+}
+
+event_queue.enqueue_event(
+    TaskStatusUpdateEvent(
+        status={
+            "state": TaskState.input_required,  # 이 상태가 중요!
+            "message": new_agent_text_message(
+                json.dumps(question_data, ensure_ascii=False),
+                context_id, task_id
+            ),
+        },
+        final=True,
+        contextId=context_id,
+        taskId=task_id,
+        metadata={"job_id": f"job-{task_id}"}  # job_id 필수
+    )
+)
+# 자동으로 events 테이블에 event_type=human_asked로 저장됨
+```
+
+## 📋 체크리스트 (실패 없는 통합을 위한)
+
+### 필수 설정
+- [ ] `.env`에 `SUPABASE_URL`, `SUPABASE_KEY` 설정
+- [ ] `requirements.txt` 설치 완료
+- [ ] Supabase에서 제공 SQL(`database_schema.sql`, `function.sql`) 적용
+
+### 코드 구현
+- [ ] 서버에서 `agent_type`이 Supabase `todolist.agent_orch`와 매칭됨
+- [ ] 익스큐터에서 `contextId`, `taskId`를 올바르게 설정
+- [ ] 상태 이벤트는 `new_agent_text_message()`로 생성
+- [ ] 최종 결과는 `new_text_artifact()` + `lastChunk=True`로 전송
+- [ ] HITL 요청시 `TaskState.input_required` 사용
+
+## 🚨 자주 발생하는 문제
+
+### 1. 설치 문제
+**증상**: `ModuleNotFoundError`
+```bash
+# 해결
+pip install -e .
+pip install a2a-sdk==0.3.0 --force-reinstall
+```
+
+### 2. 작업이 폴링되지 않음
+**원인**: Supabase 연결 문제
+**해결**:
+- `.env` 파일 위치 확인 (프로젝트 루트)
+- URL/Key 재확인
+- `agent_type`이 todolist.agent_orch와 매칭되는지 확인
+
+### 3. 이벤트가 저장되지 않음
+**원인**: 테이블/함수 누락
+**해결**:
+- `database_schema.sql`, `function.sql` 실행 확인
+- Supabase 테이블 권한 확인
+
+### 4. 결과가 래퍼와 함께 저장됨
+**원인**: JSON 문자열 변환 누락
+```python
+# 올바른 방법
+text=json.dumps(data, ensure_ascii=False)  # JSON 문자열로!
+
+# 잘못된 방법  
+text=data  # 딕셔너리 직접 전달 (X)
+```
+
+## 📚 샘플 코드 (간단 버전)
+
+### 기본 서버
+```python
+# sample_server/minimal_server.py
+import asyncio
+from dotenv import load_dotenv
+from processgpt_agent_sdk.processgpt_agent_framework import ProcessGPTAgentServer
+from sample_server.minimal_executor import MinimalExecutor
+
+async def main():
+    load_dotenv()
+    server = ProcessGPTAgentServer(
+        agent_executor=MinimalExecutor(), 
+        agent_type="crewai-action"
+    )
+    server.polling_interval = 3
+    await server.run()
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        pass
+```
+
+### 기본 익스큐터  
+```python
+# sample_server/minimal_executor.py
+import asyncio
+import json
+from typing_extensions import override
+from a2a.server.agent_execution import AgentExecutor, RequestContext
+from a2a.server.events import EventQueue
+from a2a.types import TaskStatusUpdateEvent, TaskState, TaskArtifactUpdateEvent
+from a2a.utils import new_agent_text_message, new_text_artifact
+
+class MinimalExecutor(AgentExecutor):
+    @override
+    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
+        row = context.get_context_data()["row"]
+        context_id = row.get("root_proc_inst_id") or row.get("proc_inst_id")
+        task_id = row.get("id")
+        user_input = context.get_user_input()
+
+        # 진행 상태
+        event_queue.enqueue_event(
+            TaskStatusUpdateEvent(
+                status={
+                    "state": TaskState.working,
+                    "message": new_agent_text_message("처리중", context_id, task_id),
+                },
+                final=False,
+                contextId=context_id,
+                taskId=task_id,
+                metadata={"event_type": "task_started"}
+            )
+        )
+
+        await asyncio.sleep(1)
+
+        # 최종 결과
+        result = {"input": user_input, "output": "처리 완료"}
+        artifact = new_text_artifact(
+            name="결과",
+            description="처리 결과",
+            text=json.dumps(result, ensure_ascii=False)
+        )
+        event_queue.enqueue_event(
+            TaskArtifactUpdateEvent(
+                artifact=artifact,
+                lastChunk=True,
+                contextId=context_id,
+                taskId=task_id,
+            )
+        )
+
+    @override
+    async def cancel(self, context: RequestContext, event_queue: EventQueue) -> None:
+        pass
+```
+
+## 🔧 실행 방법
+
+### 개발 환경에서 실행
+```bash
+python sample_server/minimal_server.py
+```
+
+### 실제 사용시
+```bash
+python my_server.py
+```
+
+---
+
+## 📚 레퍼런스
+
+### 주요 함수들
+- `ProcessGPTAgentServer.run()`: 서버 시작
+- `new_agent_text_message(text, context_id, task_id)`: 상태 메시지 생성
+- `new_text_artifact(name, desc, text)`: 결과 아티팩트 생성
+
+### 이벤트 저장 규칙
+- **TaskStatusUpdateEvent** → `events` 테이블 (`data` 컬럼)
+- **TaskArtifactUpdateEvent** → `todolist` 테이블 (`output` 컬럼)
+- 래퍼 자동 제거 후 순수 payload만 저장

process_gpt_agent_sdk-0.3.12.dist-info/RECORD

@@ -0,0 +1,6 @@
+processgpt_agent_sdk/database.py,sha256=k219S54XwQoGJcKYq6Zr0f7j-Dtrp-v7SpLMRnIgHCI,18979
+processgpt_agent_sdk/processgpt_agent_framework.py,sha256=YE5JB4TyRkYFYxRMRfo-SyXb5JuFZwaNtNaxFNd9PXA,16894
+process_gpt_agent_sdk-0.3.12.dist-info/METADATA,sha256=x5kNRsZ9J0jaCmYmWEhQiuDeiXqH_vgjaDkZ8jizLSE,13600
+process_gpt_agent_sdk-0.3.12.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+process_gpt_agent_sdk-0.3.12.dist-info/top_level.txt,sha256=Xe6zrj3_3Vv7d0pl5RRtenVUckwOVBVLQn2P03j5REo,21
+process_gpt_agent_sdk-0.3.12.dist-info/RECORD,,

processgpt_agent_sdk/database.py

@@ -0,0 +1,537 @@
+import os
+import json
+import asyncio
+import socket
+import uuid
+from typing import Any, Dict, List, Optional, Tuple, Callable, TypeVar
+
+from dotenv import load_dotenv
+from supabase import Client, create_client
+import logging
+import random
+
+T = TypeVar("T")
+
+
+# 모듈 전역 로거 (정상 경로는 로깅하지 않고, 오류 시에만 사용)
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# Utility: 재시도 헬퍼 및 유틸
+# 설명: 동기 DB 호출을 안전하게 재시도 (지수 백오프 + 지터) 및 유틸
+# ============================================================================
+
+async def _async_retry(
+    fn: Callable[[], T],
+    *,
+    name: str,
+    retries: int = 3,
+    base_delay: float = 0.8,
+    fallback: Optional[Callable[[], T]] = None,
+) -> Optional[T]:
+    """지수 백오프+jitter로 재시도하고 실패 시 fallback/None 반환."""
+    last_err: Optional[Exception] = None
+    for attempt in range(1, retries + 1):
+        try:
+            return await asyncio.to_thread(fn)
+        except Exception as e:
+            last_err = e
+            jitter = random.uniform(0, 0.3)
+            delay = base_delay * (2 ** (attempt - 1)) + jitter
+            await asyncio.sleep(delay)
+    if last_err is not None:
+        logger.error(
+            "retry failed: name=%s retries=%s error=%s", name, retries, str(last_err),
+            exc_info=last_err,
+        )
+    if fallback is not None:
+        try:
+            fb_val = fallback()
+            return fb_val
+        except Exception as fb_err:
+            logger.error("fallback failed: name=%s error=%s", name, str(fb_err), exc_info=fb_err)
+            return None
+    return None
+ 
+
+def _is_valid_uuid(value: str) -> bool:
+    """UUID 문자열 형식 검증 (v1~v8 포함)"""
+    try:
+        uuid.UUID(value)
+        return True
+    except Exception:
+        return False
+        
+def _to_jsonable(value: Any) -> Any:
+    """간단한 JSON 변환: dict 재귀, list/tuple/set→list, 기본형 유지, 나머지는 repr."""
+    try:
+        if value is None or isinstance(value, (str, int, float, bool)):
+            return value
+        if isinstance(value, dict):
+            return {str(k): _to_jsonable(v) for k, v in value.items()}
+        if isinstance(value, (list, tuple, set)):
+            return [_to_jsonable(v) for v in list(value)]
+        if hasattr(value, "__dict__"):
+            return _to_jsonable(vars(value))
+        return repr(value)
+    except Exception:
+        return repr(value)
+
+
+# ============================================================================
+# DB 연결/클라이언트
+# 설명: 환경 변수 로드, Supabase 클라이언트 초기화/반환, 컨슈머 식별자
+# ============================================================================
+_supabase_client: Optional[Client] = None
+
+
+def initialize_db() -> None:
+    """환경변수 로드 및 Supabase 클라이언트 초기화"""
+    global _supabase_client
+    if _supabase_client is not None:
+        return
+    try:
+        if os.getenv("ENV") != "production":
+            load_dotenv()
+        supabase_url = os.getenv("SUPABASE_URL") or os.getenv("SUPABASE_KEY_URL")
+        supabase_key = os.getenv("SUPABASE_KEY") or os.getenv("SUPABASE_ANON_KEY")
+        if not supabase_url or not supabase_key:
+            raise RuntimeError("SUPABASE_URL 및 SUPABASE_KEY가 필요합니다")
+        _supabase_client = create_client(supabase_url, supabase_key)
+    except Exception as e:
+        logger.error("initialize_db failed: %s", str(e), exc_info=e)
+        raise
+
+
+def get_db_client() -> Client:
+    """초기화된 Supabase 클라이언트 반환."""
+    if _supabase_client is None:
+        raise RuntimeError("DB 미초기화: initialize_db() 먼저 호출")
+    return _supabase_client
+
+
+def get_consumer_id() -> str:
+    """파드/프로세스 식별자 생성(CONSUMER_ID>HOST:PID)."""
+    env_consumer = os.getenv("CONSUMER_ID")
+    if env_consumer:
+        return env_consumer
+    host = socket.gethostname()
+    pid = os.getpid()
+    return f"{host}:{pid}"
+
+
+# ============================================================================
+# 데이터 조회
+# 설명: TODOLIST 테이블 조회, 완료 output 목록 조회, 이벤트 조회, 폼 조회, 테넌트 MCP 설정 조회, 사용자 및 에이전트 조회
+# ============================================================================
+async def polling_pending_todos(agent_orch: str, consumer: str) -> Optional[Dict[str, Any]]:
+    """TODOLIST 테이블에서 대기중인 워크아이템을 조회 (agent_orch 전달).
+
+    - 정상 동작 시 로그를 남기지 않는다.
+    - 예외 시에만 풍부한 에러 정보를 남기되, 호출자에게 None을 반환하여 폴링 루프가 중단되지 않게 한다.
+    """
+    if agent_orch is None:
+        agent_orch = ""
+    if consumer is None:
+        consumer = ""
+
+    def _call():
+        client = get_db_client()
+        consumer_id = consumer or socket.gethostname()
+        env = (os.getenv("ENV") or "").lower()
+
+        if env == "dev":
+            resp = client.rpc(
+                "fetch_pending_task_dev",
+                {"p_agent_orch": agent_orch, "p_consumer": consumer_id, "p_limit": 1, "p_tenant_id": "uengine"},
+            ).execute()
+        else:
+            resp = client.rpc(
+                "fetch_pending_task",
+                {"p_agent_orch": agent_orch, "p_consumer": consumer_id, "p_limit": 1},
+            ).execute()
+
+        rows = resp.data or []
+        return rows[0] if rows else None
+
+    return await _async_retry(_call, name="polling_pending_todos", fallback=lambda: None)
+
+
+def fetch_human_response_sync(job_id: str) -> Optional[Dict[str, Any]]:
+    """events에서 특정 job_id의 human_response 조회"""
+    if not job_id:
+        return None
+    try:
+        client = get_db_client()
+        resp = (
+            client
+            .table("events")
+            .select("*")
+            .eq("job_id", job_id)
+            .eq("event_type", "human_response")
+            .execute()
+        )
+        rows = resp.data or []
+        return rows[0] if rows else None
+    except Exception as e:
+        logger.error("fetch_human_response_sync failed: %s", str(e), exc_info=e)
+        return None
+
+
+async def fetch_task_status(todo_id: str) -> Optional[str]:
+    """todo의 draft_status를 조회한다."""
+    if not todo_id:
+        return None
+    def _call():
+        client = get_db_client()
+        return (
+            client.table("todolist").select("draft_status").eq("id", todo_id).single().execute()
+        )
+
+    try:
+        resp = await _async_retry(_call, name="fetch_task_status")
+    except Exception as e:
+        logger.error("fetch_task_status fatal: %s", str(e), exc_info=e)
+        return None
+    if not resp or not getattr(resp, "data", None):
+        return None
+    try:
+        return resp.data.get("draft_status")
+    except Exception as e:
+        logger.error("fetch_task_status parse error: %s", str(e), exc_info=e)
+        return None
+
+
+
+async def fetch_all_agents() -> List[Dict[str, Any]]:
+    """모든 에이전트 목록을 정규화하여 반환한다."""
+    def _call():
+        client = get_db_client()
+        return (
+            client.table("users")
+            .select("id, username, role, goal, persona, tools, profile, model, tenant_id, is_agent")
+            .eq("is_agent", True)
+            .execute()
+        )
+
+    try:
+        resp = await _async_retry(_call, name="fetch_all_agents")
+    except Exception as e:
+        logger.error("fetch_all_agents fatal: %s", str(e), exc_info=e)
+        return []
+    rows = resp.data or [] if resp else []
+    try:
+        normalized: List[Dict[str, Any]] = []
+        for row in rows:
+            normalized.append(
+                {
+                    "id": row.get("id"),
+                    "name": row.get("username"),
+                    "role": row.get("role"),
+                    "goal": row.get("goal"),
+                    "persona": row.get("persona"),
+                    "tools": row.get("tools") or "mem0",
+                    "profile": row.get("profile"),
+                    "model": row.get("model"),
+                    "tenant_id": row.get("tenant_id"),
+                    "endpoint": row.get("endpoint"),
+                }
+            )
+        return normalized
+    except Exception as e:
+        logger.error("fetch_all_agents parse error: %s", str(e), exc_info=e)
+        return []
+
+
+async def fetch_agent_data(user_ids: str) -> List[Dict[str, Any]]:
+    """TODOLIST의 user_id 값으로, 역할로 지정된 에이전트를 조회하고 정규화해 반환한다."""
+
+    raw_ids = [x.strip() for x in (user_ids or "").split(",") if x.strip()]
+    valid_ids = [x for x in raw_ids if _is_valid_uuid(x)]
+
+    if not valid_ids:
+        return await fetch_all_agents()
+
+    def _call():
+        client = get_db_client()
+        resp = (
+            client
+            .table("users")
+            .select("id, username, role, goal, persona, tools, profile, model, tenant_id, is_agent")
+            .in_("id", valid_ids)
+            .eq("is_agent", True)
+            .execute()
+        )
+        rows = resp.data or []
+        normalized: List[Dict[str, Any]] = []
+        for row in rows:
+            normalized.append(
+                {
+                    "id": row.get("id"),
+                    "name": row.get("username"),
+                    "role": row.get("role"),
+                    "goal": row.get("goal"),
+                    "persona": row.get("persona"),
+                    "tools": row.get("tools") or "mem0",
+                    "profile": row.get("profile"),
+                    "model": row.get("model"),
+                    "tenant_id": row.get("tenant_id"),
+                    "endpoint": row.get("endpoint"),
+                }
+            )
+        return normalized
+
+    try:
+        result = await _async_retry(_call, name="fetch_agent_data", fallback=lambda: [])
+    except Exception as e:
+        logger.error("fetch_agent_data fatal: %s", str(e), exc_info=e)
+        return await fetch_all_agents()
+
+    if not result:
+        return await fetch_all_agents()
+
+    return result
+
+
+async def fetch_form_types(tool_val: str, tenant_id: str) -> Tuple[str, List[Dict[str, Any]], Optional[str]]:
+    """폼 타입 정의를 조회해 (form_id, fields, html)로 반환한다."""
+    if tool_val is None:
+        tool_val = ""
+    if tenant_id is None:
+        tenant_id = ""
+    form_id = tool_val[12:] if tool_val.startswith("formHandler:") else tool_val
+
+    def _call():
+        client = get_db_client()
+        resp = (
+            client
+            .table("form_def")
+            .select("fields_json, html")
+            .eq("id", form_id)
+            .eq("tenant_id", tenant_id)
+            .execute()
+        )
+        fields_json = resp.data[0].get("fields_json") if resp.data else None
+        form_html = resp.data[0].get("html") if resp.data else None
+        if not fields_json:
+            return form_id, [{"key": form_id, "type": "default", "text": ""}], form_html
+        return form_id, fields_json, form_html
+
+    try:
+        resp = await _async_retry(
+            _call,
+            name="fetch_form_types",
+            fallback=lambda: (form_id, [{"key": form_id, "type": "default", "text": ""}], None),
+        )
+    except Exception as e:
+        logger.error("fetch_form_types fatal: %s", str(e), exc_info=e)
+        resp = None
+    return resp if resp else (form_id, [{"key": form_id, "type": "default", "text": ""}], None)
+
+
+async def fetch_tenant_mcp_config(tenant_id: str) -> Optional[Dict[str, Any]]:
+    """테넌트 MCP 설정을 조회해 반환한다."""
+    if not tenant_id:
+        return None
+    def _call():
+        client = get_db_client()
+        return client.table("tenants").select("mcp").eq("id", tenant_id).single().execute()
+
+    try:
+        resp = await _async_retry(_call, name="fetch_tenant_mcp_config", fallback=lambda: None)
+    except Exception as e:
+        logger.error("fetch_tenant_mcp_config fatal: %s", str(e), exc_info=e)
+        return None
+    return resp.data.get("mcp") if resp and getattr(resp, "data", None) else None
+
+
+async def fetch_human_users_by_proc_inst_id(proc_inst_id: str) -> str:
+    """proc_inst_id로 현재 프로세스의 모든 사용자 이메일 목록을 쉼표로 반환한다."""
+    if not proc_inst_id:
+        return ""
+    
+    def _sync():
+        try:
+            supabase = get_db_client()
+            
+            resp = (
+                supabase
+                .table('todolist')
+                .select('user_id')
+                .eq('proc_inst_id', proc_inst_id)
+                .execute()
+            )
+            
+            if not resp.data:
+                return ""
+            
+            all_user_ids = set()
+            for row in resp.data:
+                user_id = row.get('user_id', '')
+                if user_id:
+                    ids = [id.strip() for id in user_id.split(',') if id.strip()]
+                    all_user_ids.update(ids)
+            
+            if not all_user_ids:
+                return ""
+            
+            human_user_emails = []
+            for user_id in all_user_ids:
+                if not _is_valid_uuid(user_id):
+                    continue
+                
+                user_resp = (
+                    supabase
+                    .table('users')
+                    .select('id, email, is_agent')
+                    .eq('id', user_id)
+                    .execute()
+                )
+                
+                if user_resp.data:
+                    user = user_resp.data[0]
+                    is_agent = user.get('is_agent')
+                    if not is_agent:
+                        email = (user.get('email') or '').strip()
+                        if email:
+                            human_user_emails.append(email)
+            
+            return ','.join(human_user_emails)
+            
+        except Exception as e:
+            logger.error("fetch_human_users_by_proc_inst_id failed: %s", str(e), exc_info=e)
+            return ""
+    
+    return await asyncio.to_thread(_sync)
+
+
+# ============================================================================
+# 데이터 저장
+# 설명: 이벤트/알림/작업 결과 저장
+# ============================================================================
+async def record_event(payload: Dict[str, Any]) -> None:
+    """UI용 events 테이블에 이벤트 기록 (전달된 payload 그대로 저장)"""
+    if payload is None:
+        logger.error("record_event invalid payload: None")
+        return
+    def _call():
+        client = get_db_client()
+        safe_payload = _to_jsonable(payload)
+        # 상태값이 빈 문자열이면 NULL로
+        if isinstance(safe_payload, dict):
+            status_val = safe_payload.get("status")
+            if status_val == "":
+                safe_payload["status"] = None
+        return client.table("events").insert(safe_payload).execute()
+
+    try:
+        resp = await _async_retry(_call, name="record_event", fallback=lambda: None)
+    except Exception as e:
+        try:
+            logger.error("record_event fatal: %s payload=%s", str(e), json.dumps(_to_jsonable(payload), ensure_ascii=False), exc_info=e)
+        except Exception:
+            logger.error("record_event fatal (payload dump failed): %s", str(e), exc_info=e)
+        return
+    if resp is None:
+        try:
+            logger.error("events insert 실패: payload=%s", json.dumps(_to_jsonable(payload), ensure_ascii=False))
+        except Exception:
+            logger.error("events insert 실패 (payload dump failed)")
+
+
+
+async def save_task_result(todo_id: str, result: Any, final: bool = False) -> None:
+    """작업 결과를 저장한다. final=True 시 최종 저장."""
+    if not todo_id:
+        logger.error("save_task_result invalid todo_id: %s", str(todo_id))
+        return
+    # 안전한 직렬화: 실패 시 문자열화하여 저장자가 원인 파악 가능
+    def _safe_payload(val: Any) -> Any:
+        try:
+            return _to_jsonable(val)
+        except Exception as e:
+            logger.error("save_task_result payload serialization failed: %s", str(e), exc_info=e)
+            try:
+                return {"repr": repr(val)}
+            except Exception:
+                return {"error": "unserializable payload"}
+
+    def _call():
+        client = get_db_client()
+        payload = _safe_payload(result)
+        return client.rpc(
+            "save_task_result",
+            {"p_todo_id": todo_id, "p_payload": payload, "p_final": bool(final)},
+        ).execute()
+
+    try:
+        await _async_retry(_call, name="save_task_result", fallback=lambda: None)
+    except Exception as e:
+        logger.error("save_task_result fatal: %s", str(e), exc_info=e)
+
+
+def save_notification(
+    *,
+    title: str,
+    notif_type: str,
+    description: Optional[str] = None,
+    user_ids_csv: Optional[str] = None,
+    tenant_id: Optional[str] = None,
+    url: Optional[str] = None,
+    from_user_id: Optional[str] = None,
+) -> None:
+    """notifications 테이블에 알림 저장"""
+    try:
+        # 대상 사용자가 없으면 작업 생략
+        if not user_ids_csv:
+            return
+
+        client = get_db_client()
+
+        user_ids: List[str] = [uid.strip() for uid in user_ids_csv.split(',') if uid and uid.strip()]
+        if not user_ids:
+            return
+        
+        rows: List[Dict[str, Any]] = []
+        for uid in user_ids:
+            rows.append(
+                {
+                    "id": str(uuid.uuid4()),
+                    "user_id": uid,
+                    "tenant_id": tenant_id,
+                    "title": title,
+                    "description": description,
+                    "type": notif_type,
+                    "url": url,
+                    "from_user_id": from_user_id,
+                }
+            )
+
+        client.table("notifications").insert(rows).execute()
+    except Exception as e:
+        logger.error("save_notification failed: %s", str(e), exc_info=e)
+
+# ============================================================================
+# 상태 변경
+# 설명: 실패 작업 상태 업데이트
+# ============================================================================
+
+async def update_task_error(todo_id: str) -> None:
+    """실패 작업의 상태를 FAILED로 갱신한다."""
+    if not todo_id:
+        return
+    def _call():
+        client = get_db_client()
+        return (
+            client
+            .table('todolist')
+            .update({'draft_status': 'FAILED', 'consumer': None})
+            .eq('id', todo_id)
+            .execute()
+        )
+
+    try:
+        await _async_retry(_call, name="update_task_error", fallback=lambda: None)
+    except Exception as e:
+        logger.error("update_task_error fatal: %s", str(e), exc_info=e)

processgpt_agent_sdk/processgpt_agent_framework.py

@@ -17,7 +17,7 @@ from a2a.types import (
 )
 
 # DB 어댑터 사용
-from database import (
+from .database import (
     initialize_db,
     polling_pending_todos,
     record_event,

process_gpt_agent_sdk-0.3.10.dist-info/METADATA

@@ -1,336 +0,0 @@
-Metadata-Version: 2.4
-Name: process-gpt-agent-sdk
-Version: 0.3.10
-Summary: Supabase 기반 이벤트/작업 폴링으로 A2A AgentExecutor를 실행하는 SDK
-License: MIT
-Project-URL: Homepage, https://github.com/your-org/process-gpt-agent-sdk
-Project-URL: Issues, https://github.com/your-org/process-gpt-agent-sdk/issues
-Keywords: agent,a2a,supabase,workflow,sdk,processgpt
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-Requires-Dist: supabase>=2.0.0
-Requires-Dist: python-dotenv>=1.0.0
-Requires-Dist: click>=8.0.0
-Requires-Dist: asyncio-mqtt>=0.13.0
-Requires-Dist: jsonschema>=4.0.0
-Requires-Dist: structlog>=23.0.0
-Requires-Dist: typing-extensions>=4.0.0
-Requires-Dist: python-dateutil>=2.8.0
-Requires-Dist: a2a-sdk==0.3.0
-
-# ProcessGPT Agent Framework (A2A SDK 연동 가이드)
-
-이 저장소는 Supabase 기반의 프로세스 작업(Todolist)을 폴링하고, A2A 규격 이벤트를 통해 작업 상태/결과를 기록하는 **경량 에이전트 서버 프레임워크**입니다. 최소 구현으로 빠르게 통합하고, 필요하면 커스터마이즈할 수 있습니다.
-
-- 런타임: Python 3.10+
-- 저장소 의존: Supabase(Postgres) + 제공된 RPC/테이블
-- 이벤트 규격: A2A `TaskStatusUpdateEvent` / `TaskArtifactUpdateEvent`
-
-
-## 아키텍처 한눈에 보기
-```mermaid
-flowchart LR
-    subgraph Supabase
-      A[Todolist] --- B[Events]
-      A -.RPC.-> C[(save_task_result)]
-      D[(fetch_pending_task)] --> A
-    end
-
-    subgraph Agent Server
-      E[ProcessGPTAgentServer] -->|polls| D
-      E --> F[ProcessGPTRequestContext]
-      E --> G[ProcessGPTEventQueue]
-      H[Your AgentExecutor]
-      F --> H
-      H -->|A2A Events| G
-    end
-
-    G -->|TaskStatusUpdateEvent| B
-    G -->|TaskArtifactUpdateEvent| A
-```
-
-- 서버는 주기적으로 Todolist를 폴링하여 새 작업을 가져옵니다.
-- 사용자 구현 `AgentExecutor`가 요청을 처리하고, A2A 이벤트를 큐에 전달합니다.
-- 이벤트 큐는 상태 이벤트를 `events` 테이블에, 아티팩트 이벤트를 `todolist.output`에 저장합니다.
-
-
-## 엔드-투-엔드 시퀀스(정상 흐름)
-```mermaid
-sequenceDiagram
-    participant SB as Supabase
-    participant SRV as ProcessGPTAgentServer
-    participant CTX as RequestContext
-    participant EXE as Your AgentExecutor
-    participant EQ as ProcessGPTEventQueue
-
-    SRV->>SB: RPC fetch_pending_task
-    SB-->>SRV: todolist row
-    SRV->>CTX: prepare_context()
-    SRV->>EXE: execute(context, event_queue)
-    EXE->>EQ: TaskStatusUpdateEvent (state=working)
-    EQ->>SB: INSERT events (data=payload)
-    EXE->>EQ: TaskArtifactUpdateEvent (lastChunk=true, artifact)
-    EQ->>SB: RPC save_task_result (output=payload, p_final=true)
-    SRV->>EQ: task_done()
-    EQ->>SB: INSERT events (crew_completed)
-```
-
-
-## Human-in-the-loop(HITL) 시퀀스
-```mermaid
-sequenceDiagram
-    participant EXE as Your AgentExecutor
-    participant EQ as ProcessGPTEventQueue
-    participant SB as Supabase
-    participant UI as Operator UI
-
-    EXE->>EQ: TaskStatusUpdateEvent (state=input_required)
-    Note right of EXE: event_type 전송 생략 가능
-    EQ->>SB: INSERT events (event_type=human_asked, data=질문 payload)
-    UI->>SB: INSERT events (event_type=human_response, data=사용자 응답)
-    EXE-->>SB: 선택: fetch_human_response_sync(job_id)
-```
-
-
-## 친절한 시작 가이드(5분 컷)
-1) 가상환경 + 설치
-```bash
-uv venv --python 3.11.9
-uv pip install -r requirements.txt
-source .venv/Scripts/activate
-```
-
-2) .env 준비
-- SUPABASE_URL, SUPABASE_KEY 필수
-- ENV=dev (개발 환경에서 권장)
-
-3) 샘플 서버 실행
-```bash
-python sample_server/minimal_server.py | cat
-```
-
-4) 이벤트 전송 패턴 이해
-- 진행 상태: `TaskStatusUpdateEvent(state=working)` + `new_agent_text_message(text, contextId, taskId)`
-- 사용자 입력 요청(HITL): `TaskState.input_required`만 보내면 event_type은 자동 `human_asked`
-- 결과물: `TaskArtifactUpdateEvent(lastChunk=True)` + `new_text_artifact(name, desc, text)`
-
-5) 저장물 확인 포인트
-- `events` 테이블: data에는 래퍼 제거된 순수 payload 저장
-- `todolist.output`: 순수 payload 저장, 최종 청크면 `p_final=true`
-
-
-## 샘플 서버 실행 코드 (친절 버전)
-### A. 가장 간단한 서버(minimal)
-```python
-# sample_server/minimal_server.py
-import os
-import sys
-import asyncio
-from dotenv import load_dotenv
-
-# 패키지 루트 경로 추가 (샘플에서만)
-sys.path.append(os.path.dirname(os.path.dirname(__file__)))
-
-from processgpt_agent_sdk.processgpt_agent_framework import ProcessGPTAgentServer
-from sample_server.minimal_executor import MinimalExecutor
-
-async def main():
-    load_dotenv()
-    # agent_type은 Supabase의 todolist.agent_orch와 매칭되어야 함
-    server = ProcessGPTAgentServer(agent_executor=MinimalExecutor(), agent_type="crewai-action")
-    server.polling_interval = 3  # 초
-    await server.run()
-
-if __name__ == "__main__":
-    try:
-        asyncio.run(main())
-    except KeyboardInterrupt:
-        pass
-```
-
-- Windows
-```bash
-python sample_server/minimal_server.py
-```
-- macOS/Linux
-```bash
-python3 sample_server/minimal_server.py
-```
-
-### B. CLI 옵션이 있는 서버 예시
-```python
-# sample_server/crew_ai_dr_agent_server.py
-import os
-import sys
-import asyncio
-import click
-from dotenv import load_dotenv
-
-# 패키지 루트 경로 추가 (샘플에서만)
-sys.path.append(os.path.dirname(os.path.dirname(__file__)))
-
-from processgpt_agent_sdk.processgpt_agent_framework import ProcessGPTAgentServer
-from sample_server.crew_ai_dr_agent_executor import CrewAIDeepResearchAgentExecutor
-
-load_dotenv()
-
-@click.command()
-@click.option('--agent-type', default='crew-ai-dr', help='Agent type identifier')
-@click.option('--polling-interval', default=5, help='Polling interval in seconds')
-def cli_main(agent_type: str, polling_interval: int):
-    """ProcessGPT Agent Server for CrewAI Deep Research Agent"""
-
-    agent_executor = CrewAIDeepResearchAgentExecutor()
-    server = ProcessGPTAgentServer(agent_executor=agent_executor, agent_type=agent_type)
-    server.polling_interval = polling_interval
-
-    print(f"Starting ProcessGPT Agent Server...")
-    print(f"Agent Type: {agent_type}")
-    print(f"Polling Interval: {polling_interval} seconds")
-    print("Press Ctrl+C to stop")
-
-    try:
-        asyncio.run(server.run())
-    except KeyboardInterrupt:
-        print("\nShutting down server...")
-        server.stop()
-    except Exception as e:
-        print(f"Server error: {e}")
-        sys.exit(1)
-
-if __name__ == "__main__":
-    cli_main()
-```
-
-- 실행
-  - Windows
-    ```bash
-    python sample_server/crew_ai_dr_agent_server.py --agent-type crew-ai-dr --polling-interval 3
-    ```
-  - macOS/Linux
-    ```bash
-    python3 sample_server/crew_ai_dr_agent_server.py --agent-type crew-ai-dr --polling-interval 3
-    ```
-
-
-## 최소 예시(익스큐터)
-```python
-# sample_server/minimal_executor.py (요약)
-import asyncio
-import json
-from typing_extensions import override
-from a2a.server.agent_execution import AgentExecutor, RequestContext
-from a2a.server.events import EventQueue
-from a2a.types import TaskStatusUpdateEvent, TaskState, TaskArtifactUpdateEvent
-from a2a.utils import new_agent_text_message, new_text_artifact
-
-class MinimalExecutor(AgentExecutor):
-    @override
-    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
-        row = context.get_context_data()["row"]
-        context_id = row.get("root_proc_inst_id") or row.get("proc_inst_id")
-        task_id = row.get("id")
-
-        payload = {"order_process_activity_order_request_form": {"orderer_name": "안치윤","product_name": "금형세트","order_quantity": "50"}}
-
-        # 1) 진행 상태 이벤트
-        event_queue.enqueue_event(
-            TaskStatusUpdateEvent(
-                status={
-                    "state": TaskState.working,
-                    "message": new_agent_text_message(
-                        json.dumps(payload, ensure_ascii=False),
-                        context_id,
-                        task_id,
-                    ),
-                },
-                final=False,
-                contextId=context_id,
-                taskId=task_id,
-                metadata={"crew_type": "action", "event_type": "task_started", "job_id": "job-demo-0001"},
-            )
-        )
-
-        await asyncio.sleep(0.1)
-
-        # 2) HITL: 사용자 입력 요청 (event_type 생략해도 자동 human_asked)
-        event_queue.enqueue_event(
-            TaskStatusUpdateEvent(
-                status={
-                    "state": TaskState.input_required,
-                    "message": new_agent_text_message(
-                        json.dumps(payload, ensure_ascii=False),
-                        context_id,
-                        task_id,
-                    ),
-                },
-                final=True,
-                contextId=context_id,
-                taskId=task_id,
-                metadata={"crew_type": "action", "job_id": "job-demo-0001"},
-            )
-        )
-
-        await asyncio.sleep(0.1)
-
-        # 3) 최종 아티팩트
-        artifact = new_text_artifact(
-            name="current_result",
-            description="Result of request to agent.",
-            text=json.dumps(payload, ensure_ascii=False),
-        )
-        event_queue.enqueue_event(
-            TaskArtifactUpdateEvent(
-                artifact=artifact,
-                lastChunk=True,
-                contextId=context_id,
-                taskId=task_id,
-            )
-        )
-```
-
-
-## 서버가 해주는 일(정확한 규칙)
-- 메시지/아티팩트 래퍼 제거 → `parts[0].text|content|data` → `root.*` → `top-level` 순서로 텍스트만 추출 후 JSON 파싱하여 저장
-- `TaskStatusUpdateEvent` 수신 시
-  - `status.state == input_required`면 `event_type=human_asked`로 저장(명시값보다 우선)
-  - 그 외 상태는 `metadata.event_type` 저장(없으면 NULL)
-- `TaskArtifactUpdateEvent` 수신 시
-  - `final` 또는 `lastChunk`가 참이면 최종 저장(`p_final=true`)
-
-
-## 체크리스트(실패 없는 통합을 위한)
-- [ ] .env에 `SUPABASE_URL`, `SUPABASE_KEY` 설정했는가?
-- [ ] `requirements.txt` 설치 완료했는가?
-- [ ] Supabase에서 제공 SQL(`database_schema.sql`, `function.sql`) 적용했는가?
-- [ ] 익스큐터에서 `contextId`, `taskId`를 todolist의 `proc_inst_id`, `id`로 매핑했는가?
-- [ ] 상태 이벤트는 `new_agent_text_message`로 만들고 있는가?
-- [ ] 최종 아티팩트는 `new_text_artifact` + `lastChunk=True`로 보내고 있는가?
-- [ ] HITL 요청은 `TaskState.input_required`만 보내고 있는가?(event_type 생략 가능)
-
-
-## 트러블슈팅
-- 이벤트 미기록
-  - Supabase URL/Key 재확인, 테이블/권한 확인
-- 최종 아티팩트가 최종으로 저장되지 않음
-  - 익스큐터에서 `lastChunk=True` 또는 `final=True`로 보냈는지 확인
-- payload가 래퍼와 같이 저장됨
-  - 메시지에 `parts[0].text` 또는 `parts[0].root.text`에 JSON 문자열이 들어있는지 확인
-- 휴먼인더루프 이벤트 타입 미지정
-  - `input_required` 상태면 자동 `human_asked`로 저장됨
-
-
-## 레퍼런스
-- 이벤트 유틸: `new_agent_text_message`, `new_text_artifact`
-- 서버 진입점: `ProcessGPTAgentServer.run()`
-- 컨텍스트 확장: `ProcessGPTRequestContext.prepare_context()`
-- 이벤트 저장: `ProcessGPTEventQueue.enqueue_event(event)` → `database.record_event`/`save_task_result`
-- 휴먼 응답 조회: `database.fetch_human_response_sync(job_id)`
-
-
-## 라이선스
-해당 저장소의 라이선스 정책을 따릅니다.

process_gpt_agent_sdk-0.3.10.dist-info/RECORD

@@ -1,5 +0,0 @@
-processgpt_agent_sdk/processgpt_agent_framework.py,sha256=rTX9K-S6G_ZyzGUfIQClmJpoARqT4I51HicNw3i4y4g,16893
-process_gpt_agent_sdk-0.3.10.dist-info/METADATA,sha256=DtoEEh--giyvPQ2tHbD3tqs_9bzbducSHSGHTj9-bSE,12201
-process_gpt_agent_sdk-0.3.10.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-process_gpt_agent_sdk-0.3.10.dist-info/top_level.txt,sha256=Xe6zrj3_3Vv7d0pl5RRtenVUckwOVBVLQn2P03j5REo,21
-process_gpt_agent_sdk-0.3.10.dist-info/RECORD,,