Metadata-Version: 2.4
Name: nova-agent
Version: 0.1.4
Summary: Nova Agent - Browser automation agent for Nova QA platform
Project-URL: Homepage, https://github.com/nova-platform/nova-agent
Project-URL: Documentation, https://docs.nova-platform.com/agent
Project-URL: Repository, https://github.com/nova-platform/nova-agent
Author: Nova Team
License-Expression: MIT
Keywords: agent,automation,browser,playwright,qa
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: httpx>=0.26.0
Requires-Dist: orjson>=3.9.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: structlog>=24.1.0
Requires-Dist: typer>=0.9.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Nova Agent

Nova QA 플랫폼용 로컬 브라우저 자동화 Agent입니다.

## 설치

```bash
pip install nova-agent
```

설치 후 Playwright 브라우저를 설치해야 합니다:

```bash
playwright install chromium
```

## 빠른 시작

### 1. Agent 등록 (최초 1회)

```bash
nova-agent login
```

브라우저가 열리면:
1. Nova 플랫폼에 로그인
2. Agent 이름 입력 후 등록
3. 발급된 토큰을 터미널에 붙여넣기

### 2. Agent 실행

```bash
nova-agent start
```

Agent가 Gateway에 연결되어 Job을 대기합니다.

## CLI 명령어

| 명령어 | 설명 |
|--------|------|
| `nova-agent login` | Agent 등록 및 토큰 발급 |
| `nova-agent start` | Agent 실행 |
| `nova-agent status` | 연결 상태 확인 |
| `nova-agent logout` | 토큰 삭제 및 로그아웃 |
| `nova-agent --help` | 도움말 |

## 옵션

### start 명령어 옵션

```bash
nova-agent start [OPTIONS]

Options:
  --headless / --no-headless  브라우저 헤드리스 모드 (기본: headless)
  --gateway-url, -g TEXT      Gateway 서버 URL
  --pool-size, -p INTEGER     동시 실행 브라우저 수 (기본: 1, 최대: 10)
  --verbose, -v               상세 로그 출력
```

### 예시

```bash
# 헤드리스 모드로 실행 (기본값)
nova-agent start

# 브라우저 UI 표시하며 실행 (디버깅용)
nova-agent start --no-headless

# 커스텀 Gateway URL 사용
nova-agent start --gateway-url wss://gateway.example.com/ws

# 동시에 3개 Job 처리 (브라우저 풀)
nova-agent start --pool-size 3

# 상세 로그 출력
nova-agent start --verbose
```

## 설정

### 토큰 파일

토큰은 `~/.nova-agent/token` 에 저장됩니다.

### 환경 변수

`.env` 파일 또는 환경 변수로 설정할 수 있습니다:

| 환경 변수 | 설명 | 기본값 |
|-----------|------|--------|
| `NOVA_GATEWAY_URL` | Gateway WebSocket URL | `ws://localhost:9100/ws/agent` |
| `NOVA_HEADLESS` | 헤드리스 모드 | `true` |
| `NOVA_POOL_SIZE` | 브라우저 풀 크기 | `1` |
| `NOVA_LOG_LEVEL` | 로그 레벨 | `INFO` |

환경 선택: `NOVA_ENV=prod`로 설정하면 `.env.prod` 파일을 로드합니다.

## 아키텍처

```
┌──────────────────────────────────┐     WebSocket     ┌─────────────────┐
│           Nova Agent             │◄──────────────────►│   Nova Gateway  │
│         (This package)           │                    │                 │
├──────────────────────────────────┤                    └────────┬────────┘
│          Browser Pool            │                             │
│  ┌──────────┐ ┌──────────┐       │                             │ WebSocket
│  │ Browser 1│ │ Browser 2│  ...  │                             ▼
│  │  Job A   │ │  Job B   │       │                    ┌─────────────────┐
│  └──────────┘ └──────────┘       │                    │   Nova Runner   │
└──────────────────────────────────┘                    │                 │
                                                        └─────────────────┘
```

### 브라우저 풀 동작 방식

- Job 할당 시 브라우저 시작, Job 완료 시 즉시 종료
- `--pool-size`로 동시 실행 가능한 브라우저 수 설정
- 풀이 가득 차면 다음 Job은 대기열에서 대기

## 메시지 프로토콜

Agent는 Gateway를 통해 Runner와 통신합니다:

### Agent → Gateway
- `agent_connect`: Agent 연결 요청
- `heartbeat`: 연결 유지 (30초 간격)
- `job_accepted`: Job 수락
- `step_started`: Step 시작
- `dom_extracted`: DOM 추출 완료
- `script_executed`: 스크립트 실행 완료
- `step_completed`: Step 완료
- `goal_achieved`: 목표 달성 (Runner 판단 후 응답)
- `job_completed`: Job 완료
- `error`: 에러 발생

### Gateway → Agent
- `registered`: 연결 및 인증 성공
- `job_assign`: Job 할당
- `extract_dom`: DOM 추출 요청
- `execute_script`: 스크립트 실행 요청
- `next_step`: 다음 Step 진행
- `job_cancel`: Job 취소
- `check_goal`: 목표 달성 확인 요청

## 개발

```bash
# 개발 환경 설치
pip install -e ".[dev]"

# 테스트 실행
pytest

# 린트
ruff check src/

# 타입 체크
mypy src/
```

## 라이선스

MIT License
