Knowledge Work SDK

반복, 검증, 그리고 구조적 사고가 필요한 지식 노동 (knowledge work)—즉, 조사, 분석, 작성 및 의사 결정 작업을 수행하는 AI 에이전트를 구축하기 위한 Python SDK입니다.

지식 노동이 코드와 다른 이유

코드는 피드백 루프가 긴밀합니다: 코드 작성 → 테스트 실행 → 오류 수정 → 반복. 솔루션 공간(solution space)이 제한적입니다. 대개 하나의 정답이 존재하며, 자동화된 테스트가 정답을 찾았는지 알려줍니다.

지식 노동은 근본적으로 다릅니다. 솔루션 공간이 방대하고 명확하게 정의되지 않았습니다 (underspecified). "시장 분석"은 두 문단의 요약일 수도 있고, 50페이지 분량의 심층 분석일 수도 있습니다. "전략 권고"는 비용, 속도, 리스크, 혁신 또는 이들의 조합 중 무엇을 강조할 수도 있습니다. 합격/불합격(pass/fail)을 반환하는 테스트 스위트(test suite)가 존재하지 않습니다.

우리의 접근 방식: 지식 노동은 자연적인 검증 수단이 부족하기 때문에, 우리는 *루브릭 (rubrics)*을 사용하여 검증 수단을 합성합니다. 루브릭은 실행이 시작되기 전에 무엇이 "좋은" 결과물인지 정의하며, 다음과 같은 기능을 가능하게 합니다:

• 자기 검증 (Self-verification): 에이전트가 명시적인 기준에 따라 자신의 작업물을 스스로 확인합니다.
• 반복적 개선 (Iterative refinement): 검증에 실패하면 타겟팅된 개선을 트리거합니다.
• 투명한 평가 (Transparent evaluation): 인간이 루브릭과 검증 프로세스를 감사(audit)할 수 있습니다.

이 SDK는 지식 노동의 본질적으로 개방적인 특성에 구조를 부여하는 **자기 검증 에이전트 루프 (self-verifying agentic loop)**를 구현합니다. 에이전트는 웹 검색, 파일 읽기 및 쓰기, 코드 실행, 아티팩트(artifacts) 생성, 사용자에게 명확한 설명 요청 등을 수행할 수 있으며, 이 모든 과정은 자신의 출력을 검증하는 오케스트레이터(orchestrator)를 통해 조정됩니다.

이것을 공유하는 이유

이 프로젝트는 지식 작업에 대한 RL (강화학습) 훈련을 실행하기 위한 하네스(harness)로 시작되었습니다. 제가 이것을 오픈 소스로 공개하는 이유는 다음과 같습니다:

1. 지식 워크플로우는 아직 충분히 탐구되지 않았습니다. 대부분의 AI 도구는 코드에 집중합니다. 하지만 조사, 분석, 전략, 작성과 같은 지식 노동은 대부분의 전문가가 시간을 보내는 영역입니다. 이러한 시스템을 구축하기 위한 기본 요소(primitives)는 아직 잘 확립되지 않았습니다.

2. 이것은 유용한 빌딩 블록 (building block)이 될 수 있습니다. 만약 AI가 연구를 수행하거나, 추천을 하거나, 문서를 생성하는 과정이 포함된 제품을 만들고 있다면, 이 검증 루프 (verification loop)가 수 주간의 반복 작업 (iteration) 시간을 절약해 줄 수 있습니다.

3. 모델들은 여전히 검증 (verification)에 어려움을 겪고 있습니다. 자기 점검 (self-check) 단계가 가장 취약한 연결 고리입니다. 만약 이 방식이 채택된다면, 오픈 소스 모델 제공업체는 루브릭 (rubric) 기반 검증에 특화하여 학습함으로써 생태계 전체를 개선할 수 있을 것입니다.

저는 이러한 아이디어들이 독점적으로 유지되기보다 널리 퍼지는 것을 보고 싶습니다.

검증 루프 (The Verification Loop)

┌─────────────────────────────────────────────────────────────┐
│  1. 브리프 생성 (BRIEF CREATION)                            │
│     → 작업을 구조화된 요구사항으로 공식화                   │
...

설치 (Installation)

의존성으로 설치 (권장) (As a dependency)

uv pip install git+https://github.com/ClioAI/kw-sdk.git

또는 pyproject.toml에 추가하세요:

dependencies = [
    "verif @ git+https://github.com/ClioAI/kw-sdk.git",
]

개발용 (For development)

git clone https://github.com/ClioAI/kw-sdk.git
cd kw-sdk
uv venv && source .venv/bin/activate
...

.env 파일을 생성하세요:

GEMINI_API_KEY=your_gemini_key
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key

빠른 시작 (Quick Start)

from verif import RLHarness

harness = RLHarness(provider="gemini")  # 또는 "openai" 또는 "anthropic"
...

import asyncio
from verif import AsyncRLHarness

...

---

실행 모드 (Execution Modes)

SDK는 다양한 유형의 지식 노동 (knowledge work)에 최적화된 서로 다른 모드를 제공합니다:

모드	최적의 용도	루브릭 전략 (Rubric Strategy)
standard	일반적인 연구 및 분석	실행 중에 자동 생성
...

지원되는 제공업체 (Supported Providers)

제공업체 (Provider)	설정 (Config)	사고 제어 (Thinking Control)
Gemini	provider="gemini"	thinking_level: LOW / MEDIUM / HIGH
...

표준 모드 (Standard Mode, 기본값)

일반적인 작업을 위한 모드입니다. 오케스트레이터 (Orchestrator)가 짧은 요약과 루브릭 (Rubric)을 자동으로 생성합니다.

from verif import RLHarness

harness = RLHarness(provider="gemini", enable_search=True)
...

참조: examples/standard_mode.py

플랜 모드 (Plan Mode)

전략에 대한 명시적인 제어를 통해 구조화된 실행을 수행할 때 사용합니다.

from verif import RLHarness

harness = RLHarness(provider="gemini", enable_search=True)
...

참조: examples/plan_mode.py

탐색 모드 (Explore Mode)

확산적 사고 (Divergent thinking)—즉, 여러 개의 뚜렷한 관점을 생성하기 위한 모드입니다. 표준 모드 (Standard mode)와 달리, 탐색 모드는 단 하나의 "정답"을 위해 최적화되지 않습니다. 대신 솔루션 공간 (Solution space)을 매핑합니다.

탐색 모드가 표준 모드와 다른 점:

• 정확도 루브릭 (Accuracy rubric) 없음. 표준 모드는 정확성을 검증하기 위해 루브릭을 생성합니다. 탐색 모드는 품질 체크리스트를 사용합니다. 즉, 관점들이 서로 구별되는가? 서로 다른 가설들을 다루고 있는가? 등을 확인합니다.
• 격차 식별 (Gap identification) 강제. 각 관점은 반드시 자신의 가설 (Assumptions)과 무엇이 이를 무너뜨릴 수 있는지를 명시해야 합니다. 이를 통해 단일 답변으로는 찾을 수 없는 사각지대 (Blind spots)를 드러냅니다.
• 수렴보다 양 (Quantity over convergence). 표준 모드는 하나의 검증된 답변을 향해 반복합니다. 탐색 모드는 서로 모순될 수 있는 N개의 병렬적인 답변을 생성하며, 그것이 바로 핵심입니다.

from verif import RLHarness

harness = RLHarness(provider="gemini", enable_search=True)
...

각 관점에는 다음 내용이 포함됩니다:

• 솔루션/권장 사항
• 가설 (Assumptions): 이것이 작동하기 위해 반드시 참이어야 하는 것 (예: "멀티 리전 복제를 위한 예산이 있다고 가정함")
• 반사실 (Counterfactual): 이것을 실패하게 만들 수 있는 요소 (예: "지연 시간 요구 사항이 10ms 미만으로 엄격해지면 작동하지 않음")

출력은 **세트 수준의 격차 (Set-level gaps)**로 끝납니다. 즉, 전체 세트에서 누락된 것은 무엇인가?를 알려줍니다. 이는 어떤 관점들이 다뤄지지 않았는지 알려줍니다. 예를 들어, 모든 관점이 단일 클라우드 제공업체를 가정했거나, 규제 제약 조건을 고려하지 않았을 수 있습니다. 이러한 격차는 종종 관점 그 자체보다 더 가치 있는 정보를 제공합니다.

무엇이 올바른 질문인지 확신할 수 없거나, "최선의" 답변이 명시되지 않은 제약 조건에 달려 있을 때 탐색 모드를 사용하세요.

참조: examples/explore_mode.py

반복 모드 (Iterate Mode)

