ldraw-nova

AI 에이전트에게 모델 아이디어를 제공하세요. 가이드하고, 빌드하게 하고, LDraw LEGO© 모델을 얻으세요.

빌드 과정이 완료되면 다음과 같은 결과물을 받게 됩니다:

• 소스 코드: LDraw language 형식의 소스 코드.
• 다양한 뷰: 3D 뷰어, 3D 플레이어, VR 인터랙티브 (Meta Quest 3), 이미지 등...
• Blender 편집 가능 glTF 파일: .glb 형식이며, 메타 정보는 Blender의 Custom Properties로 포함됩니다.
• 채팅 기록 및 에이전트 사고 과정.
• 그리고 더 많은 것들... 👌

비디오를 확인해 보세요:

<img src="img/ldraw-nova-yt-thumb.jpg">

설치

[!IMPORTANT]
적합한 부품과 예제 모델을 찾는 데 에이전트가 사용하는 도구는 jev-rerank (저 또한 작성자입니다)를 활용합니다.
이것은 TypeSafe'의 Jev System One AI 모델을 기반으로 하는 시맨틱 검색 도구이며 재순위화(re-ranking) 기능을 갖추고 있습니다.

• TypeSafe API 키(TYPESAFE_API_KEY)가 있는 경우, 웹 앱의 설정(Settings) 섹션에 값을 설정하세요.
• 없다면, 재순위화 검색이 작동하지 않으며, 에이전트는 대체 전략으로 **FTS (Full Text Search)**를 사용하게 되며, 이 경우 (어쩌면) 더 나쁜 모델을 생성할 수 있습니다.

Docker를 사용하여 웹 앱으로 ldraw-nova를 실행하세요. Git과 Docker가 필요합니다.

이 웹 앱은 도커화되어 실행되며, Docker 이미지를 빌드하려면 두 개의 형제 리포지토리가 필요합니다:

• ldraw-nova: 당연히 이 프로젝트입니다 😉
• ldraw-nova-docker: 도커 구성과 웹 앱을 모두 제공합니다.

1. 클론(Clone) 두 리포지토리를 나란히, 같은 태그로 복제하여 함께 작동하도록 만드세요:

git clone --branch v0.6.0 https://github.com/anteloc/ldraw-nova.git
git clone --branch v0.6.0 https://github.com/anteloc/ldraw-nova-docker.git

2. Docker 이미지 빌드하기. 첫 번째 빌드는 시간이 오래 걸리며 약 5GB의 디스크 공간이 필요합니다:**

cd ldraw-nova-docker
docker compose build

3. 앱 실행하기:

docker compose up -d

4. 브라우저에서 열기:

• https://localhost:8443: Meta Quest 3용 VR에 필요합니다. 인증서가 자체 서명(self-signed)되어 있으므로, 처음에는 브라우저의 경고를 수락해야 합니다.
• http://localhost:8765: 일반 HTTP이며, 인증서 경고가 없습니다. 자체 서명 인증서가 방해가 될 경우 사용하세요. 이 방식으로도 VR은 작동하지 않습니다.

네트워크상의 다른 장치들은 localhost 대신 컴퓨터의 IP 주소로 앱에 접근할 수 있습니다. 예를 들어, Quest 3에서 https://192.168.1.20:8443과 같이 접근할 수 있습니다. 이 앱은 로그인 기능이 없으므로 신뢰하는 네트워크에서만 실행하세요.

중지하려면:

docker compose down

왜 이런 과정들이 필요한가요?

요약하자면, 저는 **설계 가능한 물리적 사물을 만들 수 있는 에이전트형 LLM(agentic LLMs)**을 얻기 위해 이 과정을 거쳤습니다!

LDraw라는 어셈블리 언어(말장난입니다! 😜)를 찾는 것은 동시에 간단하고, **저수준(low level)**이며, 3D CAD 모델을 생성할 수 있도록 실행 가능한 것이어야 했고, 이것이 저에게 ChatGPT와 Claude 모두를 사용하여 그들이 다른 프로그래밍 언어에서 하듯이 LDraw로 코딩하도록 시도하는 실험 아이디어를 주었습니다.

