ltcai 9.9.5 → 10.0.0

package/latticeai/core/agent_permission.py

@@ -0,0 +1,160 @@
+"""Agent-loop permission-mode gates (v9.9.8).
+
+Kept separate from ``agent.py`` so the large state-machine module stays
+stable; ``SingleAgentRuntime`` and ``build_agent_runtime`` call these
+helpers instead of inlining mode tables.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, Optional, Sequence
+
+from latticeai.core.permission_mode import (
+    DEFAULT_MODE,
+    PermissionMode,
+    effective_auto_approve,
+    is_circuit_breaker,
+    normalize_mode,
+    plan_requires_approval,
+)
+
+
+def call_mode_source(
+    raw: Any,
+    *,
+    user_email: Optional[str] = None,
+    workspace_id: Optional[str] = None,
+) -> Any:
+    """Resolve a mode source that may be a value, or a callable that either
+    accepts ``user_email``/``workspace_id`` scope kwargs or takes no arguments.
+
+    Scoped resolution is what makes per-user and per-workspace overrides real:
+    an unscoped call always collapses to the process-wide default.
+    """
+    if not callable(raw):
+        return raw
+    try:
+        return raw(user_email=user_email, workspace_id=workspace_id)
+    except TypeError:
+        # Legacy zero-arg resolver (or a static callable) — fall back.
+        try:
+            return raw()
+        except Exception:
+            return DEFAULT_MODE
+    except Exception:
+        return DEFAULT_MODE
+
+
+def resolve_deps_mode(
+    deps: Any,
+    ctx: Any = None,
+    *,
+    user_email: Optional[str] = None,
+    workspace_id: Optional[str] = None,
+) -> PermissionMode:
+    """Mode for this run: explicit context stamp wins, else the scoped resolver
+    on ``deps``, else strict."""
+    if ctx is not None:
+        override = getattr(ctx, "permission_mode", None)
+        if override is not None:
+            return normalize_mode(override)
+    raw = call_mode_source(
+        getattr(deps, "permission_mode", None),
+        user_email=user_email,
+        workspace_id=workspace_id,
+    )
+    return normalize_mode(raw if raw is not None else DEFAULT_MODE)
+
+
+def non_auto_plan_steps(
+    mode: PermissionMode | str,
+    steps: Sequence[Mapping[str, Any]],
+    tool_governance: Mapping[str, Mapping[str, Any]],
+    *,
+    governed_tools: Optional[Any] = None,
+) -> List[Any]:
+    """Plan steps that still need approval under the active mode."""
+    mode = normalize_mode(mode)
+    governed = frozenset(governed_tools or ())
+    non_auto: List[Any] = []
+    for step in steps:
+        name = step.get("action")
+        if not name:
+            continue
+        if name in governed and mode == PermissionMode.STRICT:
+            # Strict keeps governor tools out of the plan-level block (per-call).
+            continue
+        policy = dict(tool_governance.get(name) or {
+            "auto_approve": False, "risk": "write", "destructive": False,
+            "shell": False, "network": False, "sandbox": "workspace", "rollback": "none",
+        })
+        if effective_auto_approve(mode, str(name), policy):
+            continue
+        non_auto.append(name)
+    return non_auto
+
+
+def approval_requirements_for(
+    mode: PermissionMode | str,
+    plan: Mapping[str, Any],
+    tool_governance: Mapping[str, Mapping[str, Any]],
+    *,
+    governed_tools: Optional[Any] = None,
+) -> Dict[str, Any]:
+    steps = plan.get("steps") or []
+    non_auto = non_auto_plan_steps(
+        mode, steps, tool_governance, governed_tools=governed_tools,
+    )
+    requires = plan_requires_approval(
+        mode,
+        non_auto_steps=non_auto,
+        plan_flag=bool(plan.get("requires_approval", False)),
+    )
+    lines = [
+        f"{index}. {step.get('description') or step.get('action') or '?'}"
+        for index, step in enumerate(steps, start=1)
+        if isinstance(step, dict)
+    ]
+    summary = str(plan.get("goal") or "").strip()
+    if lines:
+        summary = (summary + "\n" if summary else "") + "\n".join(lines)
+    return {
+        "requires_approval": requires,
+        "non_auto_steps": non_auto,
+        "plan_summary": summary,
+        "permission_mode": normalize_mode(mode).value,
+    }
+
+
+def block_reason_for_tool(
+    mode: PermissionMode | str,
+    name: str,
+    policy: Mapping[str, Any],
+    args: Mapping[str, Any],
+    *,
+    approved_by_human: bool = False,
+    governor_allows_additive: bool = False,
+) -> Optional[str]:
+    """Return a block reason, or None when the call may proceed."""
+    mode = normalize_mode(mode)
+    breaker = is_circuit_breaker(name, policy, args)
+    if breaker:
+        return f"BLOCKED: {breaker}"
+    if policy.get("risk") == "destructive" or policy.get("destructive"):
+        return f"BLOCKED: destructive action '{name}' not permitted in agent mode."
+    if approved_by_human or governor_allows_additive:
+        return None
+    if effective_auto_approve(mode, name, policy, args=args):
+        return None
+    if policy.get("auto_approve"):
+        return None
+    return f"BLOCKED: action '{name}' requires explicit approval (mode={mode.value})."
+
+
+__all__ = [
+    "call_mode_source",
+    "resolve_deps_mode",
+    "non_auto_plan_steps",
+    "approval_requirements_for",
+    "block_reason_for_tool",
+]

package/latticeai/core/agent_profiles.py

@@ -0,0 +1,110 @@
+"""Agent profiles — matching the loop to the model driving it (v9.9.7).
+
+The single-agent loop asks a model to emit one strict JSON tool call per turn.
+Large models do that reliably; a 1–4B local model routinely does not, and the
+loop's answer was always the same: repair, correct, retry, and eventually give
+up with nothing written. The counters showed the strain (``model_strain`` in
+the run explanation), but every model still ran the same loop.
+
+A profile is that missing dial:
+
+* **standard** — today's behaviour, unchanged, for models that can hold a
+  tool-call contract.
+* **compact** — for small local models: a shorter transcript window, an
+  earlier escalation to naming the valid tools, and — the important one — a
+  **direct-path fallback**. When JSON tool calls keep failing, the loop stops
+  asking for JSON at all and executes the plan's own file steps, requesting
+  only *file content* in plain text. Weak models are bad at tool protocols and
+  fine at writing a file; the profile plays to that.
+
+Selection is deterministic and inspectable: a model id names its size, so the
+profile is a pure function of the id plus an explicit environment override.
+Nothing here guesses at quality — a model absent from the size heuristic gets
+``standard``, which is the conservative choice (no behaviour change).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Mapping, Optional
+
+__all__ = ["AgentProfile", "COMPACT", "STANDARD", "profile_for_model", "model_size_b"]
+
+
+@dataclass(frozen=True)
+class AgentProfile:
+    """How hard the loop should work to keep a given model on contract."""
+
+    name: str
+    # Executor transcript window (steps kept in full). Small models drown in
+    # long transcripts far sooner than large ones.
+    transcript_window: int
+    # Format slips tolerated before the run stops retrying.
+    parse_failure_budget: int
+    # Slip count at which the correction hint starts naming valid tool names.
+    escalate_after: int
+    # When JSON tool calls are exhausted, execute the plan's file steps
+    # directly and ask only for file content in plain text.
+    direct_path_fallback: bool
+
+
+STANDARD = AgentProfile(
+    name="standard",
+    transcript_window=8,
+    parse_failure_budget=3,
+    escalate_after=2,
+    direct_path_fallback=False,
+)
+
+COMPACT = AgentProfile(
+    name="compact",
+    transcript_window=4,
+    parse_failure_budget=4,
+    escalate_after=1,
+    direct_path_fallback=True,
+)
+
+_PROFILES = {profile.name: profile for profile in (STANDARD, COMPACT)}
+
+# "gemma-3-4b-it-4bit", "qwen2.5-1.5b", "llama-3.2-3B" → parameter count in B.
+# The quantization suffix ("4bit", "8bit") is deliberately excluded: it is not
+# a parameter count, and reading it as one would mislabel every quantized model.
+_SIZE_RE = re.compile(r"(?<![a-z0-9.])(\d+(?:\.\d+)?)\s*b(?![a-z0-9])", re.IGNORECASE)
+_QUANT_RE = re.compile(r"\d+\s*bit", re.IGNORECASE)
+
+# At or below this parameter count, the compact profile applies.
+COMPACT_MAX_PARAMS_B = 4.0
+
+
+def model_size_b(model_id: str) -> Optional[float]:
+    """Parameter count in billions parsed from a model id, or None.
+
+    Returns None rather than guessing when the id names no size — an unknown
+    model must not be silently downgraded to the compact loop.
+    """
+    text = _QUANT_RE.sub(" ", str(model_id or ""))
+    sizes = [float(match) for match in _SIZE_RE.findall(text)]
+    return min(sizes) if sizes else None
+
+
+def profile_for_model(
+    model_id: Optional[str], *, env: Optional[Mapping[str, str]] = None
+) -> AgentProfile:
+    """Pick the loop profile for a model.
+
+    Order: explicit ``LATTICEAI_AGENT_PROFILE`` override → size heuristic →
+    ``standard``. An unrecognized override name falls through to the
+    heuristic rather than failing the run.
+    """
+    if env is None:
+        import os
+
+        env = os.environ
+    override = str(env.get("LATTICEAI_AGENT_PROFILE") or "").strip().lower()
+    if override in _PROFILES:
+        return _PROFILES[override]
+    size = model_size_b(model_id or "")
+    if size is not None and size <= COMPACT_MAX_PARAMS_B:
+        return COMPACT
+    return STANDARD

