ahacker-1/cre-acquisition-orchestrator

상업용 부동산 (CRE) 다가구 주택 매입을 위한 오픈 소스 멀티 오케스트레이터 (multi-orchestrator) 워크스페이스: 문서를 업로드하고, 목표를 설정하면, 31개의 AI 역할이 협업하는 과정을 지켜본 뒤 매입 패키지를 검토하십시오.

저는 CRE 산업에 필요하다고 생각되는 무언가를 작업해 왔으며, 현재 어느 단계에 와 있는지 공유하고자 합니다.

몇 달 전, 저는 200세대 규모의 다가구 주택 매입 건에 489개의 AI 에이전트 (AI agents)를 투입했을 때 어떤 일이 발생하는지에 대해 글을 쓴 적이 있습니다. 그 글은 더 큰 비전을 담고 있었습니다. 이 리포지토리 (repo)는 그 비전을 실제로 사용할 수 있게 만드는 공학적 실체인 실용적인 오픈 소스 버전입니다. 즉, 명명된 31개의 AI 역할, 오케스트레이션 (orchestration) 로직, 도메인 지식 (domain knowledge) 파일, 스키마 (schemas), 로컬 대시보드 (local dashboard), 결정론적 시뮬레이션 엔진 (deterministic simulation engine), 그리고 소스 기반 검토 워크플로우 (source-backed review workflow)를 포함합니다.

이 프로젝트는 아직 완전히 프로덕션 단계에 준비된 상태는 아닙니다. 이 점에 대해서는 솔직하게 말씀드리고 싶습니다. 하지만 이 분야는 거의 존재하지 않기 때문에, 제가 본 CRE 매입 오케스트레이션을 위한 가장 심도 있는 오픈 소스 프레임워크 (framework)임은 분명합니다. 코딩, 고객 지원, 연구, 데이터 분석을 위한 에이전트 프레임워크는 존재합니다. 하지만 데이터 인수인계 (data handoffs), 검토 게이트 (review gates), 투자 위원회 증거 (investment committee evidence)를 보존하면서 실질적인 다가구 주택 매입이 실사 (due diligence), 언더라이팅 (underwriting), 금융 (financing), 법률 (legal), 종결 (closing) 단계에 따라 어떻게 진행되는지를 모델링하는 것은 거의 없습니다.

기본 경로는 의도적으로 로컬 (local) 환경에 맞춰져 있습니다. API 키 없이도 대시보드를 실행할 수 있으며, 임대 명부 (rent roll)/T12/매물 설명서 (offering memo) 패키지를 업로드하고, 출처 (provenance)와 함께 추출된 후보 필드들을 검토하며, 모호한 값을 승인하거나 생략하고, 투자 위원회 기초 패키지를 위한 마크다운 (Markdown)/JSON을 내보낼 수 있습니다. 실시간 에이전트를 원한다면 선택 사항인 ChatGPT/Codex 경로가 마련되어 있지만, 오프라인 데모가 공개적인 증명 경로로 유지됩니다.

이곳의 모든 것 — 에이전트 프롬프트 (agent prompts), 도메인 기술 (domain skills), 스키마 (schemas), 파이프라인 아키텍처 (pipeline architecture), 대시보드 (dashboard), 그리고 데모 결과물 (demo artifacts) — 은 여러분이 시작점으로 사용할 수 있도록 제공됩니다. 포크 (Fork) 하세요. 그 위에 구축하세요. 여러분만의 거래 (deals), 투자 가설 (investment thesis), 그리고 내부 인수 워크플로우 (internal acquisition workflow)에 맞게 조정하세요. 만약 이 프레임워크가 단 하나의 CRE 팀이라도 인수 방식에 대해 다시 생각하는 데 도움을 줄 수 있다면, 이를 오픈 소스 (open-sourcing)로 공개할 가치가 있었습니다.

이 산업을 미래로 이끌어 봅시다.

면책 조항 (Disclaimer): 이 프로젝트는 참조 아키텍처 (reference architecture) 및 교육용 프레임워크 (educational framework)이며, 투자 결정을 내리기 위한 운영용 소프트웨어 (production software)가 아닙니다. 여기에 포함된 어떤 내용도 금융, 법률 또는 투자 자문이 아닙니다.

