pal-code 0.1.0__py3-none-any.whl

pal/__init__.py

@@ -0,0 +1,29 @@
+"""Pal: a model-agnostic chat layer that cuts tokens and latency.
+
+Importing the package is cheap on purpose. The older `Pipeline` (which pulls in the compression
+stack: nltk, spacy, ...) is loaded only if you ask for it.
+"""
+from importlib import import_module
+from importlib.metadata import PackageNotFoundError, version
+
+
+def _version() -> str:
+    for name in ("pal-code", "pal-ai", "pal-aios"):      # the current name first, then earlier ones
+        try:
+            return version(name)
+        except PackageNotFoundError:
+            continue
+    return "0.1.0"           # a source checkout that is not installed
+
+
+__version__ = _version()
+
+__all__ = ["Pipeline", "WrapperConfig", "__version__"]
+
+_LAZY = {"Pipeline": "pal.pipeline", "WrapperConfig": "pal.llm_wrapper.components.base"}
+
+
+def __getattr__(name: str):
+    if name in _LAZY:
+        return getattr(import_module(_LAZY[name]), name)
+    raise AttributeError(f"module 'pal' has no attribute {name!r}")

pal/__main__.py

@@ -0,0 +1,3 @@
+from pal.terminal.cli import main
+
+raise SystemExit(main())

pal/access_manager/__init__.py

@@ -0,0 +1,16 @@
+from pal.access_manager.components.access_control import AccessController
+from pal.access_manager.components.base import DESTRUCTIVE_OPS, AccessDecision, AccessRequest, OperationType
+from pal.access_manager.components.intervention import UserInterventionGate
+from pal.access_manager.components.privilege_registry import PrivilegeRegistry
+from pal.access_manager.pipeline import AccessManagerPipeline
+
+__all__ = [
+    "AccessManagerPipeline",
+    "AccessDecision",
+    "AccessRequest",
+    "DESTRUCTIVE_OPS",
+    "OperationType",
+    "AccessController",
+    "UserInterventionGate",
+    "PrivilegeRegistry",
+]

pal/access_manager/components/__init__.py

@@ -0,0 +1,14 @@
+from pal.access_manager.components.access_control import AccessController
+from pal.access_manager.components.base import DESTRUCTIVE_OPS, AccessDecision, AccessRequest, OperationType
+from pal.access_manager.components.intervention import UserInterventionGate
+from pal.access_manager.components.privilege_registry import PrivilegeRegistry
+
+__all__ = [
+    "AccessController",
+    "AccessDecision",
+    "AccessRequest",
+    "DESTRUCTIVE_OPS",
+    "OperationType",
+    "UserInterventionGate",
+    "PrivilegeRegistry",
+]

pal/access_manager/components/access_control.py

@@ -0,0 +1,41 @@
+"""
+Privilege-based access control (AIOS section 3.8): validates a
+cross-agent access request against the privilege-group hashmap BEFORE
+execution -- an agent may only access another agent's resources if
+both are assigned to the same shared privilege domain. An agent acting
+on its OWN resources is always permitted regardless of privilege group
+(3.8 is specifically about cross-agent data access; a resource owner
+always has access to what it owns).
+"""
+from pal.access_manager.components.base import DESTRUCTIVE_OPS, AccessDecision, AccessRequest
+from pal.access_manager.components.privilege_registry import PrivilegeRegistry
+
+
+class AccessController:
+    def __init__(self, registry: PrivilegeRegistry):
+        self.registry = registry
+
+    def check(self, request: AccessRequest) -> AccessDecision:
+        requires_confirmation = request.operation in DESTRUCTIVE_OPS
+
+        if request.requesting_agent_id == request.target_agent_id:
+            return AccessDecision(allowed=True, requires_confirmation=requires_confirmation)
+
+        if self.registry.same_group(request.requesting_agent_id, request.target_agent_id):
+            return AccessDecision(allowed=True, requires_confirmation=requires_confirmation)
+
+        group_a = self.registry.group_of(request.requesting_agent_id)
+        group_b = self.registry.group_of(request.target_agent_id)
+        if group_a is None or group_b is None:
+            unassigned = [
+                aid for aid, g in ((request.requesting_agent_id, group_a), (request.target_agent_id, group_b))
+                if g is None
+            ]
+            reason = f"agent(s) not assigned a privilege group: {unassigned}"
+        else:
+            reason = (
+                f"'{request.requesting_agent_id}' (group '{group_a}') is not in the same "
+                f"privilege group as '{request.target_agent_id}' (group '{group_b}')"
+            )
+
+        return AccessDecision(allowed=False, requires_confirmation=requires_confirmation, reason=reason)

