ltcai 0.2.2 → 0.3.1

package/README.md

@@ -21,6 +21,30 @@
 
 ---
 
+## What's new in 0.3.1
+
+- **Reliable model selection** — `ModelResolution` unifies recommended card ID,
+  download ID, load ID, router cache key, and the front-end `current` so
+  "downloaded but not loaded" / "loaded but UI shows a different model"
+  classes of bugs are gone.
+- **Smoke test on load** — every local model load runs a one-shot Korean
+  chat probe and surfaces `ready_to_chat` / `compatibility_status` to the UI.
+- **Model Compatibility Layer** — per-family profiles (GPT-OSS, Gemma, Qwen,
+  Llama, Mistral, Phi, Deepseek …) with cached stop tokens, postprocess
+  rules, and Fast / Slow / Recovery paths so chat speed stays the same.
+- **Auto graph curator** — topic extraction → alias clustering → promotion
+  with secret/PII firewall, so the graph builds itself without the user
+  managing nodes.
+- **AI Security & Audit Command Center** — admin dashboard now shows
+  per-user risk matrix (compliant chats vs risky chats vs compliant files
+  vs risky files), sensitive-type donut, drill-down, raw explorer, and
+  JSON / CSV / XLSX / PDF exports — with hard-secret redaction
+  enforced on every response.
+
+See [docs/CHANGELOG.md](./docs/CHANGELOG.md) for the full list.
+
+---
+
 ## Why Lattice AI?
 
 Most AI tools forget everything after each conversation. Your files sit in folders, your chats vanish, and nothing connects.

package/docs/CHANGELOG.md

@@ -1,5 +1,130 @@
 # Changelog
 
