ltcai 9.6.0 → 9.7.0

package/README.md

@@ -132,21 +132,21 @@ confirm owner, check the computer, choose the Brain voice.
 Choose the owner of the Brain. The profile is not a SaaS account by default; it
 is the local identity for the knowledge you keep.
 
-![Login](output/release/v9.6.0/screenshots/01-login.png)
+![Login](output/release/v9.7.0/screenshots/01-login.png)
 
 ### 3. Recommended Models
 
 Start with a short list: safest recommendation, faster model, stronger model.
 Advanced details stay available without overwhelming first-time users.
 
-![Recommended Models](output/release/v9.6.0/screenshots/02-recommended-models.png)
+![Recommended Models](output/release/v9.7.0/screenshots/02-recommended-models.png)
 
 ### 4. Install And Load
 
 Download and load only after consent. Lattice explains model size, local
 execution, and network use before work starts.
 
-![Install and Load](output/release/v9.6.0/screenshots/03-install-load-progress.png)
+![Install and Load](output/release/v9.7.0/screenshots/03-install-load-progress.png)
 
 ### 5. Brain Chat
 
@@ -158,14 +158,14 @@ and its visible life signal follow real listening, recall, synthesis, and action
 state. Detailed memory rings, provenance, conversation history, and
 model/runtime proof open as overlays only when requested.
 
-![One-viewport Living Brain Home](output/release/v9.6.0/screenshots/04-brain-chat-home.png)
+![One-viewport Living Brain Home](output/release/v9.7.0/screenshots/04-brain-chat-home.png)
 
 ### 6. Review Center
 
 Automation results are staged for review before they become durable decisions.
 Snooze, unsnooze, run now, approve, and dismiss actions stay explicit.
 
-![Review Center](output/release/v9.6.0/screenshots/12-review-center.png)
+![Review Center](output/release/v9.7.0/screenshots/12-review-center.png)
 
 ## Brain Depths
 
@@ -181,10 +181,10 @@ The user travels inward from everyday memory to deeper structure:
 
 Walkthrough:
 
-![v9.6.0 Living Brain walkthrough](output/release/v9.6.0/gifs/v9.6.0-living-brain-walkthrough.gif)
+![v9.7.0 Living Brain walkthrough](output/release/v9.7.0/gifs/v9.7.0-living-brain-walkthrough.gif)
 
 Screenshot index and capture notes:
-[output/release/v9.6.0/SCREENSHOT_INDEX.md](output/release/v9.6.0/SCREENSHOT_INDEX.md)
+[output/release/v9.7.0/SCREENSHOT_INDEX.md](output/release/v9.7.0/SCREENSHOT_INDEX.md)
 
 ## Install
 
@@ -269,50 +269,59 @@ See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for developer workflow details.
 
 ## Current Release
 
