Metadata-Version: 2.4
Name: cdx-dock
Version: 2.1.0
Summary: Enterprise AI Agent Interoperability, Multilingual Arbiter, Lossless CDX-Tab & Parallel 10K||2K VaultPack SDK (v2.1.0)
Author-email: "Cantor Labs (CDX Enterprise Team)" <support@cdxengine.com>
License: Commercial / 30-Day Zero-Key Sandbox
Project-URL: Homepage, https://cdxengine.com/dock
Project-URL: Documentation, https://cdxengine.com/dock_docs.html
Project-URL: Pricing, https://cdxengine.com/dock#pricing
Keywords: ai-agents,llm,langchain,crewai,autogen,hermes,token-optimization,mcp,tool-routing,data-protection,byos
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: C
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Provides-Extra: vault
Requires-Dist: cryptography>=41.0.0; extra == "vault"
Dynamic: license-file

# CDX Agent Dock (`cdx-dock` v2.1.0)

> **Connect Any AI Agent in 1 Line. Multilingual Zero-LLM Routing. Lossless CDX-Tab (55–66%). Parallel 10K∥2K Encrypted VaultPack.**  
> **Enterprise AI Agent Interoperability & Runtime Optimization SDK (Python SDK v2.1.0 & Docker Sidecar)**

