ltcai 9.9.1 → 9.9.3

package/latticeai/api/setup.py

@@ -17,7 +17,15 @@ from latticeai.setup.auto_setup import (
     verify as auto_setup_verify,
 )
 from latticeai.models.router import parse_model_ref
+from latticeai.setup.demo_corpus import (
+    DEMO_DOCUMENTS,
+    DEMO_METADATA_FLAG,
+    DEMO_URI_PREFIX,
+    demo_source_uri,
+    suggested_questions,
+)
 from latticeai.setup.wizard import get_recommendations, install_stream, open_url, scan_environment
+from lattice_brain.ingestion import IngestionItem
 
 
 class SetupInstallRequest(BaseModel):
@@ -25,7 +33,18 @@ class SetupInstallRequest(BaseModel):
     confirmation_token: Optional[str] = None
 
 
-def create_setup_router(*, model_router, require_user) -> APIRouter:
+class DemoCorpusRequest(BaseModel):
+    workspace_id: Optional[str] = None
+
+
+def create_setup_router(
+    *,
+    model_router,
+    require_user,
+    ingestion_pipeline=None,
+    knowledge_graph=None,
+    workspace_service=None,
+) -> APIRouter:
     api_router = APIRouter()
     router = model_router
 
@@ -157,6 +176,120 @@ def create_setup_router(*, model_router, require_user) -> APIRouter:
         return {"status": "ok", "opened": url, "mcp_id": mcp_id}
     
     
+    # ── First Value Loop demo corpus (backlog #3, review §3.3 P0) ────────────
+
+    def _require_demo_pipeline():
+        if ingestion_pipeline is None or not ingestion_pipeline.available():
+            raise HTTPException(
+                status_code=503, detail="Knowledge Graph ingestion is disabled.",
+            )
+        if knowledge_graph is None:
+            raise HTTPException(status_code=503, detail="Knowledge Graph is disabled.")
+
+    def _demo_workspace(request: Request, body_workspace: Optional[str], user: str) -> Optional[str]:
+        header = request.headers.get("X-Workspace-Id")
+        header = header.strip() if header and header.strip() else None
+        supplied = [value for value in (body_workspace, header) if value]
+        if len(set(supplied)) > 1:
+            raise HTTPException(status_code=403, detail="Workspace selectors must match.")
+        requested = supplied[0] if supplied else None
+        if workspace_service is None:
+            return requested
+        try:
+            return workspace_service.resolve_write_scope(requested, user or None)
+        except PermissionError as exc:
+            raise HTTPException(status_code=403, detail=str(exc)) from exc
+
+    @api_router.get("/api/setup/demo-corpus")
+    async def demo_corpus_status(request: Request):
+        """Whether the demo corpus is installed + the suggestion chips."""
+        require_user(request)
+        _require_demo_pipeline()
+        installed = knowledge_graph.find_documents_by_uri_prefix(DEMO_URI_PREFIX)
+        return {
+            "installed": bool(installed),
+            "documents": installed,
+            "document_count": len(installed),
+            "suggested_questions": suggested_questions(),
+        }
+
+    @api_router.post("/api/setup/demo-corpus")
+    async def demo_corpus_install(request: Request, req: Optional[DemoCorpusRequest] = None):
+        """One-click ingest of the 3 built-in demo documents (idempotent).
+
+        Every document goes through the normal IngestionPipeline door with
+        ``demo://`` provenance so it is honest (real nodes, real chunks, real
+        provenance) and removable via DELETE. Re-POSTing reports duplicates
+        instead of duplicating.
+        """
+        user = require_user(request)
+        _require_demo_pipeline()
+        workspace_id = _demo_workspace(request, req.workspace_id if req else None, user)
+        results = []
+        ingested = 0
+        duplicates = 0
+        failed = 0
+        for doc in DEMO_DOCUMENTS:
+            result = ingestion_pipeline.ingest(
+                IngestionItem(
+                    source_type="note",
+                    title=doc["title"],
+                    text=doc["text"],
+                    source_uri=demo_source_uri(doc["id"]),
+                    owner=user or None,
+                    workspace_id=workspace_id,
+                    metadata={DEMO_METADATA_FLAG: True, "demo_id": doc["id"]},
+                ),
+                user_email=user or None,
+            )
+            if result.status != "ok":
+                failed += 1
+            elif result.duplicate:
+                duplicates += 1
+            else:
+                ingested += 1
+            results.append({
+                "demo_id": doc["id"],
+                "title": doc["title"],
+                "source_uri": demo_source_uri(doc["id"]),
+                "status": result.status,
+                "node_id": result.node_id,
+                "duplicate": result.duplicate,
+                "chunk_count": result.chunk_count,
+                "detail": result.detail,
+            })
+        status = "ok" if failed == 0 else ("partial" if (ingested + duplicates) else "failed")
+        return {
+            "status": status,
+            "ingested": ingested,
+            "duplicates": duplicates,
+            "failed": failed,
+            "documents": results,
+            "suggested_questions": suggested_questions(),
+        }
+
+    @api_router.delete("/api/setup/demo-corpus")
+    async def demo_corpus_remove(request: Request):
+        """Remove every demo document (node + chunks + edges + orphan source)."""
+        require_user(request)
+        _require_demo_pipeline()
+        installed = knowledge_graph.find_documents_by_uri_prefix(DEMO_URI_PREFIX)
+        removed = []
+        for doc in installed:
+            outcome = knowledge_graph.delete_document_tree(doc["id"])
+            removed.append({
+                "node_id": doc["id"],
+                "title": doc.get("title"),
+                "source_uri": doc.get("source_uri"),
+                "status": outcome.get("status"),
+                "removed_nodes": outcome.get("removed_nodes", 0),
+            })
+        return {
+            "status": "ok",
+            "removed_count": len(removed),
+            "removed": removed,
+        }
+
     @api_router.post("/permissions/open/{permission_id}")
     async def open_permission_settings(permission_id: str, request: Request):
         require_user(request)