+## [0.3.1] - 2026-05-29
+
+> Model loading reliability + auto-graph curation + AI Security & Audit Command Center.
+>
+> 외부 리뷰 5건(모델 추천/다운로드, 사용자 직접 모델 선택, 모델 호환성 계층,
+> 자동 그래프 방향, 관리자 보안/감사 대시보드) 피드백을 모두 반영했다.
+
+### Model loading & inference
+
+- 새 모듈 `latticeai/core/model_resolution.py` — `ModelResolution`이
+  `input_id / engine / resolved_model / download_id / load_id / expected_current`을
+  하나로 묶어 추천 카드, 다운로드, 로드, router cache, 프론트 current 표시가
+  단계마다 어긋나는 문제를 제거.
+- `prepare_and_load_model()` 와 `/engines/prepare-model/stream`이 동일한
+  `ModelResolution`을 공유하도록 통합. LM Studio처럼 `instance_id`가 부여되는
+  엔진은 `resolution.update_after_load()`로 후처리.
+- 로드 직후 `_smoke_test_loaded_model()`가 한국어 짧은 채팅 테스트를 실행 →
+  응답에 `ready_to_chat`, `compatibility_status`, `smoke_test` 필드 추가.
+  Cloud 모델은 사용자 비용 발생을 피하기 위해 자동 skip.
+- `/models` 응답에 `engine_options`(local_mlx / ollama / lmstudio / llamacpp /
+  vllm 별 실제 model_id)와 `compat_profiles` 추가.
+- 새 엔드포인트 `GET /models/compat-profiles`.
+
+### Model compatibility layer
+
+- 새 모듈 `latticeai/core/model_compat.py` — Family detection
+  (gpt-oss / gemma / qwen / llama / mistral / phi / deepseek …),
+  family 프로파일(stop tokens, disable_draft, postprocess, generation params),
+  `fast_postprocess`, `validate_smoke_response`, `record_smoke_result`,
+  `compat_cache`. 무거운 검사는 모델 로드 시 1회(Slow Path), 채팅 중에는
+  캐시된 profile만 사용하는 Fast Path. 답변이 깨졌을 때만 1회 retry하는
+  Recovery Path 구조.
+
+### Auto knowledge graph curation
+
+- 새 모듈 `latticeai/core/graph_curator.py` — 대화/파일/작업 로그에서
+  Topic candidate 추출 → alias clustering(자동 병합) → promotion 결정
+  (secret 차단, 중복 차단, 출처 최소치) → 파생 이야기 엣지 → 행동 시그널
+  기반 큐레이션. Secret/API key/private key는 그래프 후보에서 자동 제거.
+
+### Frontend — user-trusted current model
+
+- `static/scripts/chat.js`의 `prepareAndLoadModel` 결과에서 백엔드
+  `response.current`를 신뢰하고, `ready_to_chat=false` 또는
+  `compatibility_status=degraded`일 때 사용자에게 호환성 경고 표시.
+- 모델 카드를 직접 클릭할 때도 같은 표준 흐름을 타는
+  `window.selectModelByCard()` 헬퍼 추가.
+
+### Admin — AI Security & Audit Command Center
+
+- 새 라우터 `latticeai/api/security_dashboard.py`가 11개 엔드포인트 추가:
+  `/admin/security/{overview,users,events,events/{id},conversations/{id},`
+  `conversations/{id}/raw,files,files/{id},files/{id}/content,raw,export}`.
+- 모든 응답에서 hard secret(`sk-…`, `ghp_…`, `xoxb-…`, `AKIA…`,
+  private key block 등)을 자동 redact. 원문/raw 조회는 별도
+  `admin_view_sensitive_raw` 감사 이벤트로 기록.
+- 관리자 UI: Security Overview 카드(오늘 이벤트, High Risk, 위험 채팅/파일,
+  Secret/외부 전송 차단, 관리자 원문 조회 수, 검토 필요), User Risk Matrix
+  (stacked bar), 민감정보 유형 donut chart, 민감 채팅/위험 파일 모니터,
+  감사 타임라인, Raw Data Explorer.
+- 사용자별 막대 클릭 → drill-down. JSON / CSV / XLSX / PDF / TXT
+  추출 지원.
+
+### Tests / CI
+
+- 새 단위 테스트 28개 — `tests/unit/test_model_compat.py`,
+  `tests/unit/test_model_resolution.py`, `tests/unit/test_graph_curator.py`,
+  `tests/unit/test_security_dashboard.py`.
+- `.github/workflows/ci.yml` syntax-check 단계에 4개 새 모듈 추가.
+- 새 `.github/workflows/release.yml` — tag `v*` 푸시 시 PyPI / npm /
+  VS Code Marketplace / Open VSX 자동 배포(필요 secrets: `PYPI_TOKEN`,
+  `NPM_TOKEN`, `VSCE_PAT`, `OVSX_TOKEN`). 해당 secret이 비어 있는 job은
+  자동 skip.
+
+### Fixed
+
+- FastAPI에서 `Request` 인자에 `= None` 디폴트 사용 시 발생하던 잠재 문제 수정
+  (`security_dashboard.py` `/admin/security/raw`).
+- `gpt-oss` family postprocess 순서를
+  `trim_after_user_marker → strip_role_tokens`로 보정 — `<|user|>` 마커가
+  먼저 제거돼 trim이 동작하지 않던 버그.
+
+## [0.3.0] - 2026-05-27
+
+### Knowledge Graph — LLM Structured Output Extraction
+
+- `_extract_concepts()` / `_extract_triples()`를 LLM 기반으로 전환 (rule-based 폴백 유지)
+- LLM Router 참조를 knowledge_graph에 주입하는 `set_llm_router()` 함수 추가
+- `LATTICEAI_LLM_EXTRACTION` 환경변수로 LLM extraction on/off 제어
+
+### Knowledge Graph — Hybrid Retrieval & Document Generation
+
+- `search_for_document_generation()` 추가 — Hybrid Score (0.5×text + 0.3×graph + 0.2×recency) 기반 검색
+- `multi_hop_context()` 추가 — Seed nodes에서 N-hop 그래프 탐색
+- `DOCUMENT` NodeType, `USED_IN` / `INSPIRED_BY` / `CONTRADICTS` / `EVOLVES_FROM` EdgeType 추가
+- Node에 `style`, `tone`, `importance_score`, `last_used` 필드 추가 (SQLite v2 스키마 반영)
+
+### 문서 자동 생성 파이프라인
+
+- `latticeai/core/context_builder.py` 신규 — Knowledge Graph → 구조화 Markdown Context 변환
+- `latticeai/core/document_generator.py` 신규 — Intent detection + 전용 System Prompt + Session 관리
+- `llm_router.py`에 `generate_document()` / `stream_generate_document()` 추가
+- `/chat` 엔드포인트에서 "보고서 작성해줘" 같은 문서 생성 의도 자동 감지 → 전용 파이프라인 활성화
+- 생성 문서에 참조 Knowledge Graph 노드 각주 자동 첨부
+- 대화별 `DocumentGenerationSession`으로 반복 수정("이 부분 더 수정해") 지원
+
+### UI/UX — 디자인 통일
+
+- Account/Chat/Graph/Admin 전체 페이지를 통일된 lavender purple 테마로 전환
+- 다크 모드 base 스타일 완전 제거 (`.app-layout` Obsidian dark, account dark base 등)
+- 초록 테마(`#22d3a0`) 60+ 인스턴스를 보라(`#6f42e8`) 계열로 교체
+- 메시지 버블: 다크 green → 보라 gradient(user), 밝은 lavender glass(AI)
+- 사이드바, 입력창, 버튼, 모달 오버레이 모두 라이트 lavender로 통일
+- 카드/패널에 hover lift 효과, 커스텀 스크롤바, focus ring, selection 색상 추가
+- tokens.css에 글로벌 polish (scrollbar, selection, focus-visible) 추가
+
+### 테스트
+
+- `test_document_generation.py` 33개 테스트 추가 (intent detection, session, extraction, hybrid retrieval, context builder, schema v2)
+
+### Release
+
+- 배포 버전을 `0.3.0`으로 상향
+- 대상 채널: `npm` · `PyPI` · `VS Code Marketplace` · `Open VSX`
+
 ## [0.2.2] - 2026-05-26
 
 ### 모델 카탈로그

