ltcai 0.1.4 → 0.1.9

package/README.md

@@ -10,6 +10,76 @@ LTCAI                      # → http://localhost:4825
 
 ---
 
+## v0.1.9 변경사항
+
+### Security
+- 세션 TTL 7일 → 24시간, sliding refresh (활동시 자동 연장)
+- 파일 업로드 magic-number 검증 (PDF/DOCX/PNG 등 시그니처 확인)
+- Rate limiting: `/chat` 30/min, `/agent` 6/min, `/upload` 12/min (per user, 토큰 버킷)
+
+### Reliability
+- PyMuPDF 파일 핸들 누수 수정, ollama serve 좀비 방지 (detach)
+- knowledge_graph metadata 손상 row 안전 통과
+- 백그라운드 asyncio 태스크 예외 로깅 (`_spawn` 헬퍼)
+- silent except → logging.warning (sessions/config 로딩)
+
+### Tests
+- `tests/unit/test_security.py` 16개 추가 (bcrypt, MIME, rate limit, harness risk)
+
+---
+
+## v0.1.8 변경사항
+
+### Added
+- **PWA (Progressive Web App)** — iPad / Android / Galaxy Tab 홈화면 설치 지원
+  - `manifest.json` + Service Worker (`sw.js`) + 아이콘 4종 (192px, 512px, apple-touch-icon 180px, favicon 32px)
+  - iOS Safari: 공유 버튼 → "홈 화면에 추가" → 앱처럼 전체화면 실행
+  - Android Chrome: 주소창 "설치" 버튼 → 홈화면 앱
+  - `viewport-fit=cover` — iPhone Dynamic Island / 노치 안전영역 확장
+- **서버 네트워크 공개 바인딩** — 기본 host `0.0.0.0`으로 변경
+  - 같은 Wi-Fi에서 모든 기기(`http://<Mac IP>:4825`)로 바로 접근 가능
+  - 시작 배너에 로컬 URL + 네트워크 IP 자동 출력
+- **Windows 서버 호환성**
+  - `computer_screenshot`: macOS `screencapture` → Windows/Linux `pyautogui` fallback
+  - `computer_open_app` / `computer_open_url`: `open -a` / `cmd /c start` / `xdg-open` 플랫폼 자동 분기
+
+### 배포 현황
+- npm ✅
+- PyPI ✅
+- VS Code Marketplace ✅
+- Open VSX ✅
+
+---
+
+## v0.1.7 변경사항
+
+### Added
+- **모바일 반응형 UI** — 폰/태블릿 화면 크기에 자동 대응
+  - 사이드바 슬라이드 드로어 (☰ 햄버거 버튼, 오버레이 탭으로 닫기)
+  - iOS 소프트 키보드 대응 (`100dvh`), 노치/홈바 안전영역 (`safe-area-inset`)
+  - ops-strip 카드 가로 스크롤 압축, textarea 자동 줌 방지
+- 브레이크포인트 3단계: 900px / 768px / 480px
+
+---
+
+## v0.1.6 변경사항
+
+### Added
+- **LATTICEAI_ENABLE_GRAPH** 환경변수 — Data Graph를 퍼블릭 배포에서 완전히 비활성화하는 토글 (기본값 `true`)
+  - `false` 설정 시 모든 그래프 API 404, 인제스트 건너뜀, 사이드바 버튼 자동 숨김
+
+---
+
+## v0.1.5 변경사항
+
+### Added
+- **Data Graph** — 채팅·AI 답변·업로드 문서를 SQLite 지식 그래프로 자동 구조화, `/graph`에서 Canvas 기반 Force-directed 시각화
+- **Graph RAG** — 그래프 검색 결과를 채팅 컨텍스트에 자동 주입하여 이전 대화·문서 참조 강화
+- **Telegram 원격 제어** — 인라인 키보드 메뉴로 상태 조회, 모델 관리, 스크린샷, 그래프 통계 원격 제어
+- 어드민 세션 핸드오프 보안 강화 — URL 파라미터 → `sessionStorage` 1회 읽기 방식으로 교체
+
+---
+
 ## v0.1.4 변경사항
 
 ### Added
@@ -39,11 +109,42 @@ LTCAI                      # → http://localhost:4825
 
 ---
 
