Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Mozaiks는 AI 네이티브 소프트웨어 제품을 구축하고 실행하며 반복할 수 있도록 설계된 오픈 소스 AI 앱 팩토리입니다. 이 시스템은 앱 생성, 빌드 관리의 Studio와 AG2 기반의 워크플로우 오케스트레이션, 그리고 검증된 앱 파일을 통합합니다. 이를 통해 단순 데모가 아닌 프로덕션 수준의 아티팩트를 체계적으로 구축할 수 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Claude Ecosystem의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기License: MIT
Python
AG2
Discord
Studio
Runtime
Workflows
Community
Mozaiks는 AI 네이티브 소프트웨어 제품을 구축, 실행 및 반복(iterating)할 수 있는 오픈 소스 AI 앱 팩토리입니다.
이는 보통 별도의 도구에 존재하는 세 가지 요소를 하나로 통합합니다:
Mozaiks의 목표는 단순히 버릴 수 있는 데모를 생성하는 것이 아닙니다. Mozaiks는 프로덕션 형태의 아티팩트(artifacts)를 단계별로 준비하고, 엄격한 계약(strict contracts)에 따라 이를 검증하며, 런타임 관련 사항을 빌더 워크플로우와 분리하여 유지합니다.
모든 Mozaiks 앱은 하나의 Genesis Build로 시작됩니다. 이는 제품 의도(product intent)부터 단계별 검증된 앱까지의 첫 완전한 여정을 의미하며, 앱의 최초 정식 아티팩트 계보(canonical artifact lineage)를 확립합니다.
모든 후속 변경은 **Refinement Run(정제 실행)**입니다. Mozaiks는 앱의 현재 아티팩트와 히스토리에서 시작하여, 요청이 무엇에 영향을 미치는지 파악하고, 검토를 위한 안전한 새 버전을 스테이징하는 데 필요한 부분만 다시 진입합니다. 사소한 복사 수정부터 주요 제품 재고찰까지 모두 Refinement Run이며, 그 범위와 경로는 다르지만 어느 것도 앱의 계보(lineage)를 폐기하지 않습니다.
내부적으로 Refinement Engine은 Refinement Run을 분류하고 라우팅합니다. Genesis Build와 Refinement Run이 제품에 노출되는 라이프사이클 용어입니다.
체크아웃부터 Studio에서 첫 앱까지 5단계로 진행됩니다.
^20.19.0 || >=22.12.0을 요구합니다)Docker Desktop은 필요하지 않습니다. MongoDB Atlas, 로컬 MongoDB 설치 또는 MongoDB를 실행하려는 선호 방식이 Docker인 경우에만 사용하십시오.
아래 명령어는 Windows PowerShell용과 macOS / Linux 셸(bash 또는 zsh)에서 차이가 나는 부분에 대해 각각 표시됩니다.
PyPI에서 공개 패키지를 설치합니다:
python -m pip install mozaiks
프레임워크 개발에 참여하는 기여자들은 대신 편집 가능한 체크아웃을 사용해야 합니다.
이 명령어는 모든 셸에서 동일합니다:
git clone https://github.com/BlocUnited-LLC/mozaiks.git
cd mozaiks
python -m pip install -e ".[dev]"
macOS 및 Linux에서는 이 단계들이 python이라고 할 때 시스템에 python 명령어가 없다면 python3을 사용하십시오. 만약 pip이 externally-managed-environment 오류로 거부하면, Local Setup에서 보여주듯이 가상 환경을 먼저 생성하고 활성화하십시오.
Studio는 워크스페이스 상태를 MongoDB에 저장하므로, Studio를 열기 전에 설정을 구성해야 합니다:
Windows (PowerShell)
# Local MongoDB
$env:MONGO_URI="mongodb://localhost:27017/mozaiks"
...
macOS / Linux (bash 또는 zsh)
OpenAI 호출을 사용하려면 OPENAI_API_KEY를 설정해야 합니다:
Windows (PowerShell)
$env:OPENAI_API_KEY="sk-..."
macOS / Linux (bash 또는 zsh)
export OPENAI_API_KEY="sk-..."
기본 모델은 gpt-5-nano입니다. 다른 OpenAI 모델을 사용하려면 DEFAULT_LLM_MODEL을 설정하세요. Gemini와 Anthropic 키는 아직 빌드에 사용되지 않으며, Studio 또는 --provider로 선택한 공급자는 표시용으로만 기록됩니다.
이렇게 설정된 변수는 현재 터미널 세션에서만 유효합니다. 4단계는 동일한 터미널에서 실행하거나 새 터미널에서 다시 설정해야 합니다.
Windows (PowerShell)
python -m mozaiks quickstart --dir .\mozaiks-workspace
macOS / Linux (bash 또는 zsh)
python -m mozaiks quickstart --dir ./mozaiks-workspace
이 명령어는 mozaiks-workspace 폴더를 생성하고, 로컬 Studio를 시작하며, 브라우저에서 해당 Studio를 엽니다.
mozaiks-workspace는 Mozaiks가 생성된 출력물, 설정(config), 및 실행 스크립트를 사용하는 로컬 작업 공간 폴더입니다. 이것 자체가 앱은 아닙니다. 앱은 나중에 Studio 내부에서 생성됩니다.
Studio(http://127.0.0.1:3000/apps)에서 Create App을 클릭한 다음, 무엇을 만들고 싶은지 설명하세요. 워크플로우가 빌드 단계를 안내하고 생성된 아티팩트를 검토할 수 있도록 스테이징합니다. 진행 중인 빌드는 Apps에 남아 있으므로, 언제든지 중단했던 지점부터 다시 시작할 수 있습니다.
프로모션(promotion) 후에는 나중에 변경된 부분이 있다면 이를 설명하여 이미 가지고 있는 앱을 대상으로 Refinement Run을 시작할 수 있습니다. 타이포 수정부터 주요 제품 재고민까지 다양한 예시는 Genesis Builds and Refinement Runs를 참조하세요.
설정이 실패하면 다음 세 가지를 먼저 확인하세요: mozaiks 명령어가 사용 불가능한 경우 python -m mozaiks를 사용하고, MONGO_URI가 접근 가능한 MongoDB 인스턴스를 가리키는지 확인하며, 빌드를 실행하기 전에 LLM API 키를 설정하세요. 오늘날 빌드는 OPENAI_API_KEY만 사용합니다.
생성(Generation)은 보이는 부분입니다. 생성된 출력을 유지할 만한 가치를 갖게 하는 것은 그 아래의 런타임이며, 이 런타임은 앱이 생성되었든 수동으로 작성되었든 동일합니다.
이는 거의 모든 SaaS가 수동으로 재구축하는 패턴입니다. Mozaiks에서는 런타임 원시 요소(runtime primitive)입니다. 모듈 액션이 특정 기능을 명명하고, 실행기(executor)는 디스패치 전에 이를 확인합니다.
# modules/reports/module.yaml
actions:
- id: export_report
...
app/config/subscriptions.yaml은 어떤 플랜이 reports.export를 부여하는지 선언합니다. 구독이 없는 앱은 NoOpEntitlementAdapter를 받으며 완전히 영향을 받지 않습니다. 강제 적용은 닫힌 실패(fails closed) 방식을 따릅니다: 오류가 발생하는 어댑터는 부여하기보다는 거부합니다.
인프라는 런타임이 선언하고 여러분을 위해 절대 구현해주지 않는 프로토콜 뒤에 자리 잡습니다:
| 포트 | 계약(Contract) | 포함됨 |
|---|---|---|
EntitlementPort | 이 범위에 대해 이 기능이 부여되었는가? | no-op + config-driven 어댑터 |
| ... | ||
| Swap any of them for your own without forking the runtime. (런타임을 포크(fork)하지 않고도 원하는 것으로 교체할 수 있습니다.) |
모듈, 액션, 이벤트, 반응, 페이지, 워크플로우, 데이터 계약 등 모든 표준 YAML 형태는 엄격한 타입 모델에 의해 지원되며 활성화되기 전에 검증됩니다. 반복적으로 생성되고 결정론적으로 검증될 수 없는 계약은 계약으로 취급되지 않습니다.
워크플로우 큐(workflow queue)는 리스(leases), 펜싱 토큰(fencing tokens), 제한적 재시도(bounded retry), 그리고 데드 레터링(dead-lettering)을 사용하므로, 워커가 실행 도중 죽더라도 작업을 방치하거나 중복하지 않습니다. 모듈 디스패치(module dispatch)는 호출자에게 신뢰하는 대신 명시적인 권한 객체(authority object)를 필요로 합니다. 테넌트 격리(tenant isolation)는 각 쿼리가 자체적으로 처리하는 대신 하나의 표준 범위 필터(canonical scope filter)를 통해 이루어집니다.
생성된 앱들은 제공자 중립적(provider-neutral)이며 자체 호스팅이 가능합니다. 즉, Dockerfile, compose 파일, env 매니페스트, 그리고 스테이지드 데이터 계약 마이그레이션(staged data-contract migrations)으로 구성되어 있습니다. 어떤 것도 BlocUnited의 호스팅 플랫폼을 실행하는 데 필요하지 않습니다.
Widget Demo
앱의 어느 곳에든 플로팅 어시스턴트(floating assistant)를 배치하세요. 버튼을 클릭하여 채팅 인터페이스를 확장/축소할 수 있습니다.
| 워크플로우 모드 (Workflow Mode) | 질문 모드 (Ask Mode) |
|---|---|
 |  |
| 채팅 + 아티팩트 분할 보기 | 히스토리 사이드바가 있는 전체 채팅 |
문서를 로컬에서 미리 보려면 python -m pip install -e ".[docs]"를 실행한 후, python -m mkdocs serve를 실행하십시오 (모든 셸에서 동일한 명령어입니다). 자세한 내용은 Contributing을 참조하십시오.
포크(Fork)하고, 브랜치(branch)를 생성한 다음, pip install -e ".[dev]"로 개발 의존성을 설치하고, 집중적인 변경 사항을 만든 후, 관련 테스트를 실행하고, 풀 리퀘스트(pull request)를 여십시오. 문서화, 대부분의 테스트, 그리고 많은 CLI 변경 사항은 MongoDB, Node.js 또는 LLM API 키가 필요하지 않습니다. 전체 경로는 CONTRIBUTING.md에서 확인하십시오.
첫 이슈를 찾고 계신가요? good first issue부터 시작하세요 — 두 사람이 같은 수정 사항을 만들지 않도록, 작업하기 전에 하나에 댓글을 달아 소유권을 주장하십시오.
AI 코딩 에이전트를 사용하십니까? 환영합니다 — 먼저 AI Policy를 읽어보십시오. 내용은 짧으며, 유지 관리자(maintainers)와 그들의 에이전트 모두에게 동일하게 적용됩니다.
질문이 있거나 코드를 작성하기 전에 접근 방식을 논의하고 싶으신가요? Discord에서 참여하십시오.
버그를 보고하거나, 문서를 작성하거나, 코드를 검토하거나, 수정 사항을 배포하는 모든 사람이 이 벽에 속합니다.
</div>본 프로젝트는 Code of Conduct를 따릅니다.
MIT. LICENSE를 참조하십시오. 해당 라이선스는 코드에 적용되며,