package/kg_schema.py

@@ -81,6 +81,7 @@ class NodeType(str, Enum):
     CONVERSATION = "CONVERSATION"   # 대화 세션 전체
     MESSAGE      = "MESSAGE"        # 단일 발화
     FILE         = "FILE"           # 업로드/연결된 파일
+    DOCUMENT     = "DOCUMENT"       # 생성/관리되는 문서 (보고서, 계획서 등)
     CHUNK        = "CHUNK"          # 파일의 분할 청크
     CODE_SYMBOL  = "CODE_SYMBOL"    # 함수·클래스·모듈
     CONCEPT      = "CONCEPT"        # 추출된 개념 / 태그
@@ -110,6 +111,10 @@ class EdgeType(str, Enum):
     TAGGED_AS     = "TAGGED_AS"       # ANY → CONCEPT
     VERSION_OF    = "VERSION_OF"      # FILE → FILE (히스토리)
     GRANTS_ACCESS = "GRANTS_ACCESS"   # PERSON → RESOURCE
+    USED_IN       = "USED_IN"         # CONCEPT → DOCUMENT (문서에 활용됨)
+    INSPIRED_BY   = "INSPIRED_BY"     # DOCUMENT → DOCUMENT (영감/참조 관계)
+    CONTRADICTS   = "CONTRADICTS"     # DOCUMENT ↔ DOCUMENT (상충 관계)
+    EVOLVES_FROM  = "EVOLVES_FROM"    # DOCUMENT → DOCUMENT (발전/개정 관계)
 
     @classmethod
     def from_legacy(cls, label: str) -> "EdgeType":
