mana-agent 0.0.16__py3-none-any.whl

mana_agent/__init__.py

@@ -0,0 +1,6 @@
+"""mana_agent package."""
+
+from mana_agent._version import get_version
+
+__all__ = ["__version__"]
+__version__ = get_version()

mana_agent/_version.py

@@ -0,0 +1,46 @@
+"""Single-source package version resolution from pyproject.toml."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+
+_DIST_NAME = "mana-agent"
+
+
+def _read_pyproject_version(start: Path) -> str | None:
+    """Walk parents from *start* and return ``[project].version`` if present."""
+    for directory in (start, *start.parents):
+        path = directory / "pyproject.toml"
+        if not path.is_file():
+            continue
+        try:
+            import tomllib
+
+            data = tomllib.loads(path.read_text(encoding="utf-8"))
+            version = data.get("project", {}).get("version")
+            if isinstance(version, str) and version.strip():
+                return version.strip()
+        except Exception:
+            continue
+    return None
+
+
+@lru_cache(maxsize=1)
+def get_version() -> str:
+    """Return the package version.
+
+    Preference order:
+    1. ``[project].version`` from the nearest ``pyproject.toml`` (source tree).
+    2. Installed distribution metadata for ``mana-agent``.
+    3. ``\"dev\"`` when neither is available.
+    """
+    from_pyproject = _read_pyproject_version(Path(__file__).resolve().parent)
+    if from_pyproject:
+        return from_pyproject
+    try:
+        from importlib.metadata import version
+
+        return version(_DIST_NAME)
+    except Exception:
+        return "dev"

mana_agent/agent/__init__.py

@@ -0,0 +1,13 @@
+"""Agent flow primitives shared by ManaAgent orchestration paths."""
+
+from mana_agent.agent.orchestrator import AgentOrchestrator
+from mana_agent.agent.task_classifier import TaskDecision, classify_task
+from mana_agent.agent.verification_planner import VerificationDecision, plan_verification
+
+__all__ = [
+    "AgentOrchestrator",
+    "TaskDecision",
+    "VerificationDecision",
+    "classify_task",
+    "plan_verification",
+]

mana_agent/agent/evaluation_gate.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any, Literal
+
+from mana_agent.agent.evidence_queue import EvidenceQueue
+from mana_agent.agent.task_classifier import TaskDecision
+
+
+class AgentRunPhase(str, Enum):
+    RECEIVED = "RECEIVED"
+    CLASSIFIED = "CLASSIFIED"
+    PLANNED = "PLANNED"
+    GATHERING_EVIDENCE = "GATHERING_EVIDENCE"
+    READY_TO_MUTATE = "READY_TO_MUTATE"
+    MUTATING = "MUTATING"
+    VERIFYING = "VERIFYING"
+    READY_TO_FINALIZE = "READY_TO_FINALIZE"
+    DONE = "DONE"
+    FAILED_RECOVERABLE = "FAILED_RECOVERABLE"
+    FAILED_FINAL = "FAILED_FINAL"
+
+
+ExecutionDecision = Literal[
+    "execute_next_tool",
+    "skip_tool",
+    "stop_discovery",
+    "start_mutation",
+    "run_verification",
+    "ask_user",
+    "finalize",
+    "abort_due_to_error",
+]
+
+
+@dataclass(slots=True)
+class AgentRunState:
+    phase: AgentRunPhase = AgentRunPhase.RECEIVED
+    files_read: set[str] = field(default_factory=set)
+    changed_files: set[str] = field(default_factory=set)
+    failed_tool_calls: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    verification_status: str = ""
+    loop_counters: dict[str, int] = field(default_factory=dict)
+    evidence_sufficient: bool = False
+    mutation_succeeded: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class GateResult:
+    decision: ExecutionDecision
+    reason: str
+    next_action: str = ""
+    confidence: float = 0.8
+    warnings: tuple[str, ...] = ()
+
+    def trace_row(self, *, changed_files: list[str] | None = None) -> dict[str, Any]:
+        return {
+            "layer": "evaluation_gate",
+            "decision": self.decision,
+            "reason": self.reason,
+            "next_action": self.next_action,
+            "confidence": self.confidence,
+            "changed_files": list(changed_files or []),
+            "warnings": list(self.warnings),
+        }
+
+
+class EvaluationGate:
+    def __init__(self, *, repo_root: str | Path, max_repeated_tool: int = 1, max_repeated_error: int = 1) -> None:
+        self.repo_root = Path(repo_root).resolve()
+        self.max_repeated_tool = max(1, int(max_repeated_tool))
+        self.max_repeated_error = max(1, int(max_repeated_error))
+
+    def target_section_found(self, decision: TaskDecision, *, path: str) -> bool:
+        if not decision.target_sections:
+            return True
+        target = self.repo_root / path
+        try:
+            text = target.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            return False
+        headings = {
+            " ".join(line.lstrip("#").strip().split()).lower()
+            for line in text.splitlines()
+            if line.lstrip().startswith("#")
+        }
+        return any(section.lower() in headings for section in decision.target_sections)
+
+    def evidence_is_sufficient(
+        self,
+        *,
+        decision: TaskDecision,
+        state: AgentRunState,
+    ) -> bool:
+        if decision.scope == "single_file_section" and decision.target_files:
+            target = decision.target_files[0]
+            return target in state.files_read and self.target_section_found(decision, path=target)
+        if decision.scope == "single_file" and decision.target_files:
+            return decision.target_files[0] in state.files_read
+        if decision.scope == "multi_file" and decision.target_files:
+            return set(decision.target_files).issubset(state.files_read)
+        return False
+
+    def after_tool(
+        self,
+        *,
+        decision: TaskDecision,
+        state: AgentRunState,
+        evidence_queue: EvidenceQueue,
+        tool_name: str,
+        ok: bool,
+        files_read: list[str],
+        changed_files: list[str],
+        error: str = "",
+    ) -> GateResult:
+        key = f"{tool_name}:{','.join(files_read or changed_files)}"
+        state.loop_counters[key] = state.loop_counters.get(key, 0) + 1
+        state.files_read.update(files_read)
+        state.changed_files.update(changed_files)
+        if error:
+            state.failed_tool_calls.append(error)
+        if not ok and error and state.failed_tool_calls.count(error) > self.max_repeated_error:
+            state.phase = AgentRunPhase.FAILED_RECOVERABLE
+            return GateResult("abort_due_to_error", f"repeated tool error stopped: {error}", confidence=0.9)
+        if state.loop_counters[key] > self.max_repeated_tool and tool_name:
+            return GateResult("skip_tool", f"repeated tool call stopped: {tool_name}", confidence=0.9)
+        for path in files_read:
+            evidence_queue.mark_done("read", path, evidence={"source": "tool"})
+        state.evidence_sufficient = self.evidence_is_sufficient(decision=decision, state=state)
+        if state.evidence_sufficient and decision.needs_mutation:
+            skipped = evidence_queue.skip_where(
+                lambda item: item.action_type in {"search", "read"} and item.target not in decision.target_files,
+                reason="target evidence is sufficient",
+            )
+            state.phase = AgentRunPhase.READY_TO_MUTATE
+            return GateResult(
+                "start_mutation",
+                "target file was read and requested section exists; unrelated discovery is optional",
+                next_action="apply_patch",
+                confidence=0.91,
+                warnings=(f"skipped_pending_discovery:{skipped}",) if skipped else (),
+            )
+        if changed_files and decision.needs_verification:
+            state.phase = AgentRunPhase.VERIFYING
+            return GateResult("run_verification", "mutation changed files; verification is now possible")
+        if changed_files:
+            state.phase = AgentRunPhase.READY_TO_FINALIZE
+            return GateResult("finalize", "mutation changed files and no verification was required")
+        return GateResult("execute_next_tool", "continue with the next approved tool")
+
+    def before_tool(
+        self,
+        *,
+        decision: TaskDecision,
+        state: AgentRunState,
+        tool_name: str,
+        target: str = "",
+    ) -> GateResult:
+        if state.evidence_sufficient and tool_name in {"repo_search", "repo_batch_search", "semantic_search", "list_files"}:
+            return GateResult("skip_tool", "evidence is already sufficient; broad discovery is skipped")
+        if (
+            state.evidence_sufficient
+            and tool_name == "read_file"
+            and decision.target_files
+            and target not in set(decision.target_files)
+        ):
+            return GateResult("skip_tool", "target evidence is already sufficient; unrelated read is skipped")
+        return GateResult("execute_next_tool", "tool call is necessary for the current state")
+
+
+__all__ = ["AgentRunPhase", "AgentRunState", "EvaluationGate", "ExecutionDecision", "GateResult"]

mana_agent/agent/evidence_queue.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Literal
+
+
+EvidenceAction = Literal["search", "read", "patch", "verify", "summarize"]
+EvidenceStatus = Literal["pending", "running", "done", "skipped", "failed"]
+
+
+@dataclass(slots=True)
+class EvidenceQueueItem:
+    action_type: EvidenceAction
+    target: str
+    reason: str
+    priority: int = 50
+    required: bool = False
+    status: EvidenceStatus = "pending"
+    evidence: dict[str, Any] = field(default_factory=dict)
+    changed_files: list[str] = field(default_factory=list)
+    retry_count: int = 0
+    skip_reason: str = ""
+
+
+class EvidenceQueue:
+    def __init__(self, items: list[EvidenceQueueItem] | None = None) -> None:
+        self._items = list(items or [])
+
+    def add(self, item: EvidenceQueueItem) -> None:
+        self._items.append(item)
+
+    def items(self) -> list[EvidenceQueueItem]:
+        return list(self._items)
+
+    def pending(self) -> list[EvidenceQueueItem]:
+        return [item for item in self._items if item.status == "pending"]
+
+    def mark_done(self, action_type: str, target: str, *, evidence: dict[str, Any] | None = None) -> None:
+        for item in self._items:
+            if item.action_type == action_type and item.target == target and item.status in {"pending", "running"}:
+                item.status = "done"
+                item.evidence.update(evidence or {})
+                return
+
+    def skip_where(self, predicate: Callable[[EvidenceQueueItem], bool], *, reason: str) -> int:
+        skipped = 0
+        for item in self._items:
+            if item.status == "pending" and predicate(item):
+                item.status = "skipped"
+                item.skip_reason = reason
+                skipped += 1
+        return skipped
+
+    def trace_row(self) -> dict[str, Any]:
+        return {
+            "layer": "evidence_queue",
+            "decision": "queue_state",
+            "reason": "evidence queue snapshot",
+            "items": [
+                {
+                    "action_type": item.action_type,
+                    "target": item.target,
+                    "required": item.required,
+                    "status": item.status,
+                    "skip_reason": item.skip_reason,
+                }
+                for item in self._items
+            ],
+        }
+
+
+__all__ = ["EvidenceAction", "EvidenceQueue", "EvidenceQueueItem", "EvidenceStatus"]

mana_agent/agent/flow.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from mana_agent.agent.selection import AgentPhase, select_task
+from mana_agent.agent.task_context import TaskContext
+from mana_agent.agent.verification import VerificationPlan, default_verification_plan
+
+
+FLOW_ORDER: tuple[AgentPhase, ...] = (
+    AgentPhase.DISCOVER,
+    AgentPhase.SELECT,
+    AgentPhase.READ,
+    AgentPhase.ACT,
+    AgentPhase.VERIFY,
+    AgentPhase.SUMMARIZE,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class AgentFlow:
+    context: TaskContext
+    verification: VerificationPlan
+
+
+def _short_goal(request: str) -> str:
+    cleaned = " ".join(str(request or "").split())
+    if not cleaned:
+        return "Handle the current user request."
+    return cleaned[:180]
+
+
+def _candidate_search_terms(request: str, candidate_files: tuple[str, ...]) -> tuple[str, ...]:
+    terms: list[str] = []
+    terms.extend(candidate_files[:3])
+    for match in re.findall(r"`([^`]{2,120})`", request):
+        terms.append(match.strip())
+    for match in re.findall(r"\b[A-Za-z_][A-Za-z0-9_]{2,}\b", request):
+        if match.lower() not in {"the", "and", "for", "with", "this", "that", "from", "into", "when"}:
+            terms.append(match)
+        if len(terms) >= 8:
+            break
+    seen: set[str] = set()
+    unique: list[str] = []
+    for term in terms:
+        if term and term not in seen:
+            seen.add(term)
+            unique.append(term)
+    return tuple(unique[:8])
+
+
+def _done_criteria(mode: str) -> tuple[str, ...]:
+    if mode == "plan_only":
+        return (
+            "plan includes goal, requirements, implementation steps, verification, and done criteria",
+            "no repository files are edited",
+        )
+    if mode == "analyze":
+        return (
+            "analysis is backed by repository evidence",
+            "risks and recommended next steps are explicit",
+        )
+    if mode == "verify":
+        return (
+            "relevant checks are run or a concrete blocker is reported",
+            "final response includes exact command outcomes",
+        )
+    if mode == "edit":
+        return (
+            "requested code changes are implemented",
+            "changed files are reviewed",
+            "relevant verification is run or a blocker is reported",
+        )
+    return ("the user receives a direct, useful, honest answer",)
+
+
+def build_agent_flow(
+    request: str,
+    *,
+    repo_root: str | Path | None = None,
+    explicit_mode: str | None = None,
+    candidate_files: tuple[str, ...] = (),
+    files_read: tuple[str, ...] = (),
+    flow_context: str | None = None,
+) -> AgentFlow:
+    selection = select_task(
+        request,
+        explicit_mode=explicit_mode,
+        candidate_files=candidate_files,
+        files_read=files_read,
+    )
+    verification = default_verification_plan(mode=selection.mode.value, request=request)
+    context = TaskContext(
+        request=request,
+        mode=selection.mode.value,
+        phase=selection.phase,
+        goal=_short_goal(request),
+        explicit_requirements=(request.strip(),) if request.strip() else (),
+        repo_root=Path(repo_root).resolve() if repo_root is not None else None,
+        candidate_files=selection.candidate_files,
+        files_read=tuple(files_read),
+        candidate_search_terms=_candidate_search_terms(request, selection.candidate_files),
+        done_criteria=_done_criteria(selection.mode.value),
+        verification_plan=verification.commands or verification.notes,
+        flow_context=flow_context,
+    )
+    return AgentFlow(context=context, verification=verification)

mana_agent/agent/orchestrator.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Sequence
+
+from mana_agent.agent.evaluation_gate import AgentRunPhase, AgentRunState, EvaluationGate, GateResult
+from mana_agent.agent.evidence_queue import EvidenceQueue, EvidenceQueueItem
+from mana_agent.agent.task_classifier import TaskDecision, classify_task
+from mana_agent.agent.verification_planner import VerificationDecision, plan_verification
+from mana_agent.multi_agent.runtime.execution_scope import ExecutionScopeDecision, ScopeLevel
+
+
+@dataclass(frozen=True, slots=True)
+class TaskPlan:
+    decision: TaskDecision
+    evidence_queue: EvidenceQueue
+    trace: tuple[dict[str, Any], ...] = ()
+
+
+class PlanBuilder:
+    def build(self, decision: TaskDecision) -> TaskPlan:
+        queue = EvidenceQueue()
+        if decision.needs_file_read:
+            for path in decision.target_files:
+                queue.add(
+                    EvidenceQueueItem(
+                        action_type="read",
+                        target=path,
+                        reason="explicit target file named by the user",
+                        priority=10,
+                        required=True,
+                    )
+                )
+        if decision.needs_repo_search:
+            queue.add(
+                EvidenceQueueItem(
+                    action_type="search",
+                    target="repo",
+                    reason="no explicit target file was available",
+                    priority=20,
+                    required=True,
+                )
+            )
+        if decision.needs_mutation:
+            queue.add(
+                EvidenceQueueItem(
+                    action_type="patch",
+                    target=",".join(decision.target_files) or "resolved target",
+                    reason="mutation is required after sufficient evidence",
+                    priority=80,
+                    required=True,
+                )
+            )
+        if decision.needs_verification:
+            queue.add(
+                EvidenceQueueItem(
+                    action_type="verify",
+                    target="changed files",
+                    reason="verify the requested mutation",
+                    priority=90,
+                    required=True,
+                )
+            )
+        trace = (
+            {
+                "layer": "plan_builder",
+                "decision": "minimal_plan_built",
+                "reason": "explicit targets are prioritized before repository-wide discovery",
+                "next_action": "read_file" if decision.needs_file_read else "repo_search",
+                "confidence": decision.confidence,
+            },
+            queue.trace_row(),
+        )
+        return TaskPlan(decision=decision, evidence_queue=queue, trace=trace)
+
+
+@dataclass(slots=True)
+class CriticDecision:
+    progressed: bool
+    enough_evidence: bool
+    should_finalize: bool
+    reason: str
+
+    def trace_row(self) -> dict[str, Any]:
+        return {
+            "layer": "post_tool_critic",
+            "decision": "finalize" if self.should_finalize else "continue",
+            "reason": self.reason,
+            "progressed": self.progressed,
+            "enough_evidence": self.enough_evidence,
+        }
+
+
+class PostToolCritic:
+    def review(self, *, gate: GateResult, state: AgentRunState) -> CriticDecision:
+        should_finalize = gate.decision == "finalize" or state.phase == AgentRunPhase.DONE
+        progressed = gate.decision in {"start_mutation", "run_verification", "finalize", "execute_next_tool"}
+        reason = gate.reason
+        return CriticDecision(
+            progressed=progressed,
+            enough_evidence=state.evidence_sufficient,
+            should_finalize=should_finalize,
+            reason=reason,
+        )
+
+
+@dataclass(slots=True)
+class AgentOrchestrator:
+    repo_root: Path
+    decision: TaskDecision
+    plan: TaskPlan
+    state: AgentRunState = field(default_factory=AgentRunState)
+    gate: EvaluationGate = field(init=False)
+    critic: PostToolCritic = field(default_factory=PostToolCritic)
+    trace: list[dict[str, Any]] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        self.repo_root = Path(self.repo_root).resolve()
+        self.gate = EvaluationGate(repo_root=self.repo_root)
+        self.state.phase = AgentRunPhase.PLANNED
+        self.trace.append(self.decision.as_trace_row())
+        self.trace.extend(self.plan.trace)
+
+    @classmethod
+    def start(
+        cls,
+        request: str,
+        *,
+        repo_root: str | Path,
+        target_files: Sequence[str] = (),
+        requires_edit: bool | None = None,
+        execution_scope: ExecutionScopeDecision | None = None,
+    ) -> "AgentOrchestrator":
+        root = Path(repo_root).resolve()
+        if execution_scope is not None:
+            task_type = {
+                "answer": "answer_only",
+                "inspect": "repo_inspection",
+                "edit": "mutation_required",
+                "verify": "verification_only",
+                "plan": "answer_only",
+            }[execution_scope.task_type]
+            scope = {
+                ScopeLevel.DIRECT: "single_file" if len(execution_scope.explicit_target_files) == 1 else "multi_file",
+                ScopeLevel.BOUNDED: "multi_file",
+                ScopeLevel.IMPACT: "multi_file",
+                ScopeLevel.BROAD: "project_wide",
+            }[execution_scope.scope_level]
+            decision = TaskDecision(
+                task_type=task_type,  # type: ignore[arg-type]
+                target_files=tuple(execution_scope.explicit_target_files),
+                mutation_intent=str(request).strip() if execution_scope.task_type == "edit" else "",
+                constraints=tuple(execution_scope.out_of_bounds),
+                needs_repo_search=execution_scope.max_search_operations > 0,
+                needs_file_read=bool(execution_scope.all_evidence_files),
+                needs_mutation=execution_scope.task_type == "edit",
+                needs_verification=execution_scope.verification_strategy != "none",
+                scope=scope,  # type: ignore[arg-type]
+                confidence=execution_scope.confidence,
+            )
+        else:
+            decision = classify_task(request, repo_root=root, target_files=target_files, requires_edit=requires_edit)
+        plan = PlanBuilder().build(decision)
+        return cls(repo_root=root, decision=decision, plan=plan)
+
+    def before_tool(self, *, tool_name: str, target: str = "") -> GateResult:
+        result = self.gate.before_tool(decision=self.decision, state=self.state, tool_name=tool_name, target=target)
+        self.trace.append(result.trace_row(changed_files=sorted(self.state.changed_files)))
+        return result
+
+    def after_tool(
+        self,
+        *,
+        tool_name: str,
+        ok: bool,
+        files_read: list[str],
+        changed_files: list[str],
+        error: str = "",
+    ) -> GateResult:
+        result = self.gate.after_tool(
+            decision=self.decision,
+            state=self.state,
+            evidence_queue=self.plan.evidence_queue,
+            tool_name=tool_name,
+            ok=ok,
+            files_read=files_read,
+            changed_files=changed_files,
+            error=error,
+        )
+        self.trace.append(result.trace_row(changed_files=sorted(self.state.changed_files)))
+        self.trace.append(self.critic.review(gate=result, state=self.state).trace_row())
+        return result
+
+    def verification_decision(self, *, changed_files: Sequence[str], core_agent_change: bool = False) -> VerificationDecision:
+        decision = plan_verification(changed_files=changed_files, core_agent_change=core_agent_change)
+        self.trace.append(decision.trace_row())
+        return decision
+
+    def finalize_trace(self) -> None:
+        self.trace.append(
+            {
+                "layer": "final_response_builder",
+                "decision": "finalize",
+                "reason": "authoritative queue state is ready for the final response",
+                "changed_files": sorted(self.state.changed_files),
+                "warnings": list(self.state.warnings),
+            }
+        )
+
+
+__all__ = ["AgentOrchestrator", "AgentRunState", "PlanBuilder", "PostToolCritic", "TaskPlan"]

mana_agent/agent/selection.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from mana_agent.multi_agent.runtime.auto_chat import AutoChatMode, classify_auto_chat_intent
+
+
+class AgentPhase(str, Enum):
+    DISCOVER = "discover"
+    SELECT = "select"
+    READ = "read"
+    ACT = "act"
+    VERIFY = "verify"
+    SUMMARIZE = "summarize"
+
+
+@dataclass(frozen=True, slots=True)
+class SelectionResult:
+    mode: AutoChatMode
+    phase: AgentPhase
+    candidate_files: tuple[str, ...] = ()
+
+
+def select_mode(request: str, *, explicit_mode: str | None = None) -> AutoChatMode:
+    """Resolve the task mode using the same bounded classifier as chat."""
+    if explicit_mode:
+        normalized = str(explicit_mode).strip().lower().replace("-", "_")
+        for mode in AutoChatMode:
+            if normalized in {mode.value, mode.name.lower()}:
+                return mode
+    return classify_auto_chat_intent(request)
+
+
+def select_initial_phase(*, candidate_files: tuple[str, ...] = (), files_read: tuple[str, ...] = ()) -> AgentPhase:
+    """Choose the prompt-visible phase from known task context."""
+    if files_read:
+        return AgentPhase.ACT
+    if candidate_files:
+        return AgentPhase.READ
+    return AgentPhase.DISCOVER
+
+
+def select_task(
+    request: str,
+    *,
+    explicit_mode: str | None = None,
+    candidate_files: tuple[str, ...] = (),
+    files_read: tuple[str, ...] = (),
+) -> SelectionResult:
+    return SelectionResult(
+        mode=select_mode(request, explicit_mode=explicit_mode),
+        phase=select_initial_phase(candidate_files=candidate_files, files_read=files_read),
+        candidate_files=tuple(candidate_files),
+    )
+