pal/access_manager/components/base.py

@@ -0,0 +1,39 @@
+"""
+Access request/decision shapes for the Access Manager (AIOS section
+3.8). An AccessRequest always names both the requesting agent and the
+agent whose resource is being touched -- when they're the same agent,
+there's nothing cross-agent to regulate, only user-intervention (for
+destructive ops) applies.
+"""
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+
+class OperationType(str, Enum):
+    READ = "read"
+    WRITE = "write"
+    DELETE = "delete"
+    OVERWRITE = "overwrite"
+    PRIVILEGE_MODIFY = "privilege_modify"
+
+
+# "irreversible operations (deletion, overwrite, privilege modification)"
+DESTRUCTIVE_OPS = {OperationType.DELETE, OperationType.OVERWRITE, OperationType.PRIVILEGE_MODIFY}
+
+
+@dataclass
+class AccessRequest:
+    requesting_agent_id: str
+    target_agent_id: str   # whose resource is being accessed -- equal to
+                            # requesting_agent_id for an agent acting on
+                            # its own data
+    operation: OperationType
+    resource: str = ""     # a key, tool name, or other resource descriptor -- for logging/audit only
+
+
+@dataclass
+class AccessDecision:
+    allowed: bool
+    requires_confirmation: bool
+    reason: Optional[str] = None

pal/access_manager/components/intervention.py

@@ -0,0 +1,31 @@
+"""
+User intervention interface (AIOS section 3.8): irreversible operations
+(deletion, overwrite, privilege modification) require explicit user
+confirmation before proceeding, even when privilege-based access
+control alone would permit them.
+
+The actual UI a real deployment asks the user through (a CLI prompt, a
+web confirmation dialog, ...) is out of scope for this project -- what
+this implements is the gate itself: a pluggable confirmation_handler
+callback the surrounding application registers. The default handler
+denies everything, safely, rather than silently approving destructive
+operations when no real confirmation UI has been wired up.
+"""
+from typing import Callable, Optional
+
+from pal.access_manager.components.base import AccessRequest
+
+
+def _default_deny_handler(request: AccessRequest) -> bool:
+    return False
+
+
+class UserInterventionGate:
+    def __init__(self, confirmation_handler: Optional[Callable[[AccessRequest], bool]] = None):
+        self.confirmation_handler = confirmation_handler or _default_deny_handler
+
+    def set_handler(self, handler: Callable[[AccessRequest], bool]) -> None:
+        self.confirmation_handler = handler
+
+    def confirm(self, request: AccessRequest) -> bool:
+        return bool(self.confirmation_handler(request))

pal/access_manager/components/privilege_registry.py

@@ -0,0 +1,30 @@
+"""
+Privilege-group hashmap (AIOS section 3.8): agent_id -> privilege
+group, enforced by AccessController before any cross-agent access is
+permitted. Each agent is assigned to exactly one group; agents sharing
+a group are in the same "privilege domain" and may access each other's
+resources.
+"""
+from typing import Optional
+
+
+class PrivilegeRegistry:
+    def __init__(self):
+        self._groups: dict[str, str] = {}
+
+    def assign(self, agent_id: str, group: str) -> None:
+        self._groups[agent_id] = group
+
+    def group_of(self, agent_id: str) -> Optional[str]:
+        return self._groups.get(agent_id)
+
+    def same_group(self, agent_a: str, agent_b: str) -> bool:
+        group_a = self.group_of(agent_a)
+        group_b = self.group_of(agent_b)
+        return group_a is not None and group_a == group_b
+
+    def revoke(self, agent_id: str) -> None:
+        self._groups.pop(agent_id, None)
+
+    def all_assignments(self) -> dict[str, str]:
+        return dict(self._groups)

