algo-cli-runtime 0.14.0__py3-none-any.whl

algo_cli/reasoning/tree_of_thought.py

@@ -0,0 +1,241 @@
+"""Tree-of-Thoughts (ToT) Reasoning.
+
+Explores multiple reasoning paths as a tree with:
+- BFS: Breadth-first exploration of K best thoughts per level
+- DFS: Depth-first with backtracking on dead ends
+- MCTS: Monte Carlo Tree Search integration (delegates to mcts.py)
+
+Each thought is evaluated by a value function (LLM-based or heuristic).
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from ..chat_protocol import get_attr
+
+
+class SearchStrategy(Enum):
+    BFS = "bfs"
+    DFS = "dfs"
+
+
+@dataclass
+class ThoughtNode:
+    """A node in the Tree-of-Thought."""
+    thought: str
+    value: float  # 0.0-1.0 evaluation score
+    depth: int
+    children: list["ThoughtNode"] = field(default_factory=list)
+    parent: "ThoughtNode | None" = field(default=None, repr=False)
+    state: str = ""  # accumulated reasoning state
+    visited: bool = False
+    pruned: bool = False
+    timestamp: float = field(default_factory=time.time)
+
+    @property
+    def is_leaf(self) -> bool:
+        return len(self.children) == 0
+
+    @property
+    def path_from_root(self) -> list["ThoughtNode"]:
+        """Walk up to root, return path from root to this node."""
+        path = []
+        node: ThoughtNode | None = self
+        while node is not None:
+            path.append(node)
+            node = node.parent
+        path.reverse()
+        return path
+
+    def reasoning_chain(self) -> str:
+        """Human-readable chain from root to this node."""
+        nodes = self.path_from_root
+        return "\n".join(f"Step {i+1} (val={n.value:.2f}): {n.thought}" for i, n in enumerate(nodes))
+
+
+EVALUATION_PROMPT = """Evaluate this reasoning step on a scale of 0.0 to 1.0.
+
+Consider:
+- Logical soundness: Is this step valid reasoning?
+- Progress: Does it advance toward solving the task?
+- Novelty: Does it add new information or just restate?
+
+Respond with just a number between 0.0 and 1.0."""
+
+GENERATION_PROMPT = """Given the current reasoning state, generate {n} distinct next thoughts.
+
+Current state:
+{state}
+
+Task: {task}
+
+Generate {n} different reasoning steps. Each should pursue a different approach.
+Format as JSON array: [{{"thought": "...", "state": "updated reasoning state"}}]"""
+
+
+@dataclass
+class TreeOfThought:
+    """Tree-of-Thought reasoner."""
+    strategy: SearchStrategy = SearchStrategy.BFS
+    max_depth: int = 4
+    branch_factor: int = 3
+    value_threshold: float = 0.3  # Prune nodes below this score
+
+    root: ThoughtNode | None = None
+    best_leaf: ThoughtNode | None = None
+    best_score: float = 0.0
+    nodes_explored: int = 0
+
+    def _evaluate(self, thought: str, client: Any, model: str) -> float:
+        """Use LLM to evaluate a thought's quality."""
+        messages = [
+            {"role": "system", "content": EVALUATION_PROMPT},
+            {"role": "user", "content": f"Reasoning step: {thought}\n\nRate this step."},
+        ]
+        try:
+            response = client.chat(model=model, messages=messages, stream=False)
+            text = get_attr(get_attr(response, "message", {}), "content", "").strip()
+            # Parse score
+            import re
+            m = re.search(r"([0-9]*\.?[0-9]+)", text)
+            if m:
+                return max(0.0, min(1.0, float(m.group(1))))
+        except Exception:
+            pass
+        return 0.5
+
+    def _generate_thoughts(
+        self, task: str, state: str, n: int, client: Any, model: str,
+    ) -> list[tuple[str, str]]:
+        """Generate n candidate next thoughts using LLM."""
+        prompt = GENERATION_PROMPT.format(n=n, state=state[:2000], task=task)
+        messages = [
+            {"role": "system", "content": "You are a reasoning step generator. Be diverse and creative."},
+            {"role": "user", "content": prompt},
+        ]
+        try:
+            response = client.chat(model=model, messages=messages, stream=False, format="json")
+            text = get_attr(get_attr(response, "message", {}), "content", "")
+            parsed = json.loads(text)
+            if isinstance(parsed, list):
+                results = []
+                for item in parsed[:n]:
+                    if isinstance(item, dict):
+                        results.append((str(item.get("thought", "")), str(item.get("state", state))))
+                return results
+        except (json.JSONDecodeError, ValueError, TypeError):
+            pass
+        # Fallback: single thought
+        return [(state + " (continue reasoning)", state)]
+
+    def _bfs(self, task: str, client: Any, model: str) -> ThoughtNode | None:
+        """BFS search: expand K best nodes at each depth level."""
+        if not self.root:
+            return None
+        current_level = [self.root]
+        for depth in range(self.max_depth):
+            if not current_level:
+                break
+            next_level: list[ThoughtNode] = []
+            for node in current_level:
+                if node.pruned:
+                    continue
+                candidates = self._generate_thoughts(
+                    task, node.state, self.branch_factor, client, model,
+                )
+                for thought, state in candidates:
+                    value = self._evaluate(thought, client, model)
+                    child = ThoughtNode(
+                        thought=thought, value=value, depth=depth + 1,
+                        parent=node, state=state,
+                    )
+                    node.children.append(child)
+                    self.nodes_explored += 1
+                    if value >= self.value_threshold:
+                        next_level.append(child)
+                    else:
+                        child.pruned = True
+                    if value > self.best_score:
+                        self.best_score = value
+                        self.best_leaf = child
+            # Keep top-K for next level
+            next_level.sort(key=lambda n: n.value, reverse=True)
+            current_level = next_level[:self.branch_factor]
+        return self.best_leaf
+
+    def _dfs(self, task: str, client: Any, model: str) -> ThoughtNode | None:
+        """DFS with backtracking: explore promising paths first."""
+        if not self.root:
+            return None
+        stack = [self.root]
+        while stack and self.nodes_explored < self.max_depth * self.branch_factor * 2:
+            node = stack.pop()
+            if node.depth >= self.max_depth or node.pruned:
+                continue
+            candidates = self._generate_thoughts(
+                task, node.state, self.branch_factor, client, model,
+            )
+            children = []
+            for thought, state in candidates:
+                value = self._evaluate(thought, client, model)
+                child = ThoughtNode(
+                    thought=thought, value=value, depth=node.depth + 1,
+                    parent=node, state=state,
+                )
+                node.children.append(child)
+                self.nodes_explored += 1
+                if value > self.best_score:
+                    self.best_score = value
+                    self.best_leaf = child
+                if value >= self.value_threshold:
+                    children.append(child)
+            # Push best children first for DFS
+            children.sort(key=lambda n: n.value, reverse=True)
+            stack.extend(children)
+        return self.best_leaf
+
+
+def run_tot(
+    *,
+    task: str,
+    client: Any,
+    model: str,
+    strategy: str = "bfs",
+    max_depth: int = 4,
+    branch_factor: int = 3,
+    value_threshold: float = 0.3,
+    initial_state: str = "",
+) -> TreeOfThought:
+    """Run a Tree-of-Thought search.
+
+    Args:
+        task: The reasoning task.
+        client: Ollama client.
+        model: Model name for evaluation and generation.
+        strategy: "bfs" or "dfs".
+        max_depth: Maximum tree depth.
+        branch_factor: Number of candidate thoughts per node.
+        value_threshold: Minimum score to keep a thought.
+        initial_state: Starting reasoning state.
+
+    Returns:
+        The TreeOfThought with best_leaf set to the highest-scoring path.
+    """
+    strat = SearchStrategy(strategy.lower())
+    tot = TreeOfThought(
+        strategy=strat,
+        max_depth=max_depth,
+        branch_factor=branch_factor,
+        value_threshold=value_threshold,
+    )
+    tot.root = ThoughtNode(thought="(root)", value=1.0, depth=0, state=initial_state or task)
+    if strat == SearchStrategy.BFS:
+        tot._bfs(task, client, model)
+    else:
+        tot._dfs(task, client, model)
+    return tot