@@ -140,6 +145,13 @@ _LEGACY_NODE_MAP: Dict[str, NodeType] = {
     "mcp":          NodeType.TOOL,
     "project":      NodeType.PROJECT,
     "workspace":    NodeType.PROJECT,
+    "document":     NodeType.DOCUMENT,
+    "report":       NodeType.DOCUMENT,
+    "plan":         NodeType.DOCUMENT,
+    "proposal":     NodeType.DOCUMENT,
+    "보고서":       NodeType.DOCUMENT,
+    "계획서":       NodeType.DOCUMENT,
+    "기획서":       NodeType.DOCUMENT,
 }
 
 _LEGACY_EDGE_MAP: Dict[str, EdgeType] = {
@@ -171,18 +183,27 @@ _LEGACY_EDGE_MAP: Dict[str, EdgeType] = {
     "tagged_as": EdgeType.TAGGED_AS,
     "version_of": EdgeType.VERSION_OF,
     "grants_access": EdgeType.GRANTS_ACCESS,
+    "used_in":       EdgeType.USED_IN,
+    "inspired_by":   EdgeType.INSPIRED_BY,
+    "contradicts":   EdgeType.CONTRADICTS,
+    "evolves_from":  EdgeType.EVOLVES_FROM,
+    "활용됨":        EdgeType.USED_IN,
+    "영감받음":      EdgeType.INSPIRED_BY,
+    "상충함":        EdgeType.CONTRADICTS,
+    "발전함":        EdgeType.EVOLVES_FROM,
 }
 
 # 노드 타입별로 허용되는 source / target 조합 (PPT 카탈로그 그대로)
 # None == 모든 타입 허용
 EDGE_ENDPOINT_RULES: Dict[EdgeType, Tuple[Optional[Sequence[NodeType]], Optional[Sequence[NodeType]]]] = {
-    EdgeType.CONTAINS:      ((NodeType.FILE,),            (NodeType.CHUNK,)),
-    EdgeType.MENTIONS:      ((NodeType.MESSAGE, NodeType.FILE, NodeType.CHUNK),
+    EdgeType.CONTAINS:      ((NodeType.FILE, NodeType.DOCUMENT),
+                             (NodeType.CHUNK,)),
+    EdgeType.MENTIONS:      ((NodeType.MESSAGE, NodeType.FILE, NodeType.CHUNK, NodeType.DOCUMENT),
                              (NodeType.CONCEPT, NodeType.PERSON, NodeType.MODEL, NodeType.TOOL)),
     EdgeType.REFERENCES:    ((NodeType.FILE, NodeType.MESSAGE, NodeType.CHUNK),
                              (NodeType.FILE, NodeType.MESSAGE, NodeType.CHUNK)),
     EdgeType.REPLIES_TO:    ((NodeType.MESSAGE,),         (NodeType.MESSAGE,)),
-    EdgeType.AUTHORED_BY:   ((NodeType.FILE, NodeType.MESSAGE, NodeType.CONVERSATION),
+    EdgeType.AUTHORED_BY:   ((NodeType.FILE, NodeType.MESSAGE, NodeType.CONVERSATION, NodeType.DOCUMENT),
                              (NodeType.PERSON,)),
     EdgeType.USES:          ((NodeType.PROJECT, NodeType.CONVERSATION),
                              (NodeType.TOOL, NodeType.MODEL)),
@@ -194,6 +215,14 @@ EDGE_ENDPOINT_RULES: Dict[EdgeType, Tuple[Optional[Sequence[NodeType]], Optional
     EdgeType.VERSION_OF:    ((NodeType.FILE,), (NodeType.FILE,)),
     EdgeType.GRANTS_ACCESS: ((NodeType.PERSON,),
                              (NodeType.FILE, NodeType.CONVERSATION, NodeType.PROJECT)),
+    EdgeType.USED_IN:       ((NodeType.CONCEPT,),
+                             (NodeType.DOCUMENT, NodeType.FILE)),
+    EdgeType.INSPIRED_BY:   ((NodeType.DOCUMENT, NodeType.FILE),
+                             (NodeType.DOCUMENT, NodeType.FILE)),
+    EdgeType.CONTRADICTS:   ((NodeType.DOCUMENT, NodeType.FILE),
+                             (NodeType.DOCUMENT, NodeType.FILE)),
+    EdgeType.EVOLVES_FROM:  ((NodeType.DOCUMENT, NodeType.FILE),
+                             (NodeType.DOCUMENT, NodeType.FILE)),
 }
 
 
@@ -262,6 +291,10 @@ class Node:
     visibility: Visibility = Visibility.PRIVATE
     created_at: str = field(default_factory=_now_iso)
     updated_at: str = field(default_factory=_now_iso)
+    style: Optional[str] = None
+    tone: Optional[str] = None
+    importance_score: float = 0.0
+    last_used: Optional[str] = None
 
     def validate(self) -> None:
         if not isinstance(self.type, NodeType):
@@ -345,15 +378,19 @@ CREATE TABLE IF NOT EXISTS kg_meta (
 );
 
 CREATE TABLE IF NOT EXISTS nodes_v2 (
-  id          TEXT PRIMARY KEY,
-  type        TEXT NOT NULL,
-  label       TEXT NOT NULL,
-  attrs       TEXT NOT NULL DEFAULT '{}',
-  embedding   BLOB,
-  owner_id    TEXT,
-  visibility  TEXT NOT NULL DEFAULT 'private',
-  created_at  TEXT NOT NULL,
-  updated_at  TEXT NOT NULL
+  id               TEXT PRIMARY KEY,
+  type             TEXT NOT NULL,
+  label            TEXT NOT NULL,
+  attrs            TEXT NOT NULL DEFAULT '{}',
+  embedding        BLOB,
+  owner_id         TEXT,
+  visibility       TEXT NOT NULL DEFAULT 'private',
+  created_at       TEXT NOT NULL,
+  updated_at       TEXT NOT NULL,
+  style            TEXT,
+  tone             TEXT,
+  importance_score REAL NOT NULL DEFAULT 0.0,
+  last_used        TEXT
 );
 
 CREATE TABLE IF NOT EXISTS edges_v2 (
@@ -418,8 +455,9 @@ class KGStoreV2:
             conn.execute(
                 """
                 INSERT INTO nodes_v2(id, type, label, attrs, embedding,
-                                     owner_id, visibility, created_at, updated_at)
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                                     owner_id, visibility, created_at, updated_at,
+                                     style, tone, importance_score, last_used)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                 ON CONFLICT(id) DO UPDATE SET
                   type=excluded.type,
                   label=excluded.label,
@@ -427,7 +465,11 @@ class KGStoreV2:
                   embedding=COALESCE(excluded.embedding, nodes_v2.embedding),
                   owner_id=excluded.owner_id,
                   visibility=excluded.visibility,
-                  updated_at=excluded.updated_at
+                  updated_at=excluded.updated_at,
+                  style=COALESCE(excluded.style, nodes_v2.style),
+                  tone=COALESCE(excluded.tone, nodes_v2.tone),
+                  importance_score=MAX(excluded.importance_score, nodes_v2.importance_score),
+                  last_used=COALESCE(excluded.last_used, nodes_v2.last_used)
                 """,
                 (
                     node.id, node.type.value, node.label,
@@ -435,6 +477,8 @@ class KGStoreV2:
                     encode_embedding(node.embedding),
                     node.owner_id, node.visibility.value,
                     node.created_at, node.updated_at,
+                    node.style, node.tone,
+                    float(node.importance_score), node.last_used,
                 ),
             )
         return node.id
@@ -575,6 +619,7 @@ class KGStoreV2:
 
 # ── Row → model helpers ────────────────────────────────────────────────────
 def _row_to_node(row: sqlite3.Row) -> Node:
+    keys = row.keys() if hasattr(row, "keys") else []
     return Node(
         id=row["id"],
         type=NodeType(row["type"]),
@@ -585,6 +630,10 @@ def _row_to_node(row: sqlite3.Row) -> Node:
         visibility=Visibility(row["visibility"]),
         created_at=row["created_at"],
         updated_at=row["updated_at"],
+        style=row["style"] if "style" in keys else None,
+        tone=row["tone"] if "tone" in keys else None,
+        importance_score=float(row["importance_score"]) if "importance_score" in keys else 0.0,
+        last_used=row["last_used"] if "last_used" in keys else None,
     )
 
 

package/knowledge_graph.py

@@ -6,6 +6,7 @@ portable database so it can later migrate to Neo4j/Postgres without changing
 the ingestion contract.
 """
 
+import asyncio
 import hashlib
 import json
 import logging
@@ -26,6 +27,12 @@ try:
 except Exception:  # pragma: no cover - v2 schema is optional at import time
     KGStoreV2 = None  # type: ignore[assignment]
 
+_llm_router_ref = None
+
+def set_llm_router(router_instance):
+    global _llm_router_ref
+    _llm_router_ref = router_instance
+
 
 GRAPH_SCHEMA_VERSION = 1
 
@@ -365,6 +372,109 @@ def _chunks(text: str, size: int = 1200, overlap: int = 160) -> List[str]:
     return chunks
 
 
+_LLM_EXTRACT_CONCEPT_PROMPT = """Extract the key concepts from the following text.
+Return ONLY a JSON array of objects, each with "concept" (string) and "importance" (float 0-1).
+Extract up to {limit} concepts. Focus on named entities, technical terms, and domain-specific nouns.
+Do NOT include common words, stop words, or generic terms.
+
+Text:
+{text}
+
+JSON:"""
+
+_LLM_EXTRACT_TRIPLE_PROMPT = """Extract relationship triples from the following text.
+Return ONLY a JSON array of objects, each with:
+- "subject": source concept (string)
+- "relation": relationship verb (string, Korean or English)
+- "object": target concept (string)
+- "evidence": the sentence supporting this triple (string, max 240 chars)
+- "confidence": how confident you are (float 0-1)
+
+Extract up to {limit} triples. Focus on meaningful semantic relationships.
+
+Text:
+{text}
+
+Concepts already identified: {concepts}
+
+JSON:"""
+
+ENABLE_LLM_EXTRACTION = os.getenv("LATTICEAI_LLM_EXTRACTION", "true").lower() in ("1", "true", "yes")
+
+
+def _llm_extract_concepts(text: str, limit: int = 12) -> Optional[List[str]]:
+    if not ENABLE_LLM_EXTRACTION or not _llm_router_ref:
+        return None
+    if not _llm_router_ref.current_model_id:
+        return None
+    prompt = _LLM_EXTRACT_CONCEPT_PROMPT.format(text=text[:3000], limit=limit)
+    try:
+        loop = asyncio.get_event_loop()
+        if loop.is_running():
+            import concurrent.futures
+            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+                future = pool.submit(asyncio.run, _llm_router_ref.generate(prompt, max_tokens=1024, temperature=0.1))
+                raw = future.result(timeout=30)
+        else:
+            raw = asyncio.run(_llm_router_ref.generate(prompt, max_tokens=1024, temperature=0.1))
+        raw = raw.strip()
+        if raw.startswith("```"):
+            raw = re.sub(r"^```(?:json)?\s*", "", raw)
+            raw = re.sub(r"\s*```$", "", raw)
+        parsed = json.loads(raw)
+        if isinstance(parsed, list):
+            concepts = []
+            for item in parsed[:limit]:
+                if isinstance(item, dict) and "concept" in item:
+                    concepts.append(item["concept"])
+                elif isinstance(item, str):
+                    concepts.append(item)
+            return concepts if concepts else None
+    except Exception as e:
+        logging.debug("LLM concept extraction failed (falling back to rules): %s", e)
+    return None
+
+
+def _llm_extract_triples(text: str, concepts: List[str], limit: int = 20) -> Optional[List[Dict[str, str]]]:
+    if not ENABLE_LLM_EXTRACTION or not _llm_router_ref:
+        return None
+    if not _llm_router_ref.current_model_id:
+        return None
+    prompt = _LLM_EXTRACT_TRIPLE_PROMPT.format(
+        text=text[:3000], limit=limit,
+        concepts=", ".join(concepts[:15]),
+    )
+    try:
+        loop = asyncio.get_event_loop()
+        if loop.is_running():
+            import concurrent.futures
+            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+                future = pool.submit(asyncio.run, _llm_router_ref.generate(prompt, max_tokens=2048, temperature=0.1))
+                raw = future.result(timeout=30)
+        else:
+            raw = asyncio.run(_llm_router_ref.generate(prompt, max_tokens=2048, temperature=0.1))
+        raw = raw.strip()
+        if raw.startswith("```"):
+            raw = re.sub(r"^```(?:json)?\s*", "", raw)
+            raw = re.sub(r"\s*```$", "", raw)
+        parsed = json.loads(raw)
+        if isinstance(parsed, list):
+            triples = []
+            for item in parsed[:limit]:
+                if isinstance(item, dict) and "subject" in item and "object" in item:
+                    triples.append({
+                        "subject": str(item["subject"]),
+                        "relation": str(item.get("relation", "관련됨")),
+                        "object": str(item["object"]),
+                        "context": str(item.get("evidence", ""))[:240],
+                        "confidence": float(item.get("confidence", 0.8)),
+                    })
+            return triples if triples else None
+    except Exception as e:
+        logging.debug("LLM triple extraction failed (falling back to rules): %s", e)
+    return None
+
+
 _CONCEPT_STOP: set = {
     # English stop words
     "the", "and", "for", "with", "this", "that", "from", "into", "which",
@@ -385,7 +495,15 @@ _CONCEPT_STOP: set = {
 
 
 def _extract_concepts(text: str, limit: int = 12) -> List[str]:
-    """Extract meaningful named concepts from text.
+    """LLM-first concept extraction with rule-based fallback."""
+    llm_result = _llm_extract_concepts(text, limit)
+    if llm_result:
+        return llm_result
+    return _extract_concepts_rules(text, limit)
+
+
+def _extract_concepts_rules(text: str, limit: int = 12) -> List[str]:
+    """Extract meaningful named concepts from text (rule-based).
 
     Priority order:
     1. Backtick / quoted terms (explicitly technical)
@@ -586,7 +704,19 @@ def _extract_triples(
     concepts: List[str],
     limit: int = 20,
 ) -> List[Dict[str, str]]:
-    """Extract (subject, verb-edge, object, context) triples from text.
+    """LLM-first triple extraction with rule-based fallback."""
+    llm_result = _llm_extract_triples(text, concepts, limit)
+    if llm_result:
+        return llm_result
+    return _extract_triples_rules(text, concepts, limit)
+
+
+def _extract_triples_rules(
+    text: str,
+    concepts: List[str],
+    limit: int = 20,
+) -> List[Dict[str, str]]:
+    """Extract (subject, verb-edge, object, context) triples from text (rule-based).
 
     For each sentence containing ≥2 concepts, infer the verb-form edge label
     from surrounding context and create a directed triple.
@@ -2810,3 +2940,170 @@ class KnowledgeGraphStore:
             "local_file_status": local_file_status,
             "v2": v2,
         }
+
+    def search_for_document_generation(self, query: str, limit: int = 10) -> List[Dict[str, Any]]:
+        """Hybrid retrieval optimized for document generation.
+
+        Scoring: 0.5*text_relevance + 0.3*graph_relationship + 0.2*recency
+        Returns nodes with rich context for document generation prompts.
+        """
+        query = str(query or "").strip()
+        if not query:
+            return []
+        limit = max(1, min(int(limit or 10), 50))
+        terms = _topic_candidates(query, limit=12)
+        now = datetime.now()
+
+        with self._connect() as conn:
+            candidate_rows = []
+            seen_ids = set()
+
+            if query:
+                q = f"%{query}%"
+                rows = conn.execute(
+                    """
+                    SELECT id, type, title, summary, metadata_json, updated_at
+                    FROM nodes
+                    WHERE (title LIKE ? OR summary LIKE ? OR metadata_json LIKE ?)
+                      AND type IN ('Document', 'File', 'CodeFile', 'SlideDeck',
+                                   'Spreadsheet', 'Image', 'ImageText', 'Chat',
+                                   'Decision', 'Task', 'Concept', 'Feature',
+                                   'Page', 'Slide')
+                    ORDER BY updated_at DESC
+                    LIMIT ?
+                    """,
+                    (q, q, q, limit * 5),
+                ).fetchall()
+                for row in rows:
+                    if row["id"] not in seen_ids:
+                        seen_ids.add(row["id"])
+                        candidate_rows.append(row)
+
+            for term in terms:
+                t = f"%{term}%"
+                rows = conn.execute(
+                    """
+                    SELECT id, type, title, summary, metadata_json, updated_at
+                    FROM nodes
+                    WHERE (title LIKE ? OR summary LIKE ? OR metadata_json LIKE ?)
+                      AND type IN ('Document', 'File', 'CodeFile', 'SlideDeck',
+                                   'Spreadsheet', 'Image', 'ImageText', 'Chat',
+                                   'Decision', 'Task', 'Concept', 'Feature',
+                                   'Page', 'Slide')
+                    ORDER BY updated_at DESC
+                    LIMIT ?
+                    """,
+                    (t, t, t, limit * 3),
+                ).fetchall()
+                for row in rows:
+                    if row["id"] not in seen_ids:
+                        seen_ids.add(row["id"])
+                        candidate_rows.append(row)
+
+            scored_results = []
+            for row in candidate_rows:
+                haystack = f"{row['title']} {row['summary']} {row['metadata_json']}".lower()
+
+                text_hits = sum(1 for term in terms if term.lower() in haystack)
+                text_score = min(1.0, text_hits / max(len(terms), 1))
+
+                edge_count = conn.execute(
+                    "SELECT COUNT(*) AS c FROM edges WHERE from_node=? OR to_node=?",
+                    (row["id"], row["id"]),
+                ).fetchone()["c"]
+                graph_score = min(1.0, math.log1p(edge_count) / 4.0)
+
+                recency = _recency_score(row["updated_at"], now=now, half_life_days=14.0)
+
+                doc_type_boost = 1.2 if row["type"] in (
+                    "Document", "File", "SlideDeck", "Decision",
+                ) else 1.0
+
+                hybrid_score = (
+                    0.5 * text_score
+                    + 0.3 * graph_score
+                    + 0.2 * recency
+                ) * doc_type_boost
+
+                meta = _safe_loads(row["metadata_json"])
+                neighbor_concepts = []
+                neighbor_rows = conn.execute(
+                    """
+                    SELECT n.title, n.type FROM edges e
+                    JOIN nodes n ON n.id = CASE WHEN e.from_node = ? THEN e.to_node ELSE e.from_node END
+                    WHERE (e.from_node = ? OR e.to_node = ?)
+                      AND n.type IN ('Concept', 'Feature', 'Decision', 'Task')
+                    LIMIT 8
+                    """,
+                    (row["id"], row["id"], row["id"]),
+                ).fetchall()
+                for nr in neighbor_rows:
+                    neighbor_concepts.append({"title": nr["title"], "type": nr["type"]})
+
+                scored_results.append({
+                    "id": row["id"],
+                    "type": row["type"],
+                    "title": row["title"],
+                    "summary": row["summary"],
+                    "metadata": meta,
+                    "updated_at": row["updated_at"],
+                    "hybrid_score": round(hybrid_score, 4),
+                    "scores": {
+                        "text": round(text_score, 4),
+                        "graph": round(graph_score, 4),
+                        "recency": round(recency, 4),
+                    },
+                    "related_concepts": neighbor_concepts,
+                })
+
+            scored_results.sort(key=lambda x: x["hybrid_score"], reverse=True)
+            return scored_results[:limit]
+
+    def multi_hop_context(self, node_ids: List[str], max_hops: int = 2) -> Dict[str, Any]:
+        """Multi-hop graph traversal from seed nodes for richer context."""
+        visited_nodes = set()
+        visited_edges = set()
+        all_nodes = []
+        all_edges = []
+        frontier = set(node_ids)
+
+        with self._connect() as conn:
+            for hop in range(max_hops):
+                if not frontier:
+                    break
+                next_frontier = set()
+                for nid in frontier:
+                    if nid in visited_nodes:
+                        continue
+                    visited_nodes.add(nid)
+                    row = conn.execute(
+                        "SELECT id, type, title, summary, metadata_json, updated_at FROM nodes WHERE id=?",
+                        (nid,),
+                    ).fetchone()
+                    if row:
+                        all_nodes.append({
+                            "id": row["id"], "type": row["type"],
+                            "title": row["title"], "summary": row["summary"],
+                            "metadata": _safe_loads(row["metadata_json"]),
+                            "hop": hop,
+                        })
+                    edge_rows = conn.execute(
+                        """
+                        SELECT id, from_node, to_node, type, weight
+                        FROM edges WHERE from_node=? OR to_node=?
+                        """,
+                        (nid, nid),
+                    ).fetchall()
+                    for er in edge_rows:
+                        if er["id"] not in visited_edges:
+                            visited_edges.add(er["id"])
+                            all_edges.append({
+                                "from": er["from_node"], "to": er["to_node"],
+                                "type": er["type"], "weight": er["weight"],
+                            })
+                            other = er["to_node"] if er["from_node"] == nid else er["from_node"]
+                            if other not in visited_nodes:
+                                next_frontier.add(other)
+                frontier = next_frontier
+
+        return {"nodes": all_nodes, "edges": all_edges}