10분 만에 첫 번째 실제 거래 실행하기: 'First Deal Guide'를 따르고, 대시보드를 시작한 뒤, 로컬 임대료 명부 (rent roll)/T12/매각 제안서 (offering memo) 파일을 업로드하고, 소스 기반 필드 (source-backed fields)를 검토한 후, IC 스타터 패키지 (IC starter package)를 내보내세요.
결정론적 폴백 (deterministic fallback)으로 Parkview 사용하기: Command, Swarm Goal Console, Deal Team, Workpapers, 그리고 IC Package를 파일 업로드 없이 샘플 투어로 둘러보고 싶다면 Start Guided Demo를 클릭하세요.
처음부터 설치하기: 'Quick Start'를 따르세요. 대시보드 경로는 로컬 우선 (local-first) 방식이며, 종속성 (dependencies)이 설치된 후 샘플 데모는 결정론적 (deterministic) 상태를 유지합니다.
적절한 런타임 (runtime) 선택하기: 선택 사항인 라이브 에이전트 (live-agent) 경로를 통해 실제 거래 컨텍스트를 보내기 전에 'Offline Demo vs Live Codex Agents'를 읽어보세요.
시스템 이해하기: 'Architecture', 'Agent Catalog', 'API Reference', 그리고 'WebSocket Events'를 읽어보세요.
다음 기여 분야 확인하기: 'Roadmap'을 검토하세요. 특히 스캔된 문서를 위한 OCR, 법률 문서 파싱 (legal document parsing), 더 풍부한 라이브 런타임 제어 (live runtime controls), 그리고 추가적인 복잡한 파서 수정 사항 (messy parser fixtures)을 확인하세요.

가이드 경로를 원하시면 'First Deal Guide'를 사용하세요. 가장 짧은 결정론적 데모를 원하시면 'Quick Demo'를 사용하세요.

문서 우선 딜 인테이크 (Document-first deal intake)- 임대료 명세서 (rent rolls), T12 (12개월 손익계산서), 제안서 (offering memos), PDF 및 증빙 파일을 로컬 워크스페이스 (local workspace)에 업로드합니다.

소스 기반 추출 검토 (Source-backed extraction review)- 지원되는 XLSX/CSV/TXT/MD 및 텍스트 기반 PDF 소스는 신뢰도 (confidence), 경고 (warnings), 파일 해시 (file hashes), 소스 위치 (시트/행/열 또는 페이지) 출처 (provenance)와 함께 후보 필드 (candidate fields)가 됩니다. 스캔된 문서나 이미지 전용 문서는 조용히 건너뛰는 대신 OCR (광학 문자 인식) 처리가 필요함을 감지하고 플래그를 지정합니다.

인간 승인 게이트 (Human approval gate)- 운영자 (operator)가 신뢰할 수 있는 필드를 승인/적용하거나 모호한 필드를 포기/거부하기 전까지는 언더라이팅 (underwriting) 입력값이 변경되지 않습니다.

31개 역할의 AI 딜 팀 (31-role AI deal team)- 6개의 오케스트레이터 (orchestrators), 21개의 인수 전문가 (acquisition specialists), 4개의 문서 수집 (document-ingestion) 역할이 마크다운 프롬프트 (markdown prompts)로 정의되어 있습니다.

가시적인 조정 (Visible coordination)- 대시보드 이벤트는 전문가 메시지, 인수인계 (handoffs), 의존성 (dependencies), 검토 (reviews), 작업 문서 (workpapers) 및 패키지 상태를 보여줍니다.

두 가지 런타임 경로 (Two runtime paths)- 기본적으로 오프라인 결정론적 시뮬레이션 (offline deterministic simulation)을 제공하며, 라이브 에이전트 워크플로 (live agent workflows)를 위한 선택적 ChatGPT 인증 Codex CLI 경로를 제공합니다.

AI 역할 (AI Roles)	기술 (Skills)	스키마 (Schemas)	워크플로 (Workflows)	픽스처 (Fixtures)	테스트 통과 (Tests passing)
31	8	27	5	20	8

수치는 현재 체크인된 카탈로그를 반영합니다: 25개의 전문가 프롬프트 파일과 6개의 오케스트레이터; 8개의 도메인 지식 파일; 27개의 JSON 스키마 (JSON Schema) 계약; 5개의 워크플로 정의; fixtures/ 아래의 20개 큐레이션된 픽스처 파일; 그리고 package.json에 의해 추적되는 8개의 루트 test* 명령입니다.

현재 main 브랜치는 최신 공개 릴리스(v2.7.0)와 일치하며, 이전의 알려진 제한 사항들을 해결하는 동시에 로드맵 (ROADMAP)의 단기 우선순위들을 완료합니다. 안정적인 베이스라인은 로컬 우선 (local-first) 및 검토 우선 (review-first) 원칙을 유지합니다:

기본적으로 로컬 방식 (Local by default)- 오프라인 대시보드, 결정론적 Parkview 데모, 소스 기반 추출은 API 키를 필요로 하지 않습니다.

버전화된 릴리스 베이스라인 (Versioned release baseline)- v2.7.0은 로드맵의 단기 우선순위(1–5)를 완료하며, v2.6.0 상에서 이전의 알려진 제한 사항들(텍스트 기반 PDF 추출, 병합된 셀이 포함된 워크북, 단일 운영자 셀프 호스팅 배포)을 해결합니다.

신뢰성 강화 (credibility-hardening) 릴리스.현재 메인 (Current main)- 이 태그 이후에 공개되지 않은 새로운 작업이 나타나지 않는 한, v2.7.0 릴리스가 기준입니다.알려진 제한 사항 (Known limits)- 스캔된/이미지만 포함된 문서의 실제 OCR (이들은 OCR 대상으로 감지 및 플래그가 지정될 뿐, 추출되지는 않음), 멀티 테넌트 (multi-tenant) 클라우드 호스팅, 그리고 자율적인 투자 결정은 범위 외로 남아 있습니다. 텍스트 기반 PDF 추출 (Text-based PDF extraction), 병합된 셀이 포함된 워크북 (merged-cell workbooks), 그리고 단일 운영자 셀프 호스팅 배포 (single-operator self-host deployment) (배포(Deployment) 섹션 참조)는 이제 지원됩니다.

릴리스 기록 및 현재 메인 변경 사항은 CHANGELOG.md를 참조하세요.

텍스트 기반 PDF 추출 (Text-based PDF extraction)- PDF 형식의 메모(memos) 및 임대 명세서(rent rolls)를 제공하면 이제 필드별 신뢰도(confidence) 및 페이지 수준의 출처(provenance)를 포함하여 소스에 기반한 후보 필드를 생성합니다. 스캔된/이미지만 포함된 PDF는 조용히 건너뛰어지는 대신 OCR 대상으로 감지되어 플래그가 지정됩니다.
더 강력해진 스프레드시트 파싱 (Tougher spreadsheet parsing)- 병합된 셀이 포함된 워크북은 헤더 감지 전에 셀 병합을 해제하고 앞의 값으로 채우기(forward-fill)를 수행하며, 이미지만 포함된 워크북은 플래그가 지정됩니다. 또한 통화 기호, 소계/합계 행, 후행 노트 및 동의어 헤더를 처리하는 새로운 기능(fixtures)이 포함되었습니다.
검토 수준의 워크페이퍼 (Review-grade workpapers)- 워크페이퍼 품질 게이트(인용된 입력값, 가정, 계산, 주의사항, 검토자 승인), 단계별 증거 완결성 점수 산정, 원천 워크페이퍼/소스로 추적 가능한 IC 레드 플래그(red-flag) 드릴다운, 그리고 소스 드릴다운 및 패키지 버전 이력을 포함한 더 풍부한 IC 내보내기 기능을 제공합니다.
소스 결정 감사 추적 (Source-decision audit trail)- 문서 간 충돌 차단 기능과 함께 필드별 승인/거부/면제(approve/reject/waive) 이력이 타임스탬프와 함께 기록되며, 승인된 입력값에서 해당 소스 스니펫(snippet)으로 연결되는 필드 수준의 출처(provenance) 딥링크를 제공합니다.
Live Codex 런타임 강화 (Live Codex runtime hardening)- 에이전트별 재시도/백오프 (retry/backoff), 부분 실패 시 실패한 에이전트만 재실행, 로깅 경계에서의 비밀 정보 삭제 (secret redaction), 자체 스키마를 가진 삭제된 샘플 실행 매니페스트(manifest), 그리고 운영자의 "실패한 에이전트 재시도" 복구 작업을 지원합니다.
단일 운영자 셀프 호스팅 배포 (Single-operator self-host deployment)- npm run serve

빌드된 대시보드와 루프백 API/WS(loopback-default, 멀티테넌트 아님)를 함께 제공합니다. 자세한 내용은 docs/DEPLOYMENT.md를 참조하세요.

기여자 경험 (Contributor experience)

• 엔드 투 엔드(end-to-end) "새로운 전문 에이전트 추가" 가이드, 대시보드 아키텍처 맵, 그리고 npm run release:check 준비 게이트(readiness gate)를 제공합니다.

