# ProcessGPT Agent Utils
ProcessGPT Agent Utilities - 도구 로더, 지식 관리, 이벤트 로깅, 데이터베이스 유틸리티
## 🚀 주요 기능
### 🛠️ 도구 관리 (`tools/`)
- **SafeToolLoader**: MCP 서버 기반 도구 로딩 및 관리
- **KnowledgeManager**: 개인지식(mem0) 및 사내문서(memento) 검색
- **HumanQueryTool**: 사용자 확인/추가정보 요청 도구
- **DMNRuleTool**: DMN(Decision Model and Notation) 규칙 관리 및 실행
### 📊 유틸리티 (`utils/`)
- **Database**: Supabase 기반 데이터베이스 작업 (재시도, 알림 저장)
- **ContextManager**: 컨텍스트 변수 관리
- **CrewEventLogger**: CrewAI 이벤트 로깅 및 전송
## 📦 설치
```bash
pip install process-gpt-agent-utils
```
## 🔧 사용법
### 도구 로더 사용
```python
from processgpt_agent_utils import SafeToolLoader
# MCP 설정 예시
mcp_config = {
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "your_token"}
}
}
}
loader = SafeToolLoader(
tenant_id="your_tenant",
user_id="your_user",
agent_name="your_agent",
mcp_config=mcp_config
)
tools = loader.create_tools_from_names([
"mem0", "memento", "human_asked", "github"
])
```
### 지식 검색 사용
```python
from tools.knowledge_manager import Mem0Tool, MementoTool
# 개인지식 검색
mem0_tool = Mem0Tool(tenant_id="tenant", user_id="user")
result = mem0_tool._run("과거 실패 사례")
# 사내문서 검색
memento_tool = MementoTool(tenant_id="tenant")
result = memento_tool._run("회사 정책")
```
### DMN 규칙 기반 쿼리 추론
```python
from processgpt_agent_utils import DMNRuleTool
# DMN 규칙 도구 초기화
dmn_tool = DMNRuleTool(tenant_id="tenant", user_id="user-owner-id")
# 쿼리 분석 및 추론
result = dmn_tool._run("보험 위험도 평가는 어떻게 하나요?")
result = dmn_tool._run("나이 25세 남성의 위험도는?")
```
### 데이터베이스 작업
```python
from utils.database import initialize_db, save_notification
# DB 초기화
initialize_db()
# 알림 저장
await save_notification(
title="작업 완료",
notif_type="workitem_bpm",
user_ids_csv="user1,user2",
tenant_id="tenant"
)
```
## 🎯 이모지 로깅
모든 유틸리티는 이모지를 활용한 직관적인 로깅을 제공합니다:
- 🔧 초기화 완료
- 🛠️ 도구 로딩
- 🔍 검색 시작
- 📋 DMN 규칙 처리
- ⚖️ 규칙 실행
- ✅ 성공
- ❌ 실패
- ⚠️ 경고
- 📨 이벤트 전송
## 📋 DMN Rule Tool 상세 정보
### 🎯 주요 기능
- **사용자별 규칙 관리**: 초기화 시 user_id를 소유자로 해서 DMN 규칙들을 미리 로드
- **쿼리 분석**: 사용자 쿼리를 분석하여 관련 DMN 규칙들을 찾아 추론
- **XML 파싱**: DMN 1.3 표준 네임스페이스 지원
- **규칙 실행**: 비즈니스 규칙에 따른 자동화된 의사결정
- **조건 평가**: 복잡한 조건부 로직 처리
- **결과 반환**: 규칙 매칭 결과 및 출력값 제공
### 🗄️ 데이터베이스 스키마
DMN 규칙은 `proc_def` 테이블에 저장됩니다:
```sql
CREATE TABLE proc_def (
id TEXT NOT NULL,
name TEXT NULL,
definition JSONB NULL,
bpmn TEXT NULL, -- DMN XML 저장
uuid UUID NOT NULL DEFAULT gen_random_uuid(),
tenant_id TEXT NULL DEFAULT public.tenant_id(),
isdeleted BOOLEAN NOT NULL DEFAULT FALSE,
owner TEXT NULL,
type TEXT NULL, -- 'dmn' 값으로 DMN 규칙 식별
CONSTRAINT proc_def_pkey PRIMARY KEY (uuid)
);
```
### 🔧 사용 사례
- **보험 위험도 평가**: 나이, 성별, 흡연여부 기반 위험도 결정
- **승인 프로세스**: 조건에 따른 자동 승인/거부
- **가격 정책**: 복잡한 조건에 따른 가격 계산
- **품질 검사**: 제품 사양에 따른 등급 분류
### 📊 규칙 실행 예시
```python
# DMN 규칙 도구 초기화 (user_id가 소유자)
dmn_tool = DMNRuleTool(tenant_id="tenant", user_id="0f61e5fd-622b-921e-f31f-fc61958021e9")
# 쿼리 분석 (사용자의 규칙들을 기반으로 추론)
result = dmn_tool._run("보험 위험도 평가는 어떻게 하나요?")
# 결과: 관련 규칙들을 찾아 분석 결과 제공
```
## 📋 의존성
- `supabase>=2.0.0` - 데이터베이스 연결
- `crewai>=0.152.0,<=0.175.0` - AI 에이전트 프레임워크
- `mem0ai>=0.1.94` - 개인지식 저장소
- `mcp>=1.6.0` - Model Context Protocol
- `pydantic>=2.0.0` - 데이터 검증
- `a2a-sdk>=0.3.0` - A2A 통신
- `xml.etree.ElementTree` - DMN XML 파싱 (Python 내장)
## 🔄 개발
### 개발 의존성 설치
```bash
pip install -e ".[dev]"
```
### 릴리스
```bash
# Linux/Mac
./release.sh 0.1.4
python -m ensurepip --upgrade
# Windows
.\release.ps1 -Version 0.1.1
```
python -m ensurepip --upgrade
## 📄 라이선스
MIT License
## 🤝 기여
이슈 및 풀 리퀘스트를 환영합니다!
Raw data
{
"_id": null,
"home_page": null,
"name": "process-gpt-agent-utils",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "agent, processgpt, tools, knowledge, logging, database, crewai, mcp",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/de/1e/d48a1b9a8b0bade8a377622c099406cac932877af42c532e77abd72f53af/process_gpt_agent_utils-0.2.3.tar.gz",
"platform": null,
"description": "# ProcessGPT Agent Utils\r\n\r\nProcessGPT Agent Utilities - \ub3c4\uad6c \ub85c\ub354, \uc9c0\uc2dd \uad00\ub9ac, \uc774\ubca4\ud2b8 \ub85c\uae45, \ub370\uc774\ud130\ubca0\uc774\uc2a4 \uc720\ud2f8\ub9ac\ud2f0\r\n\r\n## \ud83d\ude80 \uc8fc\uc694 \uae30\ub2a5\r\n\r\n### \ud83d\udee0\ufe0f \ub3c4\uad6c \uad00\ub9ac (`tools/`)\r\n- **SafeToolLoader**: MCP \uc11c\ubc84 \uae30\ubc18 \ub3c4\uad6c \ub85c\ub529 \ubc0f \uad00\ub9ac\r\n- **KnowledgeManager**: \uac1c\uc778\uc9c0\uc2dd(mem0) \ubc0f \uc0ac\ub0b4\ubb38\uc11c(memento) \uac80\uc0c9\r\n- **HumanQueryTool**: \uc0ac\uc6a9\uc790 \ud655\uc778/\ucd94\uac00\uc815\ubcf4 \uc694\uccad \ub3c4\uad6c\r\n- **DMNRuleTool**: DMN(Decision Model and Notation) \uaddc\uce59 \uad00\ub9ac \ubc0f \uc2e4\ud589\r\n\r\n### \ud83d\udcca \uc720\ud2f8\ub9ac\ud2f0 (`utils/`)\r\n- **Database**: Supabase \uae30\ubc18 \ub370\uc774\ud130\ubca0\uc774\uc2a4 \uc791\uc5c5 (\uc7ac\uc2dc\ub3c4, \uc54c\ub9bc \uc800\uc7a5)\r\n- **ContextManager**: \ucee8\ud14d\uc2a4\ud2b8 \ubcc0\uc218 \uad00\ub9ac\r\n- **CrewEventLogger**: CrewAI \uc774\ubca4\ud2b8 \ub85c\uae45 \ubc0f \uc804\uc1a1\r\n\r\n## \ud83d\udce6 \uc124\uce58\r\n\r\n```bash\r\npip install process-gpt-agent-utils\r\n```\r\n\r\n## \ud83d\udd27 \uc0ac\uc6a9\ubc95\r\n\r\n### \ub3c4\uad6c \ub85c\ub354 \uc0ac\uc6a9\r\n```python\r\nfrom processgpt_agent_utils import SafeToolLoader\r\n\r\n# MCP \uc124\uc815 \uc608\uc2dc\r\nmcp_config = {\r\n \"mcpServers\": {\r\n \"github\": {\r\n \"command\": \"npx\",\r\n \"args\": [\"-y\", \"@modelcontextprotocol/server-github\"],\r\n \"env\": {\"GITHUB_PERSONAL_ACCESS_TOKEN\": \"your_token\"}\r\n }\r\n }\r\n}\r\n\r\nloader = SafeToolLoader(\r\n tenant_id=\"your_tenant\",\r\n user_id=\"your_user\",\r\n agent_name=\"your_agent\",\r\n mcp_config=mcp_config\r\n)\r\n\r\ntools = loader.create_tools_from_names([\r\n \"mem0\", \"memento\", \"human_asked\", \"github\"\r\n])\r\n```\r\n\r\n### \uc9c0\uc2dd \uac80\uc0c9 \uc0ac\uc6a9\r\n```python\r\nfrom tools.knowledge_manager import Mem0Tool, MementoTool\r\n\r\n# \uac1c\uc778\uc9c0\uc2dd \uac80\uc0c9\r\nmem0_tool = Mem0Tool(tenant_id=\"tenant\", user_id=\"user\")\r\nresult = mem0_tool._run(\"\uacfc\uac70 \uc2e4\ud328 \uc0ac\ub840\")\r\n\r\n# \uc0ac\ub0b4\ubb38\uc11c \uac80\uc0c9\r\nmemento_tool = MementoTool(tenant_id=\"tenant\")\r\nresult = memento_tool._run(\"\ud68c\uc0ac \uc815\ucc45\")\r\n```\r\n\r\n### DMN \uaddc\uce59 \uae30\ubc18 \ucffc\ub9ac \ucd94\ub860\r\n```python\r\nfrom processgpt_agent_utils import DMNRuleTool\r\n\r\n# DMN \uaddc\uce59 \ub3c4\uad6c \ucd08\uae30\ud654\r\ndmn_tool = DMNRuleTool(tenant_id=\"tenant\", user_id=\"user-owner-id\")\r\n\r\n# \ucffc\ub9ac \ubd84\uc11d \ubc0f \ucd94\ub860\r\nresult = dmn_tool._run(\"\ubcf4\ud5d8 \uc704\ud5d8\ub3c4 \ud3c9\uac00\ub294 \uc5b4\ub5bb\uac8c \ud558\ub098\uc694?\")\r\nresult = dmn_tool._run(\"\ub098\uc774 25\uc138 \ub0a8\uc131\uc758 \uc704\ud5d8\ub3c4\ub294?\")\r\n```\r\n\r\n### \ub370\uc774\ud130\ubca0\uc774\uc2a4 \uc791\uc5c5\r\n```python\r\nfrom utils.database import initialize_db, save_notification\r\n\r\n# DB \ucd08\uae30\ud654\r\ninitialize_db()\r\n\r\n# \uc54c\ub9bc \uc800\uc7a5\r\nawait save_notification(\r\n title=\"\uc791\uc5c5 \uc644\ub8cc\",\r\n notif_type=\"workitem_bpm\",\r\n user_ids_csv=\"user1,user2\",\r\n tenant_id=\"tenant\"\r\n)\r\n```\r\n\r\n## \ud83c\udfaf \uc774\ubaa8\uc9c0 \ub85c\uae45\r\n\r\n\ubaa8\ub4e0 \uc720\ud2f8\ub9ac\ud2f0\ub294 \uc774\ubaa8\uc9c0\ub97c \ud65c\uc6a9\ud55c \uc9c1\uad00\uc801\uc778 \ub85c\uae45\uc744 \uc81c\uacf5\ud569\ub2c8\ub2e4:\r\n\r\n- \ud83d\udd27 \ucd08\uae30\ud654 \uc644\ub8cc\r\n- \ud83d\udee0\ufe0f \ub3c4\uad6c \ub85c\ub529\r\n- \ud83d\udd0d \uac80\uc0c9 \uc2dc\uc791\r\n- \ud83d\udccb DMN \uaddc\uce59 \ucc98\ub9ac\r\n- \u2696\ufe0f \uaddc\uce59 \uc2e4\ud589\r\n- \u2705 \uc131\uacf5\r\n- \u274c \uc2e4\ud328\r\n- \u26a0\ufe0f \uacbd\uace0\r\n- \ud83d\udce8 \uc774\ubca4\ud2b8 \uc804\uc1a1\r\n\r\n## \ud83d\udccb DMN Rule Tool \uc0c1\uc138 \uc815\ubcf4\r\n\r\n### \ud83c\udfaf \uc8fc\uc694 \uae30\ub2a5\r\n- **\uc0ac\uc6a9\uc790\ubcc4 \uaddc\uce59 \uad00\ub9ac**: \ucd08\uae30\ud654 \uc2dc user_id\ub97c \uc18c\uc720\uc790\ub85c \ud574\uc11c DMN \uaddc\uce59\ub4e4\uc744 \ubbf8\ub9ac \ub85c\ub4dc\r\n- **\ucffc\ub9ac \ubd84\uc11d**: \uc0ac\uc6a9\uc790 \ucffc\ub9ac\ub97c \ubd84\uc11d\ud558\uc5ec \uad00\ub828 DMN \uaddc\uce59\ub4e4\uc744 \ucc3e\uc544 \ucd94\ub860\r\n- **XML \ud30c\uc2f1**: DMN 1.3 \ud45c\uc900 \ub124\uc784\uc2a4\ud398\uc774\uc2a4 \uc9c0\uc6d0\r\n- **\uaddc\uce59 \uc2e4\ud589**: \ube44\uc988\ub2c8\uc2a4 \uaddc\uce59\uc5d0 \ub530\ub978 \uc790\ub3d9\ud654\ub41c \uc758\uc0ac\uacb0\uc815\r\n- **\uc870\uac74 \ud3c9\uac00**: \ubcf5\uc7a1\ud55c \uc870\uac74\ubd80 \ub85c\uc9c1 \ucc98\ub9ac\r\n- **\uacb0\uacfc \ubc18\ud658**: \uaddc\uce59 \ub9e4\uce6d \uacb0\uacfc \ubc0f \ucd9c\ub825\uac12 \uc81c\uacf5\r\n\r\n### \ud83d\uddc4\ufe0f \ub370\uc774\ud130\ubca0\uc774\uc2a4 \uc2a4\ud0a4\ub9c8\r\nDMN \uaddc\uce59\uc740 `proc_def` \ud14c\uc774\ube14\uc5d0 \uc800\uc7a5\ub429\ub2c8\ub2e4:\r\n\r\n```sql\r\nCREATE TABLE proc_def (\r\n id TEXT NOT NULL,\r\n name TEXT NULL,\r\n definition JSONB NULL,\r\n bpmn TEXT NULL, -- DMN XML \uc800\uc7a5\r\n uuid UUID NOT NULL DEFAULT gen_random_uuid(),\r\n tenant_id TEXT NULL DEFAULT public.tenant_id(),\r\n isdeleted BOOLEAN NOT NULL DEFAULT FALSE,\r\n owner TEXT NULL,\r\n type TEXT NULL, -- 'dmn' \uac12\uc73c\ub85c DMN \uaddc\uce59 \uc2dd\ubcc4\r\n CONSTRAINT proc_def_pkey PRIMARY KEY (uuid)\r\n);\r\n```\r\n\r\n### \ud83d\udd27 \uc0ac\uc6a9 \uc0ac\ub840\r\n- **\ubcf4\ud5d8 \uc704\ud5d8\ub3c4 \ud3c9\uac00**: \ub098\uc774, \uc131\ubcc4, \ud761\uc5f0\uc5ec\ubd80 \uae30\ubc18 \uc704\ud5d8\ub3c4 \uacb0\uc815\r\n- **\uc2b9\uc778 \ud504\ub85c\uc138\uc2a4**: \uc870\uac74\uc5d0 \ub530\ub978 \uc790\ub3d9 \uc2b9\uc778/\uac70\ubd80\r\n- **\uac00\uaca9 \uc815\ucc45**: \ubcf5\uc7a1\ud55c \uc870\uac74\uc5d0 \ub530\ub978 \uac00\uaca9 \uacc4\uc0b0\r\n- **\ud488\uc9c8 \uac80\uc0ac**: \uc81c\ud488 \uc0ac\uc591\uc5d0 \ub530\ub978 \ub4f1\uae09 \ubd84\ub958\r\n\r\n### \ud83d\udcca \uaddc\uce59 \uc2e4\ud589 \uc608\uc2dc\r\n```python\r\n# DMN \uaddc\uce59 \ub3c4\uad6c \ucd08\uae30\ud654 (user_id\uac00 \uc18c\uc720\uc790)\r\ndmn_tool = DMNRuleTool(tenant_id=\"tenant\", user_id=\"0f61e5fd-622b-921e-f31f-fc61958021e9\")\r\n\r\n# \ucffc\ub9ac \ubd84\uc11d (\uc0ac\uc6a9\uc790\uc758 \uaddc\uce59\ub4e4\uc744 \uae30\ubc18\uc73c\ub85c \ucd94\ub860)\r\nresult = dmn_tool._run(\"\ubcf4\ud5d8 \uc704\ud5d8\ub3c4 \ud3c9\uac00\ub294 \uc5b4\ub5bb\uac8c \ud558\ub098\uc694?\")\r\n# \uacb0\uacfc: \uad00\ub828 \uaddc\uce59\ub4e4\uc744 \ucc3e\uc544 \ubd84\uc11d \uacb0\uacfc \uc81c\uacf5\r\n```\r\n\r\n## \ud83d\udccb \uc758\uc874\uc131\r\n\r\n- `supabase>=2.0.0` - \ub370\uc774\ud130\ubca0\uc774\uc2a4 \uc5f0\uacb0\r\n- `crewai>=0.152.0,<=0.175.0` - AI \uc5d0\uc774\uc804\ud2b8 \ud504\ub808\uc784\uc6cc\ud06c\r\n- `mem0ai>=0.1.94` - \uac1c\uc778\uc9c0\uc2dd \uc800\uc7a5\uc18c\r\n- `mcp>=1.6.0` - Model Context Protocol\r\n- `pydantic>=2.0.0` - \ub370\uc774\ud130 \uac80\uc99d\r\n- `a2a-sdk>=0.3.0` - A2A \ud1b5\uc2e0\r\n- `xml.etree.ElementTree` - DMN XML \ud30c\uc2f1 (Python \ub0b4\uc7a5)\r\n\r\n## \ud83d\udd04 \uac1c\ubc1c\r\n\r\n### \uac1c\ubc1c \uc758\uc874\uc131 \uc124\uce58\r\n```bash\r\npip install -e \".[dev]\"\r\n```\r\n\r\n### \ub9b4\ub9ac\uc2a4\r\n```bash\r\n# Linux/Mac\r\n./release.sh 0.1.4\r\npython -m ensurepip --upgrade\r\n# Windows\r\n.\\release.ps1 -Version 0.1.1\r\n```\r\n\r\npython -m ensurepip --upgrade\r\n\r\n## \ud83d\udcc4 \ub77c\uc774\uc120\uc2a4\r\n\r\nMIT License\r\n\r\n## \ud83e\udd1d \uae30\uc5ec\r\n\r\n\uc774\uc288 \ubc0f \ud480 \ub9ac\ud018\uc2a4\ud2b8\ub97c \ud658\uc601\ud569\ub2c8\ub2e4!\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "ProcessGPT Agent Utilities - \ub3c4\uad6c \ub85c\ub354, \uc9c0\uc2dd \uad00\ub9ac, \uc774\ubca4\ud2b8 \ub85c\uae45, \ub370\uc774\ud130\ubca0\uc774\uc2a4 \uc720\ud2f8\ub9ac\ud2f0",
"version": "0.2.3",
"project_urls": {
"Documentation": "https://github.com/your-org/process-gpt-agent-utils#readme",
"Homepage": "https://github.com/your-org/process-gpt-agent-utils",
"Issues": "https://github.com/your-org/process-gpt-agent-utils/issues",
"Repository": "https://github.com/your-org/process-gpt-agent-utils"
},
"split_keywords": [
"agent",
" processgpt",
" tools",
" knowledge",
" logging",
" database",
" crewai",
" mcp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "435943595a8dedd20c0eca082a74e5b4ee95dbf9fedeb467ebb832e3813de9d8",
"md5": "4c115d80ddf0e771b845c26ee3922cde",
"sha256": "2abe10bd25b97e8ac931207f968b4cece4cfd29cfe6b30dd090b0dde246b467a"
},
"downloads": -1,
"filename": "process_gpt_agent_utils-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4c115d80ddf0e771b845c26ee3922cde",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 39889,
"upload_time": "2025-10-24T04:35:40",
"upload_time_iso_8601": "2025-10-24T04:35:40.590613Z",
"url": "https://files.pythonhosted.org/packages/43/59/43595a8dedd20c0eca082a74e5b4ee95dbf9fedeb467ebb832e3813de9d8/process_gpt_agent_utils-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "de1ed48a1b9a8b0bade8a377622c099406cac932877af42c532e77abd72f53af",
"md5": "c1d9f9e44c335b025c286440a86b9c74",
"sha256": "6cfc82ec3971f345eb1af8f999aff98832f0337fb271ef136c0973a9f4564eec"
},
"downloads": -1,
"filename": "process_gpt_agent_utils-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "c1d9f9e44c335b025c286440a86b9c74",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 33801,
"upload_time": "2025-10-24T04:35:42",
"upload_time_iso_8601": "2025-10-24T04:35:42.045739Z",
"url": "https://files.pythonhosted.org/packages/de/1e/d48a1b9a8b0bade8a377622c099406cac932877af42c532e77abd72f53af/process_gpt_agent_utils-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-24 04:35:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "your-org",
"github_project": "process-gpt-agent-utils#readme",
"github_not_found": true,
"lcname": "process-gpt-agent-utils"
}
JSON