pal/access_manager/pipeline.py

@@ -0,0 +1,68 @@
+"""
+Access Manager (AIOS section 3.8): privilege-based access control for
+cross-agent resource access (components/privilege_registry.py,
+components/access_control.py), plus a user-intervention gate for
+irreversible operations (components/intervention.py).
+"""
+from typing import Callable, Optional
+
+from pal.access_manager.components.access_control import AccessController
+from pal.access_manager.components.base import AccessDecision, AccessRequest, OperationType
+from pal.access_manager.components.intervention import UserInterventionGate
+from pal.access_manager.components.privilege_registry import PrivilegeRegistry
+
+
+class AccessManagerPipeline:
+    def __init__(self, confirmation_handler: Optional[Callable[[AccessRequest], bool]] = None):
+        self.registry = PrivilegeRegistry()
+        self.controller = AccessController(self.registry)
+        self.intervention = UserInterventionGate(confirmation_handler)
+
+    def assign_privilege_group(self, agent_id: str, group: str) -> None:
+        self.registry.assign(agent_id, group)
+
+    def set_confirmation_handler(self, handler: Callable[[AccessRequest], bool]) -> None:
+        self.intervention.set_handler(handler)
+
+    def check_access(
+        self, requesting_agent_id: str, target_agent_id: str, operation: OperationType, resource: str = ""
+    ) -> AccessDecision:
+        """Privilege check only -- does not trigger user intervention,
+        even for a destructive operation. Use authorize() for the full
+        gate."""
+        request = AccessRequest(
+            requesting_agent_id=requesting_agent_id,
+            target_agent_id=target_agent_id,
+            operation=operation,
+            resource=resource,
+        )
+        return self.controller.check(request)
+
+    def authorize(
+        self, requesting_agent_id: str, target_agent_id: str, operation: OperationType, resource: str = ""
+    ) -> AccessDecision:
+        """Full authorization: privilege check first, then -- only if
+        that passed AND the operation is destructive -- user
+        confirmation. Returns one AccessDecision reflecting both
+        checks: a privilege-permitted destructive op the user declines
+        to confirm comes back allowed=False, not the privilege-only
+        result."""
+        request = AccessRequest(
+            requesting_agent_id=requesting_agent_id,
+            target_agent_id=target_agent_id,
+            operation=operation,
+            resource=resource,
+        )
+        decision = self.controller.check(request)
+
+        if not decision.allowed:
+            return decision
+
+        if decision.requires_confirmation and not self.intervention.confirm(request):
+            return AccessDecision(
+                allowed=False,
+                requires_confirmation=True,
+                reason="user declined confirmation for an irreversible operation",
+            )
+
+        return decision

pal/access_manager/utils/__init__.py

@@ -0,0 +1,2 @@
+"""No shared utilities yet for access_manager -- reserved for future
+helpers (e.g. loading privilege-group assignments from a config file)."""

pal/agent_constraints/__init__.py

@@ -0,0 +1,3 @@
+from pal.agent_constraints.pipeline import AgentConstraintsPipeline, with_agent_constraints
+
+__all__ = ["AgentConstraintsPipeline", "with_agent_constraints"]

pal/agent_constraints/components/AGENT_OUTPUT.md

@@ -0,0 +1,13 @@
+Output short. No fluff. No intro. No outro.
+
+Bad: "Sure! Happy to help. Issue likely caused by..."
+Good: "Bug in auth middleware."
+
+Give exactly what user ask. Yes/no question: answer "yes" or "no" only. No extra text.
+
+Code: fewest lines possible. No comments unless asked.
+No em dash in output.
+No options unless asked. Give one answer.
+Do not run code unless asked. If output already given, do not run.
+Opinion only if asked or needed.
+No question at end. Never ask "want me to do X or Y?"

pal/agent_constraints/components/__init__.py

@@ -0,0 +1,3 @@
+from pal.agent_constraints.components.constraints import load_agent_constraints
+
+__all__ = ["load_agent_constraints"]

pal/agent_constraints/components/constraints.py

