Metadata-Version: 2.5
Name: ros_checker
Version: 0.2.1
Summary: ROS2 토픽/노드/서비스/액션을 분석하고 Nav2 구동 여부를 LLM으로 진단하는 CLI 앱
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: lark>=1.1
Requires-Dist: numpy
Requires-Dist: wpycli
Requires-Dist: wpyconf
Requires-Dist: wpylog
Description-Content-Type: text/markdown

# ros_checker

ROS2 토픽/노드/서비스/액션을 그래프 전체 관점에서 모니터링하고, 항목을 역할별로 분류해 **신호 상태와 통신 구조**를 설명하는 CLI 앱입니다. Nav2 구동 가능성은 별도 `nav2` 커맨드에서만 검사하며, **LLM(ollama / Azure OpenAI)**으로 각 결과를 요약할 수 있습니다.

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

## 기능

| 커맨드 | 설명 |
| --- | --- |
| `ros-checker scan` | ROS2 그래프를 카테고리별로 모니터링 — 센서/위치/제어/네비게이션 등의 역할과 통신 상태 |
| `ros-checker health` | 전체 토픽/노드/서비스/액션의 현재 상태와 이상 징후 모니터링 |
| `ros-checker nav2` | Nav2 구동 가능성 체크 (라이프사이클, costmap, cmd_vel, 액션) |
| `ros-checker analyze` | 전체 모니터링 결과를 LLM으로 자연어 요약 (결과는 스타일 마크다운으로 출력) |
| `ros-checker config` | 설정 출력 (`config init`/`set`으로 생성·수정) |

## 모니터링 카테고리

토픽·서비스·액션은 이름과 통신 역할을 기준으로 다음 범주에 묶입니다.

- 센서: Lidar, 카메라, IMU, GPS 등 환경 인식 데이터
- 로컬라이제이션: 지도와 로봇 위치·자세 추정 데이터
- 오도메트리: 이동량 추정 데이터
- 네비게이션: 경로, costmap, 목표 지점 관련 통신
- 제어: `cmd_vel`, 관절·모터 제어 통신
- TF: 좌표 변환 통신
- 상태·진단: 배터리, 진단, 시스템 상태
- 시스템/기타: ROS2 내부 통신 및 미분류 항목

`scan`은 이 분류와 현재 발행자·구독자·주파수·대역폭을 보여주고, `health`는 전체 항목의 이상 징후를 요약합니다. Nav2 구동 여부는 `nav2`에서만 판단합니다.

## 문서

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

## 요구사항

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

## 설치 및 실행 (로컬)

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

# 그래프 모니터링 (카테고리별 출력)
uv run ros-checker scan

# 전체 통신 상태 모니터링
uv run ros-checker health

# Nav2 구동 가능성 (Nav2 전용)
uv run ros-checker nav2

# LLM 종합 모니터링 진단
uv run ros-checker analyze

# 각 결과를 LLM으로 요약
uv run ros-checker scan --ai
uv run ros-checker health --ai
uv run ros-checker nav2 --ai
```

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

## 설정

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

| 플랫폼 | 기본 경로 |
| --- | --- |
| Linux | `$XDG_CONFIG_HOME/ros-checker/config.toml` (기본 `~/.config/ros-checker/config.toml`) |
| macOS | `~/Library/Application Support/ros-checker/config.toml` |
| Windows | `%APPDATA%\ros-checker\config.toml` |

`config` 커맨드로 관리합니다.

```bash
# 기본 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 (기본)**

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

**Azure OpenAI**

```toml
[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`로 설치 없이 실행할 수 있습니다.

```bash
# 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`**로 실행해야 합니다.

```bash
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` 서비스를 해당 이미지로 교체하세요.

## 개발

```bash
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        │  │ Monitor      │  │ LLM       │  │
│  │ Introspection│→ │ Categories   │→ │ Analyzer  │  │
│  │ (rclpy/cli)  │  │ (rules)      │  │ (provider)│  │
│  └──────────────┘  └──────────────┘  └───────────┘  │
│        │                 │                │         │
│  ┌─────▼─────┐     ┌─────▼─────┐    ┌─────▼─────┐   │
│  │ ROS2 Graph│     │ Nav2      │    │ ollama /  │   │
│  │ (DDS)     │     │ Checker   │    │ AzureOpenAI│  │
│  └───────────┘     └───────────┘    └───────────┘   │
└─────────────────────────────────────────────────────┘
```

- `src/ros_checker/cmds/` — CLI 커맨드 구현 (scan/health/nav2/analyze/config, 스피너 UX)
- `src/ros_checker/graph/` — ROS2 그래프 인트로스펙션 (rclpy + ros2 CLI + Mock)
- `src/ros_checker/analysis/` — 그래프 카테고리 분류 + 전체 모니터링 분석
- `src/ros_checker/health/` — 일반 헬스 모델 + Nav2 전용 규칙
- `src/ros_checker/llm/` — LLM 프로바이더 추상화 (ollama/Azure OpenAI)
- `src/ros_checker/report/` — 테이블/JSON 리포트 및 마크다운 렌더링

## 라이선스

[MIT](LICENSE) 라이선스로 배포됩니다.