-The current release is **9.6.0 — Trusted Agent Loop**:
-
-- The single-agent reasoning loop is fully observable: a structured
-  `LoopTrace` records every llm call, parse error (recovered or not), format
-  repair, correction, tool outcome, retry, and rollback, and its summary is
-  returned as `loop` with every agent API response.
-- Weak-model robustness is stronger and measured: the action parser now also
-  repairs Python-literal dicts (single quotes, True/False/None), repairs are
-  reported by name, and a second formatting slip escalates the correction
-  with the exact list of valid tools.
-- A deterministic agent evaluation harness (`scripts/agent_eval.py`, CI
-  gate) drives the real state machine through scripted scenarios — happy
-  path, weak-model format gauntlet, correction escalation, destructive
-  block, loop detection, critic retry, unrecoverable garbage — and must stay
-  at 100% scenario pass.
-- Change governance is proposal-first (`latticeai/core/tool_governor.py`):
-  additive creates run with minimal friction, while agent edits/deletions of
-  existing files are staged as review proposals with a unified diff and a
-  small/large tier, listed at `GET /api/proposals`, applied exactly as
-  reviewed on approve, discarded on reject. The Brain home shows a
-  "변경 제안 / Change proposals" panel with diff previews and one-click
-  approve/reject.
-- Housekeeping: Ruff per-file lint ignores trimmed from 9 entries to 3,
-  AGENTS.md now carries a machine-checked current-release marker inside the
-  docs gate, and the review queue gained the `change_proposal` source.
-
-Expected artifacts for 9.6.0 release must use exact filenames:
-
-- `dist/ltcai-9.6.0-py3-none-any.whl`
-- `dist/ltcai-9.6.0.tar.gz`
-- `ltcai-9.6.0.tgz`
-- `dist/ltcai-9.6.0.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_9.6.0_aarch64.dmg`
+The current release is **9.7.0 — Proactive Hybrid Brain**:
+
+- Retrieval is unified: `KnowledgeGraphStore.hybrid_search()` fuses lexical
+  and vector search in the graph layer itself (normalized scores, per-source
+  provenance, rank fusion), degrades honestly to `lexical_only` when the
+  vector index is unavailable, and `context_for_query()` can opt into it.
+- The vector index stays in sync automatically: every successful ingest runs
+  an incremental `index_node_incremental()` pass (opt-out via
+  `LATTICEAI_AUTO_VECTOR_INDEX`), and failures downgrade to an explicit
+  `pending` status that the next `rebuild_vector_index` picks up.
+- Ingestion covers whole folders: `ingest_folder()` walks directories with
+  `.latticeignore` support (gitignore-like globs), size/extension filters,
+  and optional background scheduling; `ingest_web_page()` formalizes the
+  web seam — fetching/parsing stays upstream, the graph receives clean text.
+- The Brain is proactive in the graph layer: `lattice_brain/graph/proactive.py`
+  finds duplicate and contradictory knowledge, produces a combined quality
+  report with stale-node and edge-quality signals, and plans consent-first
+  duplicate consolidation — surfaced at `GET /api/brain/duplicates`,
+  `GET /api/brain/quality-report`, and the existing contradiction/consolidate
+  endpoints.
+- The change-governance loop is closed: Review Center approval now applies
+  staged proposals through the single application path (no more
+  status-only approvals), proposals carry tool/risk/change-class/conversation
+  provenance, reject records a reason, and pending-proposal counts badge the
+  review inbox.
+- The agent evaluation gate grew to 12 scenarios, adding file-generation
+  happy path and recovery, a 3-step multi-step workflow chain, and a
+  governed-write proposal path that pins the approve()-excludes-governed-tools
+  invariant.
+- Engineering health: `SingleAgentRuntime.execute` decomposed into focused
+  helpers, multi-agent/single-agent runtime consistency pinned by tests, all
+  root legacy modules emit deprecation warnings pointing at their package
+  homes, and `scripts/profile_kg.py` + `docs/PERFORMANCE.md` establish a
+  measured KG performance baseline.
+
+Expected artifacts for 9.7.0 release must use exact filenames:
+
+- `dist/ltcai-9.7.0-py3-none-any.whl`
+- `dist/ltcai-9.7.0.tar.gz`
+- `ltcai-9.7.0.tgz`
+- `dist/ltcai-9.7.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_9.7.0_aarch64.dmg`
 
 Do not use wildcard artifact uploads. Package registry publishing remains owner-run.
 
 See [docs/ROADMAP_RECOMMENDATIONS.md](docs/ROADMAP_RECOMMENDATIONS.md) for the
-strategic roadmap slices applied through 9.6.0 and the follow-up tracks.
+strategic roadmap slices applied through 9.7.0 and the follow-up tracks.
 
 ## Known Limitations
 
 - External package registries are owner-published and can lag behind GitHub.
 - PostgreSQL/pgvector is optional scale/migration tooling. SQLite remains the
-  live local Brain store in 9.6.0.
+  live local Brain store in 9.7.0.
 - Docker, model downloads, cloud model calls, Telegram, Brain Network, and update
   checks require explicit user action.
 - Conversation does not fabricate answers when no model is loaded.