이 프로젝트는 에이전트 아키텍처에서 시작하여 로컬 우선(local-first) 인수 워크스페이스로 성장해 왔습니다. 먼저 오케스트레이션 카탈로그(orchestration catalog), 그다음 사용 가능한 대시보드, 그다음 Codex 기반의 실시간 실행, 그다음 문서 우선 콕핏(document-first cockpit), 그다음 운영자 워크벤치(operator workbench), 그다음 에이전트 기반 딜 팀 워크스페이스(agentic deal-team workspace), 그다음 소스 기반 딜 인테이크(source-backed deal intake), 그다음 엄격한 스키마(schemas)를 갖춘 신뢰성이 강화된 샘플 패키지, 그리고 이제 PDF 추출, 검토 등급의 워크페이퍼(workpapers), 실시간 런타임 강화(live-runtime hardening), 그리고 단일 운영자 셀프 호스팅 배포(single-operator self-host deployment)를 추가하는 완성 단계에 이르렀습니다.

릴리스 (Release)	변경 사항	전체 노트
v1.0.0 - 최초 공개 릴리스	첫 번째 오픈 소스 CRE 인수 오케스트레이션 프레임워크를 공개했습니다: 마크다운 에이전트(markdown agents), 단계별 오케스트레이션(phase orchestration), 스키마(schemas), 도메인 기술(domain skills), 결정론적 시뮬레이션(deterministic simulation), 그리고 샘플 Parkview 출력물.	GitHub Release
v1.1.0 - 대시보드 딜 위저드 (Dashboard Deal Wizard)	가이드형 '새 딜 위저드(New Deal Wizard)', 저장된 딜 라이브러리, 즉시 실행 가능한 딜 플로우(deal flow), 그리고 주요 대시보드 경로에 대한 Playwright 커버리지를 통해 설정을 제품 내로 이동했습니다.	RELEASE_NOTES_v1.1.0.md
v2.0.0 - 운영자 딜 허브 (Operator Deal Hub)	대시보드를 단계별 워크스페이스, 문서 인테이크(document intake), 소스 기반 입력, 결과 워크플로우(outcome workflows), 프리셋(presets), 그리고 완성 패키지를 갖춘 로컬 우선 인수 콕핏(acquisition cockpit)으로 전환했습니다.	RELEASE_NOTES_v2.0.0.md
v2.1.0 - Codex / ChatGPT 워크플로우 런타임	선택적인 실시간 에이전트 경로를 추가했습니다: ChatGPT 인증 Codex CLI 실행, 앱 내 로그인 상태, 대시보드에서 실행되는 Codex 실행, 그리고 릴리스 준비가 된 설정 검증.	RELEASE_NOTES_v2.1.0.md
v2.2.0 - 문서 우선 인수 콕핏 (Document-First Acquisition Cockpit)	빠른 초안 생성, 업로드-to-문서 라우팅, 컴팩트한 최근 딜 목록, 그리고 지속적인 콕핏 사이드바를 통해 대시보드의 진입점을 문서 우선 방식으로 만들었습니다.

| RELEASE_NOTES_v2.2.0.md |
v2.3.0 - Operator Workbench (운영자 워크벤치) |
가이드가 포함된 딜 진행 (guided deal progression), 워크플로우 준비 상태 (workflow readiness), 업로드 대기열 복구 (upload queue recovery), 소스 기반 변경 사항 검토 (source-backed change review), 더 안전한 임베디드 실행 범위 지정 (safer embedded launch scoping), IC 검토 핸드오프 (IC review handoff), 그리고 검증된 공개 기능 경로 (verified public feature paths)를 추가했습니다. | RELEASE_NOTES_v2.3.0.md |
v2.4.0 - Agentic Deal Team Workspace (에이전트 기반 딜 팀 워크스페이스) |
대시보드를 인수 커맨드 (Acquisition Command), 미션 의도 (mission intent), 가시적인 에이전트 핸드오프 (visible agent handoffs), 전문가 팀 활동 (specialist team activity), 작업 문서/증거 (workpapers/evidence), 그리고 IC 패키지 조립 (IC package assembly)을 중심으로 재구성했습니다. | RELEASE_NOTES_v2.4.0.md |
v2.5.0 - Source-Backed Deal Intake (소스 기반 딜 인테이크) |
XLSX/CSV 형태의 임대료 명부 (rent rolls) 및 T12(최근 12개월 손익계산서)를 지속 가능하고 검토 가능하며 출처가 보장되는 후보 필드로 전환하여, 운영자가 워크플로우에서 사용하기 전에 승인하거나 적용할 수 있도록 했습니다. | RELEASE_NOTES_v2.5.0.md |
v2.5.1 - Stale Source Evidence Gate (오래된 소스 증거 게이트) |
워크플로우 실행 준비 상태에 소스 신선도 보호 (source-freshness protection) 기능을 추가하고, 패키지 베이스라인을 2.5.1로 업데이트했습니다. |
GitHub Tag |
v2.6.0 - Credibility and Infrastructure Hardening (신뢰성 및 인프라 강화) |
Parkview를 Austin 중심으로 정렬하고, 스텁(stub) 작업 문서를 교체하며, 엄격한 스키마/열거형 (schemas/enums)을 강제하고, 로컬 보안을 강화하며, API/이벤트를 문서화하고, 공개 리포지토리 인프라를 새로 고칩니다. | RELEASE_NOTES_v2.6.0.md |
v2.7.0 - Completion Pass (완료 단계) |
이전의 알려진 제한 사항들(텍스트 기반 PDF 추출, 병합된 셀/이미지만 있는 워크북, 단일 운영자 셀프 호스트 배포)을 해결하고, 로드맵 (ROADMAP)의 단기 우선순위인 검토 수준의 작업 문서 (review-grade workpapers), 라이브 Codex 런타임 강화 (live Codex runtime hardening), 소스 결정 감사 추적 (source-decision audit trail), 그리고 기여자 도구 (contributor tooling)를 구현합니다. | GitHub Release |

