ltcai 7.2.0 → 7.3.0

package/README.md

@@ -200,29 +200,33 @@ See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for developer workflow details.
 
 ## Current Release
 
-The current release is **7.2.0 Runtime Trust Baseline**:
-
-- Agent runs can be previewed before execution, including selected roles,
-  clamped retry budget, readiness state, and blocking reasons.
-- Product agent execution refuses simulation-mode success unless simulation is
-  explicitly enabled for a non-product runtime.
-- ToolRegistry exposes a live manifest and diagnostics endpoint covering
-  dispatch handlers, governance policy, catalog descriptions, and permissions.
-- Tool governance/catalog drift is covered by unit tests so tool additions
-  cannot silently bypass policy or disappear from operator views.
-- 7.1.0 Brain usability work remains intact while the runtime gains clearer
-  contracts for admin surfaces and future AgentRuntime extraction.
-
-Expected artifacts for 7.2.0 release must use exact filenames:
-
-- `dist/ltcai-7.2.0-py3-none-any.whl`
-- `dist/ltcai-7.2.0.tar.gz`
-- `ltcai-7.2.0.tgz`
-- `dist/ltcai-7.2.0.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_7.2.0_aarch64.dmg`
+The current release is **7.3.0 Runtime Contract & Retrieval Quality**:
+
+- Single-agent and multi-agent execution now share a serializable
+  `agent-run-contract/v1` payload for run identity, mode, status, roles,
+  timeline, retries, artifacts, and terminal state.
+- Agent runtime API responses include the shared contract, keeping real and
+  simulated run history distinguishable as runtime extraction continues.
+- Brain quality evaluation now includes deterministic hybrid recall/ranking
+  regression thresholds, not only "some recall exists" checks.
+- The 7.2.0 preview/diagnostics work remains the admin trust surface while
+  7.3.0 tightens the underlying run and retrieval contracts.
+- The roadmap focus is durability over model choice: knowledge, run evidence,
+  and retrieval quality become measurable product assets.
+
+Expected artifacts for 7.3.0 release must use exact filenames:
+
+- `dist/ltcai-7.3.0-py3-none-any.whl`
+- `dist/ltcai-7.3.0.tar.gz`
+- `ltcai-7.3.0.tgz`
+- `dist/ltcai-7.3.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_7.3.0_aarch64.dmg`
 
 Do not upload `dist/*`. Package registry publishing remains owner-run.
 
+See [docs/ROADMAP_RECOMMENDATIONS.md](docs/ROADMAP_RECOMMENDATIONS.md) for the
+strategic roadmap slice applied in 7.3.0 and the follow-up tracks.
+
 ## Known Limitations
 
 - External package registries are owner-published and can lag behind GitHub.
@@ -238,6 +242,7 @@ Do not upload `dist/*`. Package registry publishing remains owner-run.
 
 | Version | Theme |
 | --- | --- |
+| 7.3.0 | Runtime Contract & Retrieval Quality: shared agent-run contract across runtimes plus deterministic hybrid recall/ranking regression gates |
 | 7.2.0 | Runtime Trust Baseline: agent run preview/readiness, simulation-mode guardrails, live ToolRegistry manifest/diagnostics, and tests for dispatch/governance/catalog drift |
 | 7.1.0 | Brain Usability Completion: clearer first-run onboarding, ingestion progress/emergence, richer graph controls, inline answer proof, workspace/profile/admin discovery, empty/error/consent feedback, and VS Code sync status |
 | 7.0.0 | Brain Productization Loop: first-screen ingestion for files/folders/notes/web, answer-level memory proof and source citations, model-continuity demo flow, five-minute first-run loop, and recall/KG quality eval in CI |

package/docs/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.
 
+## [7.3.0] - 2026-06-20
+
+> Runtime Contract & Retrieval Quality. Turns the next AgentRuntime extraction
+> step and the uploaded roadmap's hybrid-search quality goals into a small,
+> tested release: shared run contracts and deterministic recall regression.
+
+### Added
+- `lattice_brain.runtime.contracts.AgentRunContract`, a serializable
+  `agent-run-contract/v1` payload shared by single-agent and multi-agent
+  execution paths.
+- Multi-agent API result/run patches now include the shared contract with
+  runtime, mode, status, roles, retries, timeline, and terminal-state data.
+- Single-agent runtime exposes the same contract helper for UI/API/storage
+  convergence in the next extraction pass.
+- `scripts/brain_quality_eval.py` now runs deterministic hybrid recall/ranking
+  regression checks with recall and precision thresholds.
+
+### Changed
+- Package/runtime/static metadata is synchronized to 7.3.0; package publish and
+  deployment remain owner-run only.
+
 ## [7.2.0] - 2026-06-20
 
 > Runtime Trust Baseline. Adds execution preview and registry diagnostics so