@@ -324,6 +333,7 @@ strategic roadmap slices applied through 9.6.0 and the follow-up tracks.
 
 | Version | Theme |
 | --- | --- |
+| 9.7.0 | Proactive Hybrid Brain: graph-native hybrid lexical+vector retrieval with automatic incremental vector indexing, folder ingestion with `.latticeignore`, proactive duplicate/contradiction detection and quality reporting in the graph layer, and a fully closed proposal→Review Center→apply governance loop |
 | 9.6.0 | Trusted Agent Loop: observable agent reasoning (LoopTrace + loop API payload), python-literal/fence/think weak-model repairs with escalating corrections, a deterministic CI agent-eval harness, and proposal-first change governance where edits/deletions of existing files become reviewable diffs |
 | 9.5.0 | Command Center: a Cmd+K palette searching knowledge, conversations, automations, and pages in one query, plus a daily briefing with Brain state at a glance and state-derived one-click quick actions |
 | 9.4.0 | Question-Driven Everyday Automation: the Brain mines recurring user questions and connected knowledge folders into one-click, consent-first automation suggestions installed as review-gated drafts |

package/auto_setup.py

@@ -1,6 +1,16 @@
 """Compatibility shim for :mod:`latticeai.setup.auto_setup`."""
 
-from latticeai.setup import auto_setup as _impl
+import warnings
+
+warnings.warn(
+    "Importing 'auto_setup' from the repository root is deprecated; "
+    "use 'from latticeai.setup import auto_setup' instead. "
+    "The root shim will be removed in a future major release.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from latticeai.setup import auto_setup as _impl  # noqa: E402
 
 
 if __name__ == "__main__":

package/docs/CHANGELOG.md

@@ -4,6 +4,60 @@ The top entry is either the current unreleased main-branch work or the current
 release line. Older entries are historical and may describe behavior as it
 existed at that release.
 
+## [9.7.0] - 2026-07-20
+
+### Added
+- Added `KnowledgeGraphStore.hybrid_search()`: graph-native fusion of
+  lexical and vector retrieval with normalized scores, per-source
+  provenance, chunk→parent roll-up, workspace scoping, and an honest
+  `lexical_only` fallback; `context_for_query()` gains an opt-in
+  `use_hybrid` flag.
+- Added `index_node_incremental()` and automatic post-ingest vector-index
+  sync in `IngestionPipeline` (opt-out `LATTICEAI_AUTO_VECTOR_INDEX`);
+  vector failures downgrade to `indexing_status: pending` instead of
+  failing the ingest.
+- Added `IngestionPipeline.ingest_folder()` (recursive walk,
+  `.latticeignore` gitignore-like filtering, size/extension limits,
+  optional background queue) and `ingest_web_page()` (formalized
+  extracted-text web seam; fetching/parsing stays upstream).
+- Added `lattice_brain/graph/proactive.py` (`ProactiveBrain`): duplicate
+  detection, contradiction detection, combined `quality_report()`,
+  consent-first `consolidate_duplicates()` planning, and the pure
+  `gate_ingest_candidate()` quality-gating seam.
+- Added `GET /api/brain/duplicates` and `GET /api/brain/quality-report`;
+  `/api/brain/contradictions` and `/api/brain/consolidate` return
+  graph-layer results additively.
+- Added `GET /api/proposals/counts`, `GET /api/proposals/{id}` (diff +
+  staged content), reject-with-reason, and
+  `GET /automation/reviews/counts`; the Review Center UI gains a
+  `change_proposal` filter, diff preview, tier/deletion badges, a
+  pending-count badge, and a reject-reason input (ko/en parity).
+- Added 4 agent-eval scenarios (12 total): file-generation happy path,
+  file-generation recovery, multi-step workflow chain, and a
+  governed-write proposal path pinning the
+  approve()-excludes-governed-tools invariant.
+- Added `tests/unit/test_runtime_consistency.py`,
+  `scripts/profile_kg.py`, and `docs/PERFORMANCE.md` (measured synthetic
+  KG baseline; flags brute-force `vector_search()` as the next
+  optimization target).
+
+### Changed
+- Review Center approval of `change_proposal` items now applies the staged
+  content through `ChangeProposalService.approve_and_apply` (single
+  application path, 409 on replay) instead of only flipping status.
+- Change proposals carry tool/risk/change-class/conversation-id
+  provenance; the agent loop forwards `conversation_id` to the governor.
+- `SingleAgentRuntime.execute` decomposed into six focused helpers
+  (behavior-preserving); the multi-agent orchestrator surfaces real
+  failure reasons in `execution_failed` timeline events.
+- All root legacy modules emit `DeprecationWarning` pointing at their
+  package homes; the legacy-compatibility registry tracks all 13 shims.
+
+### Security
+- Proposal apply/reject stays fail-closed end-to-end: approval applies
+  exactly the reviewed staged content, replays are rejected with 409, and
+  reject reasons land in provenance for audit.
+
 ## [9.6.0] - 2026-07-20
 
 ### Added

package/docs/COMMUNITY_AND_PLUGINS.md

@@ -1,6 +1,6 @@
 # Community And Plugins
 
-Current release: **9.6.0 — Trusted Agent Loop**.
+Current release: **9.7.0 — Proactive Hybrid Brain**.
 
 LatticeAI defines the path from a strong local-first framework (8.4.0
 action-aware baseline, 8.5.0 registry+DI hardening, 8.6.0 capture/navigation

package/docs/DEVELOPMENT.md

@@ -1,6 +1,6 @@
 # Lattice AI Development
 
-Current release: **9.6.0 — Trusted Agent Loop**.
+Current release: **9.7.0 — Proactive Hybrid Brain**.
 
 This document is for contributors working on the local-first Digital Brain
 codebase. Product positioning and quick start stay in `README.md`; release

package/docs/ONBOARDING.md

@@ -1,6 +1,6 @@
 # Lattice AI Onboarding
 
-Current release: **9.6.0 — Trusted Agent Loop**.
+Current release: **9.7.0 — Proactive Hybrid Brain**.
 
 The first-run goal is a five-minute path from "I opened the app" to "my Brain
 has a source, a question, and proof." This page is the product contract behind

package/docs/PERFORMANCE.md

@@ -0,0 +1,106 @@
+# Knowledge Graph Performance Baseline
+
+Synthetic performance and memory baseline for `KnowledgeGraphStore`
+(`lattice_brain/graph/`). Measured with `scripts/profile_kg.py`.
+
+**This is a synthetic baseline, not a real-workload benchmark.** Use it for
+release-over-release regression comparison, not as a marketing number.
+
+## Methodology
+
+- `scripts/profile_kg.py` builds a throwaway store the same way the unit tests
+  do (`KnowledgeGraphStore(tmp/graph.sqlite, tmp/blobs)`) and ingests N
+  synthetic text sources through the real `ingest_source()` pipeline
+  (chunking, rule-based concept/triple extraction, provenance edges).
+- Corpus: fixed-vocabulary English + Korean text, seeded RNG (`--seed`,
+  default 42), ~60% short (~40 words) / 30% medium (~160) / 10% long (~520)
+  documents with recurring entities so concept nodes are shared and edges form.
+- Fully offline: no LLM router is registered (extraction takes the rules
+  path) and the embedder is the built-in deterministic hash model. No network,
+  no model downloads.
+- Timing: `time.perf_counter()` per call; p50/p95/mean over all calls in a
+  phase. Memory: `tracemalloc` peak, reset per phase.
+- Caveat: tracemalloc runs for the whole profile and roughly doubles Python
+  allocation cost, so absolute timings are conservative upper bounds.
+- Caveat: the synthetic vocabulary is small, so FTS selectivity and concept
+  density differ from real user data; every tenth query is a guaranteed miss
+  to avoid measuring only warm hits.
+
+Run it:
+
+```bash
+.venv/bin/python scripts/profile_kg.py                 # 5000 sources, 50 queries
+.venv/bin/python scripts/profile_kg.py --nodes 500     # quick run (~10 s)
+.venv/bin/python scripts/profile_kg.py --json          # machine-readable
+```
+
+## Measured baseline (2026-07-20, v9.6.0 working tree)
+
+Apple Silicon (darwin), Python 3.x from `.venv`, SQLite with FTS5 trigram
+available, tracemalloc enabled.
+
+### 500 sources (quick profile, ~9 s total)
+
+Graph produced: 2,019 nodes / 6,546 edges, 21.2 MB SQLite file.
+
+| phase                | calls | p50 ms | p95 ms | wall s | peak MB |
+|----------------------|------:|-------:|-------:|-------:|--------:|
+| ingest_source        |   500 |   6.9  |  17.7  |   4.1  |   0.6   |
+| search               |    50 |   1.2  |   2.5  |   0.07 |   0.6   |
+| context_for_query    |    50 |   1.0  |   2.4  |   0.06 |   0.5   |
+| neighbors            |    50 |   0.35 |   0.45 |   0.02 |   0.6   |
+| traverse (depth 2)   |    50 |   4.8  |   5.2  |   0.24 |   1.1   |
+| stats                |     5 |   1.5  |   1.7  |   0.01 |   0.4   |
+| rebuild_vector_index |     1 |  1319  |  1319  |   1.3  |   5.0   |
+| vector_search        |    10 |  287   |  294   |   2.9  |  14.4   |
+
+Ingestion throughput: **~122 items/sec** (412 KB corpus).
+
+### 5000 sources (default profile, ~2.5 min total)
+
+Graph produced: 18,426 nodes / 62,534 edges, 198.8 MB SQLite file
+(4.26 MB corpus). Measured while other processes shared the CPU, so treat as
+an upper bound.
+
+| phase                | calls | p50 ms | p95 ms | wall s | peak MB |
+|----------------------|------:|-------:|-------:|-------:|--------:|
+| ingest_source        |  5000 |  20.1  |  54.6  | 119.9  |   1.4   |
+| search               |    50 |   4.3  |  19.8  |   0.40 |   1.2   |
+| context_for_query    |    50 |   4.1  |  18.5  |   0.40 |   1.2   |
+| neighbors            |    50 |   0.39 |   0.50 |   0.03 |   1.2   |
+| traverse (depth 2)   |    50 |  12.2  |  15.8  |   0.64 |   1.7   |
+| stats                |     5 |  13.1  |  13.5  |   0.07 |   1.1   |
+| rebuild_vector_index |     1 | 14624  | 14624  |  14.6  |  45.6   |
+| vector_search        |    10 |  1732  |  1774  |  17.4  |  83.5   |
+
+Ingestion throughput: **~42 items/sec** at this scale.
+
+Scaling signal (500 → 5000 sources, 10x): per-item ingest p50 grew ~3x
+(6.9 ms → 20.1 ms) — ingestion cost is superlinear in DB size (FTS triggers,
+dedup lookups, edge upserts against growing tables). `vector_search` p50 grew
+~6x (287 ms → 1732 ms), consistent with its O(index size) brute-force scan.
+Keyword search p50 grew ~3.6x but stays under 5 ms.
+
+Regenerate with `.venv/bin/python scripts/profile_kg.py` after graph-layer
+changes and compare against these tables.
+
+## Observations
+
+- Keyword `search()` / `context_for_query()` stay low-millisecond thanks to
+  the FTS5 trigram index; they are not the scaling bottleneck.
+- `traverse(depth=2)` cost grows with edge fan-out (synthetic corpus creates
+  dense shared-concept hubs); p95 is ~5 ms at 500 sources and ~16 ms at 5000.
+- `vector_search()` is a brute-force scan over every stored embedding
+  (O(index size) per query). It is the dominant cost at scale and the first
+  candidate for an ANN/pruning optimization if vector recall becomes a hot
+  path. The profiler caps vector queries at 10 for this reason.
+- `rebuild_vector_index(full=True)` embeds documents and chunks with the hash
+  embedder; with a real embedding provider expect this phase to be slower by
+  the provider's per-call latency times the item count.
+
+## Regression workflow
+
+1. Before a graph-layer change: `.venv/bin/python scripts/profile_kg.py --nodes 500 --json > /tmp/kg-before.json`
+2. After the change: same command to `/tmp/kg-after.json`.
+3. Compare phase p50/p95 and `db_size_mb`; investigate anything that moved
+   more than ~20% beyond run-to-run noise.

package/docs/TRUST_MODEL.md

@@ -1,6 +1,6 @@
 # Lattice AI Trust Model
 
-Current release: **9.6.0 — Trusted Agent Loop**.
+Current release: **9.7.0 — Proactive Hybrid Brain**.
 
 Lattice AI is local-first, explicit about external communication, and honest
 when a capability is unavailable.

package/docs/WHY_LATTICE.md

@@ -1,6 +1,6 @@
 # Why Lattice AI Exists
 
-Current release: **9.6.0 — Trusted Agent Loop**.
+Current release: **9.7.0 — Proactive Hybrid Brain**.
 
 **Lattice AI is a local-first Digital Brain that keeps your knowledge durable
 across any AI model.**

package/docs/kg-schema.md

@@ -1,6 +1,6 @@
 # Knowledge Graph Schema
 
-Current release: **9.6.0 — Trusted Agent Loop**.
+Current release: **9.7.0 — Proactive Hybrid Brain**.
 
 명세 출처: `lattice_ai_full_spec.pptx` 슬라이드 20·21·22
 구현: `kg_schema.py`

package/kg_schema.py

@@ -1,3 +1,13 @@
 """Compatibility shim for the v4 Knowledge Graph schema."""
 
-from lattice_brain.graph.schema import *  # noqa: F403,F401
+import warnings as _warnings
+
+_warnings.warn(
+    "Importing 'kg_schema' from the repository root is deprecated; "
+    "use 'from lattice_brain.graph.schema import ...' instead. "
+    "The root shim will be removed in a future major release.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from lattice_brain.graph.schema import *  # noqa: F403,F401,E402

package/knowledge_graph.py

@@ -4,7 +4,17 @@ The implementation now lives under :mod:`lattice_brain`. Root imports are
 kept for older integrations and tests.
 """
 
-from lattice_brain.graph._kg_common import (  # noqa: F401
+import warnings as _warnings
+
+_warnings.warn(
+    "Importing 'knowledge_graph' from the repository root is deprecated; "
+    "use 'from lattice_brain.graph.store import KnowledgeGraphStore' instead. "
+    "The root shim will be removed in a future major release.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from lattice_brain.graph._kg_common import (  # noqa: F401,E402
     EDGE_VERB,
     GRAPH_SCHEMA_VERSION,
     LOCAL_CODE_EXTENSIONS,
@@ -24,7 +34,7 @@ from lattice_brain.graph._kg_common import (  # noqa: F401
     _slug,
     set_llm_router,
 )
-from lattice_brain.graph.store import KnowledgeGraphStore
+from lattice_brain.graph.store import KnowledgeGraphStore  # noqa: E402
 
 __all__ = [
     "KnowledgeGraphStore",

package/knowledge_graph_api.py

@@ -6,7 +6,17 @@ importable for the deprecation window and will be removed in a future major
 release.
 """
 
-from latticeai.api.knowledge_graph import (  # noqa: F401
+import warnings as _warnings
+
+_warnings.warn(
+    "Importing 'knowledge_graph_api' from the repository root is deprecated; "
+    "use 'from latticeai.api.knowledge_graph import create_knowledge_graph_router' instead. "
+    "The root shim will be removed in a future major release.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from latticeai.api.knowledge_graph import (  # noqa: F401,E402
     KnowledgeGraphIngestRequest,
     create_knowledge_graph_router,
 )

package/lattice_brain/__init__.py

@@ -26,7 +26,7 @@ from .storage import (
     storage_from_env,
 )
 
-__version__ = "9.6.0"
+__version__ = "9.7.0"
 
 __all__ = [
     "AgentRuntime",