ltcai 9.9.2 → 9.9.4

package/latticeai/api/automation_intelligence.py

@@ -12,11 +12,21 @@ enable), review-queue gated, local-only, and idempotent per suggestion.
 
 from __future__ import annotations
 
+import asyncio
+import os
+import time
 from typing import Any, Callable, Optional
 
 from fastapi import APIRouter, HTTPException, Request
 from pydantic import BaseModel
 
+from latticeai.services.automation_execution import (
+    build_last_execution,
+    dry_run_report,
+    enqueue_failed_execution,
+    is_automation_workflow,
+    summarize_workflow_run,
+)
 from latticeai.services.automation_intelligence import AutomationIntelligenceService
 from latticeai.services.brain_automation import find_installed_recipe_workflow
 
@@ -26,6 +36,21 @@ class SuggestionInstallRequest(BaseModel):
     enabled: bool = False
 
 
+class AutomationRunNowRequest(BaseModel):
+    workflow_id: str
+    # Dry-run first: the default reports what WOULD happen without side
+    # effects; an explicit dry_run=false runs the automation once for real.
+    dry_run: bool = True
+
+
+def _run_now_wait_seconds() -> float:
+    raw = os.environ.get("LATTICEAI_AUTOMATION_RUN_NOW_WAIT", "30")
+    try:
+        return max(0.0, min(float(raw), 300.0))
+    except (TypeError, ValueError):
+        return 30.0
+
+
 def create_automation_intelligence_router(
     *,
     service: AutomationIntelligenceService,
@@ -35,7 +60,10 @@ def create_automation_intelligence_router(
     gate_write: Callable[[Request], Optional[str]],
     append_audit_event: Callable[..., None],
     workspace_graph: Callable[[], Any],
+    run_executor: Any = None,
+    review_queue: Any = None,
 ) -> APIRouter:
+    from lattice_brain.runtime.statuses import RUN_TERMINAL_STATUSES
     from lattice_brain.workflow import legacy_steps_from_nodes, validate_definition
 
     router = APIRouter()
@@ -123,6 +151,137 @@ def create_automation_intelligence_router(
             "already_installed": False,
         }
 
+    def _stamp_last_execution(
+        workflow_id: str, last_execution: dict, scope: Optional[str]
+    ) -> None:
+        """Persist the execution record on the workflow's metadata (merge)."""
+        try:
+            store.update_workflow_definition(
+                workflow_id,
+                metadata={"last_execution": last_execution},
+                workspace_id=scope,
+            )
+        except Exception:  # noqa: BLE001 — surfacing must never undo the run
+            pass
+
+    @router.post("/api/automation/run-now")
+    async def automation_run_now(req: AutomationRunNowRequest, request: Request):
+        """Run an installed automation once — dry-run by default.
+
+        * ``dry_run=true``: deterministic report of what WOULD happen; no
+          runner executes and nothing but the ``last_execution`` stamp moves.
+        * ``dry_run=false``: one real execution through the async run
+          executor; the request waits briefly for completion, stamps the
+          result, and enqueues failed executions into the review inbox.
+        """
+        user = require_user(request)
+        scope = gate_write(request)
+        try:
+            workflow = store.get_workflow(req.workflow_id, workspace_id=scope)
+        except FileNotFoundError as exc:
+            raise HTTPException(
+                status_code=404, detail=f"Automation not found: {req.workflow_id}"
+            ) from exc
+        if not is_automation_workflow(workflow):
+            raise HTTPException(
+                status_code=404,
+                detail=f"Workflow is not an installed automation: {req.workflow_id}",
+            )
+
+        if req.dry_run:
+            report = dry_run_report(workflow)
+            last_execution = build_last_execution(
+                mode="dry_run",
+                status=report["status"],
+                summary=report["summary"],
+            )
+            _stamp_last_execution(req.workflow_id, last_execution, scope)
+            append_audit_event(
+                "automation_run_now",
+                user_email=user,
+                workflow_id=req.workflow_id,
+                dry_run=True,
+                status=report["status"],
+            )
+            return {
+                "workflow_id": req.workflow_id,
+                "dry_run": True,
+                "status": report["status"],
+                "report": report,
+                "last_execution": last_execution,
+            }
+
+        if run_executor is None:
+            raise HTTPException(
+                status_code=503,
+                detail="Automation execution runtime is not available.",
+            )
+        started = await run_executor.start_workflow(
+            workflow,
+            workflow_id=req.workflow_id,
+            user_email=user or None,
+            scope=scope,
+            inputs={"trigger": "run_now"},
+        )
+        run_id = str(((started or {}).get("run") or {}).get("id") or "")
+
+        # Bounded, non-cancelling wait: poll the durable run row so a slow
+        # execution keeps running in the background instead of being aborted.
+        run = (started or {}).get("run") or {}
+        deadline = time.monotonic() + _run_now_wait_seconds()
+        while time.monotonic() < deadline:
+            try:
+                run = store.get_workflow_run(run_id, workspace_id=scope)
+            except FileNotFoundError:
+                break
+            if str(run.get("status") or "") in RUN_TERMINAL_STATUSES:
+                break
+            await asyncio.sleep(0.05)
+
+        status = str(run.get("status") or "running")
+        completed = status in RUN_TERMINAL_STATUSES
+        summary = (
+            summarize_workflow_run(run)
+            if completed
+            else "started — still running in the background"
+        )
+        last_execution = build_last_execution(
+            mode="live",
+            status=status if completed else "running",
+            summary=summary,
+            run_id=run_id or None,
+        )
+        _stamp_last_execution(req.workflow_id, last_execution, scope)
+
+        review_item = None
+        if status == "failed":
+            review_item = enqueue_failed_execution(
+                review_queue,
+                workflow=workflow,
+                run_id=run_id or None,
+                error=summary,
+                user_email=user or None,
+                workspace_id=scope,
+            )
+        append_audit_event(
+            "automation_run_now",
+            user_email=user,
+            workflow_id=req.workflow_id,
+            dry_run=False,
+            run_id=run_id or None,
+            status=last_execution["status"],
+        )
+        payload = {
+            "workflow_id": req.workflow_id,
+            "dry_run": False,
+            "status": last_execution["status"],
+            "run_id": run_id or None,
+            "last_execution": last_execution,
+        }
+        if review_item is not None:
+            payload["review_item_id"] = review_item.get("id")
+        return payload
+
     return router
 
 

package/latticeai/api/browser.py

@@ -27,7 +27,7 @@ from fastapi import APIRouter, HTTPException, Request
 from pydantic import BaseModel
 
 from latticeai import __version__
-from lattice_brain.ingestion import IngestionItem
+from lattice_brain.ingestion import IngestionItem, capture_quality_verdict
 
 MAX_TAB_BYTES = 4 * 1024 * 1024          # 4 MB per captured tab payload
 MAX_URL_FETCH_BYTES = 4 * 1024 * 1024    # 4 MB cap on a fetched page
@@ -427,7 +427,10 @@ def create_browser_router(
             raise HTTPException(status_code=422, detail=str(exc))
         if not (text or "").strip():
             return {"status": "empty", "source_type": "web_url", "url": url,
-                    "detail": "No readable text was extracted from the page."}
+                    "detail": "No readable text was extracted from the page.",
+                    # Structured CTA (backlog #9): the extraction produced
+                    # nothing, tell the UI what the user can do about it.
+                    "capture_quality": capture_quality_verdict(None, source_type="web_url")}
         res = pipeline.ingest(
             IngestionItem(
                 source_type="web_url", title=title, text=text, source_uri=url,
@@ -435,7 +438,11 @@ def create_browser_router(
             ),
             user_email=user,
         )
-        return res.as_dict()
+        payload = res.as_dict()
+        payload["capture_quality"] = capture_quality_verdict(
+            res.extraction_quality, source_type="web_url",
+        )
+        return payload
 
     @router.post("/api/browser/ingest-current-tab")
     async def ingest_current_tab(req: IngestTabRequest, request: Request):
@@ -481,6 +488,10 @@ def create_browser_router(
             ),
             user_email=user,
         )
-        return res.as_dict()
+        payload = res.as_dict()
+        payload["capture_quality"] = capture_quality_verdict(
+            res.extraction_quality, source_type="browser_tab",
+        )
+        return payload
 
     return router

package/latticeai/api/chat.py

@@ -28,6 +28,7 @@ from latticeai.api.chat_documents import (
 )
 from latticeai.api.chat_helpers import (
     _LANG_HINT,
+    assess_answer_grounding,
     build_context_quality,
     build_recent_chat_context,
     detect_language,
@@ -44,6 +45,7 @@ from latticeai.api.chat_helpers import (
     workspace_scope_from_request,
 )
 from latticeai.api.chat_history import HistoryRouteDependencies, register_history_routes
+from latticeai.core.run_store import AgentRunStore
 from latticeai.api.chat_intents import ChatIntentController
 from latticeai.api.chat_stream import stream_chat
 from latticeai.services.app_context import AppContext
@@ -189,6 +191,12 @@ def create_chat_router(context: AppContext) -> APIRouter:
         base_dir=context.base_dir or Path.cwd(),
         agent_root=AGENT_ROOT,
         ensure_agent_root=ensure_agent_root,
+        funnel_metrics=context.funnel_metrics,
+        run_store=(
+            AgentRunStore(Path(context.data_dir) / "agent_runs")
+            if context.data_dir
+            else None
+        ),
     )
     intent_controller = ChatIntentController(
         model_router=model_router,
@@ -209,6 +217,7 @@ def create_chat_router(context: AppContext) -> APIRouter:
         agent_controller=agent_controller,
         agent_root=AGENT_ROOT,
         ingestion_pipeline=context.ingestion_pipeline,
+        funnel_metrics=context.funnel_metrics,
     )
     document_coordinator = DocumentGenerationCoordinator(
         model_router=model_router,
@@ -273,7 +282,12 @@ def create_chat_router(context: AppContext) -> APIRouter:
             )
 
         selected_model_id = request_model(req.model)
-        if is_file_action_request(req.message):
+        file_intent = is_file_action_request(req.message)
+        if file_intent and context.funnel_metrics is not None:
+            # UX funnel (backlog #16): one file-intent request counted once,
+            # regardless of which delivery path handles it below.
+            context.funnel_metrics.increment("file_requests")
+        if file_intent:
             direct_response = await intent_controller.direct_file_action(
                 req,
                 model_id=selected_model_id,
@@ -284,7 +298,7 @@ def create_chat_router(context: AppContext) -> APIRouter:
                 return direct_response
         if not selected_model_id:
             return intent_controller.no_model_response()
-        if is_file_action_request(req.message):
+        if file_intent:
             return await intent_controller.route_file_to_agent(
                 req,
                 request,
@@ -375,6 +389,12 @@ def create_chat_router(context: AppContext) -> APIRouter:
         )
         if isinstance(trace_seed, dict):
             trace_seed["context_quality"] = context_quality
+        if context.funnel_metrics is not None and int(
+            context_quality.get("nodes") or 0
+        ) > 0:
+            # UX funnel (backlog #16): a grounded answer is "first value" —
+            # the TTFV clock ends on the first successful recall.
+            context.funnel_metrics.record_recall_success()
 
         history_message = (
             f"{req.message}\n[Image attached]" if req.image_data else req.message
@@ -464,6 +484,16 @@ def create_chat_router(context: AppContext) -> APIRouter:
             req.image_data,
         )
         response_text = str(result)
+        # Answer-citation binding (backlog #11): annotate — never block — how
+        # the answer relates to the retrieved sources. Recorded on the trace
+        # so the Review/proof surfaces see the same verdict as the client.
+        grounding = assess_answer_grounding(
+            response_text,
+            trace=trace_seed if isinstance(trace_seed, dict) else None,
+            context_quality=context_quality,
+        )
+        if isinstance(trace_seed, dict):
+            trace_seed["grounding"] = grounding
         trace_record = await chat_service.persist_answer(
             question=req.message,
             response=response_text,
@@ -482,6 +512,7 @@ def create_chat_router(context: AppContext) -> APIRouter:
                 "trace_id": trace_record["id"],
                 "trace": trace_record,
                 "context_quality": context_quality,
+                "grounding": grounding,
             }
         )