package/latticeai/core/artifact_ledger.py

@@ -0,0 +1,109 @@
+"""Conversation artifact ledger — closing the re-search loop (v9.9.6).
+
+A run writes ``index.html``, the file is queued for ingestion, and the user
+immediately asks "이제 그 파일에 다크모드 넣어줘". Indexing (chunking, embedding,
+graph writes) is asynchronous, so retrieval may not know about that file yet —
+the next turn could plan as if it had never been created.
+
+This ledger is the deterministic bridge: the agent path records what it just
+wrote, and the context assembler injects it as a high-priority section. It is
+intentionally **process-local and bounded**:
+
+* it answers "what did *this conversation* just make?", a question whose
+  useful lifetime is minutes;
+* by the time a restart loses it, the ingestion pipeline has indexed those
+  files and normal retrieval answers better than a ledger would;
+* nothing downstream may treat it as durable storage — the Brain remains the
+  single durable home for knowledge.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import OrderedDict
+from typing import Any, Dict, List, Optional, Sequence
+
+from latticeai.core.timeutil import now_iso
+
+__all__ = ["ArtifactLedger"]
+
+
+class ArtifactLedger:
+    """Bounded, thread-safe map of conversation → recently written artifacts."""
+
+    def __init__(
+        self,
+        *,
+        max_conversations: int = 200,
+        max_per_conversation: int = 25,
+    ) -> None:
+        self._lock = threading.Lock()
+        self._entries: "OrderedDict[tuple, List[Dict[str, Any]]]" = OrderedDict()
+        self._max_conversations = max(1, int(max_conversations))
+        self._max_per_conversation = max(1, int(max_per_conversation))
+
+    @staticmethod
+    def _key(
+        user_email: Optional[str],
+        conversation_id: Optional[str],
+        workspace_id: Optional[str],
+    ) -> tuple:
+        return (
+            str(user_email or ""),
+            str(conversation_id or "default"),
+            str(workspace_id or ""),
+        )
+
+    def record(
+        self,
+        paths: Sequence[Any],
+        *,
+        user_email: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+        run_id: str = "",
+    ) -> List[Dict[str, Any]]:
+        """Note artifacts this conversation just produced. Never raises."""
+        cleaned: List[str] = []
+        for entry in list(paths or []):
+            path = entry if isinstance(entry, str) else (entry or {}).get("path")
+            path = str(path or "").strip()
+            if path and path not in cleaned:
+                cleaned.append(path)
+        if not cleaned:
+            return []
+        stamp = now_iso()
+        key = self._key(user_email, conversation_id, workspace_id)
+        with self._lock:
+            existing = self._entries.pop(key, [])
+            by_path = {item["path"]: item for item in existing}
+            for path in cleaned:
+                by_path[path] = {"path": path, "at": stamp, "run_id": str(run_id or "")}
+            merged = sorted(by_path.values(), key=lambda item: item["at"])
+            merged = merged[-self._max_per_conversation :]
+            self._entries[key] = merged
+            while len(self._entries) > self._max_conversations:
+                self._entries.popitem(last=False)
+            return list(merged)
+
+    def recent(
+        self,
+        *,
+        user_email: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+        limit: int = 10,
+    ) -> List[Dict[str, Any]]:
+        """Most recent artifacts for one conversation, newest last.
+
+        Returns ``[]`` for an unknown conversation — honest absence, never a
+        cross-conversation leak.
+        """
+        key = self._key(user_email, conversation_id, workspace_id)
+        with self._lock:
+            items = list(self._entries.get(key, []))
+        return items[-max(1, int(limit)) :]
+
+    def clear(self) -> None:
+        with self._lock:
+            self._entries.clear()

package/latticeai/core/context_builder.py

@@ -5,18 +5,73 @@ retrieve_context_for_generation() 파이프라인:
   Step 1: Query → Hybrid Search (text + graph + recency)
   Step 2: Seed nodes → Multi-hop traversal (Document → Project → Concept)
   Step 3: Top-K 결과를 구조화된 Markdown Context로 변환
+
+**Shared context contract (v9.9.6).** Chat assembles context through
+:class:`lattice_brain.context.ContextAssembler` — budgeted, provenance-carrying,
+with an honest ``context_quality`` signal. Document generation used to build
+its own markdown with no budget and no quality signal, so the same Brain
+answered a chat question and wrote a document under different guarantees.
+
+The rendering stays different on purpose (a document prompt wants structured
+sections, a chat prompt wants terse lines), but the *contract* is now one:
+
+* the same ``approx_tokens`` accounting and an explicit budget,
+* the same ``context_quality_signal`` shape chat reports,
+* a ``trace`` in the assembler's shape (budget / used / sections).
+
+Review 2026-07-27 P1 #5: "같은 Brain이면 같은 품질 계약".
 """
 
 import re
 from typing import Any, Dict, List
 
