CAOS — Customer Assurance Operating System

고객이 보내는 보안 설문지에 한 번만 답변하세요.

고객 데이터를 다루는 모든 기업은 똑같은 요청을 반복해서 받습니다. 보안 설문지, 개인정보 평가, 벤더 위험 검토, 조달 실사, 증거 요청이 그것입니다. 대부분의 조직은 이를 수작업으로 처리합니다. 고객이 보낸 스프레드시트, 정책 문서가 담긴 폴더, 이메일 스레드, 그리고 지난번에 무엇을 답변했는지에 대한 누군가의 기억까지 동원해서 말이죠.

CAOS는 이를 기록 시스템(system of record)으로 전환합니다. 설문지는 구조화되고 답변 가능한 작업이 됩니다. 완료된 답변과 규정 준수 문서는 검색하고 인용할 수 있는 코퍼스가 됩니다. 다음 설문지는 이미 한 말에서 시작하며, 모든 주장은 그 출처가 된 문서나 이전 답변까지 추적할 수 있습니다.

자체 호스팅(self-hosted) 방식입니다. 귀사의 정책, 답변, 고객 설문지는 모두 귀사의 인프라에 보관됩니다.

상태: v0. CAOS는 프로덕션에서 운영 중이지만, 이 저장소는 이제 막 공개되었습니다. 인터페이스, 스키마, 구성은 아직 변경 중입니다. 외부 기여는 아직 열려 있지 않습니다 — 기여를 참조하세요.

기능

추측 없이 설문지를 읽습니다. 고객의 XLSX를 업로드하면 CAOS가 이를 충실히 렌더링합니다. 시트, 행, 셀, 숨겨진 열, 유효성 검사 드롭다운까지 말이죠. 그런 다음 어떤 행에 답변할 수 있고 어떤 셀을 채울지 하나씩이 아니라 범위 단위로 지정합니다. 고객별 파서는 없습니다. 표준이 없기 때문입니다. 굵은 행이 질문일 수도 있고, 빈 열이 답변 대상일 수도 있으며, 한 워크북을 올바르게 처리하는 휴리스틱이 다른 워크북은 자신 있게 틀리게 처리하기도 합니다.

이미 완료한 작업에서 코퍼스를 구축합니다. 설문지를 마감하면 답변된 행이 재사용 가능한 Q&A로 게시됩니다. 업로드한 정책, 인증서, 보고서는 인용 가능한 구절이 됩니다. 둘 다 변경 불가능하게 버전 관리되므로, 지난 분기에 보낸 답변도 당시 유효했던 문서를 기준으로 여전히 스스로를 설명할 수 있습니다.

올바른 이전 답변을 찾습니다. 검색은 어휘 검색과 의미 검색을 함께 실행하고, 두 순위를 융합한 다음 상위 후보를 재순위화합니다. 규정 준수 언어에는 둘 다 필요합니다. 임베딩이 흐릿하게 만드는 "SOC 2 Type II"와 같은 정확한 토큰, 그리고 키워드 검색이 완전히 놓치는 의역(paraphrase)이 그것입니다.

근거 기반 답변 초안을 작성합니다. 선택 사항입니다. 모델은 제한되고 허용 목록에 등록된 도구를 통해 코퍼스를 검색하고 인용을 포함한 답변 초안을 작성합니다. 여기에 정보의 권위가 어디서 나왔는지 알려주는 라벨도 붙습니다: Knowledge grounded, Mixed, General guidance, Based on current answer 중 하나입니다. General guidance 답변은 귀 조직에 대해 어떤 주장도 하지 않으며, 그 점을 명시합니다.

Google Chat에서 답변합니다. /ciso 슬래시 명령은 동일한 근거 기반 코퍼스를 조회하며, 웹 앱의 지속적인 대화로 돌아가는 링크를 제공합니다.

고객의 원본 워크북으로 다시 내보냅니다. 답변은 원본 파일 구조의, 매핑한 셀에 기록됩니다. CAOS식 근사 구조가 아니라 말이죠.

모든 것을 기록합니다. 데이터베이스가 강제하는 불변성을 갖춘 추가 전용(append-only) 감사 로그로, 답변의 정확한 변경 전후 값을 보관합니다.

모듈

CAOS는 9개의 도메인 모듈로 구성됩니다. 그중 세 가지 — Evidence, Knowledge, Tasks — 는 전역(global) 모듈입니다. 이들은 프로젝트에 속하지 않는데, 그 가치가 여러 engagement에 걸쳐 있기 때문입니다.

