process-gpt-agent-sdk 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

processgpt_agent_sdk/server.py

@@ -23,6 +23,10 @@ from .utils.event_handler import process_event_message
 from .utils.context_manager import set_context, reset_context
 
 
+# =============================================================================
+# 서버: ProcessGPTAgentServer
+# 설명: 작업 폴링→실행 준비→실행/이벤트 저장→취소 감시까지 담당하는 핵심 서버
+# =============================================================================
 class ProcessGPTAgentServer:
 	"""ProcessGPT 핵심 서버
 
@@ -31,6 +35,7 @@ class ProcessGPTAgentServer:
 	"""
 
 	def __init__(self, executor: AgentExecutor, polling_interval: int = 5, agent_orch: str = ""):
+		"""서버 실행기/폴링 주기/오케스트레이션 값을 초기화한다."""
 		self.polling_interval = polling_interval
 		self.is_running = False
 		self._executor: AgentExecutor = executor
@@ -39,6 +44,7 @@ class ProcessGPTAgentServer:
 		initialize_db()
 
 	async def run(self) -> None:
+		"""메인 폴링 루프를 실행한다. 작업을 가져와 준비/실행/감시를 순차 수행."""
 		self.is_running = True
 		write_log_message("ProcessGPT 서버 시작")
 		
@@ -64,7 +70,6 @@ class ProcessGPTAgentServer:
 						await update_task_error(str(task_id))
 					except Exception as upd_err:
 						handle_application_error("FAILED 상태 업데이트 실패", upd_err, raise_error=False)
-					# 다음 루프로 진행
 					continue
 				
 			except Exception as e:
@@ -72,10 +77,12 @@ class ProcessGPTAgentServer:
 				await asyncio.sleep(self.polling_interval)
 
 	def stop(self) -> None:
+		"""폴링 루프를 중지 플래그로 멈춘다."""
 		self.is_running = False
 		write_log_message("ProcessGPT 서버 중지")
 
 	async def _prepare_service_data(self, task_record: Dict[str, Any]) -> Dict[str, Any]:
+		"""실행에 필요한 데이터(에이전트/폼/요약/사용자)를 준비해 dict로 반환."""
 		done_outputs = await fetch_done_data(task_record.get("proc_inst_id"))
 		write_log_message(f"[PREP] done_outputs → {done_outputs}")
 		feedbacks = task_record.get("feedback")
@@ -121,12 +128,12 @@ class ProcessGPTAgentServer:
 		return prepared
 
 	async def _execute_with_cancel_watch(self, task_record: Dict[str, Any], prepared_data: Dict[str, Any]) -> None:
+		"""실행 태스크와 취소 감시 태스크를 동시에 운영한다."""
 		executor = self._executor
 
 		context = ProcessGPTRequestContext(prepared_data)
 		event_queue = ProcessGPTEventQueue(task_record)
 
