⚒️ dvergr
Clojars Project
CircleCI
Slack
Docs
담론 프레임워크 내 에이전트를 위한 FRP 프로그래밍 모델. 에이전트는 연속 시간의 방(room)에서 반응하는 프로세스이며, 인간, LLM, 스크립트가 동일한 형태로 참여하여 작은 pub/sub 커널을 통해 태그가 지정된 메시지로 구성됩니다.
사용자는 에이전트를 프로그래밍하고 이를 다중 에이전트 워크플로우로 구성할 수 있습니다. 그리고 에이전트가 빌드되는 동일한 라이브 미디움에서 실행되기 때문에, 에이전트는 심지어 포크된 환경(forked world)에서 스스로 워크플로우를 구성하는 것까지 시작할 수 있습니다 — 이는 기본 모드가 아닌 초기적이고 탐색적인 방식입니다.
Spindel (함수형 반응형 런타임), Datahike (불변 Datalog), 그리고 Yggdrasil (git + 데이터베이스 전반에 걸친 copy-on-write 브랜칭)을 기반으로 구축되었습니다.
제공하는 것들
다중 에이전트 시스템을 위한 프로그래밍 모델:
-
💬 담론 방(Discourse rooms) — 인간과 LLM 에이전트가 동등한 참여자로서 메시지를 교환합니다.
-
🏷️ 태그 라우팅(Tagged routing) — 에이전트가 :escalation/budget, 정책 봇 등을 에스컬레이션시킵니다.
-
🌿 기질 포크(Substrate forks) —
-
🧪 clojure_eval — 안전한 코드 샌드박스(safe code sandbox) — 에이전트의 주요 프로그래밍 표면:
dvergr 월드(룸, 지식, 입력)에 연결된 격리된 SCI 컨텍스트에서 Clojure eval을 사용하며, 새로운 의존성은 인간 승인 게이트를 통해 로드됩니다.
-
📦 자체 소유의 실제 작업 공간(A real workspace it owns) — 각 룸은 dvergr-sandbox 표준 라이브러리를 자체 git 레포지토리로 복제합니다. 에이전트는 그곳에서 코드를 require하고, 수정하며, git commit합니다. 작업 공간은 룸과 포크(forks)/병합(merges)됩니다.
-
🛠️ 주변의 엄선된 도구 세트(A curated toolset around it) — 구조화된 읽기/쓰기/편집 기능, 구조적 Clojure 편집, 테스트 러너, 그리고 격리된 muschel 셸 (파싱 및 파일 시스템 샌드박스 처리되며, 원시 bash -c가 아님)을 제공합니다.
-
📡 ~25개의 입력 소스(intake sources) — 읽기 전용 데이터 피드(Hacker News, Reddit, RSS, 웹/YouTube/트윗 가져오기, 메일, SEC-EDGAR, GitHub 등)가 작업 공간의 편집 가능한 소스로 전달됩니다. 에이전트는 이를 읽고 복사하며 확장하여 Datahike 지식 그래프로 끌어들입니다.
-
🔐 경계 자격 증명 처리(Boundary credential handling) — API 키가 필요한 입력 소스는 샌드박스 내에 플레이스홀더를 받습니다. 게이트화된 HTTP 이그레스는 경계 도메인에서만 실제 키로 교체하고 응답에서 이를 제거하므로, 에이전트는 자신이 결코 보지 못하는 키를 사용합니다 (design).
-
🔌 다중 LLM 제공업체(Multiple LLM providers) — Anthropic API/Claude Code, 네이티브 Codex 구독 전송, OpenAI API, Fireworks 또는 모든 OpenAI 호환 엔드포인트 등—에이전트별로 교체가 가능합니다.
-
🪙 예산 및 회계(Budgets & accounting) — 모든 턴은 에이전트당 예산을 기준으로 마이크로달러로 측정됩니다. 에이전트는 체크포인트를 만나면 :directive/raise-budget을 통해 추가 자원을 요청할 수 있으며, 모든 지출은 원장(ledger)에 기록되어 비용이 제한 범위 내에 머물도록 합니다.
-
🧠 컨텍스트 관리(Context management) — 장시간 실행 시 도구 출력물을 자동으로 가지치기하고 모델 창이 채워짐에 따라 이전 턴을 요약하여, 에이전트가 컨텍스트 오버플로우 없이 긴 대화를 유지할 수 있도록 합니다.
-
💾 영속적 + 다중 프론트엔드(Persistent + multi-frontend) — 룸, 기록 및 지식은 [생략됨]에서 영구적으로 보존됩니다.
Datahike; TUI, 웹 대시보드, Telegram 또는 nREPL에서 동일한 데몬을 구동합니다.
- 🎙️ 음성 및 비전(Voice & vision) — 하나의 음성 인식 경로를 통해 모든 프론트엔드(웹 마이크, Telegram 음성 메모, REPL, TUI
^R)에 말할 수 있으며; 인보이스/영수증에서 스키마 형태의 JSON을 추출하는 방어적인 vision/extract 기능을 통해 에이전트에게 이미지와 PDF를 전달합니다(media)
- 🔁 자가 프로그래밍 기질(Self-programming substrate) — 에이전트는 자신이 구축된 동일한 SCI/FRP 환경에서 작동하므로, 에이전트는
merge에 의해 제한되고 예산으로 경계가 지어진 포크(fork) 내에서 다른 에이전트를 생성하고 워크플로우를 연결할 수 있습니다. (우리가 탐색 중인 초기 기능이며 기본 모드는 아닙니다.)
확인하기 (See it)
에이전트, 실시간 토큰 비용, 접을 수 있는 사고 과정/도구 활동이 포함된 하나의 공간 — 브라우저에서든 터미널에서든 동일한 공간입니다.
60초 빠른 시작 (60-second quickstart)
git clone https://github.com/replikativ/dvergr.git
cd dvergr
clojure -M:cli
API 키를 내보내기(export)하거나 (config.local.edn에 설정) 제공업체(provider)를 선택하세요:
export ANTHROPIC_API_KEY=sk-ant-...
...
배포된 기본 설정은 에이전트의 제공업체를 고정(unpinned) 상태로 두어, 사용 가능한 최고의 제공업체(우선순위: Anthropic → Fireworks → OpenAI → 네이티브 Codex 구독 → 격리된 Codex CLI → 로컬 claude CLI)와 기본 모델을 자동으로 선택합니다. 위에 나열된 키 중 하나를 설정하거나 지원되는 CLI에 로그인하면 작동하며, 특정 제공업체와 일치시킬 필요가 없습니다. :provider/:model을 config.local.edn에서 고정하여 강제할 수 있습니다. 만약 어떤 제공업체 키도 설정되지 않았다면 데몬은 여전히 부팅되지만 경고를 기록하고 에이전트의 호출 시도가 실패합니다.
Copy config.example.edn → config.local.edn (gitignored)
기본 모델, 에이전트 및 Telegram 봇 토큰을 설정하려면 다음 명령어를 사용하세요. 자세한 내용은 [
doc/configuration.md]와 provider setup를 참조하세요.
메시지를 입력하고 Enter를 누르세요; Ctrl-C는 종료합니다. 방과 기록은 자동으로 유지됩니다 (Datahike). 프런트엔드는 하나의 데몬을 통해 상호 교환 가능합니다:
clojure -M:cli
clojure -M:cli --no-tui --web
독립형 uberjar: 데몬 + nREPL + TUI + 웹 + Telegram이 포함된 단일 파일입니다. CircleCI는 main에 푸시할 때마다 빌드하고 GitHub 릴리스에 첨부하므로, 최신 릴리스에서 미리 빌드된 jar를 가져오거나 직접 빌드할 수 있습니다:
clojure -T:build harness
java -jar dvergr-<ver>-harness.jar
자체 케이스로 벤치마킹 모델 사용하기
사전 요구 사항: JDK (22 이상, CI에서 사용), [
Clojure CLI], git, 그리고 babashka (bb, MCP 릴레이 bin/dvergr-mcp용). 구독 모델의 경우, 로그인된 claude CLI (Claude Code) 및/또는 codex CLI가 필요합니다.
상태 저장 위치. dvergr이 작성하는 모든 것은 하나의 상태 루트인 DVERGR_HOME (기본값 <checkout>/.dvergr)에 존재합니다. 여기에는 스토어, 로그, MCP 릴레이의 도구 캐시가 포함됩니다. 초기화하려면 rm -rf를 사용하세요. doc/homes.md에는 레이아웃, 실험 홈 및 이동된 홈 대 복사된 홈에 대한 정보가 있습니다.
Claude Code 모델은 프롬프트에 이메일 주소를 요구하지 않습니다. 대화형 로그인 기능을 사용하면 claude CLI가 로그인된 계정의 이메일 주소를 모든 프롬프트에 추가합니다. 한 번 claude setup-token을 실행하고 토큰을 ~/.dvergr/secrets/claude-oauth-token에 저장하십시오 (사용자별이며, DVERGR_HOME 아래가 아님; DVERGR_CLAUDE_TOKEN_FILE은 다른 파일을 지정함): 이후 claude-code-* 후보 모델들은 빈 설정 디렉토리와 계정 세부 정보 없이 해당 토큰으로 실행됩니다 (details).
쉘(Shell)에서, 과거 사례들로 구성된 CSV 파일(ID, 입력값, 사람이 기록한 결과)은 케이스 팩(case pack)이 되며, 이는 room-run을 통해 인증되고, 벤치마킹되며, 보고됩니다:
clojure -M -m dvergr.catalog.casepack-cli cases.csv \
--id id --inputs description,supplier_country,net_amount \
--outcome vat_code:exact --outcome vat_amount:number:0.01 --out packs/vat-codes
...
팩 내의 certification.edn 파일은 어떤 사례가 답변을 채점할 수 있고 왜 다른 사례는 할 수 없는지를 명시합니다. room-run은 실험을 자체 홈 디렉토리(--home)에 보관합니다 (기본값: $DVERGR_HOME/workflow-runs/<pack>, 또는 DVERGR_HOME 없이 workflow-runs/<pack>). 재실행하면 중단된 지점부터 이어서 진행됩니다. 표준 출력(stdout)에는 진행 상황과 보고서가 포함되며, 로그는 <home>/dvergr.log에 저장됩니다. 보고서는 각 후보 모델의 패스율을 95% 신뢰 구간과 함께, 비용(cost), 토큰 수, 시간 등의 지표와 함께 제공하며, 후보 모델들을 쌍으로 비교합니다: 두 모델 모두 답변한 사례들 중 각각 몇 개를 통과했고 상대방은 실패했는지 여부, 정확한 McNemar p값, 그리고 판정(
릴레이(relay)는 처음 사용 시 데몬(daemon)을 시작합니다. 첫 부팅에는 약 2분이 소요됩니다 (의존성 로딩, 이후 저장소 로딩). 도구들은 그 후에 나타납니다. doc/mcp.md, doc/room-workflows.md 및 doc/running-benchmarks.md를 참조하십시오.
REPL 빠른 시작
(require '[dvergr.core :as d])
;; 룸을 구축하고 코더 에이전트에 참여하기
...
태그 기반 라우팅, 소비자별 버퍼 정책, 영속성(persistence), 그리고 포크-앤-머지(fork-and-merge) 제안 패턴에 대해서는 doc/getting-started.md를 참조하십시오.
문서화 (Documentation)
- Getting Started — 첫 룸 튜토리얼, REPL + CLI 경로
- Programming Model — 버스(bus), 태그 기반 라우팅, GenerationHandle, 분배 법칙 λ
- Runs — 영속적인 에이전트 턴 식별자, 활동/출력 상관관계, 생명주기 관찰 및 목표 취소
- Agent programs — 불변의 전문화된 에이전트 명단(rosters), Run 기반 고용(hiring), Spindel 구성, 포크 안전 상태 배치
- CLI Reference —
dvergr-cli 키, 영속성, 제공자 설정(provider config)
- Architecture — 공식 모델: 룸(rooms), pub/sub 버스, 반응형 프로세스로서의 에이전트, 기질 포크를 통한 ToM
- Tools & the SCI sandbox — 도구 세트, 작업 공간 에이전트가 코드를 실행하는 곳, 그리고 그 안전 경계(자격 증명 주입 포함)
- Media — voice, vision & files — 프론트엔드 전반의 음성-텍스트 변환(speech-to-text), 이미지 설명/추출, 문서,
/drive 마운트
- Channels — Telegram · Scheduling — 채팅 인터페이스를 룸으로 연결; 룸별 반복 /
:code 작업
- Doc index — 전체 목차
예제 노트북 (Example notebooks)
실행 가능한 Clay 노트북 — 각 노트북은 실제 방을 인라인으로 구축하고 실행합니다. 렌더링된 내용은 replikativ.github.io/dvergr에서 찾아보거나, 에디터에서 소스를 열어볼 수 있습니다. 로컬에서는 clj -M:clay -m notebooks.render로 구축합니다 (이 경우 quarto CLI가 필요합니다).
| 노트북 | 내용 |
|---|
| Getting started | rooms, participants, post!, 태그 기반 라우팅 — 처음부터 |
| ... | |
The standalone, runnable scenarios는 examples/에 라이브로 임포트되어 있습니다 (clj -M:examples -m scenario-auditor). | |
빌딩 블록 (Building blocks)
| 네임스페이스 (Namespace) | 제공하는 기능 |
|---|
dvergr.core | 공개 파사드(Public facade) — 가장 많이 사용되는 변수들을 재내보냅니다 (re-exports) |
| ... | |
프로바이더 설정 (Provider setup)
(require '[dvergr.model.providers :as providers])
;; API 키, Claude Code, 그리고 로그인된 Codex 구독을 자동으로 등록합니다.
...
의존성 (Dependencies)