package/latticeai/api/tools.py

@@ -11,7 +11,7 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from fastapi import APIRouter, File, HTTPException, Request, UploadFile
-from fastapi.responses import FileResponse
+from fastapi.responses import FileResponse, Response
 from pydantic import BaseModel
 
 from latticeai.api.computer_use import create_computer_use_router
@@ -543,8 +543,38 @@ def create_tools_router(
             filename=target.name,
             media_type="application/octet-stream",
         )
-    
-    
+
+
+    @api_router.get("/tools/download_zip")
+    async def tools_download_zip(path: str, request: Request):
+        """Serve a generated project directory from the agent workspace as a zip.
+
+        The multi-file artifact loop writes bundles like ``todo-app/`` —
+        this is their one-click download. Path confinement mirrors
+        ``/tools/download``: anything outside the workspace is refused.
+        """
+        require_user(request)
+        from urllib.parse import unquote
+
+        from latticeai.tools.filesystem import zip_workspace_dir
+
+        rel = unquote(path).lstrip("/")
+        target = (AGENT_ROOT / rel).resolve()
+        if AGENT_ROOT not in target.parents and target != AGENT_ROOT:
+            raise HTTPException(status_code=403, detail="경로가 작업 공간 밖입니다.")
+        if not target.exists() or not target.is_dir():
+            raise HTTPException(status_code=404, detail="디렉터리가 없습니다.")
+        try:
+            payload, filename = zip_workspace_dir(rel)
+        except ToolError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+        return Response(
+            content=payload,
+            media_type="application/zip",
+            headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+        )
+
+
     @api_router.post("/upload/document")
     async def upload_document(request: Request, file: UploadFile = File(...)):
         current_user = require_user(request)

package/latticeai/app_factory.py

@@ -395,6 +395,7 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
     INGESTION_PIPELINE = _persistence_runtime["INGESTION_PIPELINE"]
     DEVICE_IDENTITY = _persistence_runtime["DEVICE_IDENTITY"]
     KG_PORTABILITY = _persistence_runtime["KG_PORTABILITY"]
