process-gpt-agent-sdk 0.2.11__py3-none-any.whl → 0.3.4__py3-none-any.whl

process_gpt_agent_sdk-0.3.4.dist-info/METADATA

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: process-gpt-agent-sdk
+Version: 0.3.4
+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: a2a-sdk==0.3.0
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: process-gpt-llm-factory==1.0.2
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: requests>=2.25.0
+
+# 📘 ProcessGPT Agent SDK – README
+
+## 1. 이게 뭐하는 건가요?
+이 SDK는 **ProcessGPT 에이전트 서버**를 만들 때 필요한 **공통 기능**을 제공합니다.  
+
+- DB에서 **작업(todo) 폴링** → 처리할 일감 가져오기  
+- **컨텍스트 준비** (사용자 정보, 폼 정의, MCP 설정 등 자동으로 조회)  
+- 다양한 **에이전트 오케스트레이션(A2A)** 과 호환  
+- **이벤트(Event) 전송 규격 통일화** → 결과를 DB에 안전하게 저장  
+
+👉 쉽게 말하면: **여러 종류의 AI 에이전트를 같은 규칙으로 실행/저장/호출할 수 있게 해주는 통합 SDK** 입니다.  
+
+---
+
+## 2. 아키텍처 다이어그램
+```mermaid
+flowchart TD
+    subgraph DB[Postgres/Supabase]
+        T[todolist]:::db
+        E[events]:::db
+    end
+
+    subgraph SDK
+        P[Polling\n(fetch_pending_task)] --> C[Context 준비\n(fetch_context_bundle 등)]
+        C --> X[Executor\n(MinimalExecutor)]
+        X -->|TaskStatusUpdateEvent| E
+        X -->|TaskArtifactUpdateEvent| T
+    end
+
+    classDef db fill=#f2f2f2,stroke=#333,stroke-width=1px;
+```
+
+- **todolist**: 각 작업(Task)의 진행 상태, 결과물 저장  
+- **events**: 실행 중간에 발생한 이벤트 로그 저장  
+- SDK는 두 테이블을 자동으로 연결해 줍니다.  
+
+---
+
+## 3. A2A 타입과 이벤트 종류
+
+### A2A 타입 (2가지)
+| A2A 타입 | 설명 | 매칭 테이블 |
+|----------|------|-------------|
+| **TaskStatusUpdateEvent** | 작업 상태 업데이트 | `events` 테이블 |
+| **TaskArtifactUpdateEvent** | 작업 결과물 업데이트 | `todolist` 테이블 |
+
+### Event Type (4가지)
+| Event Type | Python 클래스 | 저장 테이블 | 설명 |
+|------------|---------------|-------------|------|
+| **task_started** | `TaskStatusUpdateEvent` | `events` | 작업 시작 상태 |
+| **task_working** | `TaskStatusUpdateEvent` | `events` | 작업 진행 중 상태 |
+| **task_completed** | `TaskArtifactUpdateEvent` | `todolist` | 작업 완료 및 결과물 저장 |
+| **task_error** | `TaskStatusUpdateEvent` | `events` | 작업 오류 발생 |
+
+👉 **A2A 타입 2가지**가 핵심이며, 각각 `events`와 `todolist` 테이블에 매칭됩니다. **Event Type 4가지**로 세부 상태를 구분합니다.
+
+---
+
+## 4. 미니멀 예제 (기본 사용법)
+
+### minimal_executor.py
+```python
+class MinimalExecutor(AgentExecutor):
+    async def execute(self, context: RequestContext, event_queue: EventQueue):
+        # 1) 입력 가져오기
+        query = context.get_user_input()
+        print("User Query:", query)
+
+        # 2) 상태 이벤트 (events 테이블 저장)
+        payload = {"demo": "hello world"}
+        event_queue.enqueue_event(
+            TaskStatusUpdateEvent(
+                status={
+                    "state": TaskState.working,
+                    "message": new_agent_text_message(
+                        json.dumps(payload, ensure_ascii=False),  # ⚠️ str() 쓰지말고 반드시 json.dumps!
+                        context.get_context_data()["row"]["proc_inst_id"],
+                        context.get_context_data()["row"]["id"],
+                    ),
+                },
+                contextId=context.get_context_data()["row"]["proc_inst_id"],
+                taskId=context.get_context_data()["row"]["id"],
+                metadata={"crew_type": "action", "event_type": "task_started"},
+            )
+        )
+
+        # 3) 최종 아티팩트 이벤트 (todolist 테이블 저장)
+        artifact = new_text_artifact(
+            name="result",
+            description="Demo Result",
+            text=json.dumps(payload, ensure_ascii=False),  # ⚠️ 여기서도 str() 금지!
+        )
+        event_queue.enqueue_event(
+            TaskArtifactUpdateEvent(
+                artifact=artifact,
+                lastChunk=True,
+                contextId=context.get_context_data()["row"]["proc_inst_id"],
+                taskId=context.get_context_data()["row"]["id"],
+            )
+        )
+```
+
+### minimal_server.py
+```python
+async def main():
+    load_dotenv()
+    server = ProcessGPTAgentServer(
+        agent_executor=MinimalExecutor(),
+        agent_type="crewai-action"  # 오케스트레이터 타입
+    )
+    await server.run()
+```
+
+👉 실행하면 SDK가 자동으로:
+1. DB에서 작업 하나 가져오기 (`fetch_pending_task`)  
+2. 컨텍스트 준비 (폼/유저/MCP 조회)  
+3. Executor 실행 → 이벤트/결과 DB에 저장  
+
+---
+
+## 5. ⚠️ JSON 직렬화 주의 (str() 절대 금지)
+
+반드시 `json.dumps()`로 직렬화해야 합니다.  
+
+- ❌ 이렇게 하면 안됨:
+  ```python
+  text = str({"key": "value"})  # Python dict string → JSON 아님
+  ```
+  DB에 `"'{key: value}'"` 꼴로 문자열 저장됨 → 파싱 실패
+
+- ✅ 이렇게 해야 함:
+  ```python
+  text = json.dumps({"key": "value"}, ensure_ascii=False)
+  ```
+  DB에 `{"key": "value"}` JSON 저장됨 → 파싱 성공
+
+👉 **SDK는 내부에서 `json.loads`로 재파싱**하기 때문에, 표준 JSON 문자열이 아니면 무조건 문자열로만 남습니다.  
+
+---
+
+## 6. 요약
+- 이 SDK는 **ProcessGPT Agent**를 표준 규격으로 실행/저장/호출하는 공통 레이어  
+- 작업 → 컨텍스트 준비 → Executor 실행 → 이벤트 저장 전체를 자동화  
+- **A2A 타입 2가지**: `TaskStatusUpdateEvent`, `TaskArtifactUpdateEvent`  
+- **Event Type 4가지**: `task_started`, `task_working`, `task_completed`, `task_error`  
+- **DB 매핑**:  
+  - `TaskStatusUpdateEvent` → `events` 테이블  
+  - `TaskArtifactUpdateEvent` → `todolist` 테이블  
+- ⚠️ **str() 대신 무조건 `json.dumps` 사용!**
+
+
+
+## 7. 버전업
+- ./release.sh 버전
+- 오류 발생시 : python -m ensurepip --upgrade

