Extelligence-ai/bagel

📦 Bagel – 로봇, 드론 및 IoT 로그에 대한 자연어 분석

무엇인가요 – Bagel(Extelligence 소유)은 Docker 기반 서비스로, 로봇, 드론 또는 IoT 데이터를 자연어로 질문할 수 있게 해줍니다. 질문을 던지면(*예: "내 IMU가 과열되었나요?" 또는 "매번 강한 브레이크 발생 시 10초 전후만 유지") Bagel은 로그 데이터 위에서 실행되는 결정론적 DuckDB SQL로 요청을 변환합니다. 생성된 SQL은 사용자에게 표시되므로, 답변은 검증 가능하고 블랙박스 LLM 추측이 아닙니다.

왜 중요한가요 – 많은 로봇 파이프라인에서 데이터는 방대하고 ROS 2 배그, PX4 로그, MCAP, CAN 캡처, MQTT 스트림 등 다양한 형식으로 저장됩니다. 일반적으로 통찰을 얻기 위해 스크립트를 작성하거나, grep을 사용하거나 PlotJuggler 같은 도구에 수동으로 데이터를 불러와야 합니다. Bagel은 언어 이해 부분을 LLM(Claude Code, Gemini, Codex, Ollama 등)에 맡기지만, 필터링, 집계, 조인과 같은 모든 무거운 작업은 로봇이나 엣지 서버에서 로컬로 실행되는 SQL에 맡깁니다. 이를 통해 다음과 같은 이점을 얻을 수 있습니다:

• 자연어 인터페이스 – 정확한 토픽 이름이나 SQL 구문을 알 필요 없이 질문할 수 있습니다.
• 투명하고 재현 가능한 쿼리 – 답변을 생성한 정확한 SQL을 확인하고 편집할 수 있습니다.
• 엣지 데이터 축소 – 한 문장으로 엣지에서 실행되는 감지기(디텍터)를 정의할 수 있으며, 관련 시간 창만 유지하고, 기가바이트의 원시 데이터 대신 아주 작은 배그 파일만 전송할 수 있습니다.
• 광범위한 형식 지원 – ROS 1/2, PX4, ArduPilot, Betaflight, 자동차 MDF4/CAN, MQTT, PostgreSQL/TimescaleDB, InfluxDB 3 등.

---

🚀 주요 기능 (README에 기재된 내용)

• 일상어 쿼리 – DSL을 배울 필요 없이 로그에 대해 무엇이든 질문할 수 있습니다.
• 결정론적 SQL 백엔드 – 모든 계산은 검증 가능한 DuckDB 쿼리입니다.
• 자연어 파이프라인 – 한 문장으로 이벤트 기반 축소를 설명하고, 파이프라인을 미리 보기 후, 펌웨어 전체 또는 엣지에서 실행할 수 있습니다.
• MCP 기반 LLM 지원 – Claude Code, Gemini CLI, Codex, Cursor, Ollama 등과 호환됩니다.
• Docker 컨테이너화 – ROS 2(Kilted, Jazzy, Iron, Humble), ROS 1, PX4, ArduPilot, Betaflight, 일반 IoT용 실행 가능한 이미지 제공.
• POML을 통한 확장성 – .poml 파일을 하나 추가만 하면 새로운 "트릭"(사용자 정의 기능)을 추가할 수 있으며, 재빌드 없이 가능합니다.
• 통합 기능 – 결과를 PlotJuggler, Rerun, Foxglove/Lichtblick, Cloudini 포인트 클라우드 압축, Slack 알림, LeRobot 학습 데이터셋으로 내보낼 수 있습니다.

---

🛠️ 작동 방식 (README의 고수준 흐름)

1. 메타데이터 탐지 – Bagel은 로그의 스키마(토픽, 필드, 타임스탬프)를 읽습니다.
2. 프롬프트 해석 – LLM이 자연어 요청을 분석하고 관련 토픽을 결정합니다.
3. Arrow 변환 – 관련 메시지는 Apache Arrow 파일로 작성됩니다.
4. SQL 생성 – LLM이 요청된 계산을 구현하는 DuckDB SQL 쿼리를 생성합니다.
5. 실행 및 반복 – DuckDB가 쿼리를 실행합니다. 답변이 더 자세히 필요하면 반복하여 만족스러운 응답이 나올 때까지 반복합니다.
6. 결과 전달 – 답변(및 SQL)은 LLM 클라이언트로 반환되며, 선택적으로 파이프라인 단계에서 MCAP 스니펫, CSV/Parquet, 클라우드 스토리지로 전송할 수 있습니다.

