ltcai 3.6.0 → 4.0.1

package/p_reinforce.py

@@ -1,16 +1,21 @@
 """
-P-Reinforce Knowledge Gardener
-Raw 데이터를 자동으로 분석해서 구조화된 마크다운 위키로 정리
+P-Reinforce Knowledge Gardener — notes capture with a brain-backed memory.
+
+v4 (T4.3 garden absorption): the markdown vault is no longer a second brain.
+The vault stays as the user-owned, Obsidian-compatible *mirror* (capability
+preserved), but the Knowledge Graph is authoritative: notes created through
+the API are ingested through the unified pipeline (provenance + hooks), the
+existing vault is imported idempotently, and chat context comes from brain
+queries instead of an O(n) vault scan per message.
 """
 
-import json
+import logging
 import os
 import re
-import time
 import shutil
 from datetime import datetime
 from pathlib import Path
-from typing import Optional
+from typing import Any, Optional
 
 BRAIN_DIR = Path(
     os.getenv("LATTICEAI_OBSIDIAN_VAULT_DIR")
@@ -28,7 +33,9 @@ STRUCTURE = {
 
 
 class PReinforceGardener:
-    def __init__(self):
+    def __init__(self, ingestion_pipeline: Any = None, knowledge_graph: Any = None):
+        self._pipeline = ingestion_pipeline
+        self._kg = knowledge_graph
         self._ensure_structure()
 
     def _ensure_structure(self):
@@ -43,6 +50,7 @@ class PReinforceGardener:
         lines = ["# 🧠 Lattice AI Brain — P-Reinforce Index\n"]
         lines.append(f"*Generated: {datetime.now().strftime('%Y-%m-%d %H:%M')}*\n")
         lines.append("\nThis folder is an Obsidian-compatible Markdown vault.\n")
+        lines.append("\nThe Knowledge Graph is the authoritative store; this vault is the\nuser-owned markdown mirror of garden notes.\n")
         for folder, desc in STRUCTURE.items():
             lines.append(f"## [{folder}](./{folder}/)\n_{desc}_\n")
         lines.append("## Connector Status\n")
@@ -87,14 +95,14 @@ class PReinforceGardener:
         filename = self._make_filename(raw_data, folder)
         filepath = BRAIN_DIR / folder / filename
 
-        # 마크다운 래핑
+        # 마크다운 미러 (사용자 소유 Obsidian 호환 아티팩트)
         content = self._wrap_markdown(raw_data, folder)
         filepath.write_text(content, encoding="utf-8")
 
         # 오늘 로그에도 기록
         self._append_log(raw_data[:200], folder, filename)
 
-        return {
+        result = {
             "status": "saved",
             "folder": folder,
             "filename": filename,
@@ -102,6 +110,68 @@ class PReinforceGardener:
             "classified_as": folder,
             "description": STRUCTURE[folder],
         }
+        # 두뇌(Knowledge Graph)가 정식 저장소: 통합 수집 파이프라인으로 ingest.
+        result.update(self._ingest_note(raw_data, source_uri=str(filepath), folder=folder))
+        return result
+
+    def _ingest_note(self, text: str, *, source_uri: str, folder: str, title: Optional[str] = None) -> dict:
+        if self._pipeline is None:
+            return {"graph": "unavailable", "graph_detail": "ingestion pipeline not wired"}
+        try:
+            from latticeai.services.ingestion import IngestionItem
+
+            ingest = self._pipeline.ingest(
+                IngestionItem(
+                    source_type="note",
+                    title=title or text.strip().split("\n")[0][:80],
+                    text=text,
+                    source_uri=source_uri,
+                    metadata={"garden_folder": folder, "pipeline": "p-reinforce"},
+                )
+            )
+            if ingest.status != "ok":
+                return {"graph": ingest.status, "graph_detail": ingest.detail}
+            return {
+                "graph": "ok",
+                "graph_node_id": ingest.node_id,
+                "provenance_id": ingest.provenance_id,
+                "duplicate": ingest.duplicate,
+            }
+        except Exception as exc:
+            logging.warning("garden note ingest failed: %s", exc)
+            return {"graph": "failed", "graph_detail": str(exc)}
+
+    def import_vault(self) -> dict:
+        """Idempotent import of every existing vault note into the brain.
+
+        Content-hash dedup in the store makes re-runs safe; vault files are
+        never modified or deleted. INDEX.md and the daily logs are skipped.
+        """
+        if self._pipeline is None:
+            return {"status": "unavailable", "imported": 0}
+        imported = duplicates = failed = 0
+        for file_path in sorted(BRAIN_DIR.rglob("*.md")):
+            if file_path.name == "INDEX.md" or "40_Log" in file_path.parts:
+                continue
+            try:
+                text = file_path.read_text(encoding="utf-8")
+            except Exception:
+                failed += 1
+                continue
+            folder = file_path.parent.name if file_path.parent != BRAIN_DIR else "00_Raw"
+            outcome = self._ingest_note(
+                text, source_uri=str(file_path), folder=folder, title=file_path.stem
+            )
+            if outcome.get("graph") == "ok":
+                if outcome.get("duplicate"):
+                    duplicates += 1
+                else:
+                    imported += 1
+            else:
+                failed += 1
+        if imported:
+            logging.info("garden: imported %d vault notes into the brain (%d already known)", imported, duplicates)
+        return {"status": "ok", "imported": imported, "duplicates": duplicates, "failed": failed}
 
     def _wrap_markdown(self, raw: str, folder: str) -> str:
         now = datetime.now().strftime("%Y-%m-%d %H:%M")
@@ -112,7 +182,7 @@ class PReinforceGardener:
             "---\n",
             raw,
             "\n\n---",
-            f"*Auto-organized by P-Reinforce Gardener*",
+            "*Auto-organized by P-Reinforce Gardener*",
         ]
         return "\n".join(lines)
 
@@ -127,22 +197,62 @@ class PReinforceGardener:
 
     # ── Tree ──────────────────────────────────────────────────────────────────
 
+    def get_tree(self) -> dict:
+        """지식 정원 파일트리 (마크다운 미러 기준)."""
+        folders = []
+        for folder, desc in STRUCTURE.items():
+            folder_path = BRAIN_DIR / folder
+            files = []
+            if folder_path.exists():
+                for file_path in sorted(folder_path.glob("*.md")):
+                    try:
+                        stat = file_path.stat()
+                        files.append({
+                            "name": file_path.name,
+                            "size_bytes": stat.st_size,
+                            "modified_at": datetime.fromtimestamp(stat.st_mtime).isoformat(timespec="seconds"),
+                        })
+                    except OSError:
+                        continue
+            folders.append({"name": folder, "description": desc, "files": files, "count": len(files)})
+        return {"root": str(BRAIN_DIR), "folders": folders}
+
     def get_relevant_context(self, query: str, limit: int = 3) -> str:
-        """질문과 관련된 지식을 검색하여 컨텍스트 문자열을 반환합니다."""
+        """질문과 관련된 정원 노트를 두뇌에서 검색해 컨텍스트로 반환.
+
+        v4: 채팅마다 vault 전체를 rglob 하던 O(n) 스캔을 브레인 검색으로
+        대체. 그래프가 없으면(비활성) 기존 파일 스캔으로 정직하게 폴백.
+        """
+        if self._kg is not None:
+            try:
+                matches = self._kg.search(query, max(limit * 4, 8)).get("matches", [])
+                results = []
+                for match in matches:
+                    meta = match.get("metadata") or {}
+                    if not (meta.get("garden_folder") or meta.get("pipeline") == "p-reinforce"):
+                        continue
+                    title = match.get("title") or "note"
+                    body = match.get("summary") or ""
+                    results.append(f"--- Document: {title} ---\n{body[:800]}")
+                    if len(results) >= limit:
+                        break
+                return "\n\n".join(results)
+            except Exception as exc:
+                logging.debug("garden brain context failed, falling back to vault scan: %s", exc)
+        return self._scan_vault_context(query, limit)
+
+    def _scan_vault_context(self, query: str, limit: int = 3) -> str:
         results = []
-        # 모든 마크다운 파일 탐색 (INDEX.md 및 Log 제외)
         for file_path in BRAIN_DIR.rglob("*.md"):
             if file_path.name == "INDEX.md" or "40_Log" in str(file_path):
                 continue
-            
             try:
                 content = file_path.read_text(encoding="utf-8")
-                keywords = [k for k in re.split(r'\s+', query) if len(k) > 1]
+                keywords = [k for k in re.split(r"\s+", query) if len(k) > 1]
                 if any(k.lower() in content.lower() for k in keywords):
                     results.append(f"--- Document: {file_path.name} ---\n{content[:800]}")
                     if len(results) >= limit:
                         break
             except Exception:
                 continue
-        
         return "\n\n".join(results)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ltcai",
-  "version": "3.6.0",
-  "description": "Lattice AI v3 local-first AI workspace platform with knowledge graph, vector index, hybrid search, agents, and workspace modes.",
+  "version": "4.0.1",
+  "description": "Lattice AI — local-first Digital Brain Platform (knowledge graph, durable memory, hybrid search, agents, signed brain exchange)",
   "homepage": "https://github.com/TaeSooPark-PTS/LatticeAI#readme",
   "repository": {
     "type": "git",
@@ -21,7 +21,7 @@
     "build:assets": "node scripts/build_v3_assets.mjs",
     "build:python": "python3 -m build",
     "check:python": "python3 scripts/check_python.py",
-    "lint": "node --check static/scripts/account.js && node --check static/scripts/admin.js && node --check static/scripts/chat.js && node --check static/scripts/graph.js && node --check static/scripts/platform.js && node --check static/scripts/ux.js && node --check static/scripts/workspace.js && node --check tests/visual/mock_server.cjs && node --check tests/visual/v3.spec.js && npm run lint:v3",
+    "lint": "node --check tests/visual/mock_server.cjs && node --check tests/visual/v3.spec.js && npm run lint:v3",
     "lint:v3": "node scripts/lint_v3.mjs",
     "typecheck": "cd vscode-extension && npm run build",
     "test": "python3 -m pytest tests/ -v",
@@ -66,42 +66,32 @@
     "server.py",
     "kg_schema.py",
     "knowledge_graph.py",
-    "knowledge_graph_api.py",
     "local_knowledge_api.py",
     "llm_router.py",
     "p_reinforce.py",
     "telegram_bot.py",
     "tools/",
-    "codex_telegram_bot.py",
     "mcp_registry.py",
     "latticeai/**/*.py",
     "skills/",
-    "static/account.html",
-    "static/chat.html",
-    "static/admin.html",
-    "static/graph.html",
-    "static/workspace.html",
-    "static/plugins.html",
-    "static/workflows.html",
-    "static/agents.html",
-    "static/activity.html",
     "static/favicon.ico",
     "static/manifest.json",
     "static/sw.js",
-    "static/workspace.css",
-    "static/platform.css",
-    "static/scripts/",
     "static/css/",
     "static/v3/",
     "static/icons/",
     "plugins/",
     "scripts/",
-    "docs/",
     "!docs/images/tmp_frames/",
     "!**/__pycache__/",
     "!**/*.pyc",
-    "requirements.txt",
-    "README.md"
+    "README.md",
+    "setup_wizard.py",
+    "knowledge_graph_api.py",
+    "static/vendor/",
+    "docs/*.md",
+    "!docs/assets/",
+    "!docs/images/"
   ],
   "publishConfig": {
     "access": "public"

package/scripts/bump_version.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Single-source version bump — rewrites every synchronized version copy.
+
+The canonical version has always been nine hand-edited copies guarded by
+tests/unit/test_version_consistency.py. This script makes the bump one
+command; the consistency test keeps guarding the result.
+
+Usage:
+    python scripts/bump_version.py 4.0.0
+    python scripts/bump_version.py 4.0.0 --check   # verify only, no writes
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[1]
+
+# (path, kind, pattern) — pattern groups: (prefix, version)
+TARGETS = [
+    ("latticeai/__init__.py", "regex", r'(__version__ = ")([^"]+)(")'),
+    ("latticeai/core/workspace_os.py", "regex", r'(WORKSPACE_OS_VERSION = ")([^"]+)(")'),
+    ("latticeai/core/marketplace.py", "regex", r'(MARKETPLACE_VERSION = ")([^"]+)(")'),
+    ("latticeai/core/multi_agent.py", "regex", r'(MULTI_AGENT_VERSION = ")([^"]+)(")'),
+    ("pyproject.toml", "regex", r'(^version = ")([^"]+)(")'),
+    ("package.json", "json", "version"),
+    ("package-lock.json", "package-lock", None),
+    ("vscode-extension/package.json", "json", "version"),
+    ("vscode-extension/package-lock.json", "package-lock", None),
+    ("static/v3/asset-manifest.json", "json", "version"),
+]
+
+
+def bump(version: str, *, check: bool = False) -> int:
+    if not re.fullmatch(r"\d+\.\d+\.\d+([-.][0-9A-Za-z.]+)?", version):
+        print(f"error: '{version}' is not a sane semantic version", file=sys.stderr)
+        return 2
+    failures = 0
+    for rel, kind, spec in TARGETS:
+        path = REPO / rel
+        if not path.exists():
+            print(f"  skip  {rel} (missing)")
+            continue
+        text = path.read_text(encoding="utf-8")
+        if kind == "regex":
+            new, n = re.subn(spec, lambda m: m.group(1) + version + m.group(3), text, count=1, flags=re.MULTILINE)
+            changed = n == 1 and new != text
+            ok = n == 1
+        elif kind == "json":
+            data = json.loads(text)
+            ok = spec in data
+            changed = ok and data.get(spec) != version
+            if ok:
+                data[spec] = version
+                new = json.dumps(data, ensure_ascii=False, indent=2) + "\n"
+        elif kind == "package-lock":
+            data = json.loads(text)
+            ok = "version" in data
+            changed = ok and data.get("version") != version
+            if ok:
+                data["version"] = version
+                if "packages" in data and "" in data["packages"]:
+                    data["packages"][""]["version"] = version
+                new = json.dumps(data, ensure_ascii=False, indent=2) + "\n"
+        else:  # pragma: no cover
+            raise AssertionError(kind)
+        if not ok:
+            print(f"  FAIL  {rel}: version field not found")
+            failures += 1
+            continue
+        if check:
+            current = re.search(spec, text, flags=re.MULTILINE).group(2) if kind == "regex" else json.loads(text)["version"]
+            status = "ok" if current == version else f"MISMATCH ({current})"
+            if current != version:
+                failures += 1
+            print(f"  {status:>9}  {rel}")
+            continue
+        if changed:
+            path.write_text(new, encoding="utf-8")
+            print(f"  bumped  {rel}")
+        else:
+            print(f"  ok      {rel}")
+    return 1 if failures else 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("version")
+    parser.add_argument("--check", action="store_true", help="verify only; write nothing")
+    args = parser.parse_args()
+    return bump(args.version, check=args.check)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/generate_diagrams.py

@@ -17,7 +17,6 @@ the hero GIF is assembled from via ffmpeg by the caller).
 
 from __future__ import annotations
 
-import os
 import sys
 from pathlib import Path
 

package/scripts/lint_v3.mjs

@@ -1,33 +1,120 @@
 #!/usr/bin/env node
-/* Syntax-check every Lattice AI v3 frontend ES module (node --check, ESM auto-detect).
- * Exits non-zero on the first failure so it can gate `npm run lint`. */
-import { readdirSync, statSync } from "node:fs";
-import { join, dirname } from "node:path";
+/* Lattice v3 frontend lint. Gates `npm run lint`:
+ *  1. Syntax-check every v3 ES module (node --check).
+ *  2. Design tokens: no raw hex/rgb colors in static/v3/css outside the two
+ *     token files (lattice.tokens.css, tokens.css) — themed surfaces must use
+ *     var(--…) tokens.
+ *  3. No inline style colors in view JS (style="…color: #…" or
+ *     style.color = "#…" literals).
+ *  4. Privacy: zero CDN/external URLs in shipped static HTML/CSS/JS —
+ *     fonts/icons/libs are vendored under static/vendor.
+ *  5. i18n: routes, shell, and new v4 parity views must use the SPA i18n
+ *     runtime instead of inert localStorage-only language toggles.
+ * Exits non-zero on any failure. */
+import { readdirSync, statSync, readFileSync } from "node:fs";
+import { join, dirname, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 
-const root = join(dirname(fileURLToPath(import.meta.url)), "..", "static", "v3", "js");
+const repo = join(dirname(fileURLToPath(import.meta.url)), "..");
+const v3js = join(repo, "static", "v3", "js");
+const v3css = join(repo, "static", "v3", "css");
+const staticRoot = join(repo, "static");
 
-function walk(dir) {
+function walk(dir, ext) {
   const out = [];
   for (const name of readdirSync(dir)) {
     const p = join(dir, name);
-    if (statSync(p).isDirectory()) out.push(...walk(p));
-    else if (name.endsWith(".js")) out.push(p);
+    if (statSync(p).isDirectory()) out.push(...walk(p, ext));
+    else if (ext.some((e) => name.endsWith(e))) out.push(p);
   }
   return out;
 }
 
-const files = walk(root).sort();
 let failed = 0;
-for (const file of files) {
+const fail = (msg) => { failed++; console.error(`FAIL ${msg}`); };
+
+// ── 1. syntax ────────────────────────────────────────────────────────────
+const modules = walk(v3js, [".js"]).sort();
+let syntaxOk = 0;
+for (const file of modules) {
   const r = spawnSync(process.execPath, ["--check", file], { encoding: "utf8" });
-  if (r.status === 0) {
-    console.log(`ok   ${file.replace(root, "static/v3/js")}`);
-  } else {
-    failed++;
-    console.error(`FAIL ${file.replace(root, "static/v3/js")}\n${r.stderr || r.stdout}`);
-  }
+  if (r.status === 0) syntaxOk++;
+  else fail(`${relative(repo, file)}\n${r.stderr || r.stdout}`);
+}
+console.log(`syntax: ${syntaxOk}/${modules.length} v3 modules pass`);
+
+// ── 2. raw colors in v3 css (outside token files) ────────────────────────
+const TOKEN_FILES = new Set(["lattice.tokens.css", "tokens.css"]);
+const colorRe = /#[0-9a-fA-F]{3,8}\b|rgba?\(/;
+let cssChecked = 0;
+for (const file of walk(v3css, [".css"]).sort()) {
+  const base = file.split("/").pop();
+  if (TOKEN_FILES.has(base) || /\.[0-9a-f]{8}\.css$/.test(base)) continue; // tokens + hashed builds
+  cssChecked++;
+  const lines = readFileSync(file, "utf8").split("\n");
+  lines.forEach((line, i) => {
+    const code = line.split("/*")[0];
+    // mask-image gradients use #000/transparent as ALPHA values, not themed
+    // colors — they are theme-independent and exempt.
+    if (/mask-image|-webkit-mask/.test(code)) return;
+    if (colorRe.test(code)) fail(`${relative(repo, file)}:${i + 1} raw color (use a var(--…) token): ${line.trim().slice(0, 90)}`);
+  });
+}
+console.log(`tokens: ${cssChecked} non-token v3 css files scanned for raw colors`);
+
+// ── 3. inline style colors in view JS ────────────────────────────────────
+const inlineColorRe = /style\s*=\s*["'`][^"'`]*(?:color|background)\s*:\s*(#|rgb)/i;
+const styleAssignRe = /\.style\.(color|background(?:Color)?)\s*=\s*["'`](#|rgb)/i;
+let jsChecked = 0;
+for (const file of modules) {
+  if (/\.[0-9a-f]{8}\.js$/.test(file)) continue; // hashed builds mirror sources
+  jsChecked++;
+  const lines = readFileSync(file, "utf8").split("\n");
+  lines.forEach((line, i) => {
+    if (inlineColorRe.test(line) || styleAssignRe.test(line)) {
+      fail(`${relative(repo, file)}:${i + 1} inline style color (use a token/class): ${line.trim().slice(0, 90)}`);
+    }
+  });
+}
+console.log(`inline-style: ${jsChecked} v3 source modules scanned`);
+
+// ── 4. no CDN/external asset URLs in shipped static files ────────────────
+const cdnRe = /https?:\/\/(fonts\.googleapis\.com|fonts\.gstatic\.com|cdn\.jsdelivr\.net|unpkg\.com|cdnjs\.cloudflare\.com)/;
+let shippedChecked = 0;
+for (const file of walk(staticRoot, [".html", ".css", ".js"]).sort()) {
+  if (file.includes(`${join("static", "vendor")}`)) continue; // vendored copies may cite origins in comments
+  shippedChecked++;
+  const lines = readFileSync(file, "utf8").split("\n");
+  lines.forEach((line, i) => {
+    if (cdnRe.test(line)) fail(`${relative(repo, file)}:${i + 1} CDN reference (vendor it under static/vendor): ${line.trim().slice(0, 90)}`);
+  });
+}
+console.log(`privacy: ${shippedChecked} shipped static files scanned for CDN URLs`);
+
+// ── 5. i18n acceptance for T9 surfaces ──────────────────────────────────
+const i18nRequired = [
+  "static/v3/js/core/routes.js",
+  "static/v3/js/core/shell.js",
+  "static/v3/js/views/account.js",
+  "static/v3/js/views/workspace-admin.js",
+  "static/v3/js/views/snapshots.js",
+  "static/v3/js/views/activity.js",
+  "static/v3/js/views/runs.js",
+  "static/v3/js/views/network.js",
+];
+let i18nChecked = 0;
+for (const rel of i18nRequired) {
+  const file = join(repo, rel);
+  const text = readFileSync(file, "utf8");
+  i18nChecked++;
+  if (!/i18n\.js/.test(text)) fail(`${rel}: missing i18n runtime import`);
+  if (!/\bt\(/.test(text)) fail(`${rel}: no translation lookup found`);
+}
+console.log(`i18n: ${i18nChecked} route/shell/parity modules checked`);
+
+if (failed) {
+  console.error(`\nv3 frontend lint: ${failed} failure(s)`);
+  process.exit(1);
 }
-console.log(`\nv3 frontend: ${files.length - failed}/${files.length} modules pass`);
-process.exit(failed ? 1 : 0);
+console.log(`\nv3 frontend lint: all checks pass`);

package/scripts/validate_release_artifacts.py

@@ -20,7 +20,6 @@ from __future__ import annotations
 import argparse
 import json
 import re
-import sys
 import zipfile
 from pathlib import Path
 from typing import Dict, List, Optional

package/scripts/wheel_smoke.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Installed-wheel smoke test.
+
+Builds the wheel, installs it into a *fresh* venv, and verifies — from a
+non-repo working directory — that every module the wheel ships actually
+imports and that the FastAPI app boots and answers ``/health``. This kills the
+class of "works only with ``pip install -e .`` from the repo root" failures
+(e.g. the v3.x wheels that omitted the root ``setup.py`` wizard module while
+``latticeai.server_app`` imported it).
+
+Usage:
+    python scripts/wheel_smoke.py                 # build + install + import + /health
+    python scripts/wheel_smoke.py --wheel dist/ltcai-X.Y.Z-py3-none-any.whl
+    python scripts/wheel_smoke.py --skip-health   # imports only
+
+The build step prefers ``python -m build --wheel`` and falls back to
+``pip wheel . --no-deps`` when the ``build`` package is unavailable.
+Exit code is non-zero on any failure so CI can gate on it.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+import tempfile
+import venv
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+# Every importable module the wheel ships (pyproject py-modules + packages).
+WHEEL_MODULES = [
+    "setup_wizard",
+    "latticeai",
+    "latticeai.server_app",
+    "latticeai.app_factory",
+    "latticeai.models.router",
+    "latticeai.core.mcp_registry",
+    "latticeai.api.knowledge_graph",
+    "ltcai_cli",
+    "auto_setup",
+    "server",
+    "mcp_registry",
+    "kg_schema",
+    "knowledge_graph",
+    "knowledge_graph_api",
+    "local_knowledge_api",
+    "llm_router",
+    "p_reinforce",
+    "telegram_bot",
+    "tools",
+]
+
+IMPORT_CHECK = (
+    "import importlib\n"
+    + "".join(f"importlib.import_module({mod!r})\n" for mod in WHEEL_MODULES)
+    + f"print('wheel imports ok: {len(WHEEL_MODULES)} modules')\n"
+)
+
+HEALTH_CHECK = """
+from fastapi.testclient import TestClient
+from latticeai.app_factory import create_app
+
+app = create_app()
+response = TestClient(app).get("/health")
+assert response.status_code == 200, f"/health returned {response.status_code}"
+payload = response.json()
+assert "version" in payload, f"/health payload missing version: {payload}"
+print("health ok:", payload.get("version"))
+"""
+
+
+def run(cmd: list[str], **kwargs) -> None:
+    print("+", " ".join(str(c) for c in cmd), flush=True)
+    subprocess.run(cmd, check=True, **kwargs)
+
+
+def build_wheel(out_dir: Path) -> Path:
+    try:
+        import build  # noqa: F401 — probe only
+        run([sys.executable, "-m", "build", "--wheel", "--outdir", str(out_dir)], cwd=REPO_ROOT)
+    except ImportError:
+        print("'build' package unavailable; falling back to pip wheel --no-deps", flush=True)
+        run(
+            [sys.executable, "-m", "pip", "wheel", str(REPO_ROOT), "--no-deps", "-w", str(out_dir)],
+            cwd=REPO_ROOT,
+        )
+    wheels = sorted(out_dir.glob("ltcai-*.whl"))
+    if not wheels:
+        raise SystemExit(f"no wheel produced in {out_dir}")
+    return wheels[-1]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--wheel", type=Path, default=None, help="use an existing wheel instead of building")
+    parser.add_argument("--skip-health", action="store_true", help="run import checks only (no app boot)")
+    args = parser.parse_args()
+
+    with tempfile.TemporaryDirectory(prefix="ltcai-wheel-smoke-") as tmp:
+        tmp_path = Path(tmp)
+
+        wheel = args.wheel.resolve() if args.wheel else build_wheel(tmp_path / "dist")
+        print(f"wheel under test: {wheel}", flush=True)
+
+        venv_dir = tmp_path / "venv"
+        venv.EnvBuilder(with_pip=True, clear=True).create(venv_dir)
+        bin_dir = "Scripts" if os.name == "nt" else "bin"
+        python = venv_dir / bin_dir / ("python.exe" if os.name == "nt" else "python")
+
+        run([str(python), "-m", "pip", "install", "--quiet", str(wheel)])
+
+        # A cwd that is NOT the repo: imports must resolve from site-packages,
+        # never from checkout-relative files.
+        work_dir = tmp_path / "non-repo-cwd"
+        work_dir.mkdir()
+        # Sandbox all user-data writes so the smoke test never touches ~/.ltcai.
+        env = {
+            **os.environ,
+            "HOME": str(tmp_path / "home"),
+            "LATTICEAI_DATA_DIR": str(tmp_path / "home" / ".ltcai"),
+            "LATTICEAI_AGENT_ROOT": str(tmp_path / "home" / "agent_workspace"),
+            "LATTICEAI_BRAIN_DIR": str(tmp_path / "home" / ".ltcai-brain"),
+            "LATTICEAI_ENABLE_TELEGRAM": "false",
+            "LATTICEAI_AUTOLOAD_MODELS": "false",
+            "PYTHONPATH": "",
+        }
+        (tmp_path / "home").mkdir()
+
+        run([str(python), "-c", IMPORT_CHECK], cwd=work_dir, env=env)
+
+        if not args.skip_health:
+            run([str(python), "-c", HEALTH_CHECK], cwd=work_dir, env=env)
+
+    print("wheel smoke test passed")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())