{"id":49728712,"url":"https://github.com/10kseason/home-agent","last_synced_at":"2026-05-09T05:18:26.067Z","repository":{"id":312175762,"uuid":"1044039493","full_name":"10kseason/home-agent","owner":"10kseason","description":"GPT, Claude,Gemini, 앱들을 활용해 99% 바이브 코딩으로 완성한 (로컬)Overlay LLM 오케스트레이터. 고사양 환경에서 실시간 STT/OCR/번역 가능.","archived":false,"fork":false,"pushed_at":"2025-09-05T23:01:18.000Z","size":705,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-06T00:27:03.710Z","etag":null,"topics":["agent","llm","local","python","vibe-coding","vibecoding"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/10kseason.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY_PLUGINS.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-25T05:16:12.000Z","updated_at":"2025-09-01T08:58:00.000Z","dependencies_parsed_at":"2025-08-29T05:06:57.688Z","dependency_job_id":"84d562f5-80b4-4265-aa72-687df915e54c","html_url":"https://github.com/10kseason/home-agent","commit_stats":null,"previous_names":["10kseason/home-agent"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/10kseason/home-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/10kseason%2Fhome-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/10kseason%2Fhome-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/10kseason%2Fhome-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/10kseason%2Fhome-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/10kseason","download_url":"https://codeload.github.com/10kseason/home-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/10kseason%2Fhome-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32808045,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"online","status_checked_at":"2026-05-09T02:00:06.633Z","response_time":123,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","llm","local","python","vibe-coding","vibecoding"],"created_at":"2026-05-09T05:18:24.976Z","updated_at":"2026-05-09T05:18:26.056Z","avatar_url":"https://github.com/10kseason.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Overlay LLM Orchestrator (Experimental)\n\n\u003e ⚠️ **본 프로젝트는 GPT, Claude, 기타 앱들을 활용해 만든 결과물입니다.**  \n\u003e ⚠️ **코드의 99%는 바이브 코딩(Vibe Coding)으로 작성되었습니다.**  \n\u003e ⚠️ 저는 단지 주도하여 이어붙이고 테스트했습니다. 완벽한 작품이 아닙니다.\n\n---\n\n## 🚀 설치 및 실행\n\n압축을 풀고 `처음 사용자용 실행 및 설치.bat`를 실행합니다. LM Studio가 설치되어 있어야 하며\n**OCR/`config.json`, STT/`config.yaml`, Overlay/`config.yaml`, agent/`config.yaml` 등 각 폴더의 설정 파일에 기재된 모델·파일 경로는 PC마다 모두 다릅니다. 반드시 자신의 절대경로로 수정하세요.**\n**하드웨어 사양에 따라 모델 종류나 옵션을 바꿔 써도 무방합니다.**\n\n📦 필요 모델 목록\nQwen2.5-VL-7B (고속 OCR+한국어 번역)\njan-nano\nQwen3 8B\n\n\nGPT-OSS-20B (선택적)\nQwen3 14B (선택적)\nLM studio에서 각 모델을 받아야 합니다.\n\nWhisper Tiny\nWhisper Faster는 STT 실행시 설치됩니다. 받는데 시간이 걸릴 수 있습니다.\n\n최소 필요사양\n\n24GB 이상 램,\n\n대략 50GB 이상의 공간.\n\n16GB 이상의 VRAM. (CUDA 에서만 동작 확인됨)\n---\n\n## 🖥️ 개발 및 테스트 환경\n- GPU: **RTX 4060 Ti 16GB**\n- CPU: **AMD 7800X3D**\n- RAM: **32GB**\n- OS: **Windows 11**\n\n해당 사양에서 실시간 STT(Whisper) 전사와 Overlay 기능이 구동 가능하며, OCR은 다소 시간이 걸리지만 사용 가능합니다.\n\n---\n\n## ⚙️ 동작 구조\n\n### 기본 오케스트레이션\n- **jan-nano**\n  → Overlay의 대부분 기능(툴 호출 담당)\n\n### OCR 파이프라인\n- **LM Studio**에서 4B 종료 후:\n  - `Qwen2.5-VL-7B` : OCR 인식\n  - 종료 후 `Qwen3 8B` : 한국어 번역\n  - 결과 Overlay에 표시\n- **고속 모드**:\n  - `Qwen2.5-VL-7B`가 OCR과 한국어 번역을 한 번에 수행\n\n- **자동 고속 모드**:\n  - VRAM이 12GB 이하이거나 RAM이 24GB 이하인 시스템에서는 고속 모드가 강제 적용되며 비활성화할 수 없습니다.\n\n### STT 파이프라인\n- `Whisper Tiny / Faster` : 음성 전사 (BBC 뉴스도 인식 가능)\n- `jan-nano` : 전사 결과물 한국어 번역\n- 결과는 Overlay 및 `VSRG-Ts-to-KR.py (STT)` 창에 표시, **화자 분리 지원**\n\n### 오케스트레이션 순환\n- Overlay에 대화 전송 → LMS 설정에 따라 8B 종료 → 4B가 다시 툴 호출  \n- 필요 시 OCR / STT 자동 불러오기 후 작업 완료 시 종료  \n\n### 추가 기능\n- 웹 검색 기능 포함 (현재 일부 버그 존재)\n- `/Pin14b`, `/Pin20b` 명령어로 **Qwen3 14B**, **GPT-OSS-20B** 모델 호출 가능\n- 대부분의 툴 콜링은 4B 수준에서 처리됨\n- Overlay 종료 시 에이전트 서버도 함께 종료\n- 명시적인 툴 목록 요청 인식 및 알 수 없는 명령어에 `/help` 안내\n- 4B 모델이 번역 필요 여부를 판단하여 불필요한 번역을 방지\n- 저사양(VRAM 12GB 이하 또는 RAM 24GB 이하)에서는 OCR이 자동으로 고속 모드로 실행되며 해제할 수 없음\n- 한국어 환경에서만 테스트 완료\n\n---\n\n## 📦 필요 모델 목록\n- **Qwen2.5-VL-7B**\n- **jan-nano**\n- **Qwen3 8B**\n- **GPT-OSS-20B** (선택적)\n- **Qwen3 14B** (선택적)\n- **Whisper Tiny**\n- **Whisper Faster**\n\n---\n\n## 🔑 라이선스\n- GPL-3.0 License\n- 이 저장소의 코드는 GPLv3로 배포됩니다.\n- 이 프로젝트는 모델(가중치)을 포함하지 않습니다. 사용자는 각 모델의 라이선스 조건을 확인 후 직접 다운로드해야 합니다.\n- \"오픈소스\" 표기는 코드에 한정되며, 모델은 각 저작권자/라이선스를 따릅니다.\n- 단, **원본 GitHub 저장소 출처를 반드시 표기**해주세요\n\n### 📚 의존 라이브러리 라이선스\n아래는 `requirements.txt`에 명시된 주요 라이브러리와 그 라이선스입니다. 대부분은 GPLv3와 호환되지만, **PyQt5는 GPLv3**입니다.\n\n| 라이브러리 | 라이선스 |\n|------------|----------|\n| fastapi | MIT |\n| uvicorn | BSD-3-Clause |\n| pydantic | MIT |\n| httpx | BSD-3-Clause |\n| requests | Apache-2.0 |\n| PyYAML | MIT |\n| loguru | MIT |\n| PyQt5 | GPLv3 |\n| PySide6 | LGPL-3.0 |\n| pillow | HPND (PIL) |\n| mss | MIT |\n| keyboard | MIT |\n| sounddevice | MIT |\n| soundfile | BSD-3-Clause |\n| soundcard | BSD-3-Clause |\n| numpy | BSD-3-Clause |\n| scipy | BSD-3-Clause |\n| webrtcvad | MIT |\n| faster-whisper | MIT |\n| librosa | ISC |\n| scikit-learn | BSD-3-Clause |\n| pycaw | MIT |\n| comtypes | MIT |\n| duckduckgo-search | MIT |\n| beautifulsoup4 | MIT |\n| lxml | BSD-3-Clause |\n\n이외 윈도우 전용 알림 라이브러리(win10toast, winotify)는 모두 MIT 라이선스로 배포됩니다.\n\n**GPLv3 준수:** PyQt5는 GPLv3이므로 프로젝트 전체는 GPL 조항을 따릅니다. 나머지 라이브러리는 GPLv3와 호환되어 자유롭게 사용할 수 있습니다.\n\n이 프로젝트는 로컬 실행의 안정성과 메모리 효율을 위해 **모든 모델을 4비트 양자화(예: GGUF Q4_K_M)**로 사용하는 것을 권장합니다. \n\n특히 **Vision 모델(Qwen2.5-VL-7B)**은 시스템 **RAM/VRAM 용량이 제한적일 경우 더 보수적인 양자화(예: Q4_K_S 또는 Q3_K 계열)**를 선택해 주세요. \n\n양자화는 메모리 사용량을 크게 줄이는 대신 정확도가 일부 낮아질 수 있으므로, \n\n표·수식·복잡 레이아웃 문서에서는 입력 해상도/컨텍스트 길이를 조절하거나 필요 시 상위 비트폭으로 재시도하는 것을 권합니다. \n\n각 모델의 사용 조건과 재배포 범위는 해당 모델 배포처의 라이선스(예: Apache-2.0, MIT 등)를 그대로 따릅니다. 상업적 이용 가능 여부, 3rd-party NOTICE 동봉 의무, 로고/상표 사용 가이드는 각 라이선스의 정의를 준수해야 합니다. \n\n본 저장소 코드가 GPLv3라 하더라도 모델 가중치는 별도 라이선스를 가질 수 있으니, 다운로드 시점의 LICENSE/NOTICE를 확인하고 재배포 시 반드시 원 저작권 고지를 포함해 주세요.\n\n---\n\n## 🙋‍♂️ 마무리\n이 프로젝트는 제가 AI와 협업하여 시행착오 끝에 만들어낸 실험적 결과물입니다.  \n사양이 되는 분들은 직접 돌려보시고, 마음껏 개조해주시면 감사하겠습니다.\n\n---\n\n## 🛠️ 유지 및 보수 가이드\n\n이 섹션은 장기간 안정적인 서비스 운영을 위해 필요한 모든 관리 절차를 정리한 것입니다. 각 항목은 실제 운영 과정에서 빈번히 발생하는 문제를 예방하고, 발생하더라도 빠르게 복구할 수 있도록 돕습니다.\n\n1. **종속성 관리**\n   - `requirements.txt`를 정기적으로 확인하여 최신 버전을 추적하십시오. 새 버전 적용 시에는 항상 가상 환경에서 먼저 테스트하고, 기능이 정상적으로 동작하는지 확인해야 합니다.\n   - `pip install -r requirements.txt` 실행 후에는 버전 충돌 여부를 검토하고, 필요 시 `pip freeze` 결과를 기록해 변경 이력을 남깁니다.\n\n2. **환경 설정 백업**\n   - `config.yaml` 및 `config.json` 등 모든 설정 파일은 버전별 백업을 유지하십시오. 변경 후 문제가 발생하면 즉시 이전 버전으로 롤백할 수 있어야 합니다.\n   - 민감한 키나 토큰은 `.env` 파일이나 운영체제의 비밀 변수 기능을 활용해 관리하며, 절대 저장소에 포함시키지 마십시오.\n\n3. **로그 관리**\n   - 애플리케이션 실행 중 생성되는 `error.log`와 일반 로그 파일은 주기적으로 아카이브하거나 삭제하여 저장소 용량을 확보합니다.\n   - 오류 로그를 분석할 때는 동일 문제가 반복되는지 패턴을 파악하고, 관련 이슈를 추적 시스템에 기록하여 팀과 공유하십시오.\n\n4. **테스트 및 배포**\n   - 모든 수정 사항은 `pytest -q`를 통해 자동화 테스트를 통과해야 하며, 새로운 기능 추가 시에는 테스트 케이스를 함께 작성합니다.\n   - 배포 전에는 스테이징 환경에서 실제 사용 시나리오를 재현하여 회귀 오류를 확인합니다. 배포 후에는 모니터링 시스템을 통해 성능과 오류 여부를 지속적으로 관찰하십시오.\n\n5. **보안 업데이트**\n   - 외부 라이브러리에서 보안 패치가 발표되면 즉시 적용하고, 적용 내역을 CHANGELOG에 기록합니다.\n   - 의존성 검사 도구(`pip-audit` 등)를 사용하여 취약점을 주기적으로 점검하십시오.\n\n6. **문서화와 지식 공유**\n   - 새로운 기능이나 설정 변경 사항은 README와 위키에 즉시 반영하여 팀 내 지식 격차를 최소화합니다.\n   - 문제 해결 과정과 결정 이유를 문서화하여 향후 유지보수 담당자가 동일한 시행착오를 겪지 않도록 합니다.\n\n7. **장기적인 계획 수립**\n   - 기능 폐기 시에는 호환성 유지를 위한 대체 모듈이나 마이그레이션 방법을 미리 준비해 사용자 혼란을 방지합니다.\n   - 프로젝트의 로드맵을 수립하고, 정기적인 리팩터링과 코드 리뷰 일정을 포함시켜 기술 부채를 줄입니다.\n\n8. **백업과 복구 전략**\n   - 중요 데이터와 모델 파일은 최소 2곳 이상의 물리적 또는 클라우드 위치에 백업하십시오.\n   - 장애 발생 시 복구 순서를 문서화하고, 정기적으로 복구 절차를 리허설하여 실제 상황에서의 대응 시간을 단축합니다.\n\n이상의 지침을 꾸준히 실천한다면 프로젝트는 장기간 안정적으로 운영될 수 있으며, 예기치 못한 오류나 환경 변화에도 유연하게 대응할 수 있습니다.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F10kseason%2Fhome-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F10kseason%2Fhome-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F10kseason%2Fhome-agent/lists"}