---

🎯 일반적인 사용 사례

상황	Bagel에게 어떻게 질문할 것인가
빠른 상태 점검	"이 ROS2 배그의 메타데이터를 요약해줘." → 간결한 리포트 카드를 반환합니다.
고장 탐지	"IMU 센서가 과열되었나요?" → 온도 토픽에 대한 통계 검사를 실행합니다.
이벤트 기반 자르기	"가속도가 –10 m/s²보다 강한 감속마다 10초 전후만 유지하고 나머지는 제거해줘." → 엣지에서 작동하는 축소 파이프라인을 생성하여 2GB 로그를 약 160MB로 축소합니다.
다중 토픽 분석	"/spot/status/battery_states에서 전류와 전압의 상관관계는 무엇인가요?" – 단일 SQL 조인으로 corr()를 계산합니다.
배치 처리	"폴더 X에 있는 모든 배그에 이 파이프라인을 적용해줘." – Bagel은 동일한 결정론적 파이프라인을 펌웨어 전체에 적용하고 통합 리포트를 생성합니다.
오프라인 작업	Ollama(qwen3:8b 등)를 로컬에 설치하고 ollmcp를 사용하면 데이터와 모델이 모두 기계 내부에 머무릅니다.

---

🏁 시작하기 (README의 빠른 시작 단계)

1. Docker Desktop 설치 및 MCP 지원 LLM(Clause Code가 기본 예시) 설치.
2. 리포지토리 복제 후 적절한 Docker Compose 서비스 시작, 예:

   git clone https://github.com/Extelligence-ai/bagel.git && cd bagel
   docker compose run --service-ports ros2-kilted
   

3. LLM 연결 (Claude Code 예시):

   claude mcp add --transport sse bagel http://localhost:8000/sse
   

4. 모델에 프롬프트 – Claude(또는 다른 MCP 클라이언트)를 열고 로그에 대해 질문합니다.
5. 선택적 오프라인 모드 – Ollama 설치, 로컬 모델 다운로드 후 동일한 MCP 서버를 가리키는 ollmcp 실행.

또한 단일 명령어 데모도 제공됩니다:

docker run -it --rm ghcr.io/extelligence-ai/bagel/px4:latest demo

이 명령어는 내장된 PX4 비행 로그에 대한 건강 리포트를 출력합니다.

---

⚠️ 알려진 제한 사항 (기재된 내용)

• 자동차 MDF4/CAN 지원은 여전히 베타 상태이며(생성된 파일만 테스트됨).
• 축소 비율은 작업 부하에 따라 달라지며 벤치마크되지 않음; README의 수치는 예시용입니다.
• MCP 엔드포인트는 인증이 없으며, localhost에만 바인딩됨 – 공개하려면 프록시를 추가해야 합니다.
• 소규모 로컬 LLM(4~8B)은 다단계 파이프라인 처리에 어려움을 겪을 수 있음; 더 큰 모델이 더 신뢰할 수 있는 도구 선택을 제공합니다.
• InfluxDB/Postgres의 라이브 데이터베이스 엔드투엔드 테스트는 CI가 아닌 사용자 제공 인스턴스에서만 실행됩니다.

---

📄 라이선스

Apache License 2.0 (오픈소스).

---

결론 – Bagel은 로봇, 드론 및 IoT 텔레메트리에 대한 자연어 기반 LLM 인터페이스와 엄격한 SQL 기반 분석 사이의 실용적인 다리를 놓아줍니다. 엔지니어는 고수준 질문을 던지고, 기반 계산을 검증하며, 엣지에서 거대한 로그를 자동으로 축소할 수 있으며, 모든 작업은 Docker 격리 환경에서 수행됩니다.