SunnyBoy-y/LearnGraph

LearnGraph – AI 증강, 자체 호스팅 학습 작업 공간

그것이 무엇인가

• 사용자가 구체적인 학습 목표를 설정하고, 그 목표에 대한 지식 그래프를 구축하며, AI 에이전트가 학습, 연습, 평가를 통해 사용자를 안내할 수 있게 하는 자체 호스팅 웹 + Android 애플리케이션.
• 시스템은 그래프와 증거의 메모리 (사용자가 읽거나, 답하거나, 코딩한 내용)를 지속적으로 업데이트하여 에이전트가 다음 단계를 추천할 수 있게 합니다.

주요 기능

기능	제공되는 것
성장하는 지식 그래프	자연어 목표에서 백엔드는 주제와 선행 조건 관계의 버전 관리되고 편집 가능한 그래프를 생성합니다. 사용자는 이를 감사하고 수정할 수 있습니다.
에이전트 네이티브 학습	AI 에이전트가 작업을 계획합니다 – 소스 가져오기, 개념 설명, 연습 문제 생성, Docker 샌드박스에서 코드 실행, 결과 기록.
전이중 음성 튜터	음성 인식 및 음성 합성 (DashScope ASR + Volcano TTS)이 통합되어 있습니다. 말하면서 동시에 들을 수 있으며, 말한 문장을 강조하는 실시간 자막이 있습니다.
Docker 격리 샌드박스	에이전트가 실행하는 코드는 기본적으로 오프라인인 Docker 컨테이너에서 실행됩니다. 아웃바운드 네트워크는 명시적 승인이 필요하며, 강력한 보안 경계를 제공합니다.
Android 클라이언트	네이티브 Kotlin/Jetpack-Compose 앱 (GeckoView)은 웹 UI를 미러링하고 카메라, 파일 공유, QR 스캔, 생체 인식 로그인, TTS, 푸시 알림을 추가합니다.
이벤트 소싱 장기 메모리	모든 상호 작용은 불변 이벤트로 저장됩니다. 프로젝션 레이어는 온디맨드로 검색 가능한 컨텍스트를 구축하여 재생, 감사, 프롬프트 주입 방지를 가능하게 합니다.
대화형 학습 페이지	각 그래프 노드는 자료, 대화형 실험, 미니 게임, 채점 퀴즈가 포함된 전체 학습 페이지를 생성할 수 있습니다. 진행 상황은 저장되고 재개할 수 있습니다.
"매직 카드" 구성 요소	AI 생성 UI 위젯 (객관식, 빈칸 채우기, 차트 등)으로 상태를 가지며 학습 페이지 간에 재사용할 수 있습니다.
다중 모델 제공자 지원	OpenAI, Anthropic, Qwen, DeepSeek, Ollama, Copilot 등을 위한 플러그인 아키텍처와 통합 자격 증명 처리를 제공합니다.

아키텍처 개요

• 프론트엔드: 웹 UI용 React 19 + TypeScript (Vite); Android용 Kotlin/Jetpack-Compose. TanStack Query, React Flow, AI가 생성한 안전한 HTML을 위한 사용자 정의 신뢰할 수 있는 렌더러 사용.
• 백엔드: FastAPI (Python 3.11+)가 HTTP + SSE 엔드포인트를 노출. 핵심 서비스는 G-R-E-M-A 학습 루프 (목표 → 표현 → 증거 → 숙달 → 행동)를 구현.
• 메모리: SQLite (WAL)의 이벤트 저장소와 하이브리드 벡터 + 키워드 검색을 위한 계층화된 프로젝션.
• 샌드박스: sandboxd 데몬이 에이전트 도구를 실행하는 Docker 컨테이너를 제어. 이그레스 프록시는 "기본 오프라인, 승인 후 온라인" 정책을 강제.
• 데이터 영속성: 모든 사용자 데이터, 그래프 버전, 증거, 암호화된 제공자 비밀은 Docker 볼륨 (또는 바인드 마운트 디렉토리)에 저장되며 컨테이너 업그레이드 후에도 유지됩니다.

시도하는 방법

1. Docker compose (권장)

   git clone https://github.com/SunnyBoy-y/LearnGraph.git
   cd LearnGraph
   docker compose up -d --build   # web+API 이미지 및 샌드박스 서비스 빌드
   

   • 브라우저에서 http://127.0.0.1:18000을 엽니다.
   • 컨테이너 로그에 인쇄된 임시 관리자 비밀번호로 로그인한 후 비밀번호를 변경합니다.
2. 개발 모드 (기여하려는 경우)

   npm run dev:install   # Node 및 Python 종속성 설치, .env 파일 생성
   npm run dev           # Vite 프론트엔드 및 FastAPI 백엔드 시작
   

   • 프론트엔드: http://127.0.0.1:5173
   • API: http://127.0.0.1:8000
3. Android 클라이언트
   • mobile/native에서 Kotlin 앱을 빌드하거나 사전 빌드된 APK를 설치합니다.
   • 호스트 주소 (예: http://192.168.1.5:18000)를 지정합니다.

일반적인 워크플로우

1. 학습 목표 설정 – "2주 안에 데이터 분석을 위한 기본 Python 배우기."
2. 생성된 그래프 검토 – 변수, pandas, 시각화 같은 노드를 승인합니다.
3. 에이전트와 채팅 – 설명을 요청하거나, 코드 예제를 요청하거나, 에이전트가 연습 문제를 만들도록 요청합니다.
4. 연습 문제 수행 – UI가 대화형 페이지를 표시하고 결과는 증거로 저장됩니다.
5. 다음 추천 받기 – 시스템이 숙달 상태를 업데이트하고 다음으로 영향력이 큰 노드를 제안합니다.

누가 사용할 수 있는가

• 새로운 분야로의 구조화된 AI 안내 경로를 원하는 개인 학습자.
• 에이전트 기반 튜터링, 메모리 감사, 샌드박스 도구 실행을 실험하는 연구자.
• 내부 지식 온보딩 파이프라인을 구축하는 소규모 팀 (자체 호스팅으로 데이터 프라이버시 유지).

현재 제한 사항

• 아직 초기 개발 단계이며 프로덕션 워크로드에는 권장되지 않습니다.
• 음성 기능은 클라우드 제공자 (DashScope, Volcano)에 의존하며 오디오를 해당 서비스로 보냅니다.
• 샌드박스는 Docker만 지원하며 Docker가 없는 환경에서는 코드 실행 기능을 실행할 수 없습니다.
• 다중 사용자 협업은 기본 RBAC로 제한되며 실시간 공동 학습은 아직 구현되지 않았습니다.

더 알아보기

• 개발자 가이드 및 문서: https://sunnyboy-y.github.io/LearnGraph/
• 소스 코드: https://github.com/SunnyBoy-y/LearnGraph
• 라이선스: MIT (포크하고 확장해도 됩니다).

---

LearnGraph는 지식 그래프 계획, 자율 튜터링 에이전트, 음성 상호 작용, Docker 격리 실행 샌드박스를 결합한 진정한 오픈 소스 AI 에이전트 학습 플랫폼입니다.