사용자 피드백을 기반으로 기존 작업물을 개선하기 위한 모드입니다.

# 초기 실행
result = harness.run_single(task="Write a market analysis memo.")

...

참조: examples/iterate_workflow.py

체크포인팅 및 재개 (Checkpointing & Resume)

매 단계마다 실행 상태를 저장합니다. 선택적인 피드백 및 루브릭 (rubric) 업데이트와 함께 어떤 체크포인트에서든 재개할 수 있습니다.

from verif import RLHarness

harness = RLHarness(provider="gemini", enable_search=True)
...

참조: tests/test_checkpoint.py

---

워크플로 구성하기 (Composing Workflows)

탐색 (Explore) → 선택 (Select) → 실행 (Execute)

가장 강력한 패턴입니다: 브레인스토밍을 하고, 최선의 접근 방식을 선택한 다음, 실행합니다.

# 1단계: 여러 접근 방식 탐색
explore_result = harness.run_single(task=TASK, mode="explore", num_takes=3)
takes = explore_result.answer.split("===")
...

참조: examples/end_to_end_workflow.py

---

기능 활성화하기 (Enabling Capabilities)

웹 검색 (Web Search)

harness = RLHarness(
    provider="gemini",
    enable_search=True,  # search_web 도구 추가
...

참조: examples/standard_with_search.py

파일 시스템 액세스 (File System Access)

harness = RLHarness(
    provider="gemini",
    enable_bash=True,  # search_files 도구 추가 (ls, find, grep, cat)
...

코드 실행 (Code Execution)

from verif.executor import SubprocessExecutor

harness = RLHarness(
...

코드 실행기 (code executor)는 상태 유지 (stateful) 방식입니다. 변수는 호출 간에 유지됩니다. artifacts_dir에 저장된 파일은 추적되어 반환됩니다.

참조: examples/with_code_execution.py

파일 작업하기 (Working with Files)

from verif import RLHarness, Attachment, Prompt

# 미리보기가 포함된 첨부 파일 생성
...

참조: examples/with_files.py

사용자 확인 (User Clarification, ask_user)

작업이 모호할 때 대화형 확인 기능을 활성화합니다:

import threading
from verif import RLHarness, ProviderConfig

...

오케스트레이터 (Orchestrator)는 명확한 설명을 요청하기 위해 ask_user를 호출할 수 있습니다. 모든 대기 중인 질문에 답변이 완료될 때까지 검증 (Verification) 프로세스는 차단됩니다.

참조: tests/test_ask_user.py

---

스트리밍 이벤트 (Streaming Events)

from verif import RLHarness, HistoryEntry

def on_event(event: HistoryEntry):
...

참조: examples/with_streaming.py

---

설정 참조 (Configuration Reference)

from verif import RLHarness, ProviderConfig, CompactionConfig
from verif.executor import SubprocessExecutor

...

---

결과 객체 (Result Objects)

RunResult

result = harness.run_single(task)

result.task          # 원본 작업 텍스트
...

실행 추적 (Execution Trace)

# 포맷팅된 히스토리 가져오기
print(harness.get_history_markdown())
print(harness.get_history_text())
...

---

오케스트레이터가 사용할 수 있는 도구 (Tools Available to Orchestrator)

도구	설명	사용 가능 시점
create_brief	작업 요구사항 공식화	standard, explore
...

---

TODO

<!-- 이 내용을 최신 상태로 유지하세요. 항목이 완료되면 체크 표시를 하세요. -->

완료됨 (Done)

• 상태 체크포인트 및 재개 (State checkpointing & resume) — 매 단계마다 저장하며, 피드백 + 루브릭 (Rubric) 업데이트와 함께 모든 체크포인트에서 포크 (Fork)할 수 있습니다. Checkpointing & Resume를 참조하세요.
• Anthropic 프로바이더 (Anthropic provider) — 스트리밍, 확장된 사고 (Extended thinking), 네이티브 웹 검색 기능이 포함된 Claude.
• 컨텍스트 압축 (Context compaction) — 토큰 제한에 도달할 때 컨텍스트의 중간 부분을 요약합니다.
• 탐색 모드 (Explore mode) — 가정, 반사실 (Counterfactuals), 집합 수준의 격차 (Set-level gaps)를 포함하여 N개의 서로 다른 접근 방식을 생성합니다.
• 반복 모드 (Iterate mode) — 피드백 분류 (루브릭 vs 답변 수준)를 통한 상태 비저장 (Stateless) 정교화.
• 커스텀 모드 (Custom modes) — 런타임에 새로운 실행 모드를 등록합니다.
• 원격 실행기 (Remote executor) — SSE를 통해 코드 실행을 프론트엔드/브라우저로 위임합니다.
• ask_user 도구 — 오케스트레이터가 명확한 설명을 요청할 수 있으며, 답변이 완료될 때까지 검증이 차단됩니다.

진행 중 (In Progress)

• Anthropic 체크포인팅 (checkpointing) — 체크포인팅은 Gemini 및 OpenAI에서 작동합니다. Anthropic은 아직 완전히 테스트되지 않았습니다. 복잡한 점은 deep-copy 및 컨텍스트 재생(context replay) 과정에서 올바르게 유지되어야 하는 인터리브된 사고 블록(interleaved thinking blocks, 사고 + 시그니처 쌍) 때문입니다.
• Anthropic을 위한 압축 (Compaction) — SDK는 서버 측 컨텍스트 캐싱(context caching)을 사용하는 대신 자체적인 압축(중간 내용 요약, 최근 대화 유지)을 수행합니다. Anthropic의 200K 윈도우(window) 환경에서 스트레스 테스트를 거치지 않았습니다.

계획됨 (Planned)

• 컴퓨터 사용 서브에이전트 (Computer use subagent) — GUI 상호작용(양식 채우기, 앱 탐색, 웹 인터페이스에서 데이터 추출)을 위해 컴퓨터 사용이 가능한 서브에이전트를 연결합니다.
• 멀티 앱 워크플로우 (Multi-app workflows) — 단일 실행 내에서 브라우저, 스프레드시트, 문서를 가로질러 작업합니다.
• 병렬 검증 (Parallel verification) — 여러 번의 검증 패스를 실행하고 합의(consensus)를 도출하여, 단일 검증자의 편향(bias)을 줄입니다.
• 루브릭 품질 점수 산정 (Rubric quality scoring) — 메타 평가(Meta-evaluation): 루브릭을 검증에 사용하기 전에 루브릭 자체의 점수를 매깁니다. "항상 통과"되는 루브릭을 조기에 발견합니다.
• 실행 결과의 구조화된 출력 (Structured output from runs) — 단일 답변 문자열 대신 타입이 지정된 섹션(요약, 권장 사항, 증거)을 반환합니다.
• 평가 프레임워크 (Eval framework) — 벤치마크 작업 세트에 대해 제공자/모드/루브릭 전략 간의 체계적인 비교를 수행합니다. run_eval이 존재하지만 점수 산정 및 보고 기능이 필요합니다.
• 토큰 사용량 추적 (Token usage tracking) — 비용 분석을 위해 단계별(브리핑, 루브릭, 실행, 검증) 실행당 토큰 수를 표시합니다.
• 혼합 모델 오케스트레이션 (Mixed-model orchestration) — 오케스트레이터와 서브에이전트에 서로 다른 모델을 사용합니다 (예: 오케스트레이션에는 Opus, 검색 서브에이전트에는 Flash 사용). 현재는 동일한 제공자가 둘 다 처리합니다. 강화학습 (RL) 훈련은 단일 정책(single policy)에서 이점이 있기 때문에 이 방식을 유지했지만, 프로덕션 환경에서는 저렴한 작업을 더 작은 모델로 라우팅함으로써 얻는 비용 절감 효과가 상당할 것입니다.

---

예시 (Examples)

예시 (Examples)

예시	설명
standard_mode.py	자동 루브릭 (auto rubric)을 사용하는 기본 작업
...

¹ 철학에 대해서는 TOOL_CALLING_GUIDE.md를 참조하세요: MCP 서버를 건너뛰고 코드를 도구 (tools)로 사용합니다.
² 커스텀 모드 (custom modes) 및 프로바이더 (providers) 생성에 대해서는 EXTENSIONS.md를 참조하세요.

예시 출력 (Example Outputs)

샘플 실행 결과는 examples/outputs/를 참조하세요:

출력	설명
standard_mode_output.md	자동 생성된 루브릭 (rubric)을 사용한 탄소세 (Carbon tax) 대 배출권 거래제 (cap-and-trade) 분석
...

---

추가 가이드 (Additional Guides)