아키텍처

                          Internet
                             │
                       ┌─────┴─────┐
                       │   nginx   │   TLS · static frontend · /api proxy
                       └─────┬─────┘
              ┌──────────────┼──────────────┐
              │              │              │
        ┌─────┴─────┐  ┌─────┴─────┐  ┌─────┴──────┐
        │ Frontend  │  │    API    │  │  Taskiq    │
        │  React    │  │  FastAPI  │  │  workers   │
        │  static   │  │  :18800   │  │            │
        └───────────┘  └─────┬─────┘  └─────┬──────┘
                             │              │
                       ┌─────┴──────────────┴─────┐
                       │                          │
                 ┌─────┴──────┐            ┌──────┴─────┐
                 │ PostgreSQL │            │   Redis    │
                 │  pgvector  │            │ queue+cache│
                 └────────────┘            └────────────┘
                             │
                       ┌─────┴─────┐
                       │ Providers │   Bedrock · local models · Google Chat
                       └───────────┘

백엔드 — Python 3.12+, FastAPI, SQLAlchemy 2 async, PostgreSQL with pgvector, Redis, Taskiq 워커. 각 모듈은 domain → application → infrastructure → presentation으로 나뉘며, 단방향 의존성을 갖습니다. domain은 아무것에도 의존하지 않습니다.

프론트엔드 — React 19, TypeScript, Vite, Tailwind v4, shadcn/ui, Zustand. 앱 전체 세션 및 셸 상태는 src/app에 있고, 기능 및 서버 캐시 상태는 기능 스토어에 있으며, 오래 실행되는 페이지 워크플로는 기능 컨트롤러에 있습니다.

두 검색 채널 모두 PostgreSQL에 있습니다. 별도의 벡터 데이터베이스는 없습니다. 저장소 하나가 곧 하나의 트랜잭션 경계이자 하나의 백업이기 때문입니다.

외부 벤더는 일정 거리를 두고 유지됩니다. 모든 통합은 플랫폼 프로토콜(CAOS가 제품 언어로 기대하는 것), 어댑터 프로토콜, 벤더 구현으로 분리됩니다. 벤더 구현만이 SDK를 가져오는 유일한 계층입니다. 이것이 임베딩과 재순위화가 고정된 로컬 모델 또는 Bedrock에서 실행되며, 어떤 쪽인지 애플리케이션 코드가 알지 못하는 이유입니다.

자세히 보기: 아키텍처 · 통합 경계

데이터 흐름

문서가 검색 가능해집니다. 업로드 → 불변 버전 → 지속적인 수집 작업 → 커밋 → 워커에 디스패치 → 각각 인용 위치 지정자(PDF 페이지, DOCX 문단, XLSX 시트/행/셀)를 유지하는 ≤1,500자 구절 추출 → 임베딩 생성 → 검색 가능. 작업은 디스패치 전에 커밋되므로, 큐 실패는 보이지 않는 대기 행이 아니라 눈에 보이는 재시도 가능 상태가 됩니다.

설문지가 답변 가능한 작업이 됩니다. 업로드 → 충실한 행 뷰 → 행과 답변 대상을 매핑 → 답변 가능한 각 행마다 정확한 소스 셀을 가리키는 작업 공간 항목 하나 → 초안 자동 저장 → 예상 개정판 비교 후 설정(compare-and-set)을 통한 명시적 완료. 따라서 오래된 탭은 동료의 작업을 덮어쓰는 대신 409를 받습니다.

완료된 작업이 Knowledge가 됩니다. 설문지(또는 모든 설문지를 마감하는 프로젝트)를 마감하면 답변된 행이 재사용 가능한 Q&A로 게시됩니다. 답변되지 않은 행은 아무것도 게시하지 않습니다. 원시 워크북은 결코 수집되지 않습니다. 그것은 근거 자료가 아니라 운영 작업이기 때문입니다.

질문이 근거 기반 답변이 됩니다. 어휘 및 의미 검색이 병렬로 실행됩니다 → Reciprocal Rank Fusion이 순위를 결합합니다 → 태그 부스트 → 제외 필터 → 제한된 50개 후보 창을 재순위화 → 모델이 고정된 예산 내에서 검색하고, 검사하고, 다시 검색합니다 → 불변 소스 버전을 가리키는 인용과 근거 라벨이 포함된 초안이 생성됩니다.

