https://github.com/10kseason/home-agent

GPT, Claude,Gemini, 앱들을 활용해 99% 바이브 코딩으로 완성한 (로컬)Overlay LLM 오케스트레이터. 고사양 환경에서 실시간 STT/OCR/번역 가능.
https://github.com/10kseason/home-agent

agent llm local python vibe-coding vibecoding

Last synced: about 1 month ago
JSON representation

GPT, Claude,Gemini, 앱들을 활용해 99% 바이브 코딩으로 완성한 (로컬)Overlay LLM 오케스트레이터. 고사양 환경에서 실시간 STT/OCR/번역 가능.

• Host: GitHub
• URL: https://github.com/10kseason/home-agent
• Owner: 10kseason
• License: gpl-3.0
• Created: 2025-08-25T05:16:12.000Z (10 months ago)
• Default Branch: main
• Last Pushed: 2025-09-05T23:01:18.000Z (10 months ago)
• Last Synced: 2025-09-06T00:27:03.710Z (10 months ago)
• Topics: agent, llm, local, python, vibe-coding, vibecoding
• Language: Python
• Homepage:
• Size: 688 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 5
• Metadata Files:
  • Readme: README.md
  • License: LICENSE
  • Security: docs/SECURITY_PLUGINS.md

Awesome Lists containing this project

README

          
# Overlay LLM Orchestrator (Experimental)

> ⚠️ **본 프로젝트는 GPT, Claude, 기타 앱들을 활용해 만든 결과물입니다.**  

> ⚠️ **코드의 99%는 바이브 코딩(Vibe Coding)으로 작성되었습니다.**  

> ⚠️ 저는 단지 주도하여 이어붙이고 테스트했습니다. 완벽한 작품이 아닙니다.

---

## 🚀 설치 및 실행

압축을 풀고 `처음 사용자용 실행 및 설치.bat`를 실행합니다. LM Studio가 설치되어 있어야 하며

**OCR/`config.json`, STT/`config.yaml`, Overlay/`config.yaml`, agent/`config.yaml` 등 각 폴더의 설정 파일에 기재된 모델·파일 경로는 PC마다 모두 다릅니다. 반드시 자신의 절대경로로 수정하세요.**

**하드웨어 사양에 따라 모델 종류나 옵션을 바꿔 써도 무방합니다.**

📦 필요 모델 목록

Qwen2.5-VL-7B (고속 OCR+한국어 번역)

jan-nano

Qwen3 8B

GPT-OSS-20B (선택적)

Qwen3 14B (선택적)

LM studio에서 각 모델을 받아야 합니다.

Whisper Tiny

Whisper Faster는 STT 실행시 설치됩니다. 받는데 시간이 걸릴 수 있습니다.

최소 필요사양

24GB 이상 램,

대략 50GB 이상의 공간.

16GB 이상의 VRAM. (CUDA 에서만 동작 확인됨)

---

## 🖥️ 개발 및 테스트 환경

- GPU: **RTX 4060 Ti 16GB**

- CPU: **AMD 7800X3D**

- RAM: **32GB**

- OS: **Windows 11**

해당 사양에서 실시간 STT(Whisper) 전사와 Overlay 기능이 구동 가능하며, OCR은 다소 시간이 걸리지만 사용 가능합니다.

---

## ⚙️ 동작 구조

### 기본 오케스트레이션

- **jan-nano**

  → Overlay의 대부분 기능(툴 호출 담당)

### OCR 파이프라인

- **LM Studio**에서 4B 종료 후:

  - `Qwen2.5-VL-7B` : OCR 인식

  - 종료 후 `Qwen3 8B` : 한국어 번역

  - 결과 Overlay에 표시

- **고속 모드**:

  - `Qwen2.5-VL-7B`가 OCR과 한국어 번역을 한 번에 수행

- **자동 고속 모드**:

  - VRAM이 12GB 이하이거나 RAM이 24GB 이하인 시스템에서는 고속 모드가 강제 적용되며 비활성화할 수 없습니다.

### STT 파이프라인

- `Whisper Tiny / Faster` : 음성 전사 (BBC 뉴스도 인식 가능)

- `jan-nano` : 전사 결과물 한국어 번역

- 결과는 Overlay 및 `VSRG-Ts-to-KR.py (STT)` 창에 표시, **화자 분리 지원**

### 오케스트레이션 순환