놀랍게도 이 언어는 부품 회전, 위치 지정 등 **수학(math)**에 중점을 두고 있어 LLM이 보통 취약한 부분임에도 불구하고, 초기 테스트에서 에이전트들이 꽤 잘 작동했으며 이후 프로젝트에서도 좋은 결과를 얻었지만, 생성된 모델을 정확하다고 간주하기에는 결코 충분하지는 않았습니다:

• 초기 연구: ldbuilder-ai
• 에이전트형 Python 툴링의 1차 시도: py2bricks
• 2차 시도: py4bricks

이 세 가지 시도와 상당한 다른 실험들을 거치면서 저는 다음과 같은 결론에 도달했습니다:

💡 결론 1: 에이전트에게는 기하학 수학(geometry math)으로 가는 최소 저항 경로가 존재합니다. 즉, 다음과 같습니다.

• 에이전트에게 LDraw 소스를 생성할 수 있는 도구(tooling)를 제공하는 것은 기하학 수학을 우회하게 해줍니다 (악마!).
• ... 왜냐하면 스스로 수학을 만들어내는 것보다, 수학을 생산해내는 파이썬 코드를 생성하는 데 훨씬 더 능숙하기 때문입니다!
• ... 직접 수학을 생산하는 것보다도 말이죠!

💡 결론 2:

• 에이전트는 모델을 생산하는 파이썬 코드로부터 학습할 때, 모델 자체 (LDraw의 악마적인 기하학, 또다시...)로부터 학습할 때보다 더 나은 경향을 보입니다.

그렇다면, 남은 유일한 것은 🤔 필요한 **기본 요소(primitives), 동사(verbs), 구성적 어휘(constructive vocabulary)**를 갖춘 파이썬 기반의 도구(tooling)를 만드는 것이었습니다... 그래야 에이전트가 예시를 통해 학습하고 스스로 유사한 작업을 수행할 수 있게 됩니다.

이는 정말로 제대로 구현하기 어려운 일이었고, 심지어 '바이브 코딩(vibe coding)'을 하더라도 그랬습니다... 그러다가 GPT-6 Astra와 Claude Opus 5.5가 등장하면서... 그리고 그것을 제대로 바이브 코딩해냈습니다! 🚀🚀🚀

작동 방식

ldraw-nova는 에이전트가 실제 LDraw 부품으로 모델을 설계하는 데 필요한 도구, 예시 및 지침을 제공합니다.

과정은 다음과 같습니다:

1. 에이전트가 **프롬프트(prompt)**를 받습니다.
2. instructions.md와 관련 문서를 읽어 LDraw 언어(https://www.ldraw.org/) 및 LEGO© 모델 제작에 대해 학습합니다.
3. 모델을 어떻게 만들지 계획합니다: 필요한 부품, 생성할 하위 모델(submodels), 미학적 요소 등...
4. 반복적으로:
   1. 모델/하위 모델에서 이미지를 렌더링합니다.
   2. 이미지를 검사하고, 위치 및 미학적 요소를 조정하며... 다시 렌더링으로 돌아갑니다.
5. ... 모델이 완료되어 전달할 준비가 되었다고 판단할 때까지!

제공되는 도구는 에이전트에게 다음을 지원합니다:

• 적절한 부품을 찾는 것.
• 또한, 시작할 수 있는 예시 모델(example models) 및 하위 모델(submodels).
• 부품을 올바르게 배치하기 위한 충돌(Collision) 및 틈새(gaps) 감지.
• 현재 결과를 검사하기 위한 헤드리스 렌더링(Headless rendering).
• 그리고 그 외의 것들...

에이전트는 실제로 부품을 배치하는 것으로 시작하지 않으며, 프로토타이핑이나 기존 예시 모델을 수정하며 학습하는 경우를 제외하고는 그렇지 않습니다.

이 모델을 생성하는 방식은 다음과 같습니다:

• 실험 결과, 문서 및 계획에서 필요한 정보를 수집합니다.
• 모델과 서브모델의 기하학적 구조를 포함하여 이를 완전히 설명하는 하나 이상의 **계획(plan)**을 구축합니다. 예를 들어 atlas-crane.plan.json와 같습니다.
• 그리고 그 계획을 바탕으로, 예컨대 generate.py와 같은 하나 이상의 **생성기 스크립트(generator scripts)**를 만듭니다.
• ... 이 스크립트를 실행하면 매우 전문화된 3D CAD 언어인 LDraw 소스 파일을 생산합니다.
• ... 예컨대 atlas-crane.mpd와 같습니다.

요약하자면, 이것은 다음과 같은 과정입니다:

• **에이전트(agent)**가 **생성기(generator)**를 만드는 것
• ... 이 생성기가 3D 모델을 생산하는 것
• ... 그 모델의 언어가 LDraw라는 어셈블리 언어인 것입니다 🤯

어느 정도 컴파일러 같은 것이라고 할 수 있습니다 🤓

flowchart TD
    agent([에이전트]) -- 생산 --> plan[plan.json]
    plan -- 해석 --> gen[generator.py]
...

에이전트의 정보 출처

이것들은 에이전트를 빌더로 만들기 위해 제공되는 가이드 및 참고 자료들입니다:

개발 현황

**첫 번째 출시(first release)**인 만큼, 아직 개선해야 할 부분이 꽤 있습니다:

• Meta Quest 3용 VR: 모델 처리에서 많은 문제점과 성능 문제가 있습니다.
• 저사양 에이전트 적응: Luna, Haiku 등 저사양 모델의 사용성을 개선하기 위해 현재 도구(tooling), 문서 및 지침을 조정해야 합니다.
• 비싼 생성 과정: 현재는 대형이고 정확한 모델을 생성할 수 있는 것은 오직 고가의 최고급 모델들뿐입니다.
• 효율성 개선: 생성 프로세스가 현재 느립니다.
• 더 많은 모델군 추가 및 개선:
  • 인간과 동물: 미니피그(minifigs)
  • 테크닉 모델: 기계, 엔진 등...
  • 우주선: 생성된 모델이 그리 좋지 않습니다.
• 매뉴얼로 모델 제작: 부분적으로 작동하며, 페이지 매뉴얼을 이미지 형태로 제공하면 더 좋을 것입니다.
• 세밀 검사(Fine-grained inspection): 서브모델과 단계별 조립 과정을 검사하기 위함입니다.

기여 (Contributing)

곧 공개됩니다 (COMING SOON)

감사의 말 (Acknowledgements)

다음 분들께 감사드립니다:

• The LDraw Community
• LDView의 Travis Cobbs (@tcobbs)와 기여자분들.
• LeoCAD의 Leonardo Zide (@leozide)와 기여자분들.
• LDCad 및 Shadow Library, Roland Melkert.
• ldraw.rs의 Park Joon-Kyu (@segfault87)와 기여자분들.
• pyldraw3의 Harold Martin (@hbmartin)과 기여자분들.

... 그리고 다른 수많은 LDraw 제작자 여러분께도 감사드립니다!

참고: 이 작업을 위해 저는 여러 출처의 많은 LDraw 모델, 라이브러리, 도구, 문서 등을 사용했습니다.

이 프로젝트에 수십 년 동안, 자신의 최고 작품을 공공 영역과 오픈 소스 커뮤니티에 아낌없이 기부하며 관대하게 기여해 온 놀라운 분들이 많습니다.

만약 이 섹션에 포함되어야 한다고 생각하시면, 저에게 이메일을 보내주세요!

상표권 (Trademarks)

**LEGO(R)**는 본 소프트웨어를 후원하거나 승인하거나 보증하지 않는 LEGO Group 회사들의 상표입니다.