bi-agent 0.1.0

Autonomous Business Intelligence Agent with Proactive Insights

BI-Agent: The Frontier of Autonomous Business Intelligence

"데이터 오퍼레이션을 넘어, 비즈니스 인사이트의 자율화를 설계하는 아키텍트"
BI-Agent는 단순한 데이터 추출 도구를 넘어, 기업의 데이터 자산을 스스로 탐색하고
차세대 의사결정 시스템(Autonomous BI)을 위한 완벽한 지능형 오케스트레이션을 제공합니다.

---

✨ Recent Enhancements (v0.1.0)

• Premium Entrance Hall: 터미널 기반의 아름다운 환영 스크린과 'BI - Agent' 통합 로고 디자인 적용
• Command Palette (/): 슬래시(/) 키로 호출하는 직관적인 분석 명령어 시스템 (키보드 네비게이션 지원)
• Real-time Agent Logs: 에이전트의 사고 과정과 시스템 로그를 채팅창 내에서 실시간으로 확인 가능
• Smart Auth Onboarding: API 키가 없어도 실행 중 즉각적으로 발급 및 등록 가능한 인터랙티브 가이드 모드
• Secure Multi-Agent Core: 전략가, 데이터마스터, 디자이너 에이전트의 협업 로직 최적화

---

🏛️ Vision & Core Values

BI-Agent는 데이터 분석가의 사고 과정을 복제하고 증폭하는 AI 파트너를 지향합니다. 사용자의 질문에 답하는 수동적 존재에서 벗어나, 데이터의 문맥을 읽고 선제적으로 통찰을 제안합니다.

• Local-First & Privacy: 클라우드 의존성을 최소화하고 로컬 데이터(DuckDB, Excel, CSV)를 우선적으로 처리합니다.
• Agentic Collaboration: 전략가, 디자이너, 데이터 마스터가 각자의 전문성을 바탕으로 협업합니다.
• Proactive Intelligence: 분석 완료 후 다음 비즈니스 액션을 위한 **[가설]-[질문]-[기대효과]**를 선제적으로 제안합니다.

---

🏗️ System Architecture

BI-Agent는 멀티 에이전트 오케스트레이션 프레임워크를 기반으로 설계되었습니다.

3.1 Collaborative Orchestrator (중앙 제어)

모든 분석 요청의 관제탑 역할을 수행하며, 하위 에이전트들의 출력을 조율합니다.

• Failover LLM Provider: Google Gemini(Primary)와 Ollama(Secondary)를 결합하여 안정적인 지능을 유지합니다.
• Plan B Logic: 데이터 연결이 끊긴 상황에서도 사용자 의도를 기반으로 '가상 스키마'를 추론하여 분석을 지속합니다.

3.2 Specialized Agents & Skills

• DataMaster: ConnectionManager를 통해 다양한 데이터 소스(SQL, Local Files)를 안전하게 핸들링합니다.
• Strategist: 질문의 비즈니스 의도를 파악하고 최적의 분석 전략 및 지표(Metrics)를 선정합니다.
• Visual Designer: InHouseGenerator를 통해 데이터에 최적화된 시각화 구성을 제안합니다.

---

🚀 Key Features

🧠 하이브리드 SQL & AI 코칭

사용자가 직접 SQL을 작성하면(sql: ...), AI가 구문 오류 수정, 성능 최적화, 비즈니스 맥락 주석 추가를 지원하여 분석가의 숙련도를 한 차원 높여줍니다.

💡 가설 기반 선제적 인사이트

분석 결과 도출 시, LLM이 데이터 트렌드를 분석하여 다음에 탐색할 가치가 있는 전략적 질문을 3가지 구조화된 형태로 자동 제안합니다.

📊 프리미엄 로컬 대시보드

Glassmorphism과 Deep Sea Dark Theme이 적용된 세련된 인터랙티브 대시보드를 로컬 환경에서 즉시 생성합니다. (Plotly & Google Fonts 연동)

📂 프로젝트 기반 워크스페이스

projects/{id}/ 단위로 지표(Metrics), 설정, 연결정보를 완벽히 격리하여 멀티 도메인 분석 환경을 제공합니다.