process_gpt_agent_sdk-0.3.4.dist-info/RECORD

@@ -0,0 +1,8 @@
+processgpt_agent_sdk/__init__.py,sha256=4-Wt-FRImZa1tG4CWx2ZtICcnTkKoAiqAfva9vLitLQ,991
+processgpt_agent_sdk/database.py,sha256=4oQxJ3y28pPdUpvcQ80DEcFmcvKH37RszhSSZKf6tJU,12690
+processgpt_agent_sdk/processgpt_agent_framework.py,sha256=xsQnPXTnIjCkE5jYDVg9TZC-QiyLF0DmXHTvu-oMXa0,23080
+processgpt_agent_sdk/utils.py,sha256=pK7plUKGMIHo5lA0e4442qMAmAtCwKrbewjrXdVbFdE,9228
+process_gpt_agent_sdk-0.3.4.dist-info/METADATA,sha256=NR2O7M7WttHlU9oGJbRgFv3vcdt4pXSkIfWUOkE_ySU,6840
+process_gpt_agent_sdk-0.3.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+process_gpt_agent_sdk-0.3.4.dist-info/top_level.txt,sha256=Xe6zrj3_3Vv7d0pl5RRtenVUckwOVBVLQn2P03j5REo,21
+process_gpt_agent_sdk-0.3.4.dist-info/RECORD,,