- Overlay에 대화 전송 → LMS 설정에 따라 8B 종료 → 4B가 다시 툴 호출  

- 필요 시 OCR / STT 자동 불러오기 후 작업 완료 시 종료  

### 추가 기능

- 웹 검색 기능 포함 (현재 일부 버그 존재)

- `/Pin14b`, `/Pin20b` 명령어로 **Qwen3 14B**, **GPT-OSS-20B** 모델 호출 가능

- 대부분의 툴 콜링은 4B 수준에서 처리됨

- Overlay 종료 시 에이전트 서버도 함께 종료

- 명시적인 툴 목록 요청 인식 및 알 수 없는 명령어에 `/help` 안내

- 4B 모델이 번역 필요 여부를 판단하여 불필요한 번역을 방지

- 저사양(VRAM 12GB 이하 또는 RAM 24GB 이하)에서는 OCR이 자동으로 고속 모드로 실행되며 해제할 수 없음

- 한국어 환경에서만 테스트 완료

---

## 📦 필요 모델 목록

- **Qwen2.5-VL-7B**

- **jan-nano**

- **Qwen3 8B**

- **GPT-OSS-20B** (선택적)

- **Qwen3 14B** (선택적)

- **Whisper Tiny**

- **Whisper Faster**

---

## 🔑 라이선스

- GPL-3.0 License

- 이 저장소의 코드는 GPLv3로 배포됩니다.

- 이 프로젝트는 모델(가중치)을 포함하지 않습니다. 사용자는 각 모델의 라이선스 조건을 확인 후 직접 다운로드해야 합니다.

- "오픈소스" 표기는 코드에 한정되며, 모델은 각 저작권자/라이선스를 따릅니다.

- 단, **원본 GitHub 저장소 출처를 반드시 표기**해주세요

### 📚 의존 라이브러리 라이선스

아래는 `requirements.txt`에 명시된 주요 라이브러리와 그 라이선스입니다. 대부분은 GPLv3와 호환되지만, **PyQt5는 GPLv3**입니다.

| 라이브러리 | 라이선스 |

|------------|----------|

| fastapi | MIT |

| uvicorn | BSD-3-Clause |

| pydantic | MIT |

| httpx | BSD-3-Clause |

| requests | Apache-2.0 |

| PyYAML | MIT |

| loguru | MIT |

| PyQt5 | GPLv3 |

| PySide6 | LGPL-3.0 |

| pillow | HPND (PIL) |

| mss | MIT |

| keyboard | MIT |

| sounddevice | MIT |

| soundfile | BSD-3-Clause |

| soundcard | BSD-3-Clause |

| numpy | BSD-3-Clause |

| scipy | BSD-3-Clause |

| webrtcvad | MIT |

| faster-whisper | MIT |

| librosa | ISC |

| scikit-learn | BSD-3-Clause |

| pycaw | MIT |

| comtypes | MIT |

| duckduckgo-search | MIT |

| beautifulsoup4 | MIT |

| lxml | BSD-3-Clause |

이외 윈도우 전용 알림 라이브러리(win10toast, winotify)는 모두 MIT 라이선스로 배포됩니다.

**GPLv3 준수:** PyQt5는 GPLv3이므로 프로젝트 전체는 GPL 조항을 따릅니다. 나머지 라이브러리는 GPLv3와 호환되어 자유롭게 사용할 수 있습니다.

이 프로젝트는 로컬 실행의 안정성과 메모리 효율을 위해 **모든 모델을 4비트 양자화(예: GGUF Q4_K_M)**로 사용하는 것을 권장합니다. 

특히 **Vision 모델(Qwen2.5-VL-7B)**은 시스템 **RAM/VRAM 용량이 제한적일 경우 더 보수적인 양자화(예: Q4_K_S 또는 Q3_K 계열)**를 선택해 주세요. 

양자화는 메모리 사용량을 크게 줄이는 대신 정확도가 일부 낮아질 수 있으므로, 

표·수식·복잡 레이아웃 문서에서는 입력 해상도/컨텍스트 길이를 조절하거나 필요 시 상위 비트폭으로 재시도하는 것을 권합니다. 

각 모델의 사용 조건과 재배포 범위는 해당 모델 배포처의 라이선스(예: Apache-2.0, MIT 등)를 그대로 따릅니다. 상업적 이용 가능 여부, 3rd-party NOTICE 동봉 의무, 로고/상표 사용 가이드는 각 라이선스의 정의를 준수해야 합니다. 