-		# 실행 전 컨텍스트 변수 설정 (CrewAI 전역 리스너 등에서 활용)
 		try:
 			set_context(
 				todo_id=str(task_record.get("id")),
@@ -167,6 +174,7 @@ class ProcessGPTAgentServer:
 			write_log_message(f"[EXEC END] task_id={task_record.get('id')} agent={prepared_data.get('agent_orch','')}")
 
 	async def _watch_cancellation(self, task_record: Dict[str, Any], executor: AgentExecutor, context: RequestContext, event_queue: EventQueue, execute_task: asyncio.Task) -> None:
+		"""작업 상태를 주기적으로 확인해 취소 신호 시 안전 종료를 수행."""
 		todo_id = str(task_record.get("id"))
 		
 		while True:
@@ -192,34 +200,47 @@ class ProcessGPTAgentServer:
 						handle_application_error("취소 후 이벤트 큐 종료 실패", e, raise_error=False)
 				break
 
-
+# =============================================================================
+# 요청 컨텍스트: ProcessGPTRequestContext
+# 설명: 실행기에게 전달되는 요청 데이터/상태를 캡슐화
+# =============================================================================
 class ProcessGPTRequestContext(RequestContext):
 	def __init__(self, prepared_data: Dict[str, Any]):
+		"""실행에 필요한 데이터 묶음을 보관한다."""
 		self._prepared_data = prepared_data
 		self._message = prepared_data.get("message", "")
 		self._current_task = None
 
 	def get_user_input(self) -> str:
+		"""사용자 입력 메시지를 반환한다."""
 		return self._message
 
 	@property
 	def message(self) -> str:
+		"""현재 메시지(사용자 입력)를 반환한다."""
 		return self._message
 
 	@property
 	def current_task(self):
+		"""현재 실행 중 태스크(있다면)를 반환한다."""
 		return getattr(self, "_current_task", None)
 
 	def get_context_data(self) -> Dict[str, Any]:
+		"""실행 컨텍스트 전체 데이터를 dict로 반환한다."""
 		return self._prepared_data
 
-
+# =============================================================================
+# 이벤트 큐: ProcessGPTEventQueue
+# 설명: 실행기 이벤트를 내부 큐에 넣고, 비동기 처리 태스크를 생성해 저장 로직 호출
+# =============================================================================
 class ProcessGPTEventQueue(EventQueue):
 	def __init__(self, task_record: Dict[str, Any]):
+		"""현재 처리 중인 작업 레코드를 보관한다."""
 		self.todo = task_record
 		super().__init__()
 
 	def enqueue_event(self, event: Event):
+		"""이벤트를 큐에 넣고, 백그라운드로 DB 저장 코루틴을 실행한다."""
 		try:
 			try:
 				super().enqueue_event(event)
@@ -231,15 +252,18 @@ class ProcessGPTEventQueue(EventQueue):
 			handle_application_error("이벤트 저장 실패", e, raise_error=False)
 		
 	def task_done(self) -> None:
+		"""태스크 완료 로그를 남긴다."""
 		try:
 			write_log_message(f"태스크 완료: {self.todo['id']}")
 		except Exception as e:
 			handle_application_error("태스크 완료 처리 실패", e, raise_error=False)
 
 	async def close(self) -> None:
+		"""큐 종료 훅(필요 시 리소스 정리)."""
 		pass
 
 	def _create_bg_task(self, coro: Any, label: str) -> None:
+		"""백그라운드 태스크 생성 및 완료 콜백으로 예외 로깅."""
 		try:
 			task = asyncio.create_task(coro)
 			def _cb(t: asyncio.Task):

processgpt_agent_sdk/tools/human_query_tool.py

@@ -1,21 +1,27 @@
 from __future__ import annotations
 
+# =============================================================================
+# Imports
+# =============================================================================
+
 import time
 import uuid
-import os
 from typing import Optional, List, Literal, Type, Dict, Any
+from datetime import datetime, timezone
 
 from pydantic import BaseModel, Field
 from crewai.tools import BaseTool
 
-from ..utils.crewai_event_listener import CrewAIEventLogger
 from ..utils.context_manager import todo_id_var, proc_id_var, all_users_var
 from ..utils.logger import write_log_message, handle_application_error
-from ..core.database import fetch_human_response, save_notification
+from ..core.database import fetch_human_response_sync, save_notification, initialize_db, get_db_client
 
 
+# =============================================================================
+# 입력 스키마
+# =============================================================================
 class HumanQuerySchema(BaseModel):
-    """사용자 확인/추가정보 요청용 스키마"""
+    """사용자 확인/추가정보 요청 입력 스키마."""
 
     role: str = Field(..., description="누구에게(역할 또는 대상)")
     text: str = Field(..., description="질의 내용")
@@ -27,8 +33,12 @@ class HumanQuerySchema(BaseModel):
     )
 
 