@@ -0,0 +1,22 @@
+"""
+Permanent behavior-constraint document, not a text-processing function.
+
+The insight: trimming output AFTER the model generates it only saves
+what gets displayed/logged -- the model already paid the generation
+cost (and, for API backends, the billed cost) for every verbose token.
+Instructing the model up front to be terse means fewer output tokens
+get generated in the first place. That's a strictly better lever than
+post-hoc compression, so this is wired in as a permanent addition to
+every system prompt.
+"""
+from pathlib import Path
+
+_CONSTRAINTS_FILE = Path(__file__).parent / "AGENT_OUTPUT.md"
+
+
+def load_agent_constraints() -> str:
+    """Returns the permanent output-behavior constraints as text, ready
+    to append to any system prompt."""
+    if not _CONSTRAINTS_FILE.exists():
+        return ""
+    return _CONSTRAINTS_FILE.read_text(encoding="utf-8").strip()

pal/agent_constraints/pipeline.py

@@ -0,0 +1,22 @@
+from pal.agent_constraints.components.constraints import load_agent_constraints
+
+
+class AgentConstraintsPipeline:
+    def with_constraints(self, system_prompt: str) -> str:
+        """Merges the permanent output-behavior constraints into a given
+        system prompt. Idempotent-ish: if the constraints text is
+        already present (e.g. called twice on the same prompt), it
+        isn't duplicated."""
+        constraints = load_agent_constraints()
+        if not constraints:
+            return system_prompt
+        if constraints in system_prompt:
+            return system_prompt
+        return f"{system_prompt}\n\n{constraints}"
+
+
+# Module-level convenience, mirroring the old with_agent_constraints()
+# free function so callers that just need the one operation don't have
+# to instantiate the pipeline.
+def with_agent_constraints(system_prompt: str) -> str:
+    return AgentConstraintsPipeline().with_constraints(system_prompt)

pal/agent_constraints/utils/__init__.py

@@ -0,0 +1,2 @@
+"""No shared utilities yet for agent_constraints -- reserved for future
+constraint-set variants (e.g. per-task-type constraint documents)."""

pal/agents/__init__.py

@@ -0,0 +1,12 @@
+"""The agent application layer. Only agents live here.
+
+Everything an agent needs (spec type, base class, ReAct and Reflexion patterns, framework adapters) is in
+`pal.sdk`. Add an agent by adding a NativeAgent subclass with a spec and listing it below.
+"""
+from pal.agents.coding import CodingAgent
+from pal.agents.docs import DocumentationAgent
+from pal.sdk.agent import NativeAgent
+
+AGENTS: dict[str, type[NativeAgent]] = {a.spec.id: a for a in (CodingAgent, DocumentationAgent) if a.spec}
+
+__all__ = ["AGENTS", "CodingAgent", "DocumentationAgent"]

pal/agents/coding.py

@@ -0,0 +1,14 @@
+from pal.sdk.agent import AgentSpec, NativeAgent
+
+
+class CodingAgent(NativeAgent):
+    """Explains, reviews and writes code from an attached source zip (code graph + read-only source tool)."""
+
+    spec = AgentSpec(
+        id="coding", name="Coding agent",
+        description="Explains, reviews and writes code. Attach a source zip and ask about it.",
+        role="Role: coding agent. Answer only from the supplied code, graph excerpts and files; say so if something "
+             "is not there. Give minimal, correct code in fenced blocks and name the file. Explain only what was asked.",
+        key_env="GEMINI_API_KEY_CODING",
+        tools=frozenset({"read_source", "search_documents", "read_document", "find_usages", "search_source", "list_project_files",
+                         "query_code_graph", "build_code_graph", "file_to_markdown"}))

pal/agents/docs.py