processgpt_agent_sdk/__init__.py

@@ -1,11 +1,43 @@
-from .server import ProcessGPTAgentServer, ProcessGPTRequestContext, ProcessGPTEventQueue
-from .simulator import ProcessGPTAgentSimulator, SimulatorRequestContext, SimulatorEventQueue
-
-__all__ = [
-	"ProcessGPTAgentServer",
-	"ProcessGPTRequestContext",
-	"ProcessGPTEventQueue",
-	"ProcessGPTAgentSimulator",
-	"SimulatorRequestContext",
-	"SimulatorEventQueue",
-]
+from .processgpt_agent_framework import (
+    ProcessGPTAgentServer,
+    ProcessGPTRequestContext,
+    ProcessGPTEventQueue,
+    ContextPreparationError,
+)
+from .database import (
+    initialize_db,
+    get_consumer_id,
+    polling_pending_todos,
+    record_event,
+    record_events_bulk,
+    save_task_result,
+    update_task_error,
+    fetch_form_def,
+    fetch_users_grouped,
+    fetch_email_users_by_proc_inst_id,
+    fetch_tenant_mcp,
+)
+from .utils import (
+    summarize_error_to_user,
+    summarize_feedback,
+)
+
+__all__ = [
+    "ProcessGPTAgentServer",
+    "ProcessGPTRequestContext",
+    "ProcessGPTEventQueue",
+    "ContextPreparationError",
+    "initialize_db",
+    "get_consumer_id",
+    "polling_pending_todos",
+    "record_event",
+    "record_events_bulk",
+    "save_task_result",
+    "update_task_error",
+    "fetch_form_def",
+    "fetch_users_grouped",
+    "fetch_email_users_by_proc_inst_id",
+    "fetch_tenant_mcp",
+    "summarize_error_to_user",
+    "summarize_feedback",
+]

processgpt_agent_sdk/database.py

