ros_checker

ROS2 토픽/노드/서비스/액션을 분석해 신호 수신 여부와 Nav2 구동 가능성을 체크하고, **LLM(ollama / Azure OpenAI)**으로 자연어 진단을 제공하는 CLI 앱입니다.

로컬(호스트 ROS2)과 Docker(컨테이너 ROS2) 환경 모두에서 동작합니다.

기능

문서

• AGENTS.md — 에이전트/개발자용 개발 가이드 (TDD, 스타일, 명령어)
• CONTRIBUTING.md — 기여 가이드
• SECURITY.md — 보안 취약점 보고 절차
• docs/PLAN.md — 초기 구현 계획

요구사항

• Python 3.12
• ROS2 (Jazzy 등) — rclpy 필요. source /opt/ros/<distro>/setup.bash 후 실행
• LLM: ollama(로컬) 또는 Azure OpenAI(클라우드)

설치 및 실행 (로컬)

uv sync --group dev
source /opt/ros/<distro>/setup.bash

# 그래프 스캔
uv run ros-checker scan

# 헬스 체크
uv run ros-checker health

# Nav2 구동 가능성
uv run ros-checker nav2

# LLM 진단 (ollama 기본)
uv run ros-checker analyze

ROS2가 없는 환경에서도 --mock 플래그로 Mock 그래프를 사용해 기능을 확인할 수 있습니다. uv run ros-checker nav2 --mock

설정

설정은 플랫폼 표준 설정 디렉터리의 config.toml에서 읽습니다.

config 커맨드로 관리합니다.

# 기본 config.toml 생성
ros-checker config init

# 항목 수정·저장 (점 표기 키)
ros-checker config set llm.provider azure
ros-checker config set llm.model gpt-4o
ros-checker config set llm.timeout 30

# 현재 유효 설정 출력
ros-checker config

설정 파일이나 .env가 없어도 내장 기본값으로 동작하므로, uvx 등에서 별도 파일 없이 바로 실행할 수 있습니다. 파일을 지정하려면 -c/--config와 --dotenv 플래그를 사용합니다.

LLM 설정

config init/config set으로 생성한 설정 파일이나 .env로 프로바이더를 선택합니다.

ollama (기본)

[llm]
provider = "ollama"
base_url = "http://localhost:11434"
model = "llama3.2"

Azure OpenAI

[llm]
provider = "azure"
base_url = "https://<resource>.openai.azure.com"
model = "<deployment-name>"
api_key = "<your-api-key>"

환경 변수로도 설정 가능합니다 (ROS_CHECKER_LLM__PROVIDER 등, .env.example 참고).

uvx로 실행 (로봇에서)

패키지를 PyPI에 배포하면 로봇에서 uvx로 설치 없이 실행할 수 있습니다.

# ROS2 환경 source 후
source /opt/ros/<distro>/setup.bash

# 그래프 스캔 (rclpy 없으면 자동으로 ros2 CLI 사용)
uvx ros-checker scan

# CLI 소스 명시 (ros2 CLI만 필요, 가장 견고)
uvx ros-checker scan --source cli

# Nav2 체크 / LLM 진단
uvx ros-checker nav2 --source cli
uvx ros-checker analyze --source cli

동작 원리: uvx는 격리 환경을 만들지만 시스템 파이썬을 사용하므로 rclpy가 import 가능한 경우 rclpy 소스가 동작합니다. rclpy가 없거나 ~/.ros 로그 문제가 있으면 --source cli로 ros2 CLI만 사용해 동작합니다. 로봇에는 ros2 CLI가 항상 있으므로 --source cli가 가장 안정적입니다.

설정은 cwd가 아닌 플랫폼 기본 경로에서 읽으므로, 설정 파일이 없어도 기본값으로 동작합니다. 사용자 설정이 필요하면 uvx ros-checker config init로 기본 config를 만든 뒤 config set으로 수정하세요.

Docker 사용

체커는 ROS2 그래프의 노드로 참여하므로, ROS2 컨테이너와 **같은 네트워크 + 동일 ROS_DOMAIN_ID**로 실행해야 합니다.

docker compose build
docker compose up -d ros2-system   # ROS2 시스템(예: talker) 기동
docker compose run --rm checker scan
docker compose run --rm checker nav2
docker compose run --rm checker analyze

실제 Nav2/로봇 시스템을 사용한다면 docker-compose.yml의 ros2-system 서비스를 해당 이미지로 교체하세요.

개발

uv sync --group dev
uv run ruff check .
uv run ruff format --check .
uv run pytest

rclpy 통합 테스트는 ~/.ros에 로그를 쓰므로, 읽기 전용 환경에서는 ROS_LOG_DIR을 임시 경로로 지정하세요. 통합 테스트는 자체적으로 임시 디렉터리를 사용합니다.

아키텍처

┌─────────────────────────────────────────────────────┐
│  ros-checker CLI (wpycli 기반)                        │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────┐  │
│  │ Graph        │  │ Health       │  │ LLM       │  │
│  │ Introspection│→ │ Check Engine │→ │ Analyzer  │  │
│  │ (rclpy)      │  │ (rules)      │  │ (provider)│  │
│  └──────────────┘  └──────────────┘  └───────────┘  │
│        │                 │                │         │
│  ┌─────▼─────┐     ┌─────▼─────┐    ┌─────▼─────┐   │
│  │ ROS2 Graph│     │ Nav2      │    │ ollama /  │   │
│  │ (DDS)     │     │ Checker   │    │ AzureOpenAI│  │
│  └───────────┘     └───────────┘    └───────────┘   │
└─────────────────────────────────────────────────────┘

• src/ros_checker/graph/ — ROS2 그래프 인트로스펙션 (rclpy + Mock)
• src/ros_checker/health/ — 헬스 체크 엔진 + Nav2 규칙
• src/ros_checker/llm/ — LLM 프로바이더 추상화 (ollama/Azure OpenAI)
• src/ros_checker/report/ — 테이블/JSON 리포트 렌더링

라이선스

MIT 라이선스로 배포됩니다.