공개 데모는 의도적으로 시각적입니다. 처음 방문하는 사용자가 아키텍처를 읽기 전에 워크스페이스를 이해할 수 있어야 하기 때문입니다. 아래 경로는 로컬 문서 인테이크로 시작하여, API 키 없이도 데이터가 채워진 아티팩트(artifacts)를 보여주기 위해 결정론적인(deterministic) Parkview 샘플을 사용합니다.

스토리보드와 스크린샷 갱신 경로를 보려면 Demo Journey를 참조하세요.

시스템은 3단계 계층 구조를 사용합니다: 하나의 마스터 오케스트레이터 (Master Orchestrator)가 5개의 단계별 오케스트레이터 (Phase Orchestrators)를 조정하며, 이들은 실사 (Diligence), 언더라이팅 (Underwriting), 금융 (Financing), 법률 (Legal), 종결 (Closing), 그리고 문서 수집 (Document Ingestion) 전반에 걸쳐 전문 에이전트 (Specialist Agents)를 관리합니다. 표준 오픈 소스 카탈로그는 31개의 명명된 AI 역할 (AI Roles)로 구성됩니다: 6개의 오케스트레이터 (Orchestrators), 21개의 인수 전문가 (Acquisition Specialists), 그리고 4개의 원천 문서 수집 역할 (Source-document Ingestion Roles)입니다.

graph TD
M[Master Orchestrator] --> DD[Due Diligence Orchestrator]
M --> UW[Underwriting Orchestrator]
...

각 역할은 책임, 입력 (Inputs), 출력 (Outputs), 에스컬레이션 경로 (Escalation Paths), 그리고 핸드오프 기대치 (Handoff Expectations)를 포함하는 일반적인 마크다운 (Markdown) 프롬프트입니다. 이는 의도적인 설계입니다: 운영자 (Operators)와 엔지니어 (Engineers)가 런타임 (Runtime)을 신뢰하기 전에 역할 설계를 검토할 수 있기 때문입니다.

flowchart LR
U[Operator] --> UI[React Dashboard]
UI --> API[Local REST API]
...

오프라인 시뮬레이션 (Offline Simulation) 경로는 종속성 (Dependencies) 설치 후 로컬 (Local) 상태를 유지합니다. 선택 사항인 라이브 Codex 경로는 선택된 프롬프트와 거래 컨텍스트 (Deal Context)를 사용자의 ChatGPT 인증 Codex CLI 세션을 통해 전송한 다음, 가공되지 않은 Codex 출력값과 대시보드에서 읽을 수 있는 패키지 아티팩트 (Package Artifacts)를 로컬 data/ 트리로 다시 기록합니다. 인증 정보는 이 저장소 (Repository)에 저장되지 않습니다.

단계 (Phase)	수행 내용	예시 출력 (Example Outputs)
1. 문서 수집 (Document Intake)	운영자가 원천 파일을 업로드하고, 문서 유형을 분류하며, 파서 (Parser) 출력물을 미리 봅니다.	원천 매니페스트 (Source manifest), 해시 (Hashes), 추출 후보 (Extraction candidates), 경고 (Warnings)
...

Parkview 샘플은 결정론적 (Deterministic) 데이터를 사용하여 이 경로를 처음부터 끝까지 따르므로, 기여자 (Contributors)들은 API 키나 비공개 거래 파일 없이도 동작을 검증할 수 있습니다.