ltcai 11.2.0 → 11.4.0

package/lattice_brain/runtime/__init__.py

@@ -44,7 +44,7 @@ orchestrator, and the agent runtime service. Lazy-loaded so importing
     /agents/api/runtime/* , POST /agents (start via runtime.start or executor)
   api/chat.py
     from latticeai.services.tool_dispatch import build_agent_runtime
-    -> latticeai/core/agent.py:SingleAgentRuntime (별도 state/plan/transcript 머신, single-agent /agent 경로. dispatch_tool 만 공유)
+    -> latticeai/core/agent/:SingleAgentRuntime (별도 state/plan/transcript 머신, single-agent /agent 경로. dispatch_tool 만 공유)
   latticeai/services/tool_dispatch.py:14
     from latticeai.core.agent import SingleAgentRuntime
     (tool governance + core single-agent용)

package/lattice_brain/runtime/multi_agent.py

@@ -49,7 +49,7 @@ from typing import Any, Callable, Dict, List, Optional
 from ..utils import now_iso as _now
 from .contracts import multi_agent_contract
 
-MULTI_AGENT_VERSION = "11.2.0"
+MULTI_AGENT_VERSION = "11.4.0"
 
 AGENT_ROLES = ("researcher", "planner", "executor", "reviewer", "release")
 CORE_PIPELINE = ("planner", "executor", "reviewer")

package/latticeai/__init__.py

@@ -1,3 +1,3 @@
 """Lattice AI - modular server package."""
 
-__version__ = "11.2.0"
+__version__ = "11.4.0"

package/latticeai/api/chronicle.py

@@ -0,0 +1,63 @@
+"""Brain Chronicle API router (v11.3.0, track B).
+
+Read-only surface over :class:`~latticeai.services.chronicle.ChronicleService`
+— the first HTTP exposure of the bitemporal data v11.1.0 started recording:
+
+* ``GET /api/chronicle/overview`` — the growth curve: totals, the first and
+  last thing the Brain ever saw, and one bucket per day.
+* ``GET /api/chronicle/day/{date}`` — one day's story, grouped into what came
+  in, what was learned, what was talked about, and what changed.
+* ``GET /api/chronicle/as-of?ts=…`` — the Brain as it stood at an instant.
+
+All three follow the same require_user/gate_read contract as the command
+centre, so a workspace member never reads another workspace's timeline. A
+malformed date or timestamp answers 422 through the message catalog rather
+than a 500 or a silently empty day.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from fastapi import APIRouter, Query, Request
+
+from latticeai.core.messages import http_error, resolve_language
+from latticeai.services.chronicle import ChronicleService
+
+
+def create_chronicle_router(
+    *,
+    service: ChronicleService,
+    require_user: Callable[[Request], str],
+    gate_read: Callable[[Request], Optional[str]],
+) -> APIRouter:
+    router = APIRouter()
+
+    @router.get("/api/chronicle/overview")
+    async def chronicle_overview(request: Request):
+        user = require_user(request)
+        scope = gate_read(request)
+        return service.overview(user_email=user, workspace_id=scope)
+
+    @router.get("/api/chronicle/day/{date}")
+    async def chronicle_day(date: str, request: Request):
+        user = require_user(request)
+        scope = gate_read(request)
+        try:
+            return service.day(date, user_email=user, workspace_id=scope)
+        except ValueError:
+            raise http_error(422, "chronicle.bad_date", resolve_language(request))
+
+    @router.get("/api/chronicle/as-of")
+    async def chronicle_as_of(request: Request, ts: str = Query(..., max_length=64)):
+        require_user(request)
+        scope = gate_read(request)
+        try:
+            return service.as_of(ts, workspace_id=scope)
+        except ValueError:
+            raise http_error(422, "chronicle.bad_timestamp", resolve_language(request))
+
+    return router
+
+
+__all__ = ["create_chronicle_router"]

package/latticeai/core/agent/__init__.py

@@ -0,0 +1,93 @@
+"""Single-agent runtime — the Discover→Plan→Implement→Verify state machine.
+
+This package is the deep single-agent loop: a small interface (``AgentDeps``
+ports + ``SingleAgentRuntime.run_to_completion``) over the whole role-phased
+state machine (planner → executor → critic → rollback → memory). It carries no
+FastAPI, no globals, and no I/O of its own — every collaborator is injected
+through ``AgentDeps``.
+
+Two adapters justify the seam:
+
+* production wires ``AgentDeps`` from ``latticeai.server_app``'s ``LLMRouter``, governance
+  map, audit log, and prompts;
+* tests pass fake ports (an LLM that returns canned JSON, a recording tool
+  executor) and drive a full PLAN→EXECUTE→VERIFY→DONE cycle without a server.
+
+HTTP concerns — request parsing, chat-history persistence, response shaping,
+scheduling the background memory update — stay in the app layer. This package
+only owns the state machine.
+
+v10.0.1 split the pure helpers and the state vocabulary out to sibling modules
+(``agent_state``, ``agent_helpers``, ``agent_trace``, …). v11.3.0 finished the
+job on what was left, turning the module into a package whose submodules are
+one phase each:
+
+* :mod:`.context` — ``AgentRunContext``, the state one run carries;
+* :mod:`.deps` — ``AgentDeps``, the ports;
+* :mod:`.planning` / :mod:`.execution` / :mod:`.verification` / :mod:`.recovery`
+  — the four phase mixins;
+* :mod:`.runtime` — ``SingleAgentRuntime``, which composes them and drives the
+  loop;
+* :mod:`._contract` — the typing-only seam the mixins share.
+
+Every name this module exported still resolves from ``latticeai.core.agent``.
+
+Stubbing note: a name rebound *here* changes only this module's binding — the
+submodule that calls it holds its own, so a test standing in for a collaborator
+patches the submodule that reads it.
+"""
+
+from __future__ import annotations
+
+# The state vocabulary and the pure helpers live in sibling modules so the loop
+# holds only the loop. They are re-exported (see ``__all__``) because callers —
+# the HTTP layer, run_store, the eval harness, and the tests — have always
+# imported them from here, and that contract does not change.
+from latticeai.core.agent_helpers import PhaseBudgets as PhaseBudgets
+from latticeai.core.agent_helpers import TranscriptBudget as TranscriptBudget
+from latticeai.core.agent_helpers import _truncate_strings as _truncate_strings
+from latticeai.core.agent_helpers import artifact_checklist as artifact_checklist
+from latticeai.core.agent_helpers import compact_transcript as compact_transcript
+from latticeai.core.agent_helpers import extract_action as extract_action
+from latticeai.core.agent_helpers import (
+    extract_action_details as extract_action_details,
+)
+from latticeai.core.agent_helpers import files_written as files_written
+from latticeai.core.agent_helpers import filter_learnings as filter_learnings
+from latticeai.core.agent_helpers import (
+    format_artifact_checklist as format_artifact_checklist,
+)
+from latticeai.core.agent_helpers import (
+    format_requirement_coverage as format_requirement_coverage,
+)
+from latticeai.core.agent_helpers import normalize_plan as normalize_plan
+from latticeai.core.agent_helpers import requirement_coverage as requirement_coverage
+from latticeai.core.agent_state import AGENT_TERMINAL_STATES as AGENT_TERMINAL_STATES
+from latticeai.core.agent_state import AgentState as AgentState
+
+from .context import AgentRunContext as AgentRunContext
+from .deps import AgentDeps as AgentDeps
+from .runtime import SingleAgentRuntime as SingleAgentRuntime
+
+__all__ = [
+    # this module
+    "AgentDeps",
+    "AgentRunContext",
+    "SingleAgentRuntime",
+    # re-exported from agent_state
+    "AGENT_TERMINAL_STATES",
+    "AgentState",
+    # re-exported from agent_helpers
+    "PhaseBudgets",
+    "TranscriptBudget",
+    "artifact_checklist",
+    "compact_transcript",
+    "extract_action",
+    "extract_action_details",
+    "files_written",
+    "filter_learnings",
+    "format_artifact_checklist",
+    "format_requirement_coverage",
+    "normalize_plan",
+    "requirement_coverage",
+]

package/latticeai/core/agent/_contract.py

@@ -0,0 +1,79 @@
+"""The seam the four phase mixins share.
+
+``SingleAgentRuntime`` is assembled from the planning, execution, verification
+and recovery mixins. Each of them reads state it does not own and calls back
+into helpers defined on the runtime itself — the point of the split is that
+"how a plan is approved" and "how a tool call is gated" stop sharing a
+1,465-line file, not that they stop sharing ``self``.
+
+Typing-only, exactly like :mod:`lattice_brain.ingestion._contract`: the
+declarations below are never the implementation, so the MRO and every method
+resolution stay byte-for-byte what the single-file class had. Adding a
+cross-mixin call without declaring it here is a type error.
+"""
+
+from __future__ import annotations
+
+from typing import Any, FrozenSet, Optional
+
+from latticeai.core.agent_helpers import PhaseBudgets, TranscriptBudget
+from latticeai.core.agent_profiles import AgentProfile
+from latticeai.core.permission_mode import PermissionMode
+
+from .context import AgentRunContext
+from .deps import AgentDeps
+
+
+class AgentCore:
+    """What any phase mixin may assume about ``self``.
+
+    Never instantiated directly — see the module docstring. Members are
+    declared, not implemented: the implementation lives in ``runtime.py`` or in
+    whichever mixin owns it.
+    """
+
+    # ── State owned by SingleAgentRuntime.__init__ ───────────────────────────
+    deps: AgentDeps
+    _env_phase_budgets: Optional[PhaseBudgets]
+    _env_transcript_budget: Optional[TranscriptBudget]
+
+    # ── runtime.py: budgets, resolved from deps or the environment once ──────
+    @property
+    def phase_budgets(self) -> PhaseBudgets:
+        raise NotImplementedError
+
+    @property
+    def transcript_budget(self) -> TranscriptBudget:
+        raise NotImplementedError
+
+    # ── runtime.py: the autonomy dial every gate in one run agrees on ────────
+    def resolve_permission_mode(
+        self,
+        ctx: Optional[AgentRunContext] = None,
+        *,
+        user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+    ) -> PermissionMode:
+        raise NotImplementedError
+
+    # ── runtime.py: change-governance classification helpers ─────────────────
+    def _governed_tools(self) -> FrozenSet[str]:
+        raise NotImplementedError
+
+    def _governed_path_exists(self, name: str, path: str) -> bool:
+        raise NotImplementedError
+
+    # ── runtime.py: how hard the loop works to keep this model on contract ───
+    def profile_for(self, model_id: Optional[str]) -> AgentProfile:
+        raise NotImplementedError
+
+    # ── runtime.py: advisory telemetry every phase emits ─────────────────────
+    def _emit_step(
+        self, ctx: AgentRunContext, phase: str, event: str, **details: Any
+    ) -> None:
+        raise NotImplementedError
+
+    # ── runtime.py: project-session prompt block, or "" for a standalone run ─
+    @staticmethod
+    def _project_block(ctx: AgentRunContext) -> str:
+        raise NotImplementedError

package/latticeai/core/agent/context.py

@@ -0,0 +1,57 @@
+"""The mutable state one agent run carries from phase to phase.
+
+Every phase reads and writes this object and nothing else: the loop itself is
+stateless, so a run is exactly what its :class:`AgentRunContext` says it is.
+``__slots__`` is deliberate — a typo'd attribute is an error, not a silently
+ignored write that a later phase never sees.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+
+from latticeai.core.agent_state import AgentState
+from latticeai.core.agent_trace import LoopTrace
+
+
+class AgentRunContext:
+    """Mutable state carrier passed through all agent phases."""
+    __slots__ = ("state", "plan", "transcript", "retry_count",
+                 "state_history", "corrections", "final_message", "rollback_log",
+                 "executing_model", "reviewing_model", "approved_by_human", "trace",
+                 "on_step", "project_context", "permission_mode",
+                 "self_model_summary")
+
+    def __init__(self) -> None:
+        self.state:           AgentState   = AgentState.IDLE
+        self.trace:           LoopTrace    = LoopTrace()
+        self.plan:            dict         = {}
+        self.transcript:      list         = []
+        self.retry_count:     int          = 0
+        self.state_history:   list         = []
+        self.corrections:     list         = []
+        self.final_message:   str          = ""
+        self.rollback_log:    list         = []
+        self.executing_model: Optional[str] = None
+        self.reviewing_model: Optional[str] = None
+        self.approved_by_human: bool       = False
+        # Per-run step observer (review Wave 1.1): the HTTP layer attaches a
+        # callback here so live SSE clients see progress while EXECUTING.
+        # Never serialized; a broken observer never breaks the loop.
+        self.on_step: Optional[Callable[[Dict[str, Any]], None]] = None
+        # Multi-turn project loop (v9.9.6): a prompt block describing where the
+        # project stands — files already produced, open TODOs, the last honest
+        # verification. Empty for a standalone run, which behaves exactly as
+        # before. Set by the HTTP layer, read by plan/execute/verify.
+        self.project_context: str = ""
+        # Autonomy dial resolved once per run (v9.9.8). The HTTP layer stamps
+        # the user/workspace-scoped mode here so the plan gate and every
+        # per-tool gate in the same run agree; ``None`` falls back to the
+        # process-wide resolver on ``deps``.
+        self.permission_mode: Optional[str] = None
+        # Self-Model summary resolved once per run (v11.2.0). The executor
+        # prompt is rebuilt on every turn of the loop; reading the profile
+        # once and reusing it keeps a graph query off that hot path — and
+        # keeps every turn of one run describing the same person. ``None``
+        # means "not resolved yet"; ``""`` is a resolved, empty profile.
+        self.self_model_summary: Optional[str] = None

package/latticeai/core/agent/deps.py

@@ -0,0 +1,125 @@
+"""The ports the state machine needs from the outside world.
+
+Everything the loop touches is declared here, which is what lets the whole
+PLAN→EXECUTE→VERIFY cycle run against fakes: production wires these from the
+app layer's router, governance map, audit log and prompts; tests pass an LLM
+that returns canned JSON and a recording tool executor.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Awaitable, Callable, Dict, FrozenSet, Mapping, Optional
+
+from latticeai.core.agent_helpers import PhaseBudgets, TranscriptBudget
+from latticeai.core.agent_profiles import AgentProfile
+
+
+@dataclass
+class AgentDeps:
+    """The ports a :class:`SingleAgentRuntime` needs from the outside world.
+
+    Everything the state machine touches is here, so the loop can be exercised
+    against fakes. See module docstring for the two-adapter rationale.
+    """
+
+    # ── LLM port ─────────────────────────────────────────────────────
+    # generate_as(model_id, message, context, max_tokens, temperature) -> str
+    generate_as: Callable[..., Awaitable[Any]]
+    # generate(message, context, max_tokens, temperature) -> str
+    generate: Callable[..., Awaitable[Any]]
+
+    # ── tool port ────────────────────────────────────────────────────
+    execute_tool: Callable[[str, dict], dict]
+    policy_for: Callable[[str, dict], Mapping[str, Any]]   # name, args -> policy
+    risk_level: Callable[[Any], str]               # policy -> "low"|"medium"|"high"
+    check_role: Callable[[str, str], None]         # tool_name, user -> raises if not allowed
+    tool_governance: Mapping[str, Mapping[str, Any]]  # name -> policy (auto_approve set)
+    file_create_actions: FrozenSet[str]
+
+    # ── context / memory / audit ports ───────────────────────────────
+    recent_chat_context: Callable[..., str]        # (conversation_id=...) -> str
+    clear_history: Callable[[int], dict]
+    knowledge_save: Callable[..., Any]
+    audit: Callable[..., None]                     # (event, **kw) -> None
+
+    # ── prompts + config ─────────────────────────────────────────────
+    planner_prompt: str
+    executor_prompt: str
+    critic_prompt: str
+    memory_updater_prompt: str
+    agent_root: Path
+
+    # ── rollback port (optional) ─────────────────────────────────────
+    # Production injects this from the tool dispatch service so this pure
+    # state machine does not shell out directly. Tests can pass a recorder.
+    rollback_file: Optional[Callable[[str], Dict[str, Any]]] = None
+
+    # ── snapshot rollback ports (optional, review L7) ────────────────
+    # git-only rollback left non-git workspaces and newly created files
+    # unrecoverable. ``snapshot_file(path)`` captures pre-write state
+    # ({"existed", "content", "too_large"}) before a file-create action;
+    # ``restore_snapshot(path, content)`` restores it (content=None deletes
+    # a file the run created). Both are production-wired with workspace
+    # path safety; tests pass recorders.
+    snapshot_file: Optional[Callable[[str], Dict[str, Any]]] = None
+    restore_snapshot: Optional[Callable[[str, Optional[str]], Dict[str, Any]]] = None
+
+    # ── lifecycle hooks port (optional) ──────────────────────────────
+    # When present, every tool execution fires the shared pre_tool/post_tool
+    # lifecycle, so the agent tool path no longer bypasses hooks.
+    hooks: Any = None
+
+    # ── brain memory port (optional) ─────────────────────────────────
+    # When present, completed-run learnings become typed Experience records
+    # through the unified ingestion pipeline (with provenance), replacing
+    # the vault markdown dump.
+    brain_memory: Any = None
+
+    # ── change governor port (optional) ──────────────────────────────
+    # When present, file writes are classified centrally: additive creates
+    # run with minimal friction, while mutations/deletions of existing
+    # content are staged as review proposals instead of applied. The port is
+    # ``review(name, args, policy=..., user_email=..., workspace_id=...)``
+    # 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
+
+    # ── transcript shaping (optional) ────────────────────────────────
+    # Executor/critic prompt window caps. None reads the environment once;
+    # tests inject a fixed TranscriptBudget.
+    transcript_budget: Optional["TranscriptBudget"] = None
+
+    # ── step observer port (optional) ────────────────────────────────
+    # Default per-runtime observer for live step events; a per-run observer
+    # can also be attached on AgentRunContext.on_step. Both are advisory.
+    on_step: Optional[Callable[[Dict[str, Any]], None]] = None
+
+    # ── agent profile (optional, v9.9.7) ─────────────────────────────
+    # How hard the loop works to keep a weak model on contract. None selects
+    # per-run from the executing model id (``profile_for_model``); tests
+    # inject a fixed profile.
+    agent_profile: Optional["AgentProfile"] = None
+
+    # ── permission mode port (optional, v9.9.8) ──────────────────────
+    # The autonomy dial. Either a static mode, or a resolver callable that
+    # accepts ``user_email``/``workspace_id`` scope kwargs (preferred) or no
+    # arguments at all — see ``call_mode_source``. ``None`` means strict,
+    # which is exactly the pre-9.9.8 behaviour.
+    permission_mode: Any = None
+
+    # ── Self-Model port (optional, v11.2.0) ──────────────────────────
+    # What the Brain has learned about its owner, injected into the executor
+    # prompt. Either a fixed string or a resolver callable taking
+    # ``user_email``/``workspace_id`` scope kwargs (or none at all). 11.1.0
+    # built ``executor_prompt_for(self_model_summary=…)`` and then had nothing
+    # to pass it, because the runtime held its executor prompt as a fixed
+    # string; this is the port that was missing. ``None`` — and an empty
+    # summary — produce exactly the prompt bytes the loop produced before it
+    # existed.
+    self_model_summary: Any = None