+# =============================================================================
+# HumanQueryTool
+# 설명: 보안/모호성 관련 질문을 사용자에게 전송하고 응답을 동기 대기
+# =============================================================================
 class HumanQueryTool(BaseTool):
-    """사람에게 보안/모호성 관련 확인을 요청하고 응답을 대기하는 도구"""
+    """사람에게 질문을 보내고 응답을 동기적으로 대기한다."""
 
     name: str = "human_asked"
     description: str = (
@@ -95,6 +105,7 @@ class HumanQueryTool(BaseTool):
         agent_name: Optional[str] = None,
         **kwargs,
     ):
+        """도구 실행 컨텍스트(테넌트/유저/프로세스)를 옵션으로 설정."""
         super().__init__(**kwargs)
         self._tenant_id = tenant_id
         self._user_id = user_id
@@ -102,18 +113,19 @@ class HumanQueryTool(BaseTool):
         self._proc_inst_id = proc_inst_id
         self._agent_name = agent_name
 
-    # 동기 실행: CrewAI Tool 실행 컨텍스트에서 블로킹 폴링 허용
+    # =============================================================================
+    # 동기 실행
+    # 설명: 질문 이벤트를 저장하고 DB 폴링으로 응답을 기다린다
+    # =============================================================================
     def _run(
         self, role: str, text: str, type: str = "text", options: Optional[List[str]] = None
     ) -> str:
+        """질문 이벤트를 기록하고 최종 응답 문자열을 반환."""
         try:
-            # 초기화된 기본 agent_name 사용
             agent_name = getattr(self, "_agent_name", None)
-                
             write_log_message(f"HumanQueryTool 실행: role={role}, agent_name={agent_name}, type={type}, options={options}")
             query_id = f"human_asked_{uuid.uuid4()}"
 
-            # 이벤트 발행 데이터
             payload: Dict[str, Any] = {
                 "role": role,
                 "text": text,
@@ -121,31 +133,31 @@ class HumanQueryTool(BaseTool):
                 "options": options or [],
             }
 
-            # 컨텍스트 식별자
             todo_id = todo_id_var.get() or self._todo_id
             proc_inst_id = proc_id_var.get() or self._proc_inst_id
 
-            # 이벤트 발행
-            # 상태 정보는 data 안에 포함시켜 저장 (emit_event 시그니처에 status 없음)
             payload_with_status = {
                 **payload,
                 "status": "ASKED",
                 "agent_profile": "/images/chat-icon.png"
             }
-            ev = CrewAIEventLogger()
-            ev.emit_event(
-                event_type="human_asked",
-                data=payload_with_status,
-                job_id=query_id,
-                crew_type="action",
-                todo_id=str(todo_id) if todo_id is not None else None,
-                proc_inst_id=str(proc_inst_id) if proc_inst_id is not None else None,
-            )
-
-            # 알림 저장 (notifications 테이블)
+            
+            initialize_db()
+            supabase = get_db_client()
+            record = {
+                "id": str(uuid.uuid4()),
+                "job_id": query_id,
+                "todo_id": str(todo_id) if todo_id is not None else None,
+                "proc_inst_id": str(proc_inst_id) if proc_inst_id is not None else None,
+                "event_type": "human_asked",
+                "crew_type": "action",
+                "data": payload_with_status,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+            }
+            supabase.table("events").insert(record).execute()
+
             try:
                 tenant_id = self._tenant_id
-                # 대상 이메일: context var(all_users_var)에 이메일 CSV가 있어야만 저장
                 target_emails_csv = all_users_var.get() or ""
                 if target_emails_csv and target_emails_csv.strip():
                     write_log_message(f"알림 저장 시도: target_emails_csv={target_emails_csv}, tenant_id={tenant_id}")
@@ -163,41 +175,37 @@ class HumanQueryTool(BaseTool):
             except Exception as e:
                 handle_application_error("알림저장HumanTool", e, raise_error=False)
 
