thetable-poc 0.1.2
AI-powered project meeting management system
License: MIT
Requires Python: >=3.12
Keywords: agent, ai, cli, langchain, langgraph, meeting, project-management

# TheTable - AI와 함께하는 프로젝트 회의 시스템

> **쉽게 말하면**: 며칠, 몇 주 동안 진행되는 프로젝트를 AI와 함께 회의하며 관리하는 프로그램입니다.

## 🎯 왜 만들었나요?

**문제**: 일반 AI 챗봇은 한 번 대화하고 끝이에요.
- "로그인 기능 만들어줘" → 만들어줌 → 끝
- 다음 날: "어제 뭐 했더라?" → AI가 기억 못함 😢

**해결**: TheTable은 **장기 프로젝트**를 위한 시스템입니다!
- 매일 회의를 열어서 진행 상황을 점검해요 📅
- 어제 무슨 문제가 있었는지 기억해요 🧠
- 오늘은 뭘 해야 하는지 계획을 세워요 📋
- 여러 번의 회의를 거쳐 프로젝트를 완성해요 🎉

## 💡 이게 뭔가요?

**단발성 AI 챗봇** vs **TheTable**

| 일반 AI 챗봇 | TheTable |
|-------------|----------|
| 한 번 질문 → 한 번 답변 | 계속 만나며 프로젝트 진행 |
| 대화 끝나면 다 잊어버림 | 매 회의마다 이전 내용 기억 |
| 혼자 모든 걸 처리 | 역할 분담 (PM, 개발자 등) |
| 즉흥적 | 체계적 (현황→문제→해결) |

**예를 들면**:
- **1주차 회의**: "로그인 기능 설계하자" → 설계 완료
- **2주차 회의**: "지난주 설계한 거 구현하자" → 개발 진행
- **3주차 회의**: "버그 있네, 고치자" → 버그 수정
- **4주차 회의**: "테스트하고 배포하자" → 완성! 🎉

이렇게 **몇 주에 걸쳐** 프로젝트를 관리할 수 있어요!

## ✨ 뭐가 특별한가요?

### 🔄 지속적인 프로젝트 관리
- ✅ **매 회의마다 이어지는 맥락**: 지난 회의 내용을 기억하고 이어서 진행
- ✅ **장기 프로젝트 추적**: 몇 주, 몇 달 동안의 프로젝트 진행 상황 관리
- ✅ **정기적인 체크포인트**: 매일/매주 회의로 프로젝트 상태 점검

### 👥 팀 시뮬레이션
- ✅ **역할 분담**: 사회자, PM, 개발자 등 역할별로 AI 배치
- ✅ **AI와 사람 섞어쓰기**: 필요한 역할만 AI로, 나머지는 내가 직접
- ✅ **실제 팀처럼**: 진짜 팀 회의하듯이 체계적으로 진행

### 📊 체계적인 진행 구조
- ✅ **5단계 프로세스**: 시작 → 현황 보고 → 문제 해결 → 작업 → 마무리
- ✅ **구조화된 의사결정**: 즉흥적이 아닌 계획적인 프로젝트 관리
- ✅ **명확한 액션 아이템**: 매 회의마다 다음에 할 일이 명확함

## 🚀 어떻게 시작하나요?

### 1단계: 필요한 것들

- **Python 3.10 이상** (파이썬 프로그래밍 언어)
- **AI 서비스 연결**:
  - OpenRouter (여러 AI 모델 사용 가능, OpenAI 호환 API)

### 2단계: 설치하기

**방법 1: uvx/pipx로 설치 (권장)**
```bash
# uvx 사용 (설치 없이 바로 실행)
uvx thetable-poc

# 또는 pipx로 설치
pipx install thetable-poc
thetable-poc --help
```

**방법 2: 개발자 모드 (소스코드에서)**
```bash
# 1. 프로젝트 다운로드
git clone https://github.com/e7217/thetable.git
cd thetable

# 2. 필요한 라이브러리 설치
uv sync

# 3. 설정 파일 만들기
cp .env.example .env
```

### 3단계: 설정하기

`.env` 파일을 열어서 본인의 AI 서비스 정보를 입력하세요:

```bash
# OpenAI API 키 설정 (필수, OpenRouter 키 사용)
OPENAI_API_KEY=여기에-당신의-키를-입력

# 사용할 모델 선택 (선택사항)
LLM_MODEL=openai/gpt-4o-mini
LLM_FAST_MODEL=google/gemini-2.5-flash

# MCP (Model Context Protocol) 설정 (선택사항)
MCP_ENABLED=false              # MCP 기능 활성화 (GitHub 연동 등)
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxx  # GitHub Personal Access Token
```

<details>
<summary><strong>🔌 MCP (외부 도구 연동) 설정하기</strong></summary>

MCP를 활성화하면 AI가 GitHub PR/Issue를 직접 조회할 수 있습니다!

#### 1. GitHub Personal Access Token 발급
1. GitHub 설정 → Developer settings → Personal access tokens → Tokens (classic)
2. "Generate new token (classic)" 클릭
3. 권한 선택:
   - `repo` (전체 저장소 접근)
   - `read:org` (조직 읽기)
4. 토큰 생성 후 복사

#### 2. `.env` 파일 설정
```bash
MCP_ENABLED=true
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_여기에_발급받은_토큰_붙여넣기
GITHUB_REPOSITORY=e7217/thetable  # 조회할 레포지토리 (owner/repo 형식)
```

#### 3. MCP 서버 설정 확인
`thetable_poc/config/mcp_servers.json` 파일이 자동으로 생성됩니다.
필요시 수정 가능:
```json
{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "transport": "streamable_http",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }
}
```