+## v0.1.1 변경사항
+
+### Added
+- 비밀번호 변경 API (`POST /account/change-password`)
+- 웹 UI 비밀번호 변경 모달 (헤더 계정 아이콘)
+
+---
+
+## v0.1.0 변경사항
+
+### Added
+- FastAPI 브릿지 서버 (port 4825)
+- Apple Silicon MLX 로컬 모델 지원 (Gemma 4, Qwen 2.5 등)
+- 클라우드 모델 지원 (OpenAI, Groq, Together, OpenRouter 등)
+- VS Code / Cursor / Antigravity 확장
+- Telegram 봇 (로컬 AI 미러 + Codex 클라우드 봇)
+- 어드민 패널 (`/admin`)
+- P-Reinforce 지식 정원 엔진
+- MCP 서버 연동
+- Ollama / vLLM / LM Studio / llama.cpp 연동
+
+### Security
+- 모든 민감 엔드포인트 인증 적용
+- SameSite=Lax 쿠키 (CSRF 방어)
+- scrypt 비밀번호 해싱
+- tempfile 레이스 컨디션 수정
+- `run_command()` 위험 플래그 차단
+
+---
+
 ## 아키텍처
 
 ```
 Lattice AI/
 ├── server.py              # FastAPI 브릿지 서버 (port 4825)
+├── knowledge_graph.py     # SQLite Data Graph + Graph RAG 저장소
 ├── llm_router.py          # 로컬/클라우드 모델 라우터
 ├── tools.py               # 워크스페이스 도구 (파일, 터미널, 스크린샷 등)
 ├── p_reinforce.py         # P-Reinforce 지식 정원 엔진
@@ -169,6 +270,7 @@ docker run --rm -p 4825:4825 \
 - `LATTICEAI_MODE=public` 설정
 - 클라우드 API 키 설정 (`OPENAI_API_KEY` 등)
 - `LATTICEAI_INVITE_CODE`를 비공개 값으로 설정
+- `LATTICEAI_ENABLE_GRAPH=false` — Data Graph를 공개 서버에서 숨기려면 설정
 - `/data`에 영구 볼륨 마운트
 - HTTPS 리버스 프록시 앞에 두기 (nginx, Caddy 등)
 
@@ -325,6 +427,20 @@ curl -X POST localhost:4825/garden \
 
 ---
 
+## Data Graph / Graph RAG
+
+웹 채팅과 AI 답변, 업로드 문서(PDF/DOCX/XLSX/PPTX/TXT/CSV)를 `~/.ltcai/knowledge_graph.sqlite`에 자동 저장합니다.
+
+- 채팅/AI 답변: `Message`, `AIResponse`, `Person`, `Conversation`, `Topic`, `Decision`, `Task`
+- 문서 업로드: `File`, `Chunk`, `Page`, `Slide`, `Sheet`, `Image`, `Topic`
+- 원본 파일 blob: `~/.ltcai/knowledge_graph_blobs/`
+- 시각화: `http://localhost:4825/graph`
+- API: `/knowledge-graph/graph`, `/knowledge-graph/search`, `/knowledge-graph/context`
+
+`/clear`, `/clear_all`, 대화 삭제는 사용자 채팅창만 정리합니다. Data Graph/RAG 데이터와 관리자 감사 로그는 보존됩니다.
+
+---
+
 ## API 엔드포인트
 
 | Method | Path | 설명 |

package/docs/OPERATIONS.md

