Metadata-Version: 2.5
Name: ros_checker
Version: 0.1.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 토픽/노드/서비스/액션을 분석해 **신호 수신 여부**와 **Nav2 구동 가능성**을 체크하고, **LLM(ollama / Azure OpenAI)**으로 자연어 진단을 제공하는 CLI 앱입니다.

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

## 기능

| 커맨드 | 설명 |
|---|---|
| `ros-checker scan` | ROS2 그래프 스캔 — 토픽/노드/서비스/액션, 토픽별 hz·대역폭 |
| `ros-checker health` | 토픽 신호 수신, 노드 존재, 서비스 호출 헬스 체크 |
| `ros-checker nav2` | Nav2 구동 가능성 체크 (라이프사이클, costmap, cmd_vel, 액션) |
| `ros-checker analyze` | 수집 데이터를 LLM으로 자연어 진단 |
| `ros-checker config` | 설정 출력 (`config init`/`set`으로 생성·수정) |

## 문서

- [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 구동 가능성
uv run ros-checker nav2

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

> ROS2가 없는 환경에서도 `--mock` 플래그로 Mock 그래프를 사용해 기능을 확인할 수 있습니다.
> `uv run ros-checker nav2 --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        │  │ 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](LICENSE) 라이선스로 배포됩니다.