+    FUNNEL_METRICS = _persistence_runtime["FUNNEL_METRICS"]
 
     def _require_graph():
         if not ENABLE_GRAPH or KNOWLEDGE_GRAPH is None:
@@ -911,6 +912,7 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         chat_service=CHAT_SERVICE,
         context_assembler=CONTEXT_ASSEMBLER,
         brain_memory=BRAIN_MEMORY,
+        ingestion_pipeline=INGESTION_PIPELINE if ENABLE_GRAPH else None,
         chat_agent_runtime=CHAT_AGENT_RUNTIME,
         gardener=gardener,
         hooks=HOOKS_REGISTRY,
@@ -950,6 +952,7 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         public_model=PUBLIC_MODEL,
         local_model=LOCAL_MODEL or "",
         on_chat_message=on_chat_message,
+        funnel_metrics=FUNNEL_METRICS,
     )
     app.state.context = context
 
@@ -1035,6 +1038,17 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
             gate_write=PLATFORM.gate_write,
             append_audit_event=append_audit_event,
             workspace_graph=_workspace_graph,
+            run_executor=RUN_EXECUTOR,
+            review_queue=REVIEW_QUEUE,
+        )
+    )
+    # UX funnel metrics (backlog #16): admin-only runtime counters.
+    from latticeai.api.funnel_metrics import create_funnel_metrics_router
+
+    app.include_router(
+        create_funnel_metrics_router(
+            service=FUNNEL_METRICS,
+            require_admin=require_admin,
         )
     )
     COMMAND_CENTER = CommandCenterService(
@@ -1211,6 +1225,7 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         gardener=gardener,
         create_setup_router=create_setup_router,
         model_router=router,
+        knowledge_graph=KNOWLEDGE_GRAPH,
     )
 
     # ── Entry Point ────────────────────────────────────────────────────────────────

package/latticeai/core/agent.py

@@ -27,11 +27,12 @@ import re
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
-from typing import Any, Awaitable, Callable, Dict, FrozenSet, List, Optional, Tuple
+from typing import Any, Awaitable, Callable, Dict, FrozenSet, List, Mapping, Optional, Tuple
 
 from lattice_brain.runtime.hooks import dispatch_tool
 from lattice_brain.runtime.contracts import runtime_boundary_contract, single_agent_contract
 from latticeai.core.agent_trace import LoopTrace
+from latticeai.core.file_generation import infer_file_target, sanitize_write_content
 from latticeai.core.tool_registry import SCOPED_KNOWLEDGE_TOOLS
 from latticeai.tools import ToolError
 
@@ -141,6 +142,129 @@ def extract_action(raw: str) -> Dict:
     return action
 
 