@@ -0,0 +1,149 @@
+# Lattice AI — Operations Guide
+
+## 1. 데이터 파일 위치
+
+| 파일 | 용도 |
+|------|------|
+| `~/.ltcai/users.json` | 사용자 계정 (bcrypt 해시 저장) |
+| `~/.ltcai/history.json` | 대화 히스토리 |
+| `~/.ltcai/audit.json` | 감사 로그 (agent 실행, 사용자 변경 등) |
+| `~/.ltcai/brain/` | Knowledge Graph 노드 (Markdown) |
+| `~/ltcai-agent/` | Agent workspace (agent가 생성한 파일) |
+
+## 2. 백업 및 복구
+
+### 2.1 전체 백업
+```bash
+tar -czf ltcai-backup-$(date +%Y%m%d).tar.gz ~/.ltcai ~/ltcai-agent
+```
+
+### 2.2 복구
+```bash
+tar -xzf ltcai-backup-YYYYMMDD.tar.gz -C ~
+```
+
+### 2.3 히스토리만 초기화
+```bash
+rm ~/.ltcai/history.json
+```
+
+### 2.4 감사 로그 보관 (90일 보관 예시)
+```bash
+# crontab -e 에 추가
+0 2 * * * find ~/.ltcai -name "audit*.json" -mtime +90 -delete
+```
+
+## 3. 로그 관리
+
+서버 로그는 stdout/stderr로 출력됩니다. systemd 환경에서는 journald가 관리합니다.
+
+### 3.1 로그 확인
+```bash
+# systemd 사용 시
+journalctl -u ltcai -f
+
+# 직접 실행 시 파일로 redirect
+LTCAI > /var/log/ltcai.log 2>&1
+```
+
+### 3.2 로그 보관
+`logrotate` 예시 (`/etc/logrotate.d/ltcai`):
+```
+/var/log/ltcai.log {
+    daily
+    rotate 30
+    compress
+    missingok
+    notifempty
+}
+```
+
+## 4. 감사 로그 이벤트 유형
+
+| event_type | 발생 시점 |
+|------------|-----------|
+| `login` | 로그인 성공/실패 |
+| `user_update` | 관리자가 사용자 수정 |
+| `user_delete` | 관리자가 사용자 삭제 |
+| `history_delete` | 대화 히스토리 삭제 |
+| `agent_exec` | Agent가 medium/high risk 도구 실행 |
+| `agent_blocked` | Agent가 시스템 경로 쓰기 시도하여 차단됨 |
+| `model_load` | 모델 로드 |
+| `model_switch` | 모델 전환 |
+
+### 4.1 감사 로그 조회
+```bash
+python3 -c "
+import json, sys
+events = json.load(open('~/.ltcai/audit.json'.replace('~', __import__('os').path.expanduser('~'))))
+for e in events[-20:]:
+    print(e['timestamp'], e['event_type'], e.get('user_email',''))
+"
+```
+
+## 5. 사용자 관리
+
+### 5.1 첫 번째 사용자 (admin) 생성
+서버 첫 실행 시 `/register` API 또는 웹 UI를 통해 등록합니다.  
+최초 등록 사용자는 자동으로 `admin` 역할이 부여됩니다.
+
+### 5.2 사용자 목록 확인 (admin 전용)
+```
+GET /admin/users
+Cookie: session_id=<admin-session>
+```
+
+### 5.3 비밀번호 정책
+- 최소 8자
+- bcrypt (cost 12) 해시로 저장
+- 평문은 저장되지 않음
+
+## 6. 업그레이드 마이그레이션
+
+### 6.1 npm 패키지 업그레이드
+```bash
+npm install -g ltcai@latest
+```
+
+### 6.2 PyPI 패키지 업그레이드
+```bash
+pip install --upgrade ltcai
+```
+
+### 6.3 데이터 마이그레이션 주의사항
+- `users.json` 스키마 변경 시: 서버가 자동으로 누락 필드를 기본값으로 보완합니다.
+- `history.json` 스키마 변경 시: 하위 호환성 유지. 구버전 레코드는 무시됩니다.
+- `brain/` Knowledge Graph: Markdown 파일 기반이므로 별도 마이그레이션 없음.
+
+## 7. 공개 서버 체크리스트
+
+공개 인터넷에 노출할 경우 반드시 확인:
+
+- [ ] `LATTICEAI_SECRET_KEY` 환경변수 설정 (32자 이상 랜덤 문자열)
+- [ ] `LATTICEAI_ENABLE_GRAPH=false` (불필요 시 Graph 비활성화)
+- [ ] `HTTPS` 종단 프록시 설정 (nginx / Caddy)
+- [ ] `CSRF_TRUSTED_ORIGINS` 화이트리스트 설정
+- [ ] `ALLOWED_COMMANDS` 검토 — python3/node 등 불필요한 실행 도구 제거
+- [ ] 방화벽으로 8899 포트를 프록시만 접근 허용
+
+## 8. 사용자 데이터 격리
+
+- 대화 히스토리는 `user_email` 필드로 필터링됩니다.
+- Agent workspace (`~/ltcai-agent/`)는 현재 단일 공유 디렉토리입니다.  
+  멀티 유저 환경에서는 `~/ltcai-agent/<email>/` 구조로 분리를 권장합니다.
+- Knowledge Graph (`brain/`) 역시 단일 공유 공간입니다.
+
+## 9. 서버 시작 / 종료
+
+```bash
+# 시작
+LTCAI
+
+# 환경변수와 함께 시작
+LATTICEAI_SECRET_KEY=xxx LATTICEAI_ENABLE_GRAPH=true LTCAI
+
+# 종료
+Ctrl+C  또는  kill <pid>
+```
+
+서버는 종료 시 진행 중인 HTTP 요청을 완료한 후 종료됩니다 (graceful shutdown — uvicorn 기본 동작).