비전-언어 모델(vision-language model)을 기반으로 하는 완전히 로컬이며 개인 정보 보호를 우선하는 데스크톱 자동화 도구입니다.

사용자의 화면을 보고, 일반 텍스트 설명으로 UI 요소를 찾고, 클릭합니다. 이 모든 과정은 클라우드 호출 없이 사용자의 자체 하드웨어에서 이루어집니다.

Python 3.10+

Platform: Windows

Hacktoberfest 2026

팀 (Team)

팀 이름: Texperts | 팀 코드: HTF 009

멤버	역할	기여 내용
Bavan Vijaya Raja M.K	GPU 리드 (6GB VRAM)	llama-server 설정, Vision-Grounding 파이프라인, 추론 최적화
...

문제 정의 (Problem Statement)

수백만 개의 일상적인 사무 업무는 API가 노출되지 않은 데스크톱 앱 및 내부 도구 내에서 발생합니다. 예를 들어, 송장(invoice)을 읽어 스프레드시트에 기록하거나, 창 간에 값을 복사하거나, 동일한 양식을 반복적으로 작성하는 등의 작업입니다. 기존의 RPA(Robotic Process Automation) 도구는 픽셀 좌표나 취약한 선택자(selector)를 녹화하여 자동화합니다. 따라서 버튼이 이동하면 전체 워크플로우가 깨지고 누군가 수동으로 수정해야 합니다. 특히 스크린샷을 클라우드 서비스로 전송하는 것이 허용되지 않는 경우(은행, 내부 도구, 규제 산업 등), 반복적인 백오피스 작업을 처리하는 소규모 팀이 가장 큰 영향을 받습니다.

우리가 이것을 선택한 이유: 최근의 GUI-grounding 비전-언어 모델은 일반 텍스트 설명만으로 UI 요소를 찾을 수 있게 되어, UI 변경에도 살아남는 자동화를 현실적으로 만들었으며 단일 소비자 GPU에서도 실행할 만큼 작아졌습니다. 모든 것을 로컬로 유지하는 것은 민감한 워크플로우에 실현 가능성을 제공합니다.

해결책 (Solution)

Shadow Automator는 로컬 데스크톱 자동화 에이전트입니다. 사용자는 Ctrl+Space Spotlight 바를 통해 자연어로 원하는 것을 설명합니다. 시스템은 다음과 같이 작동합니다:

화면을 캡처하고(mss를 통해) PII(신용카드, SSN, 이메일)를 오프라인에서 OpenCV + 정규표현식으로 마스킹합니다.
비식별화된 스크린샷을 로컬에 호스팅되는 Qwen2.5-VL-3B 비전 모델로 전송합니다.
대상 요소의 정확한 [x1, y1, x2, y2] 경계 상자 좌표를 수신합니다.
투명 오버레이를 통해 화면에 빛나는 AR 경계 상자를 투영합니다.
PyAutoGUI를 통해 인간과 유사한 마우스 스무딩으로 클릭을 수행합니다.
UI 상태 변화가 감지되지 않으면 스스로 복구합니다 — 자동으로 재캡처하고 재기준화(re-grounds)합니다.
모든 작업을 SQLite에 기록하고 실시간 ROI 절감액(클라우드 비용 + 절약된 인력 시간)을 표시합니다.

주요 기능 (Key Features)

설명 기반 찾기 및 기준화 (Describe-and-find grounding) — 저장된 픽셀 좌표 없이 텍스트 설명으로부터 클릭 위치를 파악합니다.
오프라인 PII 마스킹 (Offline PII Redaction) — 이미지가 모델에 도달하기 전에 정규표현식 + OpenCV로 민감 데이터를 흐리게 처리합니다.
자가 복구 루프 (Self-Healing Loop) — MSE 기반 시각 상태 검증과 실패 시 자동 재기준화(re-grounding)를 수행합니다.
AR 경계 상자 오버레이 (AR Bounding Box Overlay) — 실제 UI 위에 빛나고 애니메이션되며 모서리 브래킷이 있는 상자를 투영합니다.
실시간 ROI 대시보드 (Live ROI Dashboard) — 클라우드 비용과 절약된 인력 시간을 추적하는 FastAPI 웹 대시보드를 제공합니다.
완전 로컬 구동 (Fully Local) — 자동화 과정 중 외부 네트워크 호출이 전혀 없으며, 모든 추론은 온디바이스에서 이루어집니다.

혁신 및 차별점 (Innovation and Differentiation)

기능	Shadow Automator	전통적인 RPA
UI 변경 허용성	✅ 텍스트 설명으로부터 재기준화(Re-grounds) 가능	❌ 픽셀 이동에 깨짐
...

기술 구현 (Technical Implementation)

아키텍처 (Architecture)