+from lattice_brain.context import approx_tokens
+from lattice_brain.graph.retrieval import context_quality_signal
+
 _CLEAN_RE = re.compile(r"\s+")
 
+# Approximate-token ceiling for the document-generation context block. Mirrors
+# the chat assembler's default budget so neither path can silently outgrow the
+# other on the same Brain.
+DEFAULT_DOCUMENT_CONTEXT_BUDGET = 2000
+
 
 def _clean(text: str, max_len: int = 700) -> str:
     return _CLEAN_RE.sub(" ", str(text or "")).strip()[:max_len]
 
 
+def _empty_result(query: str, reason: str) -> Dict[str, Any]:
+    quality = context_quality_signal("none", 0, reason=reason)
+    return {
+        "query": query,
+        "context_markdown": "",
+        "sources": [],
+        "stats": {"method": "none", "matches": 0},
+        "context_quality": quality,
+        "trace": {
+            "budget_approx_tokens": DEFAULT_DOCUMENT_CONTEXT_BUDGET,
+            "used_approx_tokens": 0,
+            "sections": [],
+        },
+    }
+
+
+def _fit_to_budget(context_md: str, budget: int) -> tuple:
+    """Trim rendered markdown to ``budget`` approximate tokens.
+
+    Cuts at a section boundary when possible so the prompt never ends inside
+    half an entry, and reports the trim so the trace stays honest.
+    """
+    if budget <= 0 or approx_tokens(context_md) <= budget:
+        return context_md, False
+    limit = budget * 4
+    head = context_md[:limit]
+    boundary = head.rfind("\n### ")
+    if boundary > limit // 3:
+        head = head[:boundary]
+    return head.rstrip(), True
+
+
 def retrieve_context_for_generation(
     kg_store,
     query: str,
@@ -25,6 +80,7 @@ def retrieve_context_for_generation(
     max_hops: int = 2,
     allowed_workspaces=None,
     include_legacy_global: bool = False,
+    budget: int = DEFAULT_DOCUMENT_CONTEXT_BUDGET,
 ) -> Dict[str, Any]:
     """Knowledge Graph에서 문서 생성에 필요한 컨텍스트를 검색·조합한다.
 
@@ -34,11 +90,13 @@ def retrieve_context_for_generation(
             "context_markdown": str,   # LLM 프롬프트에 직접 주입할 Markdown
             "sources": [...],          # 참조된 소스 목록
             "stats": {...},            # 검색 통계
+            "context_quality": {...},  # chat과 동일한 정직 신호 (v9.9.6)
+            "trace": {...},            # assembler와 동일한 예산/섹션 추적
         }
     """
     query = str(query or "").strip()
     if not query or not kg_store:
-        return {"query": query, "context_markdown": "", "sources": [], "stats": {}}
+        return _empty_result(query, "문서 생성 컨텍스트를 조회할 수 없습니다")
 
     scope_kwargs = (
         {
@@ -55,11 +113,30 @@ def retrieve_context_for_generation(
             limit=max_results,
             **scope_kwargs,
         )
+        fallback_ctx, trimmed = _fit_to_budget(fallback_ctx or "", budget)
+        # Lexical fallback: the hybrid document search found nothing, so the
+        # signal says lexical_only — exactly what chat reports in the same
+        # situation, never a quiet downgrade.
+        quality = context_quality_signal(
+            "lexical_only" if fallback_ctx else "none",
+            1 if fallback_ctx else 0,
+        )
         return {
             "query": query,
             "context_markdown": fallback_ctx,
             "sources": [],
-            "stats": {"method": "fallback", "matches": 0},
+            "stats": {"method": "fallback", "matches": 0, "budget_trimmed": trimmed},
+            "context_quality": quality,
+            "trace": {
+                "budget_approx_tokens": budget,
+                "used_approx_tokens": approx_tokens(fallback_ctx),
+                "sections": [{
+                    "name": "Knowledge (fallback)",
+                    "source": "knowledge",
+                    "approx_tokens": approx_tokens(fallback_ctx),
+                    "provenance": [],
+                }],
+            },
         }
 
     seed_ids = [r["id"] for r in results]
@@ -77,6 +154,7 @@ def retrieve_context_for_generation(
     sections = _build_context_sections(results, extra_nodes_by_id, hop_data.get("edges", []))
     context_md = _render_markdown(query, sections)
     sources = _extract_sources(results)
+    context_md, trimmed = _fit_to_budget(context_md, budget)
 
     return {
         "query": query,
@@ -87,6 +165,27 @@ def retrieve_context_for_generation(
             "primary_matches": len(results),
             "graph_nodes": len(hop_data.get("nodes", [])),
             "graph_edges": len(hop_data.get("edges", [])),
+            "budget_trimmed": trimmed,
+        },
+        # Same honest signal chat reports for the same Brain.
+        "context_quality": context_quality_signal("hybrid", len(results)),
+        "trace": {
+            "budget_approx_tokens": budget,
+            "used_approx_tokens": approx_tokens(context_md),
+            "sections": [
+                {
+                    "name": section["title"],
+                    "source": "knowledge",
+                    "approx_tokens": approx_tokens(
+                        " ".join(str(item.get("summary") or "") for item in section["items"])
+                    ),
+                    "provenance": [
+                        {"id": item.get("id"), "type": item.get("type")}
+                        for item in section["items"][:8]
+                    ],
+                }
+                for section in sections
+            ],
         },
     }
 

package/latticeai/core/legacy_compatibility.py

@@ -14,7 +14,7 @@ from pathlib import Path
 from typing import Any, Dict, List
 
 
-LEGACY_COMPATIBILITY_VERSION = "9.9.5"
+LEGACY_COMPATIBILITY_VERSION = "10.0.0"
 
 
 @dataclass(frozen=True)

package/latticeai/core/marketplace.py

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