모든 단계는 더 약하지만 정직한 모드로 저하됩니다. 재순위화기가 다운되면 융합된 순서와 신뢰도 칩 없음이 의미되고, 임베딩이 다운되면 어휘 폴백을 의미하며, 그렇게 표시됩니다.

자세히 보기: 데이터 흐름

빠른 시작

전제 조건: Compose가 포함된 Docker. 프론트엔드 작업에는 Node.js >=22.22.0과 pnpm 11.9.0이 필요합니다. 백엔드 개발에는 uv도 사용합니다.

AWS 계정이나 LLM 제공자가 필요 없습니다. 생성(generation)은 기본적으로 꺼져 있으며, 아래의 모든 내용은 그것 없이도 작동합니다.

git clone https://github.com/DigiCred-OSS/caos-os.git
cd caos-os/backend
cp .env.example .env

backend/.env의 BACKEND_USERS_SECRET 자리 표시자를 최소 32바이트의 난수로 교체하세요:

python3 -c 'import secrets; print(secrets.token_urlsafe(48))'

PostgreSQL, Redis, API, 워커를 시작합니다. 마이그레이션은 migrator 서비스를 통해 자동으로 실행됩니다:

cd backend && docker compose up --build

첫 실행 시 약 500MB의 고정(pinned) 모델 아티팩트를 다운로드합니다. 그러면 API는 http://localhost:18800에, Swagger는 /api/docs에, PostgreSQL은 호스트 포트 15432에 위치합니다.

CAOS에는 가입 페이지가 없습니다. 호스트에서 첫 번째 관리자를 생성하세요:

./caos-cli user create-superadmin --email [email protected]

cd frontend && pnpm install && pnpm dev

http://localhost:5173을 엽니다.

프론트엔드와 API 모두 localhost를 일관되게 사용하세요. 세션 쿠키는 호스트 범위로 지정되므로 localhost와 127.0.0.1을 섞으면 조용히 세션이 끊깁니다 — 가장 흔한 로컬 설정 문제입니다.

다음: 시작 튜토리얼이 여기서부터 답변되고 내보내진 설문지까지 안내합니다.

알아두면 좋은 기본값

• 임베딩과 재순위화는 Compose에서 기본적으로 local입니다(고정된 Nomic 및 MiniLM 크로스 인코더가 이미지에 내장됨). 프로덕션은 기본적으로 AWS Bedrock을 사용합니다. 런타임은 모델을 다운로드하지 않습니다.
• 답변 생성은 꺼져 있습니다. 이를 활성화하려면 BACKEND_KNOWLEDGE_GENERATION_PROVIDER와 _MODEL을 모두 설정하세요.
• Google Chat은 꺼져 있으며, 프로덕션에서 활성화하려면 Google SSO가 필요합니다.

모든 설정은 backend/.env.example에 인라인으로 문서화되어 있으며 구성 참조에 그룹화되어 있습니다.

개발

cd backend && uv sync --locked
uv run ruff check caos
uv run mypy caos

cd frontend && pnpm install && pnpm lint && pnpm build

이 공개 배포판에는 CAOS의 내부 테스트 스위트가 포함되어 있지 않습니다. 린트, 타입 검사, 깨끗한 빌드가 여기서의 검증 관문입니다.

모든 마이그레이션 작업에는 Alembic을 직접 호출하는 대신 ./caos-cli를 사용하세요. 올바른 환경, 컨테이너, 데이터베이스를 선택해 줍니다.

코드만으로는 명확하지 않은 프로젝트 규칙은 AGENTS.md에 있으며, 모듈별 규칙은 각 모듈의 AGENTS.md에 있습니다.

문서

docs/는 Diátaxis를 따릅니다. 모든 페이지는 튜토리얼, 하우투, 참조 또는 설명 중 하나이며, 네 유형은 서로 분리되어 있습니다.

보안

취약점에 대해 공개 이슈를 열지 마세요. 비공개 보고는 SECURITY.md를 참조하세요.

기여

CAOS는 오픈 소스이지만 아직 외부 기여는 받지 않습니다. 2027년에 외부 풀 리퀘스트를 받을 예정입니다. 그때까지 이슈를 통한 버그 보고와 질문은 환영하며 실제로 유용합니다 — CONTRIBUTING.md를 참조하세요.

라이선스

Apache License 2.0. 저작권 2026 DigiCred Technologies Pvt Ltd.