flowchart TD
    A[

다음 내용은 **Hacktoberfest Hack Day — Coimbatore 2026** 기간 동안 구축되었습니다:

### 1단계 — 환경 설정 및 핵심 모듈 (0~3시간)

-   GPU 오프로딩(`-ngl 99`) 및 모델 로드 검증을 통해 `llama-server`를 구성함
-   디스플레이 좌표 정규화 및 마우스 안전 경계가 적용된 화면 캡처 모듈(`mss`)을 구축함
-   핫키 리스너가 있는 투명한 `Ctrl+Space` 스포트라이트 검색창을 구축함
-   GitHub 저장소 초기화, MIT 라이선스, SQLite 로거 스키마 및 ROI 계산 공식을 마련함

### 2단계 — AI 통합 (3~7시간)

-   `[x1,y1,x2,y2]` JSON을 추출하는 비전-그라운딩 파이프라인(`POST /v1/chat/completions`)을 구축함
-   인간과 유사한 `easeOutQuad` 궤적을 가진 마우스 스무딩 알고리즘을 구현함
-   애니메이션되는 빛나는 경계 상자와 모서리 브래킷이 있는 AR 스타일의 투명 오버레이를 구축함
-   오프라인 PII(개인 식별 정보) 삭제(Regex + OpenCV) 및 FastAPI ROI 대시보드를 구현함

### 3단계 — 파이프라인 통합 및 자가 복구 (7~10시간)

-   응답 시간 500ms 미만을 목표로 추론 최적화 (temperature, 토큰 제한, 비전 압축)
-   자가 복구 루프(Self-Healing Loop) 구현: MSE 시각 상태 검증 및 자동 재그라운딩
-   이벤트 버스(Event Bus)를 통해 Spotlight UI와 오케스트레이터(Orchestrator) 연결 (단계 레이블, 진행률 표시줄, 토스트 팝업)
-   분석 상태 관리자(analytics state manager)가 있는 라이브 ROI 계산기를 작업 완료 이벤트에 연동함

### 4단계 — 테스트 및 다듬기 (10~12시간)

-   지속적인 자동화 루프 하에서 `llama-server`의 엔드투엔드 스트레스 테스트를 수행함
-   Excel, 브라우저, PDF 리더 등 다양한 엣지 케이스(Edge-case)에서 정확한 클릭 타겟팅을 위한 테스트를 진행함
-   시각적 다듬기: 빛나는 애니메이션, 타이머 바 및 스태킹이 적용된 PyQt5 토스트 알림 기능 구현
-   종합적인 README 작성, 아키텍처 다이어그램, 커밋 히스토리 감사(audit), 제출 준비를 완료함

## 오픈 소스와 AI 사용

### AI 모델

-   **Qwen3VL-4B-Instruct (Q4_K_M GGUF):** 모든 UI 접지(grounding)를 구동하는 비전-언어 모델(vision-language model). 스크린샷과 텍스트 설명을 받으면 정확한 경계 상자 좌표(bounding box coordinates)를 반환합니다. `llama-server`를 통해 `localhost:8080`에서 로컬로 서비스됩니다. [HuggingFace](https://huggingface.co/ShuaiBai623/Qwen3VL-4B-Instruct-GGUF)에서 다운로드할 수 있습니다.

### 오픈 소스 라이브러리 (Open Source Libraries)

| 라이브러리 | 역할 | 라이선스 |
| :--- | :--- | :--- |
| `llama.cpp` | 로컬 모델 서버 (OpenAI 호환 API) | MIT |
| ... | 
## 설정 및 사용법 (Setup and Usage)

### 전제 조건 (Prerequisites)

-   Windows 10/11
-   Python 3.10+
-   **4–6 GB VRAM**을 갖춘 GPU (또는 추론 속도가 느린 CPU)
-   [llama.cpp releases](https://github.com/ggerganov/llama.cpp/releases)에서 가져온 `llama-server` 바이너리

### 1. 저장소 복제 (Clone the Repository)

git clone https://github.com/bavanvrmk/Hacktoberfest-Texperts.git
cd Hacktoberfest-Texperts


### 2. Python 의존성 설치 (Install Python Dependencies)

pip install customtkinter pyqt5 mss pyautogui opencv-python numpy fastapi uvicorn keyboard jinja2


### 3. GGUF 모델 다운로드 (Download the GGUF Model)

자동 다운로드 스크립트 실행:

.\scripts\download_models.ps1


또는 수동으로 다운로드:

-   `Qwen3VL-4B-Instruct-Q4_K_M.gguf` → `models/` 폴더에 배치
-   `mmproj-Qwen3VL-4B-Instruct-F16.gguf` → `models/` 폴더에 배치

### 4. 환경 변수 구성 (Configure Environment Variables)

cp .env.example .env

모델 경로를 사용하여 .env 파일 편집

LLAMA_SERVER_URL=http://localhost:8080
MODEL_PATH=./models/Qwen3VL-4B-Instruct-Q4_K_M.gguf
MMPROJ_PATH=./models/mmproj-Qwen3VL-4B-Instruct-F16.gguf


### 5. 모델 서버 시작 (Start the Model Server)

.\scripts\start_server.ps1

진행하기 전에 서버 준비 상태를 기다립니다.


### 6. Shadow Automator 실행 (Run Shadow Automator)

전체 애플리케이션

python main.py

...


### 7. 사용법 (Usage)

1. 아무 곳에나 **`Ctrl + Space`**를 눌러 Spotlight 바를 열기
2. 자연어 명령어를 입력합니다: "폼에서 저장 버튼을 클릭하세요"
3. 앱을 실행하려면 `Open Spotify` 또는 `Open Brave Browser`를 입력합니다. Windows 검색창이 열리고, 이름이 입력되며, 상단 결과가 실행됩니다.
4. 파일을 열려면 `Open README.md` 또는 `Find the budget file`를 입력합니다. 파일 탐색기가 해당 이름을 검색하고 결과를 더블클릭합니다.
5. 다른 명령어의 경우, AR 빛나는 박스가 화면에서 목표 요소를 강조 표시하는 것을 지켜봅니다. 시스템은 인간과 유사한 궤적으로 클릭하고 상태 변화를 검증합니다.
6. 토스트 알림이 완료를 확인하며 ROI 절감액을 표시합니다.

## 도전 과제 및 학습 내용 (Challenges and Learnings)

-   **Q4_K_M 양자화 정확도:** 공개된 벤치마크 점수는 전체 정밀도 가중치를 기준으로 합니다. 양자화 모델의 바운딩 박스 정밀도는 신뢰할 수 있는 서브픽셀 정확도를 위해 프롬프트 엔지니어링을 통한 보정이 필요했습니다.
-   **Windows에서의 DPI 스케일링:** DPI 인식 캡처 및 클릭은 동일한 좌표 공간을 사용해야 합니다. 이는 가장 흔하게 오작동하는 원인이었으며 명시적인 DPI 정규화가 필요했습니다.
-   **모델 추론 지연 시간 (Model inference latency):** 콜드 인퍼런스(Cold inference)는 500ms를 초과합니다. 지속적인 서버 워밍업 호출 및 비전 토큰 압축을 통해 P90 지연 시간을 400ms 미만으로 낮췄습니다.
-   **UI의 스레드 안전성 (Thread safety in UI):** Tkinter와 PyQt5에서 백그라운드 스레드로부터 발생하는 UI 업데이트는 충돌을 야기했습니다. 모든 UI 변경 사항을 `.after()` 및 `QTimer.singleShot()`을 통해 라우팅함으로써 이 문제를 해결했습니다.
-   **자가 치유 허위 양성 (Self-healing false positives):** 정적 화면(예: 로딩 스피너)은 상태가 변경되었음에도 불구하고 거의 0에 가까운 MSE를 생성합니다. 1.5%의 델타 임계값은 경험적으로 조정되었습니다.

## 크레딧 및 라이선스 (Credits and License)

### 크레딧 (Credits)

-   **Qwen Team** — Qwen2.5-VL 모델
-   **llama.cpp 기여자들 (contributors)** — 로컬 추론 서버
-   **CustomTkinter** — TomSchimansky 제작
-   **INIT CLUB × iDEA CLUB** — Hacktoberfest Hack Day Coimbatore 2026 주최 측
-   **Major League Hacking (MLH)** — 이벤트 플랫폼 및 도전 과제

### 라이선스 (License)

본 프로젝트는 **MIT 라이선스**에 따라 배포됩니다. 자세한 내용은 [LICENSE](https://dev.toLICENSE)를 참고하세요.

제3자 모델은 자체 라이선스를 유지합니다. Qwen2.5-VL은 [Qwen License](https://huggingface.co/Qwen/Qwen2.5-VL-3B-Instruct/blob/main/LICENSE)에 따라 라이선스가 부여되었습니다.

## 제출 체크리스트

-   [x] 프로젝트 제목 및 설명 추가됨
-   [x] 모든 팀원 명단과 기여 내용 기록됨
-   [x] 문제점 명확하게 설명됨
-   [x] 문제 선택 이유 설명됨
-   [x] 솔루션 및 주요 기능 문서화됨
-   [x] 혁신성 및 차별점 설명됨
-   [x] 아키텍처 다이어그램 포함 (Mermaid)
-   [x] 기술 구현 내용 문서화됨
-   [x] 해커톤 기간 중 완료된 작업 기록됨
-   [x] 팀 기여도 문서화됨
-   [x] AI 및 오픈소스 구성 요소와 출처 명시됨
-   [x] 설정 및 사용 지침 완벽하게 갖춤
-   [x] 환경 변수 문서화됨
-   [x] 어려움과 학습 내용 기록됨
-   [x] 크레딧 추가됨
-   [x] MIT 라이선스 포함됨
-   [x] 리포지토리 정리 및 완벽함
-   [x] 비밀 정보 커밋되지 않음

섀도우 오토메이터 (Shadow Automator)

요약

핵심 포인트