-            # 응답 폴링 (events 테이블에서 동일 job_id, event_type=human_response)
             answer = self._wait_for_response(query_id)
             return answer
         except Exception as e:
-            # 사용자 미응답 또는 기타 에러 시에도 작업이 즉시 중단되지 않도록 문자열 반환
             handle_application_error("HumanQueryTool", e, raise_error=False)
             return "사용자 미응답 거절"
 
+    # =============================================================================
+    # 응답 대기
+    # 설명: events 테이블에서 human_response를 폴링하여 응답을 가져온다
+    # =============================================================================
     def _wait_for_response(
         self, job_id: str, timeout_sec: int = 180, poll_interval_sec: int = 5
     ) -> str:
-        """DB events 테이블을 폴링하여 사람의 응답을 기다림"""
+        """DB 폴링으로 사람의 응답을 기다려 문자열로 반환."""
         deadline = time.time() + timeout_sec
 
         while time.time() < deadline:
             try:
                 write_log_message(f"HumanQueryTool 응답 폴링: {job_id}")
-                event = fetch_human_response(job_id=job_id)
+                event = fetch_human_response_sync(job_id=job_id)
                 if event:
                     write_log_message(f"HumanQueryTool 응답 수신: {event}")
                     data = event.get("data") or {}
-                    # 기대 형식: {"answer": str, ...}
                     answer = (data or {}).get("answer")
                     if isinstance(answer, str):
                         write_log_message("사람 응답 수신 완료")
                         return answer
-                    # 문자열이 아니면 직렬화하여 반환
                     return str(data)
 
             except Exception as e:
-                # 응답이 아직 없는 경우(0개 행) 또는 기타 DB 오류 시 계속 폴링
                 write_log_message(f"인간 응답 대기 중... (오류: {str(e)[:100]})")
-
             time.sleep(poll_interval_sec)
-
-        # 타임아웃: 사용자 미응답으로 간주
         return "사용자 미응답 거절"
 

processgpt_agent_sdk/tools/safe_tool_loader.py

@@ -9,23 +9,30 @@ from .knowledge_tools import Mem0Tool, MementoTool
 from ..utils.logger import write_log_message, handle_application_error
 
 
+# =============================================================================
+# SafeToolLoader
+# 설명: 로컬/외부 MCP 도구들을 안전하게 초기화·로드·종료 관리
+# =============================================================================
 class SafeToolLoader:
 	"""도구 로더 클래스"""
-	adapters = []  # MCPServerAdapter 인스턴스 등록
+	adapters = []
 	
 	ANYIO_PATCHED: bool = False
 
 	def __init__(self, tenant_id: Optional[str] = None, user_id: Optional[str] = None, agent_name: Optional[str] = None, mcp_config: Optional[Dict] = None):
+		"""실행 컨텍스트(tenant/user/agent)와 MCP 설정을 보관한다."""
 		self.tenant_id = tenant_id
 		self.user_id = user_id
 		self.agent_name = agent_name
-		# 외부에서 전달된 MCP 설정 사용 (DB 접근 금지)
 		self._mcp_servers = (mcp_config or {}).get('mcpServers', {})
 		self.local_tools = ["mem0", "memento", "human_asked"]
 		write_log_message(f"SafeToolLoader 초기화 완료 (tenant_id: {tenant_id}, user_id: {user_id})")
 
+	# =============================================================================
+	# Warmup (npx 서버 사전 준비)
+	# =============================================================================
 	def warmup_server(self, server_key: str, mcp_config: Optional[Dict] = None):
-		"""npx 기반 서버의 패키지를 미리 캐시에 저장해 실제 실행을 빠르게."""
+		"""npx 서버 패키지를 미리 캐싱해 최초 실행 지연을 줄인다."""
 		servers = (mcp_config or {}).get('mcpServers') or self._mcp_servers or {}
 		server_config = servers.get(server_key, {}) if isinstance(servers, dict) else {}
 		if not server_config or server_config.get("command") != "npx":
