ltcai 0.1.22 → 0.1.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +210 -263
  2. package/docs/CHANGELOG.md +54 -1
  3. package/docs/images/logo.svg +33 -0
  4. package/docs/images/screenshot-admin.png +0 -0
  5. package/docs/images/screenshot-chat.png +0 -0
  6. package/docs/images/screenshot-graph.png +0 -0
  7. package/package.json +1 -1
package/README.md CHANGED
@@ -1,341 +1,243 @@
1
- # Lattice AI
2
-
3
- **개인 AI 워크스페이스 서버** — 로컬/클라우드 LLM을 웹 UI · VS Code 확장 · Telegram 봇 · MCP 도구 하나로 묶습니다.
4
-
5
- Apple Silicon MLX 로컬 추론 · OpenAI/Groq/OpenRouter 클라우드 모델 · Graph RAG · 멀티스텝 에이전트 워크플로
6
-
7
- [![PyPI](https://img.shields.io/pypi/v/ltcai?label=pypi)](https://pypi.org/project/ltcai/)
1
+ <div align="center">
2
+ <img src="docs/images/logo.svg" alt="Lattice AI" width="280"/>
3
+ <br/>
4
+ <strong>Your personal AI workspace server — local & cloud, one stack.</strong>
5
+ <br/><br/>
6
+
7
+ [![PyPI](https://img.shields.io/pypi/v/ltcai?label=PyPI&color=blue)](https://pypi.org/project/ltcai/)
8
+ [![PyPI Downloads](https://img.shields.io/pypi/dm/ltcai?label=PyPI%20downloads)](https://pypi.org/project/ltcai/)
8
9
  [![npm](https://img.shields.io/npm/v/ltcai?label=npm)](https://www.npmjs.com/package/ltcai)
9
- [![VS Code Marketplace](https://vsmarketplacebadges.dev/version/parktaesoo.ltcai.svg)](https://marketplace.visualstudio.com/items?itemName=parktaesoo.ltcai)
10
+ [![VS Code](https://img.shields.io/badge/VS%20Code%20Marketplace-v0.1.23-blue?logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=parktaesoo.ltcai)
10
11
  [![Open VSX](https://img.shields.io/open-vsx/v/parktaesoo/ltcai?label=Open%20VSX)](https://open-vsx.org/extension/parktaesoo/ltcai)
11
- [![License](https://img.shields.io/github/license/TaeSooPark-PTS/LatticeAI)](./LICENSE)
12
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green)](./LICENSE)
13
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue)](https://www.python.org/)
12
14
 
13
- Lattice AI는 개인 개발자가 로컬 모델, 클라우드 모델, 에이전트 툴링, 코드 에디터 연동을 하나의 워크스페이스로 운영할 수 있게 만든 서버입니다.
15
+ </div>
14
16
 
15
- ### 현재 배포 버전
17
+ ---
18
+
19
+ ## What is Lattice AI?
16
20
 
17
- - `PyPI`: `ltcai==0.1.22`
18
- - `npm`: `ltcai@0.1.22`
19
- - `VS Code Marketplace`: `parktaesoo.ltcai@0.1.22`
20
- - `Open VSX`: `parktaesoo.ltcai@0.1.22`
21
+ **Lattice AI** is a self-hosted AI server that unifies local and cloud LLMs into one workspace — web chat, VS Code extension, Telegram bot, and MCP tools, all from a single `pip install`.
21
22
 
22
- ### 왜 Lattice AI인가
23
+ - 🖥️ **Web UI** — chat, file upload, admin dashboard, data graph
24
+ - 🧩 **VS Code / Cursor extension** — edit, explain, generate commands inline
25
+ - 📱 **Telegram bot** — access your AI from anywhere
26
+ - 🔌 **MCP server** — use Lattice tools inside Claude Desktop / Cursor
27
+ - 🔒 **Zero telemetry** — all data stays in `~/.ltcai/` on your machine
23
28
 
24
- - **하나의 서버, 여러 인터페이스**: 웹 UI, VS Code/Cursor 확장, Telegram 봇, MCP 도구를 한 번에 연결합니다.
25
- - **로컬 우선 + 클라우드 선택**: Apple Silicon MLX 로컬 모델과 OpenAI 호환 클라우드 모델을 같은 UX로 다룹니다.
26
- - **실전형 에이전트 워크플로**: 파일 편집, grep, todo, 터미널 도구를 묶어 멀티스텝 작업을 수행합니다.
29
+ ---
27
30
 
28
- ### 빠른 링크
31
+ ## 📸 Screenshots
29
32
 
30
- - [설치 & 첫 실행](#설치--첫-실행-30초)
31
- - [퍼블릭 배포 가이드](./docs/public-deploy.md)
32
- - [보안 모델](./docs/security-model.md)
33
- - [아키텍처](./docs/architecture.md)
34
- - [변경 이력](./docs/CHANGELOG.md)
33
+ <table>
34
+ <tr>
35
+ <td width="33%"><b>Chat UI</b><br/><img src="docs/images/screenshot-chat.png" alt="Lattice AI Chat" width="100%"/></td>
36
+ <td width="33%"><b>Admin Dashboard</b><br/><img src="docs/images/screenshot-admin.png" alt="Admin Dashboard" width="100%"/></td>
37
+ <td width="33%"><b>Data Graph (Graph RAG)</b><br/><img src="docs/images/screenshot-graph.png" alt="Knowledge Graph" width="100%"/></td>
38
+ </tr>
39
+ </table>
35
40
 
36
41
  ---
37
42
 
38
- ## 설치 & 첫 실행 (30초)
43
+ ## ⚡ Quick Start (30 seconds)
39
44
 
40
45
  ```bash
41
- # PyPI (클라우드 모델)
46
+ # Install (cloud models)
42
47
  pip install ltcai
43
48
 
44
- # PyPI (Apple Silicon MLX 로컬 모델 포함)
49
+ # Install (+ Apple Silicon local models)
45
50
  pip install "ltcai[local]"
46
51
 
47
- # npm (자동 Python 환경 구성)
48
- npm install -g ltcai
49
-
50
- # 서버 실행 (로컬)
52
+ # Start server
51
53
  LTCAI
52
54
  # → http://localhost:4825
53
55
 
54
- # 외부에서 접속 가능하게 실행 (Cloudflare 터널 자동 개설)
56
+ # Start with public HTTPS tunnel (Cloudflare, no account needed)
55
57
  LTCAI --tunnel
56
- # → http://localhost:4825
57
- # → https://xxxx.trycloudflare.com ← 어디서든 접속 가능한 공개 URL
58
+ # → https://xxxx.trycloudflare.com
58
59
  ```
59
60
 
60
- **`--tunnel` 동작 방식:**
61
- - cloudflared가 없으면 자동 다운로드 (계정 불필요)
62
- - 서버를 `0.0.0.0`에 바인딩하고 Cloudflare 무료 터널로 HTTPS 공개 URL 발급
63
- - `LATTICEAI_TELEGRAM_BOT_TOKEN` + `LATTICEAI_TELEGRAM_CHAT_ID` 환경변수가 있으면 시작 시 Telegram으로 URL 자동 전송
64
- - 서버 종료 시 터널도 함께 종료
65
-
66
- **설치 확인:**
67
-
68
- ```
69
- $ LTCAI doctor
70
- [OK] Python 3.11+: 3.11.9
71
- [OK] FastAPI: required server dependency
72
- [OK] Uvicorn: required server dependency
73
- [OK] OpenAI SDK: required for cloud providers
74
- [OK] MLX: required for Apple Silicon local models
75
- [OK] MLX-LM: required for local text models
76
- [OK] MLX-VLM: required for Gemma/VLM models
77
- [OPTIONAL] Ollama binary: optional local-server engine
78
- [OK] Data dir: /Users/you/.ltcai
79
- [OK] Static UI: /path/to/static
80
- [INFO] Cloud keys configured: OPENAI_API_KEY
81
- ```
61
+ **First run:** open `http://localhost:4825` → sign up → first account auto-becomes admin → pick a model → start chatting.
82
62
 
83
63
  ---
84
64
 
85
- ## 첫 채팅 → VS Code 연결 → Telegram 연결
86
-
87
- ### 1단계: 첫 채팅
88
-
89
- 1. `http://localhost:4825` 열기
90
- 2. **회원가입** → 첫 번째 계정이 자동으로 admin
91
- 3. 상단 모델 드롭다운 → 모델 선택 → 채팅 시작
92
-
93
- 클라우드 모델 사용 시 API 키를 먼저 설정하거나, 어드민 패널에서 입력합니다:
94
-
95
- ```bash
96
- OPENAI_API_KEY=sk-... LTCAI
97
- ```
98
-
99
- ### 2단계: VS Code 연결
100
-
101
- 1. VS Code → Extensions → `ltcai` 검색 → Install
102
- 2. `Cmd+Shift+A` → Lattice AI 채팅 패널 열기
103
- 3. 기본적으로 `http://localhost:4825` 에 자동 연결됩니다
65
+ ## 🆚 Why Lattice AI?
66
+
67
+ | | Lattice AI | Open WebUI | Continue.dev | GitHub Copilot |
68
+ |---|:---:|:---:|:---:|:---:|
69
+ | Local model (offline, Apple Silicon) | ✅ | ✅ | ✅ | ❌ |
70
+ | Cloud models (OpenAI, Groq…) | ✅ | ✅ | ✅ | ✅ |
71
+ | VS Code extension | ✅ | ❌ | ✅ | ✅ |
72
+ | Telegram bot | ✅ | ❌ | ❌ | ❌ |
73
+ | Graph RAG (auto knowledge graph) | ✅ | ❌ | ❌ | ❌ |
74
+ | MCP registry & install | ✅ | ❌ | ✅ | ❌ |
75
+ | Admin dashboard + audit log | ✅ | ✅ | ❌ | ❌ |
76
+ | Self-hosted, zero telemetry | ✅ | ✅ | ✅ | ❌ |
77
+ | One-command public tunnel | ✅ | ❌ | ❌ | ❌ |
78
+ | Free | ✅ | ✅ | ✅ | ❌ |
104
79
 
105
- | 단축키 | 기능 |
106
- |--------|------|
107
- | `Cmd+Shift+A` | 채팅 패널 열기 |
108
- | `Cmd+Shift+E` | 선택 코드 편집 |
109
- | `Cmd+Shift+M` | 모델 로드 / 전환 |
110
- | 우클릭 메뉴 | Explain / Edit / Knowledge Garden 저장 |
80
+ ---
111
81
 
112
- ### 3단계: Telegram 봇 연결
82
+ ## 🧠 Supported Models
113
83
 
114
- BotFather에서 토큰을 발급받은 후:
84
+ **Local — Apple Silicon only (MLX):**
115
85
 
116
- ```bash
117
- LATTICEAI_TELEGRAM_BOT_TOKEN=your-token LTCAI
118
- ```
86
+ | Model | Best for | Size |
87
+ |-------|----------|------|
88
+ | `mlx-community/gemma-4-26b-a4b-it-4bit` | General / coding | ~14 GB |
89
+ | `mlx-community/Qwen2.5-Coder-32B-Instruct-4bit` | Coding | ~18 GB |
90
+ | `mlx-community/DeepSeek-R1-0528-4bit` | Reasoning | ~38 GB |
91
+ | `mlx-community/Phi-4-4bit` | Coding (fast) | ~8 GB |
119
92
 
120
- 이후 Telegram에서 봇과 대화하면 로컬 AI 서버와 실시간으로 연결됩니다.
93
+ **Cloud (any platform):**
94
+ OpenAI · Groq · Together · OpenRouter · any OpenAI-compatible endpoint
121
95
 
122
96
  ---
123
97
 
124
- ## 기능 개요
125
-
126
- | 기능 | 설명 |
127
- |------|------|
128
- | **웹 UI** | 반응형 채팅 + 어드민 패널 + 그래프 시각화 |
129
- | **Auto Setup Wizard** | 구성요소 감지 → 공식 다운로드 연결 → 설치 감지 → PATH/env 세팅 → 동작 테스트 → 자동 복구 |
130
- | **VS Code / Cursor 확장** | 채팅, Edit Selection, Diff 뷰, 파일 첨부 |
131
- | **Telegram 봇** | 로컬 AI 미러 + Codex 클라우드 봇 |
132
- | **MCP 서버** | Claude Desktop / Cursor에서 직접 도구 사용 |
133
- | **MCP 레지스트리** | [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io) 원격 목록 실시간 통합 — stdio MCP 서버 원클릭 설치 |
134
- | **Skills 마켓플레이스** | Anthropic + Adobe · Airtable · Auth0 · Expo · Pydantic 공식 skills 77개 (Apache-2.0 / MIT) |
135
- | **플러그인 디렉터리** | 오픈소스 플러그인 149개 메타데이터 브라우저 (검색 · 카테고리 · 라이선스 필터) |
136
- | **MLX 로컬 추론** | Apple Silicon에서 Gemma, Qwen, DeepSeek 등 |
137
- | **클라우드 모델** | OpenAI, Groq, Together, OpenRouter |
138
- | **Graph RAG** | 채팅·문서를 SQLite 지식 그래프로 자동 구조화 |
139
- | **에이전트** | 파일 편집·생성, grep, todo, 터미널 (25스텝) |
140
- | **PWA** | iPad / Android 홈화면 설치 지원 |
98
+ ## ✨ Features
99
+
100
+ | Feature | Description |
101
+ |---------|-------------|
102
+ | **Web UI** | Responsive chat + admin panel + graph visualisation |
103
+ | **Auto Setup Wizard** | Detects → downloads → installs → verifies → repairs dependencies |
104
+ | **VS Code / Cursor** | Chat panel, Edit Selection, Explain, Generate command |
105
+ | **Telegram bot** | Local AI mirror + cloud Codex bot |
106
+ | **MCP server** | Use Lattice tools in Claude Desktop / Cursor |
107
+ | **MCP registry** | One-click install from registry.modelcontextprotocol.io |
108
+ | **Skills marketplace** | 77 official skills (Anthropic + Adobe · Airtable · Auth0 · Pydantic) |
109
+ | **Plugin directory** | Browse 149 open-source plugins |
110
+ | **Graph RAG** | Chat & docs auto-indexed as SQLite knowledge graph |
111
+ | **Multi-step agent** | File edit/create, grep, todo, terminal (25 steps) |
112
+ | **Multi-LLM pipeline** | Plan → Execute → Review with different models |
113
+ | **Human-in-the-loop** | Approve agent plan before execution |
114
+ | **Audit dashboard** | Per-user AI usage, sensitive data detection, event log |
115
+ | **PWA** | Install on iPad / Android home screen |
141
116
  | **SSO** | Entra ID / Okta OIDC |
142
117
 
143
118
  ---
144
119
 
145
- ## 플랫폼 지원
120
+ ## 🖥️ Platform Support
146
121
 
147
- | 기능 | macOS (Apple Silicon) | Windows / Linux |
148
- |------|:---:|:---:|
149
- | 웹 UI / 클라우드 모델 | ✅ | ✅ |
150
- | VS Code / Cursor 확장 | ✅ | ✅ |
151
- | Telegram 봇 | ✅ | ✅ |
152
- | MLX 로컬 모델 (Gemma, Qwen 등) | ✅ | ❌ Apple Silicon 전용 |
153
- | Ollama / vLLM / LM Studio 연동 | ✅ | ✅ |
122
+ | Feature | macOS Apple Silicon | macOS Intel / Windows / Linux |
123
+ |---------|:---:|:---:|
124
+ | Web UI + cloud models | ✅ | ✅ |
125
+ | VS Code / Cursor extension | ✅ | ✅ |
126
+ | Telegram bot | ✅ | ✅ |
127
+ | MLX local models | ✅ | ❌ |
128
+ | Ollama / LM Studio / vLLM | ✅ | ✅ |
154
129
 
155
130
  ---
156
131
 
157
- ## 로컬 모델 (Apple Silicon)
132
+ ## 🛠️ Setup & Usage
133
+
134
+ ### Install & run
158
135
 
159
136
  ```bash
137
+ # Verify everything is ready
138
+ LTCAI doctor
139
+
140
+ # Run with cloud API key
141
+ OPENAI_API_KEY=sk-... LTCAI
142
+
143
+ # Run with local MLX model (Apple Silicon)
160
144
  LATTICEAI_MODE=local \
161
145
  LATTICEAI_LOCAL_MODEL=mlx-community/gemma-4-26b-a4b-it-4bit \
162
146
  LTCAI
163
147
  ```
164
148
 
165
- ### 추천 모델 (M-series Mac)
149
+ ### VS Code extension
166
150
 
167
- | 모델 | 용도 | 크기 | 추천 |
168
- |------|------|------|------|
169
- | `mlx-community/gemma-4-26b-a4b-it-4bit` | 범용/코딩 | ~14GB | ⭐⭐⭐⭐⭐ |
170
- | `mlx-community/Qwen2.5-Coder-32B-Instruct-4bit` | 코딩 | ~18GB | ⭐⭐⭐⭐⭐ |
171
- | `mlx-community/Qwen2.5-Coder-14B-Instruct-4bit` | 코딩 | ~8GB | ⭐⭐⭐⭐ |
172
- | `mlx-community/DeepSeek-R1-0528-4bit` | 추론 | ~38GB | ⭐⭐⭐⭐ |
173
- | `mlx-community/Phi-4-4bit` | 코딩 | ~8GB | ⭐⭐⭐⭐ |
151
+ 1. VS Code → Extensions → search `ltcai` → Install
152
+ 2. `Cmd+Shift+A` — open chat panel (auto-connects to `localhost:4825`)
174
153
 
175
- > **32GB Mac 추천**: `gemma-4-26b-a4b-it-4bit` — 빠르고 뛰어난 범용 성능
154
+ | Shortcut | Action |
155
+ |----------|--------|
156
+ | `Cmd+Shift+A` | Open chat |
157
+ | `Cmd+Shift+E` | Edit selected code |
158
+ | `Cmd+Shift+M` | Load / switch model |
159
+ | Right-click | Explain / Save to Knowledge Garden |
176
160
 
177
- ### 멀티모델 핫스왑
161
+ ### Telegram bot
178
162
 
179
163
  ```bash
180
- curl -X POST localhost:4825/models/load \
181
- -H "Content-Type: application/json" \
182
- -d '{"model_id": "mlx-community/Qwen2.5-Coder-14B-Instruct-4bit"}'
164
+ LATTICEAI_TELEGRAM_BOT_TOKEN=your-token LTCAI
183
165
  ```
184
166
 
185
- ---
186
-
187
- ## 퍼블릭 모드 (클라우드 서버)
188
-
189
- Render, Fly.io, Railway, VPS 등에서 운영할 때:
167
+ ### Public server (Render / Fly.io / Docker)
190
168
 
191
169
  ```bash
192
170
  LATTICEAI_MODE=public \
193
- LATTICEAI_ALLOW_LOCAL_MODELS=false \
194
171
  LATTICEAI_PUBLIC_MODEL=openai:gpt-4o-mini \
195
172
  OPENAI_API_KEY=sk-... \
196
- LATTICEAI_INVITE_CODE=my-secret-code \
173
+ LATTICEAI_INVITE_CODE=my-secret \
197
174
  LTCAI
198
175
  ```
199
176
 
200
- 자세한 내용은 [docs/public-deploy.md](docs/public-deploy.md)를 참고하세요.
201
-
202
- ### Docker
203
-
204
177
  ```bash
178
+ # Docker
205
179
  docker build -t lattice-ai .
206
180
  docker run --rm -p 4825:4825 \
207
181
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
208
- -e LATTICEAI_INVITE_CODE="my-secret-code" \
182
+ -e LATTICEAI_INVITE_CODE="my-secret" \
209
183
  -v "$PWD/.data:/data" \
210
184
  lattice-ai
211
185
  ```
212
186
 
213
187
  ---
214
188
 
215
- ## 보안
189
+ ## 🔒 Security
216
190
 
217
- - **바인딩**: 기본 `127.0.0.1:4825` (로컬 전용) — 같은 Wi-Fi 기기 접근 허용 시 `LATTICEAI_HOST=0.0.0.0` 설정
218
- - **인증**: 퍼블릭 모드 또는 `0.0.0.0` 등 네트워크 노출 호스트에서는 로그인 세션이 기본으로 필요합니다
219
- - **세션**: 24시간 TTL + sliding refresh, 서버 디스크 저장 (재시작 후에도 유지)
220
- - **CORS**: 기본 localhost만 허용 — 외부 브라우저 origin은 `LATTICEAI_CORS_ALLOWED_ORIGINS`에 명시
221
- - **API 키**: OS keyring/Keychain 저장 (평문 미저장)
222
- - **쿠키**: `HttpOnly + SameSite=Lax` (세션 토큰은 localStorage에 저장하지 않음)
223
- - **로컬 파일 접근**: list/read/write/preview는 서버 발급 approval token으로 경로·사용자·작업 범위를 검증하고, 웹 UI 또는 Discord permission flow에서 승인 후 실행
224
- - **채팅 경로 자동 읽기**: 기본 OFF. `LATTICEAI_AUTO_READ_CHAT_PATHS=true`로 명시한 경우에만 `/path` 또는 `~/path` 내용을 모델 컨텍스트에 주입
225
- - **Rate limit**: `/chat` 30/분, `/agent` 6/분, `/upload` 12/분 (per user)
226
- - **파일 업로드**: magic-number 시그니처 검증 (확장자 위조 차단)
227
- - **텔레메트리**: 없음. 모든 데이터는 로컬(`~/.ltcai/`)에만 저장됩니다.
191
+ | Property | Detail |
192
+ |----------|--------|
193
+ | Binding | Default `127.0.0.1:4825` — local only |
194
+ | Auth | Session required when network-exposed or public mode |
195
+ | Cookies | `HttpOnly + SameSite=Lax` — no localStorage token |
196
+ | Local file access | Approval-token gated (path + user + action scope) |
197
+ | CORS | Localhost only by default; add origins via `LATTICEAI_CORS_ALLOWED_ORIGINS` |
198
+ | File upload | Magic-number signature check (blocks extension spoofing) |
199
+ | Rate limits | `/chat` 30/min · `/agent` 6/min · `/upload` 12/min per user |
200
+ | Telemetry | None — all data in `~/.ltcai/` |
228
201
 
229
- 보안 취약점 제보: [SECURITY.md](SECURITY.md) 참고
202
+ Report vulnerabilities: [SECURITY.md](SECURITY.md)
230
203
 
231
204
  ---
232
205
 
233
- ## 문제 해결
234
-
235
- | 증상 | 원인 | 해결 |
236
- |------|------|------|
237
- | 포트 4825 이미 사용 중 | 이전 프로세스 잔존 | `lsof -i :4825` → `kill <PID>` 또는 `--port 4826` |
238
- | `ModuleNotFoundError: mlx` | MLX 미설치 | `pip install "ltcai[local]"` (Apple Silicon 전용) |
239
- | Python 3.10 이하 | 버전 불일치 | Python 3.11+ 필요. `python3 --version` 확인 |
240
- | `pyautogui` 권한 오류 | macOS 접근성 권한 | 시스템 설정 → 개인정보 보호 → 접근성 → 터미널 허용 |
241
- | `LTCAI doctor` OPTIONAL 표시 | 선택 의존성 미설치 | 해당 기능 불필요 시 무시 가능 |
242
- | API 키 없음 경고 | 클라우드 모델 미설정 | `OPENAI_API_KEY=sk-...` 환경변수 또는 어드민 패널에서 입력 |
243
- | Telegram 봇 응답 없음 | 토큰 미설정 또는 서버 미실행 | `LATTICEAI_TELEGRAM_BOT_TOKEN` 확인, 서버 로그 확인 |
244
- | iPad / 다른 기기에서 접근 안 됨 | 기본 바인딩 127.0.0.1 | `LATTICEAI_HOST=0.0.0.0 LTCAI` 로 재시작 |
206
+ ## 🗂️ API Reference
207
+
208
+ | Method | Path | Description |
209
+ |--------|------|-------------|
210
+ | GET | `/health` | Server status & current model |
211
+ | GET | `/models` | Model list + load state |
212
+ | POST | `/models/load` | Load a model |
213
+ | POST | `/chat` | Chat (`stream=true/false`) |
214
+ | POST | `/agent` | Multi-step file agent |
215
+ | GET | `/mcp/installed` | Installed MCP servers |
216
+ | POST | `/mcp/install` | Install MCP server |
217
+ | GET | `/skills/marketplace` | Skills marketplace |
218
+ | POST | `/skills/install` | Install a skill |
219
+ | GET | `/plugins/directory` | Plugin directory |
220
+ | GET | `/permissions/pending` | Pending file-access approvals (admin) |
221
+ | POST | `/permissions/approve/{token}` | Approve file access (admin) |
222
+
223
+ Full reference: [docs/mcp-tools.md](docs/mcp-tools.md)
245
224
 
246
225
  ---
247
226
 
248
- ## 에디터 확장
227
+ ## 🔧 Troubleshooting
249
228
 
250
- | 마켓플레이스 | 링크 |
251
- |---|---|
252
- | VS Code / Cursor | [marketplace.visualstudio.com](https://marketplace.visualstudio.com/items?itemName=parktaesoo.ltcai) |
253
- | Antigravity / VSCodium | [open-vsx.org](https://open-vsx.org/extension/parktaesoo/ltcai) |
254
-
255
- ### 릴리스 체크
256
-
257
- `0.1.22` 릴리스는 아래 네 채널을 동일 버전으로 맞춥니다.
258
-
259
- - `npm`
260
- - `PyPI`
261
- - `VS Code Marketplace`
262
- - `Open VSX`
263
-
264
- ### 수동 설치 (VSIX)
265
-
266
- ```bash
267
- cd vscode-extension
268
- npm install && npm run build && npm run package:vsix
269
- # Extensions → "..." → "Install from VSIX"
270
- ```
271
-
272
- ---
273
-
274
- ## 어드민 패널
275
-
276
- `http://localhost:4825/admin` — 관리자 계정으로 로그인 후 접근
277
-
278
- - 사용자 목록 및 역할 관리 (admin / user)
279
- - 대시보드 (메모리, 모델, 시스템 상태, 활동 차트)
280
- - 초대 링크 생성 및 복사
281
-
282
- > 첫 번째로 가입한 계정이 자동으로 admin입니다.
283
- > 환경변수로 고정: `LATTICEAI_ADMIN_EMAILS=you@example.com`
284
-
285
- ---
286
-
287
- ## P-Reinforce 지식 정원
288
-
289
- 코드/텍스트를 `~/.ltcai-brain/`에 자동 분류 저장합니다.
290
-
291
- ```
292
- ~/.ltcai-brain/
293
- ├── 00_Raw/ # 원시 데이터, 아이디어
294
- ├── 10_Wiki/ # 검증된 개념, 레퍼런스
295
- ├── 20_Skills/ # 코드 스니펫, 프롬프트
296
- ├── 30_Projects/ # 프로젝트 컨텍스트
297
- └── 40_Log/ # 날짜별 작업 로그
298
- ```
299
-
300
- 에디터에서 텍스트 선택 → 우클릭 → **"Save to Knowledge Garden"**
301
-
302
- ---
303
-
304
- ## Data Graph / Graph RAG
305
-
306
- 채팅·AI 답변·업로드 문서(PDF/DOCX/XLSX/PPTX/TXT/CSV)를 `~/.ltcai/knowledge_graph.sqlite`에 자동 저장합니다.
307
-
308
- - 시각화: `http://localhost:4825/graph`
309
- - 검색 및 RAG 컨텍스트 자동 주입
229
+ | Symptom | Cause | Fix |
230
+ |---------|-------|-----|
231
+ | Port 4825 in use | Previous process | `lsof -i :4825` → `kill <PID>` or `--port 4826` |
232
+ | `ModuleNotFoundError: mlx` | MLX not installed | `pip install "ltcai[local]"` (Apple Silicon only) |
233
+ | Python < 3.11 | Version mismatch | Upgrade: `python3 --version` |
234
+ | `LTCAI doctor` OPTIONAL | Optional dep missing | Safe to ignore if feature not needed |
235
+ | No API key warning | Cloud model not set | `OPENAI_API_KEY=sk-... LTCAI` or set in admin panel |
236
+ | Can't reach from iPad | Default bind 127.0.0.1 | `LATTICEAI_HOST=0.0.0.0 LTCAI` or use `--tunnel` |
310
237
 
311
238
  ---
312
239
 
313
- ## API 엔드포인트
314
-
315
- | Method | Path | 설명 |
316
- |--------|------|------|
317
- | GET | `/health` | 서버 상태, 현재 모델 |
318
- | GET | `/models` | 추천 모델 목록 + 로드 상태 |
319
- | POST | `/models/load` | 모델 로드 |
320
- | POST | `/models/switch/{id}` | 활성 모델 전환 |
321
- | DELETE | `/models/unload/{id}` | 모델 언로드 |
322
- | POST | `/chat` | 채팅 생성 (`stream=true/false`) |
323
- | POST | `/agent` | 파일 생성/수정 에이전트 |
324
- | GET | `/tools/list_dir` | 디렉토리 목록 |
325
- | POST | `/tools/run_command` | 터미널 명령 실행 |
326
- | GET | `/mcp/installed` | 설치된 MCP 목록 (로컬 + 원격 레지스트리) |
327
- | POST | `/mcp/install` | MCP 설치 (bundled / pip / npm / pypi) |
328
- | POST | `/mcp/registry/refresh` | 원격 MCP 레지스트리 캐시 갱신 |
329
- | GET | `/skills/marketplace` | Skills 마켓플레이스 (Anthropic + 서드파티, `?category=` `?author=`) |
330
- | POST | `/skills/install` | Skill 설치 (`{ "plugin": "...", "skill": "..." }`) |
331
- | GET | `/skills/list` | 로컬 설치 skills 목록 |
332
- | GET | `/plugins/directory` | 오픈소스 플러그인 디렉터리 149개 (`?q=` `?category=` `?license=`) |
333
-
334
- 자세한 MCP 도구 목록: [docs/mcp-tools.md](docs/mcp-tools.md)
335
-
336
- ---
337
-
338
- ## 자동 시작 (Mac)
240
+ ## 🚀 Auto-start (Mac)
339
241
 
340
242
  ```bash
341
243
  cat > ~/Library/LaunchAgents/com.ltcai.plist << 'EOF'
@@ -344,9 +246,7 @@ cat > ~/Library/LaunchAgents/com.ltcai.plist << 'EOF'
344
246
  <plist version="1.0">
345
247
  <dict>
346
248
  <key>Label</key><string>com.ltcai</string>
347
- <key>ProgramArguments</key><array>
348
- <string>/usr/local/bin/LTCAI</string>
349
- </array>
249
+ <key>ProgramArguments</key><array><string>/usr/local/bin/LTCAI</string></array>
350
250
  <key>RunAtLoad</key><true/>
351
251
  <key>KeepAlive</key><true/>
352
252
  <key>StandardOutPath</key><string>/tmp/ltcai.log</string>
@@ -357,22 +257,69 @@ EOF
357
257
  launchctl load ~/Library/LaunchAgents/com.ltcai.plist
358
258
  ```
359
259
 
360
- 또는: `./start_ai.sh` (자동 재시작 + caffeinate)
260
+ Or: `./start_ai.sh` (auto-restart + caffeinate)
261
+
262
+ ---
263
+
264
+ ## 📦 Distribution
265
+
266
+ | Channel | Link |
267
+ |---------|------|
268
+ | PyPI | [pypi.org/project/ltcai](https://pypi.org/project/ltcai/) |
269
+ | npm | [npmjs.com/package/ltcai](https://www.npmjs.com/package/ltcai) |
270
+ | VS Code Marketplace | [marketplace.visualstudio.com](https://marketplace.visualstudio.com/items?itemName=parktaesoo.ltcai) |
271
+ | Open VSX | [open-vsx.org](https://open-vsx.org/extension/parktaesoo/ltcai) |
272
+
273
+ Current version: **0.1.23** — [Changelog](docs/CHANGELOG.md)
274
+
275
+ ---
276
+
277
+ ## 🤝 Contributing
278
+
279
+ See [CONTRIBUTING.md](CONTRIBUTING.md). All PRs welcome.
280
+
281
+ ## 📄 License
282
+
283
+ MIT — [TaeSoo Park](https://github.com/TaeSooPark-PTS)
361
284
 
362
285
  ---
363
286
 
364
- ## 기여
287
+ <details>
288
+ <summary>한국어 안내 (Korean)</summary>
289
+
290
+ ## 한국어 안내
365
291
 
366
- [CONTRIBUTING.md](CONTRIBUTING.md)를 참고하세요.
292
+ **Lattice AI**는 로컬/클라우드 LLM을 웹 UI · VS Code 확장 · Telegram 봇 · MCP 도구로 하나의 서버에서 운영하는 개인 AI 워크스페이스입니다.
367
293
 
368
- ## 보안 취약점 제보
294
+ ### 설치
369
295
 
370
- [SECURITY.md](SECURITY.md)를 참고하세요.
296
+ ```bash
297
+ pip install ltcai # 클라우드 모델
298
+ pip install "ltcai[local]" # + Apple Silicon MLX 로컬 모델
299
+ LTCAI # 서버 실행 → http://localhost:4825
300
+ LTCAI --tunnel # + Cloudflare 공개 URL 자동 발급
301
+ ```
302
+
303
+ ### 주요 기능
371
304
 
372
- ## 릴리스 노트
305
+ - 웹 UI 채팅 + 어드민 대시보드 + Data Graph 시각화
306
+ - VS Code / Cursor 확장 (`Cmd+Shift+A`)
307
+ - Telegram 봇 연동
308
+ - MCP 레지스트리 & Skills 마켓플레이스
309
+ - Graph RAG — 채팅·문서를 SQLite 지식 그래프로 자동 구조화
310
+ - 멀티 LLM 파이프라인 (Plan → Execute → Review)
311
+ - Human-in-the-loop 에이전트 승인
312
+ - 감사 로그 & 데이터 거버넌스 대시보드
313
+ - 텔레메트리 없음 — 모든 데이터 로컬 저장
373
314
 
374
- 현재 버전: **0.1.22** — 자세한 변경 이력은 [docs/CHANGELOG.md](docs/CHANGELOG.md) 참고.
315
+ ### 추천 로컬 모델 (M-series Mac)
316
+
317
+ | 모델 | 용도 | 크기 |
318
+ |------|------|------|
319
+ | `mlx-community/gemma-4-26b-a4b-it-4bit` | 범용 | ~14GB |
320
+ | `mlx-community/Qwen2.5-Coder-32B-Instruct-4bit` | 코딩 | ~18GB |
321
+ | `mlx-community/DeepSeek-R1-0528-4bit` | 추론 | ~38GB |
375
322
 
376
- ## 라이선스
323
+ 자세한 내용: [docs/CHANGELOG.md](docs/CHANGELOG.md) · [보안](SECURITY.md) · [기여](CONTRIBUTING.md)
377
324
 
378
- MIT
325
+ </details>
package/docs/CHANGELOG.md CHANGED
@@ -1,14 +1,67 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.1.23] - 2026-05-24
4
+
5
+ ### Discord 권한 알림 시스템
6
+
7
+ - **`GET /permissions/pending`** — 대기 중인 파일 접근 권한 요청 목록 (관리자)
8
+ - **`POST /permissions/approve/{token}`** — 권한 승인 (관리자 세션 또는 `LATTICEAI_PERMISSION_SECRET`)
9
+ - **`POST /permissions/deny/{token}`** — 권한 거부/취소
10
+ - **`GET /permissions/status/{token}`** — 승인 상태 폴링 (AI 에이전트용)
11
+ - 권한 토큰 기본값 `approved: False` — 명시적 승인 전까지 파일 접근 불가
12
+ - `~/.ltcai/permission_queue.json` — 서버가 기록, Claude Code Discord 플러그인이 읽어 알림 전송
13
+ - `LATTICEAI_PERMISSION_SECRET` 환경변수 — 모니터 스크립트가 세션 없이 approve/deny 호출 가능
14
+ - `perm_monitor.py` — 권한 목록 조회·승인·거부 CLI 도우미 (`list` / `approve TOKEN` / `deny TOKEN` / `discord-msg`)
15
+ - Discord에서 `승인 <토큰앞8자>` / `거부 <토큰앞8자>` 로 파일 접근 제어 가능
16
+
17
+ ### 리포지터리 UX 개선
18
+
19
+ - **영어 README** 전면 재작성 — 한국어는 접을 수 있는 `<details>` 섹션으로 이동
20
+ - **SVG 로고** 추가 (`docs/images/logo.svg`)
21
+ - **경쟁 제품 비교표** — Lattice AI vs Open WebUI · Continue.dev · GitHub Copilot
22
+ - **실제 UI 스크린샷 3장** — Chat UI · Admin Dashboard · Data Graph (Playwright 2x 캡처)
23
+ - **VS Code 익스텐션 카테고리** `Other` → `AI, Machine Learning, Chat, Other`
24
+ - **VS Code 익스텐션 키워드** 8개 → 16개 (copilot, apple-silicon, groq, graph-rag 등)
25
+ - **VS Code 익스텐션 README** 전면 재작성 (기능표, 비교표, 모델 목록)
26
+ - 구버전 `.tgz` / `.vsix` 빌드 파일 삭제
27
+
28
+ ### Release
29
+ - 배포 버전을 `0.1.23`으로 상향
30
+ - 대상 채널: `npm` · `PyPI` · `VS Code Marketplace` · `Open VSX`
31
+
3
32
  ## [0.1.22] - 2026-05-24
4
33
 
34
+ ### 리포지터리 UX 개선 — 다운로드 유입 최적화
35
+
36
+ #### README 전면 재작성
37
+ - **영어 메인 문서** — 한국어는 접을 수 있는 `<details>` 섹션으로 이동 (국제 유입 대응)
38
+ - **SVG 로고 추가** (`docs/images/logo.svg`) — 인디고→시안 그라디언트 래티스 그리드 아이콘
39
+ - **경쟁 제품 비교표** — Lattice AI vs Open WebUI · Continue.dev · GitHub Copilot 10개 기준 비교
40
+ - **PyPI 월간 다운로드 수 배지** 추가 (신뢰도 지표)
41
+ - 기능 · 보안 · API · 트러블슈팅 섹션을 표(table) 형식으로 정리 (가독성 향상)
42
+
43
+ #### 실제 UI 스크린샷 자동 캡처
44
+ - `docs/images/screenshot-chat.png` — 웹 채팅 UI (사이드바, 모델/파이프라인/VPC 카드)
45
+ - `docs/images/screenshot-admin.png` — 어드민 대시보드 + Audit & Data Governance 섹션
46
+ - `docs/images/screenshot-graph.png` — Data Graph 시각화 (299 노드, 443 엣지)
47
+ - README 상단에 3단 그리드 스크린샷 테이블 추가
48
+ - `scripts/take_screenshots.js` — Playwright Chromium 헤드리스 캡처 스크립트 (2x 레티나)
49
+
50
+ #### VS Code 익스텐션 메타데이터 개선
51
+ - **카테고리** `Other` → `AI, Machine Learning, Chat, Other` (Marketplace 검색 노출 증가)
52
+ - **키워드** 8개 → 16개 추가 (`copilot`, `apple-silicon`, `groq`, `graph-rag` 등)
53
+ - **설명 문구** 구체화 — 핵심 차별점(MLX, MCP, Graph RAG, zero telemetry) 명시
54
+ - **익스텐션 README 전면 재작성** — 기능표 · 빠른 시작 · 단축키 · 지원 모델 · 설정 · 비교표 포함
55
+
56
+ #### 리포지터리 정리
57
+ - 루트 및 `vscode-extension/`의 구버전 `.tgz` / `.vsix` 빌드 파일 삭제
58
+
5
59
  ### Release preparation
6
60
 
7
61
  - 배포 버전을 `0.1.22`로 상향
8
62
  - `package.json`
9
63
  - `pyproject.toml`
10
64
  - `vscode-extension/package.json`
11
- - README 현재 배포 버전과 릴리스 체크 섹션을 `0.1.22` 기준으로 갱신
12
65
  - npm / PyPI / VS Code Marketplace / Open VSX 배포 전 빌드 산출물 생성
13
66
 
14
67
  ### Verification
package/docs/images/logo.svg ADDED
@@ -0,0 +1,33 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 240 60" width="240" height="60">
2
+ <defs>
3
+ <linearGradient id="g" x1="0%" y1="0%" x2="100%" y2="100%">
4
+ <stop offset="0%" style="stop-color:#6366f1"/>
5
+ <stop offset="100%" style="stop-color:#06b6d4"/>
6
+ </linearGradient>
7
+ </defs>
8
+ <!-- Lattice grid icon -->
9
+ <g transform="translate(8,10)">
10
+ <!-- dots -->
11
+ <circle cx="0" cy="0" r="3" fill="url(#g)" opacity="0.9"/>
12
+ <circle cx="16" cy="0" r="3" fill="url(#g)" opacity="0.9"/>
13
+ <circle cx="32" cy="0" r="3" fill="url(#g)" opacity="0.9"/>
14
+ <circle cx="0" cy="16" r="3" fill="url(#g)" opacity="0.9"/>
15
+ <circle cx="16" cy="16" r="4" fill="url(#g)"/>
16
+ <circle cx="32" cy="16" r="3" fill="url(#g)" opacity="0.9"/>
17
+ <circle cx="0" cy="32" r="3" fill="url(#g)" opacity="0.9"/>
18
+ <circle cx="16" cy="32" r="3" fill="url(#g)" opacity="0.9"/>
19
+ <circle cx="32" cy="32" r="3" fill="url(#g)" opacity="0.9"/>
20
+ <!-- lines -->
21
+ <line x1="0" y1="0" x2="32" y2="0" stroke="url(#g)" stroke-width="1.2" opacity="0.4"/>
22
+ <line x1="0" y1="16" x2="32" y2="16" stroke="url(#g)" stroke-width="1.2" opacity="0.4"/>
23
+ <line x1="0" y1="32" x2="32" y2="32" stroke="url(#g)" stroke-width="1.2" opacity="0.4"/>
24
+ <line x1="0" y1="0" x2="0" y2="32" stroke="url(#g)" stroke-width="1.2" opacity="0.4"/>
25
+ <line x1="16" y1="0" x2="16" y2="32" stroke="url(#g)" stroke-width="1.2" opacity="0.4"/>
26
+ <line x1="32" y1="0" x2="32" y2="32" stroke="url(#g)" stroke-width="1.2" opacity="0.4"/>
27
+ <!-- diagonals -->
28
+ <line x1="0" y1="0" x2="32" y2="32" stroke="url(#g)" stroke-width="1" opacity="0.25"/>
29
+ <line x1="32" y1="0" x2="0" y2="32" stroke="url(#g)" stroke-width="1" opacity="0.25"/>
30
+ </g>
31
+ <!-- Text -->
32
+ <text x="58" y="34" font-family="'SF Pro Display','Segoe UI',system-ui,sans-serif" font-size="26" font-weight="700" fill="url(#g)" letter-spacing="-0.5">Lattice AI</text>
33
+ </svg>
package/docs/images/screenshot-admin.png ADDED
Binary file
package/docs/images/screenshot-chat.png ADDED
Binary file
package/docs/images/screenshot-graph.png ADDED
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ltcai",
3
- "version": "0.1.22",
3
+ "version": "0.1.23",
4
4
  "description": "Lattice AI local MLX/cloud LLM workspace server",
5
5
  "homepage": "https://github.com/TaeSooPark-PTS/LatticeAI#readme",
6
6
  "repository": {