본 저장소 코드가 GPLv3라 하더라도 모델 가중치는 별도 라이선스를 가질 수 있으니, 다운로드 시점의 LICENSE/NOTICE를 확인하고 재배포 시 반드시 원 저작권 고지를 포함해 주세요.

---

## 🙋‍♂️ 마무리

이 프로젝트는 제가 AI와 협업하여 시행착오 끝에 만들어낸 실험적 결과물입니다.  

사양이 되는 분들은 직접 돌려보시고, 마음껏 개조해주시면 감사하겠습니다.

---

## 🛠️ 유지 및 보수 가이드

이 섹션은 장기간 안정적인 서비스 운영을 위해 필요한 모든 관리 절차를 정리한 것입니다. 각 항목은 실제 운영 과정에서 빈번히 발생하는 문제를 예방하고, 발생하더라도 빠르게 복구할 수 있도록 돕습니다.

1. **종속성 관리**

   - `requirements.txt`를 정기적으로 확인하여 최신 버전을 추적하십시오. 새 버전 적용 시에는 항상 가상 환경에서 먼저 테스트하고, 기능이 정상적으로 동작하는지 확인해야 합니다.

   - `pip install -r requirements.txt` 실행 후에는 버전 충돌 여부를 검토하고, 필요 시 `pip freeze` 결과를 기록해 변경 이력을 남깁니다.

2. **환경 설정 백업**

   - `config.yaml` 및 `config.json` 등 모든 설정 파일은 버전별 백업을 유지하십시오. 변경 후 문제가 발생하면 즉시 이전 버전으로 롤백할 수 있어야 합니다.

   - 민감한 키나 토큰은 `.env` 파일이나 운영체제의 비밀 변수 기능을 활용해 관리하며, 절대 저장소에 포함시키지 마십시오.

3. **로그 관리**

   - 애플리케이션 실행 중 생성되는 `error.log`와 일반 로그 파일은 주기적으로 아카이브하거나 삭제하여 저장소 용량을 확보합니다.

   - 오류 로그를 분석할 때는 동일 문제가 반복되는지 패턴을 파악하고, 관련 이슈를 추적 시스템에 기록하여 팀과 공유하십시오.

4. **테스트 및 배포**

   - 모든 수정 사항은 `pytest -q`를 통해 자동화 테스트를 통과해야 하며, 새로운 기능 추가 시에는 테스트 케이스를 함께 작성합니다.

   - 배포 전에는 스테이징 환경에서 실제 사용 시나리오를 재현하여 회귀 오류를 확인합니다. 배포 후에는 모니터링 시스템을 통해 성능과 오류 여부를 지속적으로 관찰하십시오.

5. **보안 업데이트**

   - 외부 라이브러리에서 보안 패치가 발표되면 즉시 적용하고, 적용 내역을 CHANGELOG에 기록합니다.

   - 의존성 검사 도구(`pip-audit` 등)를 사용하여 취약점을 주기적으로 점검하십시오.

6. **문서화와 지식 공유**

   - 새로운 기능이나 설정 변경 사항은 README와 위키에 즉시 반영하여 팀 내 지식 격차를 최소화합니다.

   - 문제 해결 과정과 결정 이유를 문서화하여 향후 유지보수 담당자가 동일한 시행착오를 겪지 않도록 합니다.

7. **장기적인 계획 수립**

   - 기능 폐기 시에는 호환성 유지를 위한 대체 모듈이나 마이그레이션 방법을 미리 준비해 사용자 혼란을 방지합니다.

   - 프로젝트의 로드맵을 수립하고, 정기적인 리팩터링과 코드 리뷰 일정을 포함시켜 기술 부채를 줄입니다.

8. **백업과 복구 전략**

   - 중요 데이터와 모델 파일은 최소 2곳 이상의 물리적 또는 클라우드 위치에 백업하십시오.

   - 장애 발생 시 복구 순서를 문서화하고, 정기적으로 복구 절차를 리허설하여 실제 상황에서의 대응 시간을 단축합니다.

이상의 지침을 꾸준히 실천한다면 프로젝트는 장기간 안정적으로 운영될 수 있으며, 예기치 못한 오류나 환경 변화에도 유연하게 대응할 수 있습니다.