@@ -54,8 +61,11 @@ class SafeToolLoader:
 		except Exception:
 			pass
 
+	# =============================================================================
+	# 유틸: npx 경로 탐색
+	# =============================================================================
 	def _find_npx_command(self) -> str:
-		"""npx 명령어 경로 찾기"""
+		"""npx 실행 파일 경로를 탐색해 반환한다."""
 		try:
 			import shutil
 			npx_path = shutil.which("npx") or shutil.which("npx.cmd")
@@ -65,6 +75,9 @@ class SafeToolLoader:
 			pass
 		return "npx"
 
+	# =============================================================================
+	# 로컬 도구 생성
+	# =============================================================================
 	def create_tools_from_names(self, tool_names: List[str], mcp_config: Optional[Dict] = None) -> List:
 		"""tool_names 리스트에서 실제 Tool 객체들 생성"""
 		if isinstance(tool_names, str):
@@ -88,6 +101,9 @@ class SafeToolLoader:
 		write_log_message(f"총 {len(tools)}개 도구 생성 완료")
 		return tools
 
+	# =============================================================================
+	# 로컬 도구 로더들
+	# =============================================================================
 	def _load_mem0(self) -> List:
 		"""mem0 도구 로드 - 에이전트별 메모리"""
 		try:
@@ -110,12 +126,14 @@ class SafeToolLoader:
 	def _load_human_asked(self) -> List:
 		"""human_asked 도구 로드 (선택사항: 사용 시 외부에서 주입)"""
 		try:
-			# 필요한 경우 외부에서 HumanQueryTool을 이 패키지에 추가하여 import하고 리턴하도록 변경 가능
 			return []
 		except Exception as error:
 			handle_application_error("툴human오류", error, raise_error=False)
 			return []
 
+	# =============================================================================
+	# 외부 MCP 도구 로더
+	# =============================================================================
 	def _load_mcp_tool(self, tool_name: str, mcp_config: Optional[Dict] = None) -> List:
 		"""MCP 도구 로드 (timeout & retry 지원)"""
 		self._apply_anyio_patch()
@@ -157,8 +175,11 @@ class SafeToolLoader:
 					handle_application_error(f"툴{tool_name}오류", e, raise_error=False)
 					return []
 
+	# =============================================================================
+	# anyio 서브프로세스 stderr 패치
+	# =============================================================================
 	def _apply_anyio_patch(self):
-		"""anyio stderr 패치 적용"""
+		"""stderr에 fileno 없음 대비: PIPE로 보정해 예외를 방지한다."""
 		if SafeToolLoader.ANYIO_PATCHED:
 			return
 		from anyio._core._subprocesses import open_process as _orig
@@ -173,9 +194,12 @@ class SafeToolLoader:
 		anyio._core._subprocesses.open_process = patched_open_process
 		SafeToolLoader.ANYIO_PATCHED = True
 
+	# =============================================================================
+	# 종료 처리
+	# =============================================================================
 	@classmethod
 	def shutdown_all_adapters(cls):
-		"""모든 MCPServerAdapter 연결 종료"""
+		"""모든 MCPServerAdapter 연결을 안전하게 종료한다."""
 		for adapter in cls.adapters:
 			try:
 				adapter.stop()

processgpt_agent_sdk/utils/context_manager.py

@@ -1,9 +1,15 @@
 from __future__ import annotations
 
+# =============================================================================
+# Context Manager
+# 설명: 요청/프로세스 범위의 컨텍스트 값을 ContextVar로 관리
+# =============================================================================
+
 from contextvars import ContextVar
 from typing import Optional
 
 
+# 컨텍스트 변수 정의
 todo_id_var: ContextVar[Optional[str]] = ContextVar("todo_id", default=None)
 proc_id_var: ContextVar[Optional[str]] = ContextVar("proc_id", default=None)
 crew_type_var: ContextVar[Optional[str]] = ContextVar("crew_type", default=None)