algo_cli/reasoning_bridge.py

@@ -0,0 +1,150 @@
+"""Bridge the reasoning/* algorithms into the everyday chat loop.
+
+Historically the Tree/Graph/MCTS/Reflexion/QCR algorithms were only reachable
+from the agent *pipeline*; the chat loop the user lives in was plain ReAct, so
+``/reason tot`` (etc.) changed a flag nothing in chat read. This module runs a
+"reasoning preflight": when reasoning chat mode is enabled and the active
+``reasoning_mode`` is not plain react, it runs the selected algorithm to produce
+a short strategy artifact and returns it as a guidance block. The chat loop
+injects that block into the turn (same pattern as RAG/intuition/ICL injection)
+so the model executes against an algorithm-derived plan.
+
+Design constraints:
+- Best-effort: any failure returns "" and the turn proceeds as plain ReAct.
+- These algorithms make several model calls, so the preflight is gated on the
+  user explicitly opting in (reasoning_chat_enabled) AND choosing a non-react
+  mode. It produces a *plan*, not tool execution — the main loop still owns
+  tool calls, approvals, and safety.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from .config import Config
+
+logger = logging.getLogger(__name__)
+
+_PLAN_HEADER = "## Reasoning Plan ({mode})"
+_PLAN_FOOTER = (
+    "\nUse the plan above as strategy guidance only. Verify with tools before "
+    "acting; it is not proof of any fact."
+)
+_MAX_PLAN_CHARS = 2000
+
+
+def _safe_chain(obj: Any, *attrs: str) -> str:
+    """Pull the first available human-readable chain/text off a result object."""
+    for attr in attrs:
+        value = getattr(obj, attr, None)
+        if callable(value):
+            try:
+                value = value()
+            except Exception:
+                continue
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+        # node-like with reasoning_chain()
+        chain = getattr(value, "reasoning_chain", None)
+        if callable(chain):
+            try:
+                text = chain()
+                if isinstance(text, str) and text.strip():
+                    return text.strip()
+            except Exception:
+                continue
+    return ""
+
+
+def _plan_for_mode(mode: str, task: str, client: Any, model: str, cfg: Config) -> str:
+    from . import reasoning
+
+    depth = max(1, int(getattr(cfg, "reasoning_depth", 4)))
+    branches = max(1, int(getattr(cfg, "reasoning_branches", 3)))
+
+    if mode == "reflexion":
+        episodes = reasoning.run_reflexion_loop(
+            task=task, client=client, model=model,
+            max_attempts=max(1, int(getattr(cfg, "reasoning_reflexion_attempts", 3))),
+        )
+        if episodes:
+            best_episode = max(episodes, key=lambda episode: getattr(episode, "score", 0.0))
+            return (
+                f"Best attempt (score {getattr(best_episode, 'score', 0.0):.2f}):\n"
+                f"{getattr(best_episode, 'output', '')}"
+            )
+        return ""
+
+    if mode == "tot":
+        tot = reasoning.run_tot(
+            task=task, client=client, model=model,
+            max_depth=depth, branch_factor=branches,
+        )
+        return _safe_chain(tot, "best_leaf")
+
+    if mode == "got":
+        got = reasoning.run_got(
+            task=task, client=client, model=model,
+            max_rounds=depth, branch_factor=branches,
+        )
+        return _safe_chain(got, "best_vertex", "best_leaf")
+
+    if mode == "mcts":
+        reasoner = reasoning.run_mcts(
+            task=task, client=client, model=model,
+            max_depth=depth, branch_factor=branches,
+        )
+        # MCTSReasoner exposes root; best leaf chain is the robust conclusion.
+        root = getattr(reasoner, "root", None)
+        if root is not None and hasattr(root, "best_leaf"):
+            try:
+                return root.best_leaf().reasoning_chain()
+            except Exception:
+                pass
+        return _safe_chain(reasoner, "best_leaf")
+
+    if mode == "qcr":
+        result = reasoning.run_qcr_aggregation(
+            task=task, client=client, model=model,
+            n_samples=max(1, int(getattr(cfg, "reasoning_qcr_samples", 5))),
+        )
+        # returns (best, candidates, meta)
+        if isinstance(result, tuple) and result:
+            best = result[0]
+            return str(best) if best else ""
+        return ""
+
+    # neuro_symbolic / hybrid: no generic symbolic verifier to supply here, so
+    # we skip rather than fabricate one. The pipeline path still supports them.
+    return ""
+
+
+def maybe_reasoning_plan(cfg: Config, client: Any, user_message: str) -> str:
+    """Return a guidance block for the active reasoning mode, or "" to skip.
+
+    Skips when: chat reasoning is disabled, mode is react/neuro_symbolic/hybrid,
+    the message is trivial, or the algorithm errors/returns nothing.
+    """
+    if not getattr(cfg, "reasoning_chat_enabled", False):
+        return ""
+    mode = str(getattr(cfg, "reasoning_mode", "react") or "react").lower()
+    if mode in {"react", "neuro_symbolic", "hybrid"}:
+        return ""
+    task = (user_message or "").strip()
+    if len(task) < 12:  # trivial prompt; not worth a multi-call preflight
+        return ""
+    model = str(getattr(cfg, "model", "") or "")
+    if not model:
+        return ""
+    try:
+        plan = _plan_for_mode(mode, task, client, model, cfg)
+    except Exception as exc:
+        logger.debug("Reasoning preflight (%s) failed: %s", mode, exc)
+        return ""
+    plan = (plan or "").strip()
+    if not plan:
+        return ""
+    if len(plan) > _MAX_PLAN_CHARS:
+        plan = plan[:_MAX_PLAN_CHARS].rstrip() + "…"
+    return f"{_PLAN_HEADER.format(mode=mode)}\n{plan}{_PLAN_FOOTER}"

algo_cli/reconciliation.py

@@ -0,0 +1,284 @@
+"""Task-local reasoning guidance for conflicting structured sources."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from collections import deque
+from pathlib import Path
+from typing import Any
+
+from .chat_protocol import normalize_tool_call
+
+
+_AUTHORITY_CUES = ("authoritative", "source of truth", "live files", "live manifest")
+_STALE_CUES = ("stale", "retrieved context", "retrieved memory", "rag", "lower authority")
+_STRUCTURED_CUES = ("settings", "config", "manifest", "json", "yaml", "structured")
+_RECONCILIATION_MESSAGE_WINDOW = 128
+
+
+def guidance_for_prompt(prompt: str) -> str | None:
+    """Return a compact reconciliation algorithm only for clear conflict tasks."""
+
+    lowered = (prompt or "").casefold()
+    if not all(
+        any(cue in lowered for cue in family)
+        for family in (_AUTHORITY_CUES, _STALE_CUES, _STRUCTURED_CUES)
+    ):
+        return None
+    return (
+        "Use provenance-aware structured reconciliation:\n"
+        "1. Establish source priority from the task and inspect the authoritative, target, and lower-authority sources.\n"
+        "2. Preserve the target schema. Trace each existing target value to matching facts in the stale and authoritative sources; key names may differ across schemas.\n"
+        "3. Replace every stale semantic slot with its authoritative counterpart. Do not leave the stale value in place or merely append a source-named duplicate.\n"
+        "4. Turn every required field, objective assertion, and artifact-content requirement into a checklist. Confirm each exact authoritative value appears where required, then run fail-on-mismatch verification."
+        "\n5. Treat negative artifact requirements strictly: if stale values must not be included or presented as facts, omit the literal stale values even from comparison sections; describe the overridden categories without quoting obsolete values."
+    )
+
+
+def _normalized_field(value: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "_", value.casefold()).strip("_")
+
+
+def _read_records(messages: list[dict[str, Any]]) -> list[tuple[str, str]]:
+    """Pair read results with their model-requested paths."""
+
+    pending: deque[tuple[str, str | None]] = deque()
+    records: list[tuple[str, str]] = []
+    for message in messages[-_RECONCILIATION_MESSAGE_WINDOW:]:
+        if message.get("role") == "assistant":
+            for call in message.get("tool_calls") or ():
+                name, args = normalize_tool_call(call)
+                if name == "read_file":
+                    pending.append((str(args.get("path") or ""), str(call.get("id") or "") or None))
+            continue
+        if message.get("role") != "tool" or message.get("name") != "read_file":
+            continue
+        call_id = str(message.get("tool_call_id") or "") or None
+        path = ""
+        if call_id:
+            for index, (candidate_path, candidate_id) in enumerate(pending):
+                if candidate_id == call_id:
+                    path = candidate_path
+                    del pending[index]
+                    break
+        elif pending:
+            path, _candidate_id = pending.popleft()
+        records.append((path, str(message.get("content") or "")))
+    return records
+
+
+def _json_objects(messages: list[dict[str, Any]]) -> list[tuple[str, dict[str, Any]]]:
+    objects: list[tuple[str, dict[str, Any]]] = []
+    for path, content in _read_records(messages):
+        try:
+            value = json.loads(content)
+        except (TypeError, json.JSONDecodeError):
+            continue
+        if isinstance(value, dict):
+            objects.append((path, value))
+    return objects
+
+
+def _stale_label(text: str, value: str) -> str | None:
+    pattern = re.compile(
+        rf"([A-Za-z][A-Za-z _/-]{{1,40}}?)\s+[`\"']?{re.escape(value)}(?:[`\"']|\b)",
+        re.IGNORECASE,
+    )
+    matches = list(pattern.finditer(text))
+    if not matches:
+        return None
+    label = matches[-1].group(1).strip().rsplit(" and ", 1)[-1]
+    return _normalized_field(label)
+
+
+def _lineage_replacements(
+    messages: list[dict[str, Any]],
+    stale_text: str,
+) -> list[tuple[str, str, str, str, str]]:
+    objects = _json_objects(messages)
+    authoritative = next(
+        (
+            (path, obj)
+            for path, obj in objects
+            if any(
+                isinstance(value, str)
+                and ("source of truth" in value.casefold() or "authoritative" in value.casefold())
+                for value in obj.values()
+            )
+        ),
+        None,
+    )
+    if authoritative is None:
+        return []
+    _authoritative_path, authoritative_object = authoritative
+    authority_by_field = {
+        _normalized_field(str(key)): value for key, value in authoritative_object.items()
+    }
+    replacements: list[tuple[str, str, str, str, str]] = []
+    for target_path, target in objects:
+        if target is authoritative_object:
+            continue
+        for target_key, old_value in target.items():
+            if not isinstance(old_value, str) or old_value not in stale_text:
+                continue
+            label = _stale_label(stale_text, old_value)
+            if not label:
+                continue
+            authority_key = next(
+                (
+                    key
+                    for key in authority_by_field
+                    if key == label or key.endswith(f"_{label}") or label.endswith(f"_{key}")
+                ),
+                None,
+            )
+            if authority_key is None:
+                continue
+            new_value = authority_by_field[authority_key]
+            if isinstance(new_value, str) and new_value != old_value:
+                replacements.append(
+                    (target_path, str(target_key), old_value, authority_key, new_value)
+                )
+    return list(dict.fromkeys(replacements))
+
+
+def lineage_guidance(messages: list[dict[str, Any]], stale_text: str) -> str | None:
+    """Infer cross-schema replacements by tracing target values to stale labels."""
+
+    replacements = _lineage_replacements(messages, stale_text)
+    if not replacements:
+        return None
+    lines = [
+        f"- Keep target key `{target_key}` and set its value to authoritative `{new_value}` "
+        f"because its current `{old_value}` value matches the stale `{authority_key}` fact. "
+        f"Do not remove or rename `{target_key}`, and do not add `{authority_key}` as a duplicate."
+        for _target_path, target_key, old_value, authority_key, new_value in replacements
+    ]
+    return (
+        "[Algo provenance inference]\n"
+        "Cross-schema value lineage found:\n"
+        + "\n".join(lines)
+        + "\nDo not retain those stale target values or add duplicate source-named keys."
+    )
+
+
+def lineage_constraints(
+    messages: list[dict[str, Any]],
+) -> list[tuple[str, str, str, str, str]]:
+    """Recover unique provenance constraints from recent read results."""
+
+    constraints: list[tuple[str, str, str, str, str]] = []
+    for _path, text in _read_records(messages):
+        constraints.extend(_lineage_replacements(messages, text))
+    return list(dict.fromkeys(constraints))
+
+
+_STALE_VALUE_PATTERNS = tuple(
+    re.compile(pattern, re.IGNORECASE)
+    for pattern in (
+        r"\bproject(?:\s+name)?(?:\s+is)?\s+([^,.\n]+)",
+        r"\bapproval\s+ticket\s+([^,.\n]+)",
+        r"\bstatus\s+endpoint\s+([^,.\n]+)",
+        r"\bfeature\s+flag\s+([^,.\n]+)",
+        r"\boperations\s+contact\s+([^,.\n]+)",
+        r"\bgo-live\s+date(?:/window)?\s+([^,.\n]+)",
+    )
+)
+
+
+def _stale_fact_values(messages: list[dict[str, Any]]) -> list[str]:
+    values: list[str] = []
+    for _path, text in _read_records(messages):
+        source_text = text.split("\n\n[Algo ", 1)[0]
+        lowered = source_text.casefold()
+        if (
+            "stale" not in lowered
+            or "claim" not in lowered
+            or not any(cue in lowered for cue in ("rag", "cache", "lower authority"))
+        ):
+            continue
+        for pattern in _STALE_VALUE_PATTERNS:
+            for match in pattern.finditer(source_text):
+                value = match.group(1).strip().strip(".`'\"")
+                if value:
+                    values.append(value)
+    return list(dict.fromkeys(values))
+
+
+def structured_write_violation(
+    name: str,
+    args: dict[str, Any],
+    messages: list[dict[str, Any]],
+) -> str | None:
+    """Reject full-object JSON writes that violate inferred target-schema lineage."""
+
+    if name not in {"write_file", "edit_file"}:
+        return None
+    raw = args.get("content") if name == "write_file" else args.get("new_string")
+    write_path = str(args.get("path") or "")
+    write_name = Path(write_path).name.casefold()
+    if name == "write_file" and write_name:
+        explicit_omission = any(
+            "do not include stale" in str(message.get("content") or "").casefold()
+            and write_name in str(message.get("content") or "").casefold()
+            for message in messages[-_RECONCILIATION_MESSAGE_WINDOW:]
+        )
+        if explicit_omission:
+            stale_present = [value for value in _stale_fact_values(messages) if value in str(raw or "")]
+            if stale_present:
+                return (
+                    "Artifact omission invariant blocked this write: the task says not to include stale "
+                    "values in the summary. Omit the literal stale values entirely, including in comparison "
+                    f"or 'not facts' sections. Present: {', '.join(stale_present[:6])}. Describe the "
+                    "overridden categories generically and include only authoritative values."
+                )
+    try:
+        candidate = json.loads(str(raw or ""))
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(candidate, dict):
+        return None
+    normalized_write_path = os.path.normcase(os.path.normpath(write_path))
+    for target_path, target_key, old_value, authority_key, new_value in lineage_constraints(messages):
+        if not target_path or os.path.normcase(os.path.normpath(target_path)) != normalized_write_path:
+            continue
+        if candidate.get(target_key) != new_value:
+            return (
+                "Provenance invariant blocked this structured write: preserve target schema by "
+                f"keeping `{target_key}` and setting its value to `{new_value}`. Do not remove or "
+                f"rename `{target_key}`, and do not substitute a new `{authority_key}` key."
+            )
+    return None
+
+
+def augment_read_result(
+    name: str,
+    result: str,
+    *,
+    messages: list[dict[str, Any]] | None = None,
+) -> str:
+    """Attach guidance when a newly read task/file reveals a source conflict."""
+
+    if name != "read_file":
+        return result
+    additions = []
+    guidance = guidance_for_prompt(result)
+    if guidance is not None:
+        additions.append(f"[Algo reasoning strategy]\n{guidance}")
+    lineage = lineage_guidance(messages or [], result)
+    if lineage is not None:
+        additions.append(lineage)
+    if not additions:
+        return result
+    return f"{result}\n\n" + "\n\n".join(additions)
+
+
+__all__ = [
+    "augment_read_result",
+    "guidance_for_prompt",
+    "lineage_constraints",
+    "lineage_guidance",
+    "structured_write_violation",
+]