---

🗺️ User Journey (Process Flow)

1. Connect: DB, CSV, Excel, DuckDB 등 소스 연결
2. Index: 메타데이터 스캔 및 시멘틱 레이어(Metric Store) 구축
3. Refine: 하이브리드 SQL 엔진을 통한 쿼리 코칭 및 최적화
4. Inquire: 자연어 질문 기반 복합 분석 및 대시보드 생성
5. Deliver: 인사이트 패키지 번들링 및 Slack/로컬 공유

---

🚦 Getting Started

1단계: 환경 준비 (Setup)

• Python 3.10+ (필수: 3.9 이하 환경에서는 패키지를 찾을 수 없거나 설치에 실패할 수 있습니다.)
• Node.js 18+ (MCP 서버 기능 사용 시 필요)
• .env 파일 (Gemini API 키 등) 또는 실행 후 TUI에서 직접 입력 가능

2단계: 설치 및 실행 (Go Live)

📦 방법 A: PyPI에서 정식 설치 (추천)

가장 안정적인 최신 릴리스 버전을 설치합니다.

# 파이썬 버전 확인 후 설치
python3 -m pip install --upgrade bi-agent

# 어디서든 실행
bi-agent

🛠️ 방법 B: GitHub 소스 설치

개발 버전이나 직접 소스 코드를 수정하고 싶다면:

# 깃허브에서 직접 설치
pip install git+https://github.com/KnellBalm/BI-Agent.git

# 또는 로컬 소스 폴더에서 설치 (개발자용)
git clone https://github.com/KnellBalm/BI-Agent.git
cd BI-Agent
pip install -e .
npm install

[!IMPORTANT] 설치 오류 발생 시: ERROR: Could not find a version... 에러가 난다면, 현재 실행된 pip 명령어가 Python 3.10 이상 버전에 연결되어 있는지 확인해 주세요. python3 -m pip install bi-agent 명령어가 가장 확실한 방법입니다.

---

🏛️ Entrance Hall (지능형 관문)

패키지 설치 후 bi-agent를 실행하면 고도화된 Entrance Hall UI가 실행됩니다.

• 슬래시 명령어 (/): /를 입력하여 분석 명령어 팔레트 호출
• 실시간 사고 로그: 에이전트의 내부 추론 과정과 시스템 로그를 채팅창 하단에서 실시간 모니터링
• 지능형 온보딩: API 키가 없어도 실행 중 보안 가이드에 따라 즉시 등록 가능

---

🛠️ Technical Excellence

Layer	Technologies
Intelligence	LangGraph, Gemini 2.0 Flash, Ollama, PydanticAI
Interface	Premium TUI (Rich), Interactive Dashboard (Plotly)
Data Engine	DuckDB, Pandas, Postgres, Snowflake, BigQuery
Connectivity	Model Context Protocol (MCP), Node.js
Aesthetics	CSS Glassmorphism, Google Fonts (Outfit/Inter)

---

---

❓ Troubleshooting (자주 묻는 질문)

Q. ERROR: Could not find a version that satisfies the requirement bi-agent 에러가 발생합니다.

• A: 이 프로젝트는 Python 3.10 이상이 필요합니다. 현재 사용 중인 pip가 3.9 이하의 파이썬 버전에 연결되어 있을 때 발생하는 메시지입니다. python3 --version으로 버전을 확인하신 후, python3 -m pip install bi-agent 명령어로 재시도해 보세요.

Q. bi-agent 명령어를 찾을 수 없다고 나옵니다.

• A: pip 설치 시 --user 옵션으로 설치된 경우 관련 디렉토리가 PATH에 등록되어 있지 않을 수 있습니다. 터미널을 재시작하거나, $HOME/.local/bin이 환경변수에 포함되어 있는지 확인해 주세요.

---

📖 Related Documents

• MASTER_SPEC.md: 상세 기술 명세서
• PLAN.md: 로드맵 및 설계 철학
• USER_GUIDE.md: 기능 활용 가이드

---

Copyright © 2026 BI-Agent Team. All rights reserved.