[![PyPI](https://img.shields.io/pypi/v/cdx-dock.svg)](https://pypi.org/project/cdx-dock/)
[![License](https://img.shields.io/badge/License-Commercial%20%2F%20Sandbox-blue.svg)](https://cdxengine.com)
[![Interoperability](https://img.shields.io/badge/Interoperability-LangChain%20%7C%20CrewAI%20%7C%20AutoGen%20%7C%20Hermes-success.svg)](https://cdxengine.com)
[![BYOS](https://img.shields.io/badge/BYOS-Standard%20JSON%20%26%20SQLite3-emerald.svg)](https://cdxengine.com)

---

## ⚡ Why CDX Agent Dock? (3초 핵심 요약)

기업과 개발팀이 여러 AI 에이전트를 운영할 때 겪는 **3가지 가장 큰 문제**를 코드 단 1줄로 해결합니다:

| 기존 멀티 에이전트 운영의 문제점 (Before) | **CDX Agent Dock 도입 후 (After)** |
| :--- | :--- |
| **1. 프레임워크 파편화:** LangChain, CrewAI, AutoGen, Hermes 에이전트를 서로 연결하려면 수백 줄의 변환 래퍼 코드를 직접 짜고 유지보수해야 함 | **`as_crewai_tool()`, `CDXHermesDock`, `bridge()` 1줄 호출로 즉시 연결** (프레임워크 업데이트 시에도 안정적 호환) |
| **2. 폭발하는 LLM 토큰 비용:** 에이전트끼리 주고받는 긴 JSON 응답과 수십 개의 도구(MCP) 스키마 때문에 매달 API 비용이 눈덩이처럼 불어남 | **`slimmer=True, route=True`로 전달 페이로드 평균 48.2% 경량화 & 필요한 도구만 <10ms 내에 선별 주입** |
| **3. 사내 기밀·계좌·고객명 유출 불안:** 외부 LLM API로 프롬프트를 보낼 때 중요 코드명이나 계좌번호가 그대로 노출됨 | **`CDXCloak` 명시적 핀닝(`pin_secret`)으로 지정한 기밀만 로컬에서 가명화 후 응답 수신 시 100% 복원** |

---

## 🚀 30초 퀵스타트 (`pip install cdx-dock` / `pip install "cdx-dock[vault]"`)

```python
from cdx_dock import (
    as_crewai_tool, bridge, CDXCloak, create_arbiter, CDXHermesDock,
    DockSlimmer, CDXDualTokenPack, ROLE_CLOUD_PLANNER, ROLE_PAYMENT_EXECUTOR,
)

# 1. [1줄 호환] 기존 LangChain 에이전트를 CrewAI 도구로 즉시 변환 (+ 토큰 48% 절감 스위치 ON)
sql_tool = as_crewai_tool(my_langchain_sql_agent, name="db_searcher", slimmer=True)

# 2. [1줄 직결] CrewAI 리서처의 출력을 LangChain 분석가의 입력으로 바로 연결
pipeline = bridge(crewai_researcher, langchain_analyst, slimmer=True)
report = pipeline("2026년 3분기 클라우드 인프라 비용 분석")

# 3. [명시적 기밀 보호] 고객사 로컬 DB(SQLite3/JSON)에 보호할 기밀만 등록하여 안전하게 가명화·복원
cloak = CDXCloak(storage_path="./enterprise_vault.db")
cloak.pin_secret("PROJECT_NAME", "타이탄 프로젝트")
masked_prompt, session = cloak.mask_text("타이탄 프로젝트 1분기 예산 보고서 작성해줘")
restored_text = cloak.unmask_text(masked_prompt, session)

# 4. [<10ms 인메모리 도구 라우터] 수십 개 도구 중 현재 질문에 필요한 상위 도구만 로컬 메모리에서 즉시 선별
arbiter = create_arbiter(storage_path="./enterprise_tools.db")
arbiter.add_tool(
    name="erp_invoice_lookup",
    description="거래처 세금계산서 및 정산 내역을 조회합니다",
    required_params=["vendor_id", "fiscal_year"],
    tags=["세금계산서", "인보이스", "정산"]
)
decision = arbiter.route("이번 달 거래처 세금계산서 정산 내역 찾아줘", top_k=2)
print(decision.tool_name, decision.latency_ms)

# 5. [Hermes 에이전트 & SKILL.md 연동] 터미널 작업형 Hermes 에이전트에 토큰 절감 + 기밀 핀닝 + Top-K 라우팅 결합
hermes_dock = CDXHermesDock(hermes_agent, slimmer=True, cloak=True, route=True)
res = hermes_dock.invoke(
    "배포 스크립트 점검 후 타이탄 프로젝트 서버 상태 확인해줘",
    skills=my_skills_catalog,
    pin_secrets={"PROJECT_NAME": "타이탄 프로젝트"}
)

# 6. [CDX-CoT-Guard Lite] 추론 모델(<think>) 무한 루프 조기 차단 및 Single-Slot INT8 KV-Cache 댐핑 (~75% 절감)
from cdx_dock import CDXCoTProxyMiddleware, CDXCoTLiteMiddleware
cot_proxy = CDXCoTProxyMiddleware(min_think_steps=6, enable_slimmer=True, enable_cloak=True)
guard_res = cot_proxy.inspect_and_guard_stream(reasoning_chunks, lang="ko")

# 7. [CDX-TokenPack-10K Lite] 벡터 DB 없이 로컬 폴더(pack_dir) SQLite WAL로 8개국어 10,000토큰 장기 기억 실시간 공유
from cdx_dock import CDXTokenPack10KLite, CDXLangChainDock, CDXCrewAIDock
pack = CDXTokenPack10KLite(pack_dir="./shared_agent_memory")
pack.ingest("[핵심 규격] 프로덕션 DB 커넥션 타임아웃은 1500ms, 최대 풀 사이즈는 64개로 고정한다.")
lc_dock   = CDXLangChainDock(langchain_agent, pack_dir="./shared_agent_memory")
crew_dock = CDXCrewAIDock(crewai_agent, pack_dir="./shared_agent_memory")

# 8. [v2.1.0 CDX-Tab 무손실 표 압축 & CDX-VaultPack-2K (10K || 2K 병렬 암호화 금고)]
slimmer = DockSlimmer()
encoded_tab = slimmer.to_mode_b([{"id": i, "status": "COMPLETED", "region": "ap-northeast-2"} for i in range(25)])
restored_rows = slimmer.to_mode_a(encoded_tab)  # CDXTAB1: 54.7~66% 무손실 압축 및 100% 원본 복원

# 100% 고객 로컬 Zero-Knowledge AES-256-GCM + AAD + PCI CVV 소각 + 1-Bit RBAC (Sandbox 체험 · Growth+ 기본 포함)
dual = CDXDualTokenPack(pack_dir="./agent_dual_pack")
turn = dual.ingest_turn("결제 카드 4532-1122-3344-5566 CVV=831, 이메일 ceo@acme.io")
card_h = [h for h in turn["vault"]["handles"] if ":CARD:" in h][0]
assert not dual.resolve_for_tool(card_h, ROLE_CLOUD_PLANNER, True)["authorized"]
assert dual.resolve_for_tool(card_h, ROLE_PAYMENT_EXECUTOR, True)["authorized"]

# 8. [CFO/CTO/CISO 정산·품의 보고서 엔진] 외부 전송 0 Byte로 월간 API 비용 절감 정산서 즉시 생성
from cdx_dock import CDXInternalReportBuilder
report_md = CDXInternalReportBuilder().render_report('cfo_roi_settlement_report')
```

---

## 🧩 에이전트 구축 방식 비교 및 `cdx-dock` 아키텍처 원리

### 1. 단순 프롬프트(개념)형 에이전트 vs. 4대 엔터프라이즈 에이전트 프레임워크

단순히 시스템 프롬프트에 *"너는 친절한 재무 상담원이다"*라고 적어 만드는 **단순 프롬프트(개념)형 에이전트**는 대화는 가능하지만, 사내 DB 조회·코드 실행·작업 순서 강제·다중 에이전트 검수가 불가능합니다. 이를 해결하기 위해 기업들은 각기 다른 철학의 **에이전트 프레임워크**를 사용하며, `cdx-dock`은 이 모든 프레임워크를 1줄로 연결하고 보호합니다:

| 에이전트 방식 / 프레임워크 | 핵심 작동 원리 (비유) | 주요 강점 | 프레임워크 단독 사용 시 한계 | **`cdx-dock` 결합 시 해결 효과** |
| :--- | :--- | :--- | :--- | :--- |
| **단순 프롬프트형**<br>*(Custom GPTs 등)* | **말로만 지시받은 상담원**<br>시스템 프롬프트(페르소나)만 부여 | 1분 만에 제작 가능 | 외부 시스템 제어 불가, 작업 순서 통제 불가 | 에이전트 프레임워크로 전환 시 표준 어댑터 제공 |
| **LangChain / LangGraph** | **컨베이어 벨트 공장 (DAG)**<br>`A단계 → B단계 → 조건분기`를 그래프/체인으로 엄격히 연결 | 엔터프라이즈 백엔드·금융권 워크플로우 정밀 통제 | 체인 단계마다 누적되는 JSON 컨텍스트로 인한 토큰 급증 | `CDXLangChainDock` / `as_langchain_tool`로 단계 간 페이로드 **48.2% 경량화** |
| **CrewAI** | **회사 조직도 & 역할극 팀**<br>`직책(Role)`, `목표(Goal)`, `배경(Backstory)`을 부여해 팀처럼 분업 | 직관적인 기획·리서치·보고서 작성 멀티 에이전트 구성 | 에이전트 간 보고서 전달 시 컨텍스트 비대화 및 타 프레임워크 도구 호환 불가 | `CDXCrewAIDock` / `as_crewai_tool`로 타 프레임워크 도구를 1줄 이식 및 압축 |
| **Microsoft AutoGen** | **끝장 토론 회의실 (GroupChat)**<br>작성자·검수자·실행자 에이전트가 채팅방에서 합의될 때까지 루프 대화 | 코드 작성·디버깅·복합 수리 추론에 강점 | 다자간 대화 루프가 길어질수록 토큰 비용이 기하급수적으로 폭발 | `CDXAutoGenDock` / `as_autogen_agent`로 대화 턴마다 메시지 자동 슬리밍 |
| **Nous Hermes Agent**<br>*(agentskills.io)* | **업무 수첩(`SKILL.md`)을 적는 터미널 실무자**<br>도커/SSH/터미널에서 직접 일하며 작업 절차를 마크다운 스킬로 기록 | 오픈모델 기반 자율 서버 운영 및 절차적 스킬 축적 | 수십 개의 `SKILL.md`와 MCP 도구 전체 주입 시 문맥 한계 초과 및 기밀 노출 위험 | `CDXHermesDock`으로 **Top-K 스킬만 `<10ms` 선별 주입 + `SKILL.md` 압축 + 기밀 핀닝** |

---

### 2. 왜 `CDXCloak` 수동 마스킹(`pin_secret`)은 모든 에이전트 프레임워크에서 오탐 없이 100% 작동하는가?

기존 보안 솔루션처럼 정규식(Regex)이나 AI 추측으로 민감정보를 자동 탐색하면 일반 날짜(`2026-10-17`)나 수량까지 마스킹해 에이전트 추론을 망가뜨리거나, 반대로 사내 프로젝트명(`타이탄 프로젝트`)을 놓치는 사고가 발생합니다. `cdx-dock`이 기본값 `auto_regex=False` 기반의 **명시적 핀닝(`pin_secret`)**으로 모든 프레임워크에서 100% 정확하게 작동하는 이유는 다음 **2가지 구조적 원리** 때문입니다:

1. **프레임워크 변수 템플릿(Prompt Template) 구조의 필연성:**
   - 모든 엔터프라이즈 에이전트(LangChain, CrewAI, AutoGen, Hermes)는 하드코딩된 문장이 아니라 **프롬프트 템플릿과 변수 바인딩**(`"고객 {customer_name}님의 계좌 {account_num}에서 {amount}원을 이체해줘"`) 방식으로 제작됩니다.
   - 즉, 개발자는 DB나 API에서 가져온 **어떤 파이썬 변수(`customer_name`, `account_num`, `db_password`)가 민감정보인지 코드 작성 시점에 이미 정확히 알고 있으므로**, 추측할 필요 없이 해당 변수를 `cloak.pin_secret("CUSTOMER_NAME", customer_name)`처럼 1줄로 콕 집어 지정할 수 있습니다.
2. **최종 출입구(Final Outbound Gateway) 텍스트 직렬화 법칙:**
   - 각 프레임워크가 내부에서 컨베이어 벨트(LangChain)로 돌리든, 역할극(CrewAI)을 하든, 토론(AutoGen)을 하든, 터미널 스킬(Hermes)을 읽든 상관없이 **외부 LLM 서버(OpenAI, Claude, Gemini 등)로 출발하는 마지막 순간(`invoke` / `run`)에는 반드시 하나의 평문 문자열(String/JSON)로 합쳐져서 나갑니다.**
   - `cdx-dock` 어댑터는 바로 이 **최종 출입구(Gateway)**를 가로채어, 출발 직전 텍스트에서 등록된 기밀 변수값만 결정론적 가명 토큰(`[[VAULT_PIN_CUSTOMER_NAME_...]]`)으로 치환해 내보내고, LLM 응답이 돌아오면 로컬 메모리에서 즉시 원래 값으로 복원(`unmask_text` — 괄호 변형 및 한국어 조사 자동 교정 포함)합니다. 덕분에 LLM은 문맥과 추론 정확도를 100% 유지하면서도 실제 기밀값은 단 1바이트도 알 수 없습니다.

---

### 3. `Mode A` vs `Mode B`는 무엇이며, 왜 양방향 왕복 변환(`slimmer=True`)이 필요한가?

`DockSlimmer`는 에이전트 파이프라인에서 **"누가 데이터를 읽느냐(기계 시스템 vs AI 모델)"**에 따라 포맷을 전환하는 양방향 코덱입니다.

| 구분 | **Mode A (표준 JSON — DB·서버 시스템용)** | **Mode B (구조적 압축 — 에이전트·LLM 전달용)** |
| :--- | :--- | :--- |
| **구조 특징** | 중괄호 `{ }`, 대괄호 `[ ]`, 쌍따옴표 `" "`, 쉼표 `,`가 매 줄마다 반복됨 | 기호 거품을 모두 제거하고 **들여쓰기(Indentation)와 콜론(`:`)**만으로 계층 구조 100% 보존 |
| **토큰 소모량** | **142 Tokens** (기호 하나하나가 전부 토큰 비용으로 청구됨) | **74 Tokens (-48.2% 절감)** — LLM 추론 정확도 100% 동일 |
| **주 용도** | 사내 DB 저장, REST API 응답, 파이썬 `json.loads()` 파싱 | LangChain·CrewAI·AutoGen·Hermes 에이전트 간 메시지 전달 및 LLM 프롬프트 주입 |

- **보낼 때는 `Mode B`로 압축 (`to_mode_b`):** LLM은 굳이 쌍따옴표(`"`)와 중괄호(`{}`)가 없어도 들여쓰기된 `Mode B` 텍스트를 100% 똑같이 이해하고 추론하므로, 에이전트 간 대화 시 토큰 비용과 지연 시간을 절반 가까이 아낍니다.
- **받을 때는 `Mode A`로 무손실 복원 (`to_mode_a`):** AI 작업이 끝나고 결과를 사내 DB나 백엔드 API에 저장할 때는 프로그램 파서가 읽어야 하므로 `DockSlimmer.to_mode_a()`를 통해 단 1글자 손실도 없이 원래의 표준 JSON(`Mode A`)으로 100% 되돌려 놓습니다.

---

## 💾 고객 자체 저장소 (`BYOS`) 100% 표준 규격 원칙

- **독자 규격 0%:** 고객 디스크(`storage_path`)에는 독자 바이너리 포맷을 일절 사용하지 않으며, 오직 **국제 표준 `UTF-8 JSON (.json)`** 또는 **표준 관계형 `SQLite3 (.db / .sqlite)` 테이블(`cdx_explicit_vault`, `cdx_arbiter_tools`)**로만 저장됩니다.
- DBeaver, SQLite Browser, VS Code 등 모든 표준 DB 관리 도구로 직접 조회·수정·백업할 수 있습니다.

---

## 📊 공식 SaaS 요금제 및 월간 스텝 쿼터 매트릭스 (Unified Official Pricing)

고객사가 절감한 LLM API 비용의 **70% 이상을 고객사 순이익(Net Profit)으로 남기고**, 절감액의 일부만으로 구독료를 충당하는 **상호 이익(Win-Win) 구조**입니다:

| 플랜 (Tier) | 월 구독료 (USD) | 월간 스텝 쿼터 (Monthly Steps) | 동시 에이전트 | 쿼터 도달 시 정책 (Zero-Downtime Policy) |
| :--- | :---: | :---: | :---: | :--- |
| **🟢 SANDBOX** | **$0 / 월** | **150,000 steps** *(30일 무료 체험)* | 최대 2개 | 30일 체험 기간 내 전 기능 검증 제공 |
| **⚡ STARTER** | **$390 / 월** | **500,000 steps** | 최대 5개 | **Zero-Downtime Safe Pass-Through + Upgrade Notice** |
| **🔵 GROWTH** | **$1,490 / 월** | **3,000,000 steps** | 최대 15개 | **Zero-Downtime Safe Pass-Through + Upgrade Notice** |
| **🟠 SCALE** | **$4,900 / 월** | **15,000,000 steps** | 최대 40개 | **Zero-Downtime Safe Pass-Through + Upgrade Notice** |
| **👑 ENTERPRISE** | **$14,900 / 월**<br>*(Custom / On-Prem 별도 협의)* | **60,000,000 steps** | 무제한 | **Zero-Downtime Safe Pass-Through + Upgrade Notice** |

> **🛡️ 무중단 안전 패스스루 보장 (Zero-Downtime Safe Pass-Through + Upgrade Notice):**  
> 상용 플랜 운용 중 월간 스텝 쿼터(Monthly Quota)에 도달하더라도 프로덕션 에이전트 파이프라인은 **절대 중단(Crash/Hard-Stop)되지 않습니다.** 초과 트래픽은 원본 그대로 안전하게 통과(**Safe Pass-Through**)되며, 관리 콘솔 및 로그를 통해 플랜 업그레이드 안내(**Upgrade Notice**)만 비침습적으로 발송됩니다. 긴급 점검 시 환경변수 `CDX_BYPASS=1` 설정으로 즉시 패스스루 전환도 가능합니다.

---

Copyright © 2026 Cantor Labs (Cantor Diagonal eXpress). All rights reserved.