+def normalize_plan(plan: Any, user_message: str) -> Tuple[Dict[str, Any], List[str]]:
+    """Enforce the minimal plan schema so execution never starts adrift.
+
+    A weak planner that returns junk steps / a missing goal previously flowed
+    straight into the executor, which then had to reconstruct intent from the
+    raw request. Normalization keeps the loop honest: ``goal`` is always a
+    non-empty string, ``steps`` only contains dicts with an ``action``, and an
+    empty plan for an obvious file-creation request gets a deterministic
+    single ``write_file`` step instead of leaving the executor to improvise.
+
+    Returns ``(plan, fixes)`` where ``fixes`` names every applied repair —
+    the loop trace records them so plan quality is observable per model.
+    """
+    fixes: List[str] = []
+    if not isinstance(plan, dict):
+        plan = {}
+        fixes.append("plan_not_object")
+    plan = dict(plan)
+
+    goal = str(plan.get("goal") or "").strip()
+    if not goal:
+        plan["goal"] = user_message
+        fixes.append("goal_defaulted")
+
+    raw_steps = plan.get("steps")
+    steps = [
+        s for s in (raw_steps if isinstance(raw_steps, list) else [])
+        if isinstance(s, dict) and s.get("action")
+    ]
+    if raw_steps and steps != raw_steps:
+        fixes.append("steps_filtered")
+    if not steps:
+        inferred = infer_file_target(user_message)
+        if inferred:
+            steps = [{
+                "action": "write_file",
+                "args": {"path": inferred},
+                "description": f"Create {inferred} for: {user_message[:120]}",
+            }]
+            fixes.append("heuristic_file_step")
+    plan["steps"] = steps
+
+    try:
+        estimated = int(plan.get("estimated_steps") or 0)
+    except (TypeError, ValueError):
+        estimated = 0
+        fixes.append("estimated_steps_invalid")
+    plan["estimated_steps"] = max(1, estimated, len(steps))
+    plan["requires_approval"] = bool(plan.get("requires_approval", False))
+    if not isinstance(plan.get("rollback_strategy"), str):
+        plan["rollback_strategy"] = "none"
+    return plan, fixes
+
+
+_TRIVIAL_LEARNING_RE = re.compile(
+    r"^(파일(을|이)?\s*(만들|생성|작성|저장)|작업(을|이)?\s*(완료|성공)|성공적으로"
+    r"|task\s+(was\s+)?complet|file\s+(was\s+)?(creat|written|saved)"
+    r"|(successfully\s+)?(created|completed|finished|done)\b)",
+    re.IGNORECASE,
+)
+
+
+def filter_learnings(learnings: List[Any]) -> List[str]:
+    """Drop trivial/duplicate learnings before they enter the brain.
+
+    "파일을 만들었다"-class statements restate what the transcript already
+    records and pollute recall. A learning survives when it is long enough to
+    carry information and is not a bare completion announcement.
+    """
+    kept: List[str] = []
+    seen: set = set()
+    for raw in learnings or []:
+        text = str(raw or "").strip()
+        if len(text) < 12:
+            continue
+        if _TRIVIAL_LEARNING_RE.match(text) and len(text) < 48:
+            continue
+        key = text.lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        kept.append(text)
+    return kept
+
+
+@dataclass(frozen=True)
+class PhaseBudgets:
+    """Per-phase token budgets for the agent loop.
+
+    One shared budget let a weak model burn everything on planning prose and
+    reach EXECUTE with nothing left. Each role phase now has its own cap, so
+    a verbose planner can never starve execution or verification. Defaults
+    match the historical hardcoded values; every cap is overridable through
+    the ``Config.from_env`` environment pattern.
+    """
+
+    plan_tokens: int = 1024
+    execute_tokens: int = 4096
+    verify_tokens: int = 512
+    memory_tokens: int = 256
+
+    @classmethod
+    def from_env(cls, env: Optional[Mapping[str, str]] = None) -> "PhaseBudgets":
+        from latticeai.core.config import _int
+
+        if env is None:
+            import os
+
+            env = os.environ
+
+        def cap(key: str, default: int) -> int:
+            # A misconfigured/absurd value must not brick the loop: floor at a
+            # budget that still fits one JSON action object.
+            return max(128, _int(env, key, default))
+
+        return cls(
+            plan_tokens=cap("LATTICEAI_AGENT_PLAN_TOKENS", cls.plan_tokens),
+            execute_tokens=cap("LATTICEAI_AGENT_EXECUTE_TOKENS", cls.execute_tokens),
+            verify_tokens=cap("LATTICEAI_AGENT_VERIFY_TOKENS", cls.verify_tokens),
+            memory_tokens=cap("LATTICEAI_AGENT_MEMORY_TOKENS", cls.memory_tokens),
+        )
+
+
 @dataclass
 class AgentDeps:
     """The ports a :class:`SingleAgentRuntime` needs from the outside world.
@@ -200,12 +324,29 @@ class AgentDeps:
     # returning None (fall through to the classic gates) or a verdict dict.
     change_governor: Any = None
 
+    # ── phase budgets (optional) ─────────────────────────────────────
+    # Per-phase token caps (plan/execute/verify/memory). None reads the
+    # environment once at first use; tests inject a fixed PhaseBudgets.
+    phase_budgets: Optional[PhaseBudgets] = None
+
 
 class SingleAgentRuntime:
     """Drives the agent state machine over injected :class:`AgentDeps`."""
 
     def __init__(self, deps: AgentDeps) -> None:
         self.deps = deps
+        self._env_phase_budgets: Optional[PhaseBudgets] = None
+
+    @property
+    def phase_budgets(self) -> PhaseBudgets:
+        # getattr twice: partially-constructed runtimes/deps (tests build them
+        # via __new__ or minimal fakes) still get working default budgets.
+        injected = getattr(self.deps, "phase_budgets", None)
+        if injected is not None:
+            return injected
+        if getattr(self, "_env_phase_budgets", None) is None:
+            self._env_phase_budgets = PhaseBudgets.from_env()
+        return self._env_phase_budgets
 
     def boundary(self) -> Dict[str, Any]:
         return runtime_boundary_contract(
@@ -245,7 +386,7 @@ class SingleAgentRuntime:
         raw = await d.generate_as(
             model_id,
             message="Produce a JSON execution plan for this request.",
-            context=context, max_tokens=1024, temperature=0.1,
+            context=context, max_tokens=self.phase_budgets.plan_tokens, temperature=0.1,
         )
         ctx.trace.llm_call("plan", model=model_id)
         try:
@@ -258,6 +399,9 @@ class SingleAgentRuntime:
                 "goal": req.message, "steps": [],
                 "requires_approval": False, "rollback_strategy": "none", "estimated_steps": 1,
             }
+        plan, plan_fixes = normalize_plan(plan, req.message)
+        if plan_fixes:
+            ctx.trace.repair("plan", repairs=plan_fixes)
         ctx.plan = plan
         ctx.transcript.append({
             "state": AgentState.PLANNING.value,
@@ -266,12 +410,19 @@ class SingleAgentRuntime:
             "requires_approval": plan.get("requires_approval", False),
             "rollback_strategy": plan.get("rollback_strategy", "none"),
             "estimated_steps": plan.get("estimated_steps", 1),
+            **({"plan_fixes": plan_fixes} if plan_fixes else {}),
         })
         ctx.state = AgentState.WAITING_APPROVAL
 
     # ── APPROVAL ─────────────────────────────────────────────────────
-    def approve(self, ctx: AgentRunContext, current_user: str, *, approved_by_human: bool = False) -> None:
-        """APPROVAL: Check governance, log decision, auto-approve (future: UI prompt)."""
+    def approval_requirements(self, ctx: AgentRunContext) -> Dict[str, Any]:
+        """Read-only preview of the approval gate for a planned run.
+
+        Shares the exact predicate :meth:`approve` enforces, so the HTTP
+        layer can pause a run as ``awaiting_approval`` (with a plan summary
+        for the user) instead of letting it fail closed — without ever
+        weakening the gate itself.
+        """
         d = self.deps
         auto_approve_tools = {name for name, p in d.tool_governance.items() if p["auto_approve"]}
         # Governor-managed tools never hard-block the plan: each call is
@@ -287,7 +438,26 @@ class SingleAgentRuntime:
             if s.get("action") not in auto_approve_tools
             and s.get("action") not in governed_tools
         ]
-        requires = ctx.plan.get("requires_approval", False) or bool(non_auto)
+        requires = bool(ctx.plan.get("requires_approval", False)) or bool(non_auto)
+        lines = [
+            f"{index}. {step.get('description') or step.get('action') or '?'}"
+            for index, step in enumerate(steps, start=1)
+        ]
+        summary = str(ctx.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,
+        }
+
+    def approve(self, ctx: AgentRunContext, current_user: str, *, approved_by_human: bool = False) -> None:
+        """APPROVAL: Check governance, log decision, auto-approve (future: UI prompt)."""
+        d = self.deps
+        requirements = self.approval_requirements(ctx)
+        non_auto = requirements["non_auto_steps"]
+        requires = requirements["requires_approval"]
 
         ctx.transcript.append({
             "state": AgentState.WAITING_APPROVAL.value,
@@ -330,7 +500,8 @@ class SingleAgentRuntime:
             raw = await d.generate_as(
                 model_id,
                 message="Execute the next step.",
-                context=context, max_tokens=4096, temperature=req.temperature,
+                context=context, max_tokens=self.phase_budgets.execute_tokens,
+                temperature=req.temperature,
             )
             ctx.trace.llm_call("execute", model=model_id)
             try:
@@ -557,6 +728,26 @@ class SingleAgentRuntime:
     ) -> None:
         """Role check + shared tool lifecycle, recorded on the transcript either way."""
         d = self.deps
+        sanitize_meta: Optional[Dict[str, Any]] = None
+        if name == "write_file" and isinstance(args.get("content"), str):
+            # ArtifactWritePipeline: the executor's args.content is untrusted
+            # model output. The same extract→validate→repair guarantee as the
+            # direct chat path applies here, so a weak model driving the JSON
+            # loop can never persist fenced/chatty/truncated payloads.
+            cleaned, meta = sanitize_write_content(
+                str(args.get("path") or ""), args["content"],
+                user_request=str(ctx.plan.get("goal") or thoughts or name),
+            )
+            if meta.get("sanitized"):
+                args = dict(args)
+                args["content"] = cleaned
+                sanitize_meta = meta
+                ctx.trace.repair(
+                    "execute",
+                    repairs=[
+                        "artifact_repair" if meta.get("repaired") else "artifact_sanitize"
+                    ],
+                )
         try:
             d.check_role(name, current_user)
             # Shared tool lifecycle: pre_tool (may block) → execute → post_tool.
@@ -570,6 +761,7 @@ class SingleAgentRuntime:
                 "state": AgentState.EXECUTING.value, "action": name,
                 "thoughts": thoughts, "args": args,
                 "risk": risk, "governance": dict(policy), "result": result,
+                **({"content_sanitize": sanitize_meta} if sanitize_meta else {}),
             })
         except (ToolError, KeyError, TypeError, PermissionError) as exc:
             ctx.trace.tool("execute", name=name, outcome="error", risk=risk)
@@ -616,7 +808,7 @@ class SingleAgentRuntime:
         raw = await d.generate_as(
             model_id,
             message="Review the execution transcript and return your verdict JSON.",
-            context=context, max_tokens=512, temperature=0.1,
+            context=context, max_tokens=self.phase_budgets.verify_tokens, temperature=0.1,
         )
         ctx.trace.llm_call("verify", model=model_id)
         verdict: Optional[Dict[str, Any]] = None
@@ -638,7 +830,8 @@ class SingleAgentRuntime:
             raw = await d.generate_as(
                 model_id,
                 message="Return your verdict as one strict JSON object.",
-                context=strict_context, max_tokens=512, temperature=0.0,
+                context=strict_context, max_tokens=self.phase_budgets.verify_tokens,
+                temperature=0.0,
             )
             ctx.trace.llm_call("verify", model=model_id)
             try:
@@ -788,11 +981,12 @@ class SingleAgentRuntime:
         try:
             raw = await d.generate(
                 message="Extract learnings from this completed task.",
-                context=context, max_tokens=256, temperature=0.1,
+                context=context, max_tokens=self.phase_budgets.memory_tokens, temperature=0.1,
             )
             mem = extract_action(str(raw))
-            if mem.get("save_to_knowledge") and mem.get("learnings"):
-                learnings = "\n".join(mem["learnings"])
+            kept_learnings = filter_learnings(mem.get("learnings") or [])
+            if mem.get("save_to_knowledge") and kept_learnings:
+                learnings = "\n".join(kept_learnings)
                 if d.brain_memory is not None:
                     # This runtime is LLM-driven — its learnings are real
                     # experiences and enter the brain with provenance.