#### 4. 참여자에게 MCP 도구 할당
`thetable_poc/config/participants.yaml`에서 참여자별로 사용할 도구 지정:
```yaml
  - name: John
    role: tech_lead
    type: ai
    checked: true
    mcp_tools:
      - github  # TechLead가 GitHub 도구 사용
```

#### 5. 테스트
```bash
# MCP 설정 로더 테스트
python scripts/test_mcp_config.py

# 실제 회의에서 사용
uv run example_meeting.py
```

이제 TechLead AI가 회의 중에 GitHub PR 상태를 확인하고 논의할 수 있습니다! 🎉

</details>

### 4단계: 실행해보기

```bash
uv run example_meeting.py
```

<details>
<summary><strong>💡 코드 예시 (어떻게 쓰나요?)</strong></summary>

```python
from core import ParticipantFactory, Role
from meeting import MeetingSession

# 1. 회의 만들기
meeting = MeetingSession()

# 2. AI 참가자 추가하기
host = ParticipantFactory.create_ai("Alex", Role.HOST)  # 사회자 AI
pm = ParticipantFactory.create_ai("Sarah", Role.PM)     # PM AI
meeting.add_participant(host)
meeting.add_participant(pm)

# 3. 나도 참가하기
me = ParticipantFactory.create_human("나", Role.MEMBER)
meeting.add_participant(me)

# 4. 회의 시작!
meeting.run()
```

</details>

## 👥 역할 설명

| 역할 | 하는 일 |
|------|---------|
| **Host** (사회자) | 회의 진행, 시간 체크 |
| **PM** (프로젝트 매니저) | 프로젝트 현황 보고 |
| **Tech Lead** (기술 리더) | 기술 결정, 작업 분배 |
| **개발자들** | 실제 개발 작업 |
| **Member** (참가자) | 실제 개발 작업 |

## 🔄 회의 진행 순서 (매번 반복)

```
시작 인사 → 현황 보고 → 문제 해결 → 작업하기 → 마무리
```

<details>
<summary><strong>실제 진행 예시 (2주 프로젝트)</strong></summary>

**1주차 월요일 회의** 📅
1. **시작**: "이번 주 목표는 로그인 기능 설계입니다" 👋
2. **현황 보고**: "아직 아무것도 시작 안 함" 📊
3. **문제 해결**: "어떤 인증 방식을 쓸까?" 🤔
4. **작업**: "JWT 방식으로 설계 문서 작성" 💻
5. **마무리**: "다음 회의 때 설계 검토하자!" 👍

**1주차 금요일 회의** 📅
1. **시작**: "설계 검토 시간입니다" 👋
2. **현황 보고**: "설계 완료, 구현 대기 중" 📊
3. **문제 해결**: "설계에 보안 이슈 발견" 🔧
4. **작업**: "보안 보완 후 구현 시작" 💻
5. **마무리**: "다음 주에 구현 완료 목표!" 👍

**2주차 월요일 회의** 📅
1. **시작**: "구현 진행 확인합니다" 👋
2. **현황 보고**: "70% 완료, 테스트 남음" 📊
3. **문제 해결**: "비밀번호 해싱 버그 있음" 🔧
4. **작업**: "버그 수정 & 테스트 작성" 💻
5. **마무리**: "다음 회의에 배포 준비!" 👍

→ 이렇게 **여러 번 회의**를 거치며 프로젝트를 완성합니다!

</details>

## 📝 현재 상태

### ✅ 완성된 기능 (지금 쓸 수 있어요!)

- **회의 시스템**: 5단계로 체계적인 회의 진행
- **AI 참가자**: 역할별 AI 에이전트 (사회자, PM, 개발자)
- **사람 참가자**: AI와 섞어서 회의 가능
- **역할 관리**: 각자 맡은 역할대로 행동

### 🔜 개발 중인 기능 (더 강력해집니다!)

**왜 이 기능들이 필요할까요?**

#### 1. 외부 도구 연결 (GitHub, Jira)
- **문제**: 지금은 대화만 하고, 실제 일은 수동으로 해야 함
- **해결**: AI가 직접 GitHub에 이슈 만들고, Jira 업데이트
- **예시**: "버그 발견!" → 자동으로 GitHub 이슈 생성 🎯

#### 2. 여러 AI 동시 작업
- **문제**: 지금은 한 명씩 순서대로만 발언
- **해결**: 여러 개발자 AI가 동시에 각자 작업
- **예시**: Frontend AI는 UI 만들고, Backend AI는 API 만들고 🚀

#### 3. 회의 기록 저장 (가장 중요!)
- **문제**: 프로그램 끄면 지난 회의 내용 날아감
- **해결**: 모든 회의 내용을 데이터베이스에 저장
- **예시**: 3주 전 회의에서 뭐 결정했는지 다시 확인 가능 📚
- **장기 프로젝트의 핵심!** 몇 달 지나도 맥락 유지

자세한 개발 현황은 [GitHub Issues](https://github.com/e7217/thetable/issues)에서 확인하세요!

## 🤝 같이 만들어요!

이 프로젝트에 참여하고 싶으신가요?
1. 이 저장소를 Fork 하기
2. 새로운 기능 만들기
3. Pull Request 보내기

## 📄 라이선스

MIT License - 자유롭게 사용하세요!

---

**더 궁금한 점이 있다면?**
- 📧 Issue 남기기: [GitHub Issues](https://github.com/e7217/thetable/issues)
- 📖 상세 기획: `idea01.md` 파일 참고