@@ -0,0 +1,383 @@
+import os
+import json
+import asyncio
+import socket
+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__)
+
+# ------------------------------ Retry & JSON utils ------------------------------
+async def _async_retry(
+    fn: Callable[[], Any],
+    *,
+    name: str,
+    retries: int = 3,
+    base_delay: float = 0.8,
+    fallback: Optional[Callable[[], Any]] = None,
+) -> Optional[Any]:
+    """
+    - 각 시도 실패: warning 로깅(시도/지연/에러 포함)
+    - 최종 실패: FATAL 로깅(스택 포함), 예외는 재전파하지 않고 None 반환(기존 정책 유지)
+    - 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
+            logger.warning(
+                "retry warn: name=%s attempt=%d/%d delay=%.2fs error=%s",
+                name, attempt, retries, delay, str(e),
+                exc_info=e
+            )
+            await asyncio.sleep(delay)
+
+    # 최종 실패
+    if last_err is not None:
+        logger.error(
+            "FATAL: retry failed: name=%s retries=%s error=%s",
+            name, retries, str(last_err), exc_info=last_err
+        )
+
+    if fallback is not None:
+        try:
+            return fallback()
+        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 _to_jsonable(value: Any) -> Any:
+    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 Client ------------------------------
+_supabase_client: Optional[Client] = None
+
+def initialize_db() -> None:
+    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:
+    if _supabase_client is None:
+        raise RuntimeError("DB 미초기화: initialize_db() 먼저 호출")
+    return _supabase_client
+
+def get_consumer_id() -> str:
+    env_consumer = os.getenv("CONSUMER_ID")
+    if env_consumer:
+        return env_consumer
+    host = socket.gethostname()
+    pid = os.getpid()
+    return f"{host}:{pid}"
+
+# ------------------------------ Polling ------------------------------
+async def polling_pending_todos(agent_orch: str, consumer: str) -> Optional[Dict[str, Any]]:
+    """단일 RPC(fetch_pending_task) 호출: p_env 로 dev/prod 분기"""
+    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 값을 dev / (그외=prod) 로만 정규화
+        p_env = (os.getenv("ENV") or "").lower()
+        if p_env != "dev":
+            p_env = "prod"
+
+        resp = client.rpc(
+            "fetch_pending_task",
+            {
+                "p_agent_orch": agent_orch,
+                "p_consumer": consumer_id,
+                "p_limit": 1,
+                "p_env": p_env,
+            },
+        ).execute()
+
+        rows = resp.data or []
+        if not rows:
+            return None
+        
+        row = rows[0]
+        # 빈 값들을 NULL로 변환
+        if row.get("feedback") in ([], {}):
+            row["feedback"] = None
+        if row.get("output") in ([], {}):
+            row["output"] = None
+        if row.get("draft") in ([], {}):
+            row["draft"] = None
+            
+        return row
+
+    return await _async_retry(_call, name="polling_pending_todos", fallback=lambda: None)
+
+
+# ------------------------------ Events & Results ------------------------------
+async def record_events_bulk(payloads: List[Dict[str, Any]]) -> None:
+    """이벤트 다건 저장 함수"""
+
+    if not payloads:
+        return
+
+    safe_list: List[Dict[str, Any]] = []
+    for p in payloads:
+        sp = _to_jsonable(p)
+        if isinstance(sp, dict) and sp.get("status", "") == "":
+            sp["status"] = None
+        safe_list.append(sp)
+
+    def _call():
+        client = get_db_client()
+        return client.rpc("record_events_bulk", {"p_events": safe_list}).execute()
+
+    res = await _async_retry(_call, name="record_events_bulk", fallback=lambda: None)
+    if res is None:
+        logger.error("❌ record_events_bulk failed: events not persisted count=%d", len(safe_list))
+    else:
+        logger.info("record_events_bulk ok: count=%d", len(safe_list))
+
+async def record_event(payload: Dict[str, Any]) -> None:
+    """단건 이벤트 저장 함수"""
+
+    if not payload:
+        return
+
+    def _call():
+        client = get_db_client()
+        safe_payload = _to_jsonable(payload)
+        if isinstance(safe_payload, dict) and safe_payload.get("status", "") == "":
+            safe_payload["status"] = None
+        return client.table("events").insert(safe_payload).execute()
+
+    res = await _async_retry(_call, name="record_event", fallback=lambda: None)
+    if res is None:
+        logger.error("❌ record_event failed =%s", payload.get("event_type"))
+    else:
+        logger.info("record_event ok: event_type=%s", payload.get("event_type"))
+
+async def save_task_result(todo_id: str, result: Any, final: bool = False) -> None:
+    """결과 저장 함수"""
+
+    if not todo_id:
+        logger.error("save_task_result invalid todo_id: %s", str(todo_id))
+        return
+
+    def _safe(val: Any) -> Any:
+        try:
+            return _to_jsonable(val)
+        except Exception:
+            try:
+                return {"repr": repr(val)}
+            except Exception:
+                return {"error": "unserializable payload"}
+
+    def _call():
+        client = get_db_client()
+        payload = _safe(result)
+        return client.rpc("save_task_result", {"p_todo_id": todo_id, "p_payload": payload, "p_final": bool(final)}).execute()
+
+    res = await _async_retry(_call, name="save_task_result", fallback=lambda: None)
+    if res is None:
+        logger.error("❌ save_task_result failed todo_id=%s", todo_id)
+    else:
+        logger.info("save_task_result ok todo_id=%s", todo_id)
+
+# ------------------------------ Failure Status ------------------------------
+async def update_task_error(todo_id: str) -> None:
+    """작업 실패 상태 업데이트 함수"""
+
+    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()
+
+    res = await _async_retry(_call, name="update_task_error", fallback=lambda: None)
+    if res is None:
+        logger.error("❌ update_task_error failed todo_id=%s", todo_id)
+    else:
+        logger.info("update_task_error ok todo_id=%s", todo_id)
+
+# ============================== Prepare Context ==============================
+
+from typing import Any, Dict, List, Optional, Tuple
+
+async def fetch_form_def(tool_val: str, tenant_id: str) -> Tuple[str, List[Dict[str, Any]], Optional[str]]:
+    """폼 정의 조회 함수"""
+    form_id = (tool_val or "").replace("formHandler:", "", 1)
+
+    def _call():
+        client = get_db_client()
+        resp = (
+            client.table("form_def")
+            .select("fields_json, html")
+            .eq("id", form_id)
+            .eq("tenant_id", tenant_id or "")
+            .execute()
+        )
+        data = (resp.data or [])
+        if not data:
+            return None
+
+        row = data[0]
+        return {
+            "fields": row.get("fields_json"),
+            "html": row.get("html"),
+        }
+
+    try:
+        res = await _async_retry(_call, name="fetch_form_def")
+    except Exception as e:
+        logger.error("fetch_form_def fatal: %s", str(e), exc_info=e)
+        res = None
+
+    if not res or not res.get("fields"):
+        # 기본(자유형식) 폼
+        return (
+            form_id or "freeform",
+            [{"key": "freeform", "type": "textarea", "text": "자유형식 입력", "placeholder": "원하는 내용을 자유롭게 입력해주세요."}],
+            None,
+        )
+    return (form_id or "freeform", res["fields"], res.get("html"))
+
+
+async def fetch_users_grouped(user_ids: List[str]) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
+    """해당 todo에서 사용자 목록과 에이전트 목록 조회하는는 함수"""
+    ids = [u for u in (user_ids or []) if u]
+    if not ids:
+        return ([], [])
+
+    def _call():
+        client = get_db_client()
+        resp = (
+            client.table("users")
+            .select("*")
+            .in_("id", ids)
+            .execute()
+        )
+        rows = resp.data or []
+        return rows
+
+    try:
+        rows = await _async_retry(_call, name="fetch_users_grouped", fallback=lambda: [])
+    except Exception as e:
+        logger.error("fetch_users_grouped fatal: %s", str(e), exc_info=e)
+        rows = []
+
+    agents, users = [], []
+    for r in rows:
+        if r.get("is_agent") is True:
+            agents.append(r)
+        else:
+            users.append(r)
+    return (agents, users)
+
+async def fetch_email_users_by_proc_inst_id(proc_inst_id: str) -> str:
+    """proc_inst_id로 이메일 수집(사람만): todolist → users(in) 한 번에"""
+    if not proc_inst_id:
+        return ""
+
+    def _call():
+        client = get_db_client()
+        # 3-1) 해당 인스턴스의 user_id 수집(중복 제거)
+        tl = (
+            client.table("todolist")
+            .select("user_id")
+            .eq("proc_inst_id", proc_inst_id)
+            .execute()
+        )
+        ids_set = set()
+        for row in (tl.data or []):
+            uid_csv = (row.get("user_id") or "").strip()
+            if not uid_csv:
+                continue
+            # user_id는 문자열 CSV라고 전제
+            for uid in uid_csv.split(","):
+                u = uid.strip()
+                if u:
+                    ids_set.add(u)
+        if not ids_set:
+            return []
+
+        # 3-2) 한 번의 IN 조회로 사람만 이메일 추출
+        ur = (
+            client.table("users")
+            .select("id, email, is_agent")
+            .in_("id", list(ids_set))
+            .eq("is_agent", False)
+            .execute()
+        )
+        emails = []
+        for u in (ur.data or []):
+            email = (u.get("email") or "").strip()
+            if email:
+                emails.append(email)
+        # 중복 제거 및 정렬(보기 좋게)
+        return sorted(set(emails))
+
+    try:
+        emails = await _async_retry(_call, name="fetch_email_users_by_proc_inst_id", fallback=lambda: [])
+    except Exception as e:
+        logger.error("fetch_email_users_by_proc_inst_id fatal: %s", str(e), exc_info=e)
+        emails = []
+
+    return ",".join(emails) if emails else ""
+
+async def fetch_tenant_mcp(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", fallback=lambda: None)
+    except Exception as e:
+        logger.error("fetch_tenant_mcp fatal: %s", str(e), exc_info=e)
+        return None
+
+    return resp.data.get("mcp") if resp and getattr(resp, "data", None) else None