@@ -13,6 +19,7 @@ all_users_var: ContextVar[Optional[str]] = ContextVar("all_users", default=None)
 
 
 def set_context(*, todo_id: Optional[str] = None, proc_inst_id: Optional[str] = None, crew_type: Optional[str] = None, form_key: Optional[str] = None, form_id: Optional[str] = None, all_users: Optional[str] = None) -> None:
+    """전달된 값들만 ContextVar에 설정한다."""
     if todo_id is not None:
         todo_id_var.set(todo_id)
     if proc_inst_id is not None:
@@ -28,6 +35,7 @@ def set_context(*, todo_id: Optional[str] = None, proc_inst_id: Optional[str] =
 
 
 def reset_context() -> None:
+    """모든 컨텍스트 값을 초기 상태(None)로 되돌린다."""
     todo_id_var.set(None)
     proc_id_var.set(None)
     crew_type_var.set(None)

processgpt_agent_sdk/utils/crewai_event_listener.py

@@ -21,6 +21,7 @@ class CrewAIEventLogger:
     # Initialization
     # =============================================================================
     def __init__(self):
+        """Supabase 클라이언트를 초기화한다."""
         initialize_db()
         self.supabase = get_db_client()
         write_log_message("CrewAIEventLogger 초기화 완료")
@@ -151,7 +152,6 @@ class CrewAIEventLogger:
             except Exception as e:
                 if attempt < 3:
                     handle_application_error("이벤트저장오류(재시도)", e, raise_error=False)
-                    # 지수 백오프: 0.3s, 0.6s
                     import time
                     time.sleep(0.3 * attempt)
                     continue
@@ -178,7 +178,10 @@ class CrewAIEventLogger:
             handle_application_error("이벤트처리오류", e, raise_error=False)
 
 
-
+# =============================================================================
+# CrewConfigManager
+# 설명: 이벤트 리스너를 프로세스 단위로 1회 등록
+# =============================================================================
 class CrewConfigManager:
     """글로벌 CrewAI 이벤트 리스너 등록 매니저"""
     _registered_by_pid: set[int] = set()
@@ -188,6 +191,7 @@ class CrewConfigManager:
         self._register_once_per_process()
 
     def _register_once_per_process(self) -> None:
+        """현재 프로세스에만 한 번 이벤트 리스너를 등록한다."""
         try:
             pid = os.getpid()
             if pid in self._registered_by_pid:

processgpt_agent_sdk/utils/logger.py

@@ -11,16 +11,25 @@ if not logging.getLogger().handlers:
 		format="%(asctime)s %(levelname)s %(name)s - %(message)s",
 	)
 
-APPLICATION_LOGGER = logging.getLogger("process-gpt-agent-framework")
+LOGGER_NAME = os.getenv("LOGGER_NAME") or "processgpt"
+APPLICATION_LOGGER = logging.getLogger(LOGGER_NAME)
+
+
+def set_application_logger_name(name: str) -> None:
+	"""애플리케이션 로거 이름을 런타임에 변경한다."""
+	global APPLICATION_LOGGER
+	APPLICATION_LOGGER = logging.getLogger(name or "processgpt")
 
 
 def write_log_message(message: str, level: int = logging.INFO) -> None:
+	"""로그 메시지를 쓴다."""
 	spaced = os.getenv("LOG_SPACED", "1") != "0"
 	suffix = "\n" if spaced else ""
 	APPLICATION_LOGGER.log(level, f"{message}{suffix}")
 
 
 def handle_application_error(title: str, error: Exception, *, raise_error: bool = True, extra: Optional[Dict] = None) -> None:
+	"""예외 상황을 처리한다."""
 	spaced = os.getenv("LOG_SPACED", "1") != "0"
 	suffix = "\n" if spaced else ""
 	context = f" | extra={extra}" if extra else ""