<div align="center">
<img src="https://capsule-render.vercel.app/api?type=waving&color=0F9D58&height=250§ion=header&text=IRIS%20Mini&fontSize=90&fontColor=ffffff&animation=fadeIn&desc=A%20Premium%20Voice%20AI%20Assistant%20powered%20by%20Google%20Gemini%20Live&descAlignY=70&descAlign=62" />
</div>
<p align="center">
<strong>끊김 없는 CLI 경험을 제공하는 궁극의 데스크톱 음성 비서</strong>
</p>
<p align="center">
<a href="https://www.npmjs.com/package/iris-mini"><img src="https://img.shields.io/npm/v/iris-mini?style=for-the-badge&color=0F9D58" alt="NPM Version" /></a>
<img src="https://img.shields.io/badge/Google-Gemini_Live-0F9D58?style=for-the-badge&logo=google" alt="Google Gemini" />
<img src="https://img.shields.io/badge/CLI-Ready-0F9D58?style=for-the-badge&logo=command-line" alt="CLI Ready" />
<img src="https://img.shields.io/badge/React-UI-0F9D58?style=for-the-badge&logo=react" alt="React UI" />
<img src="https://img.shields.io/badge/Node.js-Backend-0F9D58?style=for-the-badge&logo=nodedotjs" alt="Node.js" />
</p>
🌟 개요 (Overview)
IRIS-MINI는 프로덕션급의 최첨단 음성 AI 비서입니다. Google Gemini Live API의 강력한 기능을 활용하여, IRIS는 실시간 대화형 상호작용과 강력한 시스템 통합을 제공합니다.
아름다운 그래픽 사용자 인터페이스(GUI)를 선호하든, 빠르고 효율적인 명령줄 인터페이스(CLI) 경험을 선호하든, IRIS-MINI가 사용자의 작업 흐름에 끊김 없이 적응합니다.
📸 기능 소개 (Showcase)
| 프리미엄 웹 인터페이스 | 해커 스타일 CLI |
|---|
| <img src="https://raw.githubusercontent.com/IRISX-AI/IRIS-Mini/HEAD/assets/1.png" width="450" alt="IRIS Web UI" /> | <img src="https://raw.githubusercontent.com/IRISX-AI/IRIS-Mini/HEAD/assets/2.png" width="450" alt="IRIS CLI" /> |
| 아름다운 Three.js 시각화 및 React UI | 깔끔하고 조용한 브랜딩 터미널 경험 |
✨ 기능 (Features)
- 🎙️ 고급 음성 AI: Google Gemini Live API를 통해 실시간적이고, 낮은 지연 시간(low-latency)이며, 매우 지능적인 대화형 경험을 제공합니다.
- 💻 심층 OS 통합: 사용자의 로컬 Windows 기기에서 애플리케이션을 원활하게 열고, 닫고, 관리할 수 있습니다.
- 🌍 웹 검색 및 지식: Google을 즉시 검색하고 정확하며 최신 정보를 가져옵니다.
- 🚀 CLI 강력 기능: 파워 유저들이 터미널에서 어시스턴트를 완전히 관리할 수 있도록 사용하기 쉬운 Command Line Interface (CLI)를 노출합니다.
🛠️ 기술 스택 (Tech Stack)
높은 성능과 프리미엄한 느낌을 보장하는 최신, 견고한 기술들로 구축되었습니다:
- 프론트엔드: React, Tailwind CSS, Framer Motion, Three.js
- 백엔드: Node.js, Express, Socket.io
- AI 코어: Google Gemini Live API, Glowe Agent
- 시스템: Windows API, Decibri (마이크 통합)
🔑 사전 준비 사항 (Prerequisites)
시작하기 전에, 필요한 API 키를 확보했는지 확인하십시오:
🚀 빠른 시작 및 설치 (Quick Start & Installation)
IRIS-MINI는 전역으로 설치된 CLI로 사용하거나(권장), 개발을 위해 소스 코드에서 로컬로 실행할 수 있습니다.
옵션 A: 전역 CLI 설치 (Global CLI Installation) (주요 경로)
IRIS를 경험하는 가장 강력한 방법은 터미널을 통해 직접 사용하는 것입니다.
⚠️ 중요 요구 사항: IRIS-MINI는 **Node.js v24+**가 필수입니다. 진행하기 전에 환경이 업데이트되었는지 확인하십시오.
1단계: 전역 설치 (Install Globally)
npm을 통해 패키지를 전역으로 설치하여 시스템의 모든 곳에서 iris 명령어를 사용할 수 있게 합니다:
2단계: 첫 실행 경험 (First Run Experience)
어시스턴트를 처음 실행합니다:
이 초기 실행 시, 대화형 **설정 마법사(Setup Wizard)**가 시작됩니다. 이 마법사는 다음을 안내할 것입니다:
- Gemini API Key를 입력합니다.
- 선호하는 **음성 페르소나(Voice Personality)**를 선택합니다 (Lyra의 또렷한 톤 또는 Puck 중에서 선택).
참고: 다음 실행부터는 이 설정 과정을 완전히 건너뛰고, Neural Core를 즉시 부팅하여 Voice AI 경험으로 바로 진입합니다.
옵션 B: 로컬 개발 및 해커 세팅
코드베이스를 탐색하거나(poke around), UI를 수정하거나, 프로젝트에 기여하고 싶다면 이 경로를 따르세요.
1. 리포지토리 클론하기
git clone https://github.com/201Harsh/IRIS-Mini.git
cd IRIS-Mini
2. 의존성 설치하기
Node.js v24 이상 버전인지 확인한 후, 다음을 실행하세요:
3. 환경 변수 설정하기
다음 템플릿을 기반으로 루트 디렉토리에 .env 파일을 생성하세요. 플레이스홀더를 실제 API 키로 교체해야 합니다:
# Voice AI용 Google Gemini API Key
GEMINI_API_KEY=your_gemini_api_key_here
4. 코어 작동시키기
백엔드 서버와 React 프론트엔드를 개발 모드로 동시에 시작하세요:
옵션 C: Docker 배포
헤드리스 환경(headless environments), 홈랩 서버, 또는 클라우드 배포를 위해 IRIS-MINI는 별도의 설정 없이 완전히 컨테이너화되어 제공됩니다.
참고: Docker를 통해 실행하면 컨테이너 격리(container isolation)로 인해 로컬 Windows 통합 및 네이티브 마이크 접근이 비활성화됩니다. 네트워크 레벨 액세스나 백엔드 서비스에 가장 적합합니다.
전체 스택을 분리된 모드(detached mode)로 실행하세요:
docker-compose up -d --build
🚑 문제 해결 및 일반적인 이슈
문제가 발생했나요? 가장 흔한 장애물과 이를 우회하는 방법을 알려드립니다:
├── bin/ # CLI 실행 파일
│ └── iris-mini.ts
├── data/ # 로컬 데이터 저장소
...
🛠️ 개발자 경험 (DX)
IRIS-MINI는 프로덕션 환경에서 사용할 수 있는 개발자 경험을 염두에 두고 구축되었습니다. 다음 기능을 포함합니다:
- Node 버전 관리: Node/NPM 환경을 엄격하게 제어하고 일치시키기 위한
.nvmrc 및 .npmrc.
- 컨테이너화 (Containerization): 쉽게 격리된 배포를 할 수 있도록 네이티브
Dockerfile 및 docker-compose.yml 지원.
- 코드 품질: Prettier와 Commitlint를 통해 강제되는 린팅(linting) 및 포맷팅 규칙.
- 변경 로그 자동화 (Changelog Automation): 자동적이고 표준화된 변경 로그 생성을 위한 설정.
🤝 기여 (Contributing)
커뮤니티의 기여를 환영합니다! 버그 수정, 문서 개선 또는 새로운 기능 추가 등 어떤 것이든 원하신다면, 기여 가이드라인을 확인하여 시작해 주세요.
또한, 커뮤니티가 접근하기 쉽고 존중받는 분위기를 유지할 수 있도록 행동 강령(Code of Conduct)도 검토해 주시기 바랍니다.
🛡️ 보안 (Security)
보안은 최우선 순위입니다. 취약점 보고 방법 및 당사의 보안 관행에 대한 지침은 보안 정책(Security Policy)을 참조해 주세요.
📄 라이선스 (License)
본 프로젝트는 포함된 LICENSE 파일의 약관에 따라 라이선스가 부여됩니다.
---<p align="center">
201Harsh가 💚를 담아 제작했습니다.
</p>