@@ -0,0 +1,15 @@
+from pal.sdk.agent import AgentSpec, NativeAgent
+
+
+class DocumentationAgent(NativeAgent):
+    """Writes README, API reference and docstrings strictly from the code or text it is given."""
+
+    spec = AgentSpec(
+        id="docs", name="Documentation agent",
+        description="Writes README, API reference and docstrings from code or text you attach.",
+        role="Role: documentation agent. Write accurate, concise markdown documentation (README, API reference, "
+             "docstrings, changelog) strictly from the supplied code or text. Never invent behaviour: mark unknowns "
+             "as TODO. Use headings and short sentences.",
+        key_env="GEMINI_API_KEY_DOCS", max_tokens=1536,
+        tools=frozenset({"read_source", "search_documents", "read_document", "document_outline", "list_project_files", "search_source",
+                         "save_file", "query_code_graph", "build_code_graph", "file_to_markdown"}))

pal/chat/__init__.py

@@ -0,0 +1,4 @@
+from pal.chat.providers import API_PROVIDERS, build_api_core
+from pal.chat.service import ChatService, TurnResult
+
+__all__ = ["API_PROVIDERS", "ChatService", "TurnResult", "build_api_core"]

pal/chat/demo.py

@@ -0,0 +1,231 @@
+"""The experiment tab's demo: the same 6 messages, sent two ways, measured.
+
+  naive  : what a plain chat client does. Full history every turn (attachments included), the raw
+           message, no output rules, every message to the API model.
+  pal : ChatService.send() with everything on (routing, input savers, direct answers, document
+           index, paging, output rules).
+
+Both arms use the same API model and count the tokens the provider itself reports. Latency is
+wall-clock time per turn; Pal's includes the local-model time, so a slow local model can make
+Pal *slower* on some turns, and the summary says so instead of hiding it. Demo turns read and
+write no memory and are not added to the Stats.
+"""
+from __future__ import annotations
+
+import threading
+import time
+import uuid
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from typing import Any
+
+from pal.chat.service import ChatService
+from pal.errors import NotFoundError, UserInputError
+from pal.llm_wrapper.components.base import LLMSyscall
+
+SURVEY_NAME = "student-survey.md"
+SURVEY = """# Papertrail student survey (120 students, 4 campuses)
+
+## Who answered
+- 120 students: 58 undergraduates, 41 master's students, 21 PhD students.
+- 71% take notes on a laptop, 19% on a tablet, 10% on paper only.
+- 64% use more than one note app today; the most common are Google Docs (62%), Notion (38%) and OneNote (27%).
+
+## What they dislike about current tools
+- Finding old notes is the top complaint: 57% say they often cannot find a note they wrote last semester.
+- 41% say syncing between phone and laptop fails at least once a month.
+- 33% say the tools are too complicated for lecture notes and slow to open in class.
+- 18% say subscription prices are too high for a student budget.
+
+## What they would pay
+- 46% would pay nothing for a note app.
+- 38% would pay up to 3 dollars a month.
+- 12% would pay 3 to 6 dollars a month.
+- 4% would pay more than 6 dollars a month.
+- 72% say a free tier with a paid upgrade is what they prefer.
+
+## Where they hear about new apps
+- Instagram: 61%. Student WhatsApp and Telegram groups: 48%.
+- Campus posters and notice boards: 35%. Friends and classmates: 33%.
+- Reddit: 22%. Email newsletters from the university: 14%. TikTok: 12%.
+
+## Features they asked for most
+- Search that also finds words inside handwriting and photos of slides: 52%.
+- Works offline in lecture halls: 44%.
+- Share a notebook with a study group: 39%.
+- Turn notes into flashcards: 27%.
+
+## Quotes
+- "I write everything down and then never find it again."
+- "I would try anything that opens instantly and does not need a login."
+- "I only download new apps when three friends already use them."
+"""
+
+STEPS: list[dict[str, Any]] = [
+    {"message": "Hi there! So, I was basically wondering if you could please help me plan a small launch for "
+                "my new note-taking app called Papertrail. It is really just for students, and I would like to "
+                "keep the whole thing under a budget of 500 dollars, if that is at all possible.",
+     "route": "api"},
+    {"message": "Thanks so much. Here are my survey notes, please just read them and tell me the three most "
+                "important things that students say.",
+     "attach": True, "route": "api"},
+    {"message": "what is 500*0.35", "route": None},
+    {"message": "Quick question, what does ROI stand for?", "route": None},
+    {"message": "Given the survey notes and the budget, could you please suggest the three channels that I "
+                "should focus on, and roughly how to split the 500 dollars between them?",
+     "route": "api"},
+    {"message": "Great, now please put everything together into a one page launch brief for Papertrail: goal, "
+                "audience, budget split, channels, an email subject line, and a first week timeline.",
+     "route": "api"},
+]
+
+_MAX_RUNS = 20
+_TTL = 3600.0
+_NAIVE_SYSTEM_NOTE = ""  # a naive client adds nothing to the base prompt: no output rules
+
+
+@dataclass
+class _Run:
+    id: str
+    sid: str
+    provider: str
+    model: str
+    naive_history: list[dict] = field(default_factory=list)
+    steps: list[dict] = field(default_factory=list)
+    local: dict = field(default_factory=dict)
+    created: float = field(default_factory=time.time)
+    lock: threading.Lock = field(default_factory=threading.Lock)
+
+
+def _public_steps() -> list[dict]:
+    return [{"message": s["message"], "attachment": SURVEY_NAME if s.get("attach") else None} for s in STEPS]
+
+
+class Demo:
+    def __init__(self, service: ChatService):
+        self.service = service
+        self._runs: OrderedDict[str, _Run] = OrderedDict()
+        self._lock = threading.Lock()
+
+    # -- lifecycle ---------------------------------------------------------------------------------
+    def start(self, provider: str, model: str, api_key: str | None) -> dict:
+        self.service.api_core(provider, model, api_key)  # fail fast on a bad provider, model or missing key
+        run = _Run(id=uuid.uuid4().hex, sid=f"demo-{uuid.uuid4().hex[:24]}", provider=provider, model=model,
+                   local=self.service.local_status())
+        with self._lock:
+            self._expire()
+            self._runs[run.id] = run
+            while len(self._runs) > _MAX_RUNS:
+                _, old = self._runs.popitem(last=False)
+                self.service.reset(old.sid)
+        return {"run_id": run.id, "steps": _public_steps(), "local": run.local}
+
+    def _expire(self) -> None:
+        now = time.time()
+        for k in [k for k, r in self._runs.items() if now - r.created > _TTL]:
+            self.service.reset(self._runs.pop(k).sid)
+
+    def _get(self, run_id: str) -> _Run:
+        with self._lock:
+            run = self._runs.get(run_id)
+        if run is None:
+            raise NotFoundError("demo run not found or expired: start it again")
+        return run
+
+    def cancel(self, run_id: str) -> None:
+        with self._lock:
+            run = self._runs.pop(run_id, None)
+        if run:
+            self.service.reset(run.sid)
+
+    # -- one step ---------------------------------------------------------------------------------------------
+    def step(self, run_id: str, api_key: str | None) -> dict:
+        run = self._get(run_id)
+        with run.lock:
+            i = len(run.steps)
+            if i >= len(STEPS):
+                raise UserInputError("the demo already finished")
+            spec = STEPS[i]
+            api = self.service.api_core(run.provider, run.model, api_key)
+
+            # naive arm: full history, raw message, the file re-sent every time it is in the history
+            user_text = spec["message"] + (f"\n\n[file: {SURVEY_NAME}]\n{SURVEY}" if spec.get("attach") else "")
+            messages = [{"role": "system", "content": self.service.settings.base_system_prompt}]
+            messages += run.naive_history + [{"role": "user", "content": user_text}]
+            t0 = time.perf_counter()
+            try:
+                resp = api.chat(LLMSyscall(messages=messages, max_tokens=2048))
+            except Exception as e:  # noqa: BLE001
+                from pal.errors import ProviderError
+                secret = getattr(getattr(api, "config", None), "api_key", None) or ""
+                text = str(e).replace(secret, "***") if secret else str(e)
+                raise ProviderError(f"naive arm: {type(e).__name__}: {text}") from e
+            naive = {"input_tokens": resp.prompt_tokens or 0, "output_tokens": resp.completion_tokens or 0,
+                     "latency": round(time.perf_counter() - t0, 3), "reply": resp.text or ""}
+
+            # Pal arm: the real service, on its own throwaway session
+            attachments = [{"name": SURVEY_NAME, "text": SURVEY, "kind": "document"}] if spec.get("attach") else []
+            res = self.service.send(run.sid, run.provider, run.model, api_key, spec["message"], attachments,
+                                    None, route=spec["route"], ephemeral=True)
+            pal = {"route": res.handled_by, "reason": res.route_reason, "input_tokens": res.input_tokens,
+                      "output_tokens": res.output_tokens, "latency": res.latency.get("total", 0.0),
+                      "latency_local": res.latency.get("local", 0.0), "latency_api": res.latency.get("api", 0.0),
+                      "tools": [t["name"] for t in res.tools], "reply": res.reply,
+                      "reduced_tokens_saved": getattr(res.saver, "tokens_saved", 0),
+                      "history_turns_sent": (res.context or {}).get("turns_sent"),
+                      "history_tokens_saved": (res.context or {}).get("tokens_saved", 0),
+                      "document_chunks": (res.documents or {}).get("chunks", 0)}
+
+            # commit only after both arms succeeded, so a retry of this step stays consistent
+            run.naive_history += [{"role": "user", "content": user_text},
+                                  {"role": "assistant", "content": naive["reply"]}]
+            row = {"step": i + 1, "message": spec["message"], "naive": naive, "pal": pal}
+            run.steps.append(row)
+            out: dict[str, Any] = {"row": row, "done": len(run.steps) == len(STEPS)}
+            if out["done"]:
+                out["summary"] = self._summary(run)
+                self.cancel(run.id)
+            return out
+
+    # -- totals ---------------------------------------------------------------------------------------------------
+    @staticmethod
+    def _pct(saved: float, base: float) -> float:
+        return round(100 * saved / base, 1) if base else 0.0
+
+    def _summary(self, run: _Run) -> dict:
+        rows = run.steps
+        n_in = sum(r["naive"]["input_tokens"] for r in rows)
+        n_out = sum(r["naive"]["output_tokens"] for r in rows)
+        m_in = sum(r["pal"]["input_tokens"] for r in rows)
+        m_out = sum(r["pal"]["output_tokens"] for r in rows)
+        n_lat = sum(r["naive"]["latency"] for r in rows)
+        m_lat = sum(r["pal"]["latency"] for r in rows)
+        routes = [r["pal"]["route"] for r in rows]
+        saved_tokens = (n_in + n_out) - (m_in + m_out)
+        saved_lat = n_lat - m_lat
+        local_ok = run.local.get("ok")
+        notes = []
+        if local_ok is False:
+            notes.append("The local model was not reachable, so input reduction and local answering did not run. "
+                         "The saving below comes from direct answers, the output rules and document handling only. "
+                         "Start Ollama and run the demo again to see the full effect.")
+        if saved_lat < 0:
+            notes.append("Pal was slower overall: the local model's time is included, and on a slow machine it "
+                         "can cost more than it saves.")
+        notes.append("Pal's output rules make replies shorter, which is part of the token saving and also "
+                     "changes the style of the answers.")
+        return {
+            "naive": {"input_tokens": n_in, "output_tokens": n_out, "total_tokens": n_in + n_out,
+                      "latency": round(n_lat, 2), "api_calls": len(rows)},
+            "pal": {"input_tokens": m_in, "output_tokens": m_out, "total_tokens": m_in + m_out,
+                       "latency": round(m_lat, 2),
+                       "api_calls": sum(1 for r in routes if r == "api"),
+                       "local_answers": routes.count("local"), "direct_answers": routes.count("tool"),
+                       "tool_calls": sum(len(r["pal"]["tools"]) for r in rows)},
+            "tokens_saved": saved_tokens, "tokens_saved_pct": self._pct(saved_tokens, n_in + n_out),
+            "input_saved": n_in - m_in, "output_saved": n_out - m_out,
+            "latency_saved": round(saved_lat, 2), "latency_saved_pct": self._pct(saved_lat, n_lat),
+            "api_calls_avoided": len(rows) - sum(1 for r in routes if r == "api"),
+            "local": run.local, "notes": notes,
+            "result": rows[-1]["pal"]["reply"], "result_naive": rows[-1]["naive"]["reply"],
+        }