package/docs/ROADMAP_RECOMMENDATIONS.md

@@ -0,0 +1,55 @@
+# Strategic Roadmap Recommendations
+
+This roadmap captures the 2026-06-20 product direction input and maps it to
+small release-sized work. The operating principle stays unchanged:
+
+> Models are temporary. Knowledge is durable. The Brain is the product.
+
+## 7.3.0 Applied Slice
+
+7.3.0 implements the first narrow slice of the roadmap:
+
+- Runtime evolution: single-agent and multi-agent execution share
+  `agent-run-contract/v1`, making mode/status/timeline evidence inspectable.
+- Hybrid search optimization: the Brain quality gate now includes deterministic
+  recall and ranking regression thresholds.
+- Security and trust: run contracts distinguish runtime type and execution mode
+  so simulated output is not presented as real execution.
+
+## Near-Term Tracks
+
+1. Retrieval quality and scale
+   - Expand fixture datasets for hybrid search.
+   - Add latency budgets for large corpora.
+   - Track recall, precision, and ranking regressions in CI.
+   - Tune semantic/graph/keyword fusion by query class.
+
+2. Incremental ingestion
+   - Add background indexing jobs.
+   - Detect duplicates and merge memory candidates.
+   - Surface conflict resolution for contradictory memories.
+
+3. Runtime convergence
+   - Use `agent-run-contract/v1` across single-agent, multi-agent, workflows,
+     audit logs, and UI event streams.
+   - Keep simulation mode explicit and never record it as product success.
+   - Route tools through explicit registry/governance contracts.
+
+4. Brain SDK boundary
+   - Continue extracting `lattice_brain` as a reusable Brain Core package.
+   - Keep compatibility shims until downstream imports are migrated.
+   - Preserve migration rollback paths for graph and memory storage.
+
+5. Trust and operations
+   - Extend audit logging around tool execution and retrieval injection.
+   - Add dependency vulnerability monitoring.
+   - Add Tauri update/rollback planning before enabling auto-update.
+
+## Longer-Term Tracks
+
+- Multi-modal ingestion and retrieval for images, audio, and video.
+- Proactive Brain synthesis, contradiction detection, and recommendations.
+- Temporal reasoning over historical graph states.
+- Interoperability with Obsidian, Notion, Email, Calendar, Git, Slack, and Teams.
+- Encrypted Brain Network sharing.
+- Plugin marketplace and public benchmarks.

package/lattice_brain/__init__.py

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

package/lattice_brain/runtime/agent_runtime.py

@@ -37,6 +37,7 @@ from .multi_agent import (
     MULTI_AGENT_VERSION,
     ROLE_AGENT_IDS,
 )
+from .contracts import multi_agent_contract
 
 ROLE_DESCRIPTIONS = {
     "researcher": "Gathers workspace context and memory for the goal.",
@@ -344,6 +345,7 @@ class AgentRuntime:
             "retry_history": result.retry_history,
             "memory_snapshots": result.memory_snapshots,
             "mode": getattr(result, "mode", "simulation"),
+            "contract": multi_agent_contract(result=result, goal=goal),
             "current_role": None,
         }
 
@@ -509,6 +511,12 @@ class AgentRuntime:
             status=updated.get("status") or result.status,
         )
         result_payload = result.as_dict()
+        result_payload["contract"] = multi_agent_contract(
+            result=result,
+            goal=goal,
+            run_id=run_id,
+            current_role=updated.get("current_role") if isinstance(updated, dict) else None,
+        )
         if updated.get("status") == "cancelled":
             result_payload = {"status": "cancelled", "reason": updated.get("cancel_reason"), "completed_result": result_payload}
         payload = {"run": updated, "result": result_payload}
@@ -601,7 +609,9 @@ class AgentRuntime:
                 user_email=user_email, workspace_id=scope,
             )
 
-        payload = {"run": run, "result": result.as_dict()}
+        result_payload = result.as_dict()
+        result_payload["contract"] = multi_agent_contract(result=result, goal=goal, run_id=run.get("id") if isinstance(run, dict) else None)
+        payload = {"run": run, "result": result_payload}
         if pre_dispatch is not None:
             payload["pre_run_hooks"] = pre_dispatch
         if post_dispatch is not None:

package/lattice_brain/runtime/contracts.py

@@ -0,0 +1,107 @@
+"""Shared runtime contracts for agent execution surfaces.
+
+These contracts are deliberately small and serializable.  The single-agent
+state machine and the multi-agent facade can evolve independently, but callers
+should see the same run identity, mode, status, role, timeline and artifact
+shape across both paths.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+
+def runtime_timestamp() -> str:
+    return datetime.now().isoformat(timespec="seconds")
+
+
+@dataclass(frozen=True)
+class AgentRunContract:
+    run_id: Optional[str]
+    agent_id: str
+    runtime: str
+    mode: str
+    status: str
+    goal: str
+    roles: List[str] = field(default_factory=list)
+    current_role: Optional[str] = None
+    retries: int = 0
+    timeline: List[Dict[str, Any]] = field(default_factory=list)
+    artifacts: List[Dict[str, Any]] = field(default_factory=list)
+    blocking_reasons: List[str] = field(default_factory=list)
+    schema_version: str = "agent-run-contract/v1"
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.status in {"ok", "retried_ok", "failed", "rejected", "cancelled", "interrupted", "partial", "done"}
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "run_id": self.run_id,
+            "agent_id": self.agent_id,
+            "runtime": self.runtime,
+            "mode": self.mode,
+            "status": self.status,
+            "goal": self.goal,
+            "roles": list(self.roles),
+            "current_role": self.current_role,
+            "retries": self.retries,
+            "timeline": list(self.timeline),
+            "artifacts": list(self.artifacts),
+            "blocking_reasons": list(self.blocking_reasons),
+            "is_terminal": self.is_terminal,
+        }
+
+
+def multi_agent_contract(
+    *,
+    result: Any,
+    goal: str,
+    run_id: Optional[str] = None,
+    current_role: Optional[str] = None,
+    blocking_reasons: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    return AgentRunContract(
+        run_id=run_id,
+        agent_id=getattr(result, "agent_id", "agent:executor"),
+        runtime="multi_agent",
+        mode=getattr(result, "mode", "simulation"),
+        status=getattr(result, "status", "unknown"),
+        goal=goal,
+        roles=list(getattr(result, "roles_run", []) or []),
+        current_role=current_role,
+        retries=int(getattr(result, "retries", 0) or 0),
+        timeline=list(getattr(result, "timeline", []) or []),
+        artifacts=[],
+        blocking_reasons=list(blocking_reasons or []),
+    ).as_dict()
+
+
+def single_agent_contract(
+    *,
+    ctx: Any,
+    goal: str,
+    run_id: Optional[str] = None,
+    agent_id: str = "agent:single",
+    mode: str = "llm",
+    blocking_reasons: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    state = getattr(getattr(ctx, "state", None), "value", getattr(ctx, "state", "unknown"))
+    status = "done" if state == "DONE" else "failed" if state == "FAILED" else str(state or "unknown").lower()
+    return AgentRunContract(
+        run_id=run_id,
+        agent_id=agent_id,
+        runtime="single_agent",
+        mode=mode,
+        status=status,
+        goal=goal,
+        roles=["planner", "executor", "critic"],
+        current_role=str(state or ""),
+        retries=int(getattr(ctx, "retry_count", 0) or 0),
+        timeline=list(getattr(ctx, "transcript", []) or []),
+        artifacts=[],
+        blocking_reasons=list(blocking_reasons or []),
+    ).as_dict()

package/lattice_brain/runtime/multi_agent.py

@@ -18,8 +18,10 @@ from dataclasses import dataclass, field
 from datetime import datetime
 from typing import Any, Callable, Dict, List, Optional
 
+from .contracts import multi_agent_contract
 
-MULTI_AGENT_VERSION = "7.2.0"
+
+MULTI_AGENT_VERSION = "7.3.0"
 
 AGENT_ROLES = ("researcher", "planner", "executor", "reviewer", "release")
 CORE_PIPELINE = ("planner", "executor", "reviewer")
@@ -288,7 +290,7 @@ class AgentRunResult:
     mode: str = "simulation"
 
     def as_dict(self) -> Dict[str, Any]:
-        return {
+        payload = {
             "agent_id": self.agent_id,
             "mode": self.mode,
             "status": self.status,
@@ -305,6 +307,8 @@ class AgentRunResult:
             "plan_review": self.plan_review,
             "memory_snapshots": self.memory_snapshots,
         }
+        payload["contract"] = multi_agent_contract(result=self, goal=self.output)
+        return payload
 
 
 def default_role_runner(

package/latticeai/__init__.py

@@ -1,3 +1,3 @@
 """Lattice AI - modular server package."""
 
-__version__ = "7.2.0"
+__version__ = "7.3.0"

package/latticeai/core/agent.py

@@ -30,6 +30,7 @@ from pathlib import Path
 from typing import Any, Awaitable, Callable, Dict, FrozenSet, List, Optional
 
 from lattice_brain.runtime.hooks import dispatch_tool
+from lattice_brain.runtime.contracts import single_agent_contract
 from tools import ToolError
 
 
@@ -142,6 +143,10 @@ class AgentRuntime:
     def __init__(self, deps: AgentDeps) -> None:
         self.deps = deps
 
+    def contract(self, ctx: AgentRunContext, req: Any, *, run_id: Optional[str] = None) -> Dict[str, Any]:
+        """Expose the shared agent-run contract for the single-agent loop."""
+        return single_agent_contract(ctx=ctx, goal=getattr(req, "message", ""), run_id=run_id)
+
     # ── PLAN ─────────────────────────────────────────────────────────
     async def plan(
         self, ctx: AgentRunContext, req: Any, lang_hint: str, current_user: str,

package/latticeai/core/marketplace.py

@@ -11,7 +11,7 @@ from copy import deepcopy
 from typing import Any, Dict, List, Optional
 
 
-MARKETPLACE_VERSION = "7.2.0"
+MARKETPLACE_VERSION = "7.3.0"
 TEMPLATE_KINDS = ("plugin", "workflow", "agent")
 
 

package/latticeai/core/workspace_os.py

@@ -19,7 +19,7 @@ from pathlib import Path
 from typing import Any, Callable, Dict, Iterable, List, Optional
 
 
-WORKSPACE_OS_VERSION = "7.2.0"
+WORKSPACE_OS_VERSION = "7.3.0"
 
 # Workspace types separate single-user Personal workspaces from shared
 # Organization workspaces. Both keep the same local-first JSON store; the type

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ltcai",
-  "version": "7.2.0",
+  "version": "7.3.0",
   "description": "Lattice AI — local-first Digital Brain that keeps your knowledge durable across any AI model.",
   "homepage": "https://github.com/TaeSooPark-PTS/LatticeAI#readme",
   "repository": {

package/scripts/brain_quality_eval.py

@@ -12,6 +12,7 @@ import sys
 import tempfile
 from pathlib import Path
 
+from lattice_brain.quality import RetrievalBenchmarkRunner
 from latticeai.services.memory_service import MemoryService
 
 
@@ -110,7 +111,29 @@ def main() -> int:
     if proof.get("proofs", {}).get("vector_items", 0) < 1:
         return _fail("vector items must be counted in Brain proof")
 
-    print("brain-quality-eval: OK")
+    benchmark = RetrievalBenchmarkRunner()
+    retrieval_metrics = benchmark.run_fixture(
+        "7.3.0-hybrid-recall-regression",
+        [
+            {
+                "query": "first five minute Brain proof",
+                "relevant": ["note:first-loop", "doc:first-loop"],
+                "retrieved": [item.get("id") for item in recall_items],
+            },
+            {
+                "query": "local-first memory product wedge",
+                "relevant": ["decision:pricing"],
+                "retrieved": ["decision:pricing", "note:first-loop"],
+            },
+        ],
+        top_k=4,
+    )
+    if retrieval_metrics.get("recall@5", 0.0) < 0.75:
+        return _fail(f"hybrid recall regression below threshold: {retrieval_metrics}")
+    if retrieval_metrics.get("precision@5", 0.0) < 0.4:
+        return _fail(f"hybrid precision regression below threshold: {retrieval_metrics}")
+
+    print(f"brain-quality-eval: OK {retrieval_metrics}")
     return 0
 
 

package/src-tauri/Cargo.lock

@@ -1654,7 +1654,7 @@ dependencies = [
 
 [[package]]
 name = "lattice-ai-desktop"
-version = "7.2.0"
+version = "7.3.0"
 dependencies = [
  "plist",
  "serde",

package/src-tauri/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "lattice-ai-desktop"
-version = "7.2.0"
+version = "7.3.0"
 description = "Lattice AI Digital Brain desktop shell"
 authors = ["TaeSoo Park"]
 edition = "2021"

package/src-tauri/tauri.conf.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://schema.tauri.app/config/2",
   "productName": "Lattice AI",
-  "version": "7.2.0",
+  "version": "7.3.0",
   "identifier": "ai.lattice.desktop",
   "build": {
     "beforeDevCommand": "npm run frontend:dev",

package/static/app/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "7.2.0",
+  "version": "7.3.0",
   "generated_at": "vite",
   "entrypoints": {
     "app": "/static/app/index.html"