FocusRoom | 생산성 에이전트

Python, Streamlit, Groq, SQLite, MCP로 구축된 개인 생산성 워크스페이스입니다. 작업 관리, 일일 계획, 영구 메모리, 멀티 에이전트 슈퍼바이저, 선택적 이메일 알림을 하나의 프로젝트에 결합합니다.

기능

• Streamlit 생산성 대시보드

• 작업 생성, 목록 조회, 필터링, 완료 처리

• 작업 우선순위, 마감일, 프로젝트, 상태

• productivity.db의 영구 SQLite 저장소

• 일일 계획 및 생산성 보고서

• 개인 메모리 저장 및 검색

• Groq 기반 생산성 어시스턴트

• 작업, 메모리, 계획 요청을 처리하는 멀티 에이전트 슈퍼바이저

• 외부 클라이언트를 위한 HTTP 도구가 포함된 MCP 서버

• 선택적 자동 이메일 알림

Related MCP server: Task API MCP

요구 사항

• Python 3.10 이상

• AI 기능을 위한 Groq API 키

• 이메일 알림을 위한 Gmail SMTP 자격 증명 또는 다른 SMTP 제공자

설정

1. 가상 환경 만들기

PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

PowerShell이 현재 세션에서 스크립트 실행을 차단하는 경우:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned
.\.venv\Scripts\Activate.ps1

2. 종속성 설치

python -m pip install -r requirements.txt

3. 환경 변수 구성

.env.example을 .env로 복사하고 값을 입력하세요:

Copy-Item .env.example .env

Groq 기반 에이전트에 필요한 항목:

GROQ_API_KEY=your_groq_api_key
GROQ_MODEL=openai/gpt-oss-120b

선택적 MCP 구성:

MCP_HOST=127.0.0.1
MCP_PORT=8000
MCP_API_KEY=local_or_remote_api_key

이메일 알림의 경우:

EMAIL_SENDER=your_email@gmail.com
EMAIL_RECIPIENT=recipient@example.com
EMAIL_PASSWORD=your_smtp_or_app_password
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587

.env나 API 자격 증명을 커밋하지 마세요. .gitignore에 의해 제외됩니다.

Streamlit 앱 실행

streamlit run streamlit_app.py

앱은 다음 섹션을 제공합니다:

• Overview - 작업 지표, 진행 중인 작업, 일일 요약, 완료 진행률

• Tasks - 작업을 생성하고 필터링한 다음 완료로 표시

• Plan - 현재 일일 계획 및 생산성 보고서 보기

• Memory - 영구 컨텍스트 저장 및 검색

• Assistant - 생산성 슈퍼바이저에게 자연어 요청 보내기

MCP 서버 실행

다음 명령으로 Streamable HTTP MCP 서버를 시작하세요:

python -m orchestrator.mcp_server

기본적으로 http://127.0.0.1:8000/mcp에서 실행됩니다.

서버는 다음 도구를 제공합니다:

• productivity_assistant

• create_task

• list_tasks

• update_task

• complete_task

• delete_task

• save_memory

• search_memory

• daily_plan

• productivity_report

MCP 서버를 로컬 호스트가 아닌 호스트에 바인딩할 때는 MCP_API_KEY를 설정하세요. 원격 요청은 bearer 토큰을 사용해야 합니다:

Authorization: Bearer <MCP_API_KEY>

알림 실행

알림 워커는 다가오는 작업을 확인하고 설정된 이메일 알림을 보냅니다:

python reminder_worker.py

알림 일정은 워커에서 구성되며 작업 마감 24시간 전, 1시간 전, 15분 전 알림을 지원합니다. 이메일 알림을 보내려면 .env에 유효한 SMTP 설정이 필요합니다.

테스트 실행

pytest를 사용할 수 있도록 프로젝트 가상 환경을 사용하세요:

.\.venv\Scripts\python -m pytest -q

특정 테스트 파일을 실행하려면:

.\.venv\Scripts\python -m pytest -q test_multi_agent.py

앱을 시작하지 않고 Python 구문을 확인하려면:

.\.venv\Scripts\python -m compileall streamlit_app.py orchestrator

프로젝트 구조

Productivity_Agent/
|-- streamlit_app.py              # Streamlit user interface
|-- requirements.txt              # Python dependencies
|-- .env.example                  # Environment variable template
|-- productivity.db               # Local SQLite database, generated locally
|-- reminder_service.py           # Reminder service implementation
|-- reminder_worker.py            # Continuous reminder worker
|-- orchestrator/
|   |-- agent.py                  # Core task, memory, plan, and report logic
|   |-- database.py               # SQLite persistence layer
|   |-- orchestrator.py           # Multi-agent supervisor
|   |-- mcp_server.py             # MCP HTTP server and tools
|   |-- memory_agent.py           # Memory agent adapter
|   |-- planning_agent.py         # Planning agent adapter
|   |-- task_agent.py             # Task agent adapter
|-- test_*.py                     # Project tests

데이터 및 보안 참고 사항

• 작업과 메모리는 SQLite에 로컬로 저장됩니다.

• .env에는 비밀 정보가 포함되어 있으므로 반드시 비공개로 유지해야 합니다.

• Gmail의 경우 기본 계정 비밀번호 대신 필요한 곳에 앱 비밀번호를 사용하세요.

• 서버가 localhost 외부에 노출될 때는 MCP API 키가 필요합니다.

• 로컬 작업 및 메모리 기록이 중요하다면 productivity.db를 백업하세요.

문제 해결

pytest가 인식되지 않는 경우

가상 환경을 통해 pytest를 실행하세요:

.\.venv\Scripts\python -m pytest -q

앱이 시작되지만 어시스턴트를 사용할 수 없는 경우

.env 파일이 존재하고 유효한 GROQ_API_KEY를 포함하는지 확인한 다음 Streamlit을 다시 시작하세요.

Streamlit에 missing ScriptRunContext 오류가 표시되는 경우

이 경고는 python -c로 Streamlit 모듈을 직접 가져올 때 표시됩니다. 정상적인 실행을 위해서는 streamlit run streamlit_app.py로 애플리케이션을 시작하세요.

컴파일은 되지만 테스트 수집 중 실패하는 경우

수집 오류는 pytest가 테스트 가져오기를 완료하지 못했음을 의미합니다. 먼저 보고된 첫 번째 예외를 읽고 해당 종속성 또는 생성자 불일치를 해결한 다음 나머지 테스트를 평가하세요.