@openlucaskaka/kagent 0.1.7

package/src/kagent/core/agent.py

@@ -0,0 +1,296 @@
+from __future__ import annotations
+
+import time
+from dataclasses import asdict
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+from uuid import uuid4
+
+from langgraph.graph import END, StateGraph
+
+from kagent.core.normalization import (
+    plan_goal as _plan_goal,
+)
+from kagent.core.planning import (
+    normalize_fault_plan,
+    plan_errors,
+    validate_plan_steps,
+)
+from kagent.core.state import AgentConfig, AgentState, AgentStatus
+from kagent.core.tools import execute_step, expected_answer
+from kagent.core.trace import (
+    copy_agent_state,
+    record_execution_attempt,
+    record_node_event,
+)
+
+
+def build_agent_graph(config: AgentConfig):
+    graph = StateGraph(AgentState)
+    graph.add_node("planner", _planner)
+    graph.add_node("executor", _executor)
+    graph.add_node("verifier", _verifier)
+    graph.add_node("reflector", _reflector)
+    graph.set_entry_point("planner")
+    graph.add_conditional_edges(
+        "planner",
+        _route_after_planner,
+        {
+            "execute": "executor",
+            "end": END,
+        },
+    )
+    graph.add_edge("executor", "verifier")
+    graph.add_conditional_edges(
+        "verifier",
+        _route_after_verifier,
+        {
+            "execute": "executor",
+            "reflect": "reflector",
+            "end": END,
+        },
+    )
+    graph.add_edge("reflector", "executor")
+    return graph.compile(name=f"kagent-{config.max_steps}-{config.max_retries}")
+
+
+def agent_topology() -> Dict[str, List[str]]:
+    return {
+        "nodes": ["planner", "executor", "verifier", "reflector"],
+        "edges": [
+            "planner -> executor",
+            "executor -> verifier",
+            "verifier -> reflector",
+            "reflector -> executor",
+            "verifier -> executor",
+            "verifier -> END",
+            "planner -> END",
+        ],
+    }
+
+
+def run_agent(
+    goal: str,
+    *,
+    config: Optional[AgentConfig] = None,
+    fault_plan: Optional[Dict[str, List[str]]] = None,
+) -> AgentState:
+    active_config = config or AgentConfig()
+    run_id = str(uuid4())
+    started_at = _utc_timestamp()
+    started_timer = time.perf_counter()
+    initial_state: AgentState = {
+        "run_id": run_id,
+        "started_at": started_at,
+        "completed_at": "",
+        "duration_seconds": "0.0000",
+        "goal": goal,
+        "config": asdict(active_config),
+        "plan": [],
+        "plan_validations": [],
+        "current_step": 0,
+        "answer": None,
+        "step_results": [],
+        "tool_calls": [],
+        "execution_attempts": [],
+        "verified": False,
+        "retry_count": 0,
+        "step_retry_count": 0,
+        "status": AgentStatus.RUNNING,
+        "errors": [],
+        "events": [],
+        "fault_plan": normalize_fault_plan(fault_plan or {}),
+        "fault_counters": {},
+        "reflection_notes": [],
+        "reflections": [],
+        "verification_results": [],
+    }
+    graph = build_agent_graph(active_config)
+    final_state = graph.invoke(initial_state)
+    final_state["run_id"] = run_id
+    final_state["started_at"] = started_at
+    final_state["completed_at"] = _utc_timestamp()
+    final_state["duration_seconds"] = f"{time.perf_counter() - started_timer:.4f}"
+    return final_state
+
+
+def preview_plan(
+    goal: str,
+    *,
+    config: Optional[AgentConfig] = None,
+) -> Dict[str, Any]:
+    active_config = config or AgentConfig()
+    plan = _plan_goal(goal)
+    plan_validations = validate_plan_steps(plan)
+    errors = plan_errors(plan, active_config.max_steps)
+
+    return {
+        "status": "failed" if errors else "ready",
+        "goal": goal,
+        "plan": plan,
+        "plan_validations": plan_validations,
+        "errors": errors,
+    }
+
+
+def _planner(state: AgentState) -> AgentState:
+    next_state = copy_agent_state(state)
+    next_state["plan"] = _plan_goal(next_state["goal"])
+    next_state["plan_validations"] = validate_plan_steps(next_state["plan"])
+    next_state["current_step"] = 0
+    errors = plan_errors(next_state["plan"], next_state["config"]["max_steps"])
+    if errors:
+        next_state["status"] = AgentStatus.FAILED
+        next_state["errors"].extend(errors)
+    else:
+        next_state["status"] = AgentStatus.RUNNING
+    record_node_event(next_state, "planner")
+    return next_state
+
+
+def _executor(state: AgentState) -> AgentState:
+    next_state = copy_agent_state(state)
+    step = _current_step(next_state)
+    if step is None:
+        next_state["status"] = AgentStatus.FAILED
+        next_state["errors"].append("no executable step")
+        record_node_event(next_state, "executor")
+        return next_state
+
+    fault = _consume_fault(next_state, step)
+    if fault == "wrong-answer":
+        next_state["answer"] = "6"
+        record_execution_attempt(next_state, step, "", "6", fault)
+    elif fault == "empty-answer":
+        next_state["answer"] = ""
+        record_execution_attempt(next_state, step, "", "", fault)
+    elif fault == "tool-error":
+        next_state["answer"] = "TOOL_ERROR"
+        record_execution_attempt(next_state, step, "", "TOOL_ERROR", fault)
+    else:
+        execution = execute_step(step)
+        if execution is None:
+            next_state["answer"] = None
+            next_state["errors"].append(f"unsupported step: {step}")
+            record_execution_attempt(next_state, step, "", "None", "")
+        else:
+            next_state["answer"] = execution["output"]
+            next_state["tool_calls"].append(execution)
+            record_execution_attempt(
+                next_state,
+                step,
+                execution["tool"],
+                execution["output"],
+                "",
+            )
+
+    record_node_event(next_state, "executor")
+    return next_state
+
+
+def _verifier(state: AgentState) -> AgentState:
+    next_state = copy_agent_state(state)
+    step = _current_step(next_state)
+    expected = expected_answer(step)
+    next_state["verified"] = bool(expected is not None and next_state.get("answer") == expected)
+    next_state["verification_results"].append(
+        {
+            "step": step or "",
+            "actual": str(next_state.get("answer")),
+            "expected": str(expected),
+            "passed": str(next_state["verified"]).lower(),
+            "retry": str(next_state["step_retry_count"]),
+        }
+    )
+
+    if next_state["verified"]:
+        if next_state.get("answer") is not None:
+            next_state["step_results"].append(next_state["answer"])
+        next_state["current_step"] = next_state["current_step"] + 1
+        next_state["step_retry_count"] = 0
+        if next_state["current_step"] >= len(next_state.get("plan", [])):
+            next_state["status"] = AgentStatus.DONE
+        else:
+            next_state["status"] = AgentStatus.RUNNING
+    elif next_state["step_retry_count"] >= next_state["config"]["max_retries"]:
+        next_state["status"] = AgentStatus.FAILED
+        next_state["errors"].append("retry budget exhausted")
+    else:
+        next_state["status"] = AgentStatus.RUNNING
+
+    record_node_event(next_state, "verifier")
+    return next_state
+
+
+def _reflector(state: AgentState) -> AgentState:
+    next_state = copy_agent_state(state)
+    next_state["retry_count"] = next_state["retry_count"] + 1
+    next_state["step_retry_count"] = next_state["step_retry_count"] + 1
+    step = _current_step(next_state)
+    actual = str(next_state.get("answer"))
+    reason = _reflection_reason(actual)
+    next_state["reflection_notes"].append(_reflection_note(reason))
+    next_state["reflections"].append(
+        {
+            "step": step or "",
+            "actual": actual,
+            "expected": str(expected_answer(step)),
+            "retry": str(next_state["step_retry_count"]),
+            "reason": reason,
+        }
+    )
+    record_node_event(next_state, "reflector")
+    return next_state
+
+
+def _route_after_planner(state: AgentState) -> str:
+    if state["status"] == AgentStatus.FAILED:
+        return "end"
+    return "execute"
+
+
+def _route_after_verifier(state: AgentState) -> str:
+    if state["status"] in {AgentStatus.DONE, AgentStatus.FAILED}:
+        return "end"
+    if state.get("verified"):
+        return "execute"
+    return "reflect"
+
+
+def _current_step(state: AgentState) -> Optional[str]:
+    plan = state.get("plan", [])
+    current_step = state.get("current_step", 0)
+    if current_step < 0 or current_step >= len(plan):
+        return None
+    return plan[current_step]
+
+
+def _consume_fault(state: AgentState, step: str) -> Optional[str]:
+    fault_plan = state.get("fault_plan", {})
+    faults = fault_plan.get(step, [])
+    counters = state.setdefault("fault_counters", {})
+    index = counters.get(step, 0)
+    counters[step] = index + 1
+    if index >= len(faults):
+        return None
+    return faults[index]
+
+
+def _utc_timestamp() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _reflection_reason(actual: str) -> str:
+    if actual == "":
+        return "answer was empty"
+    if actual == "TOOL_ERROR":
+        return "tool execution failed"
+    return "answer did not match verifier expectation"
+
+
+def _reflection_note(reason: str) -> str:
+    if reason == "answer was empty":
+        return "executor returned an empty answer; retry the same planned step"
+    if reason == "tool execution failed":
+        return "tool execution failed; retry the same planned step"
+    return "executor returned an unverifiable answer; retry with stricter arithmetic"

package/src/kagent/core/faults.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import Iterable
+
+SUPPORTED_FAULTS = {"empty-answer", "tool-error", "wrong-answer"}
+
+
+def validate_faults(faults: Iterable[str]) -> None:
+    for fault in faults:
+        if fault not in SUPPORTED_FAULTS:
+            raise ValueError(f"unsupported fault: {fault}")

package/src/kagent/core/invariants.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from collections import Counter
+from enum import Enum
+from typing import Any, Dict, List
+
+
+def validate_run_invariants(state: Dict[str, Any]) -> List[str]:
+    issues = []
+    events = state.get("events", [])
+    node_counts = Counter(event["node"] for event in events)
+    status = _value(state.get("status"))
+
+    if len(state.get("plan_validations", [])) != len(state.get("plan", [])):
+        issues.append("plan_validations count does not match plan")
+
+    if node_counts["executor"] != len(state.get("execution_attempts", [])):
+        issues.append("executor event count does not match execution_attempts")
+
+    if node_counts["verifier"] != len(state.get("verification_results", [])):
+        issues.append("verifier event count does not match verification_results")
+
+    if node_counts["reflector"] != len(state.get("reflections", [])):
+        issues.append("reflector event count does not match reflections")
+
+    if state.get("retry_count", 0) != len(state.get("reflections", [])):
+        issues.append("retry_count does not match reflections")
+
+    if state.get("current_step", 0) != len(state.get("step_results", [])):
+        issues.append("current_step does not match completed step_results")
+
+    if status == "done" and state.get("current_step", 0) != len(state.get("plan", [])):
+        issues.append("done status does not match completed plan")
+
+    failed_verifications = [
+        item for item in state.get("verification_results", []) if item["passed"] == "false"
+    ]
+    if status == "done" and len(failed_verifications) != len(state.get("reflections", [])):
+        issues.append("done run failed verification count does not match reflections")
+
+    return issues
+
+
+def _value(value: Any) -> Any:
+    if isinstance(value, Enum):
+        return value.value
+    return value

package/src/kagent/core/normalization.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import List
+
+
+def normalize_goal(goal: str) -> str:
+    return " then ".join(plan_goal(goal))
+
+
+def plan_goal(goal: str) -> List[str]:
+    return [
+        normalized
+        for part in _split_goal_steps(goal)
+        if (normalized := _normalize_step(part))
+    ]
+
+
+def _normalize_step(step: str) -> str:
+    quote = None
+    output = []
+    previous_space = False
+    for char in step.strip():
+        if char in {"'", '"'}:
+            if quote == char:
+                quote = None
+            elif quote is None:
+                quote = char
+            output.append(char)
+            previous_space = False
+        elif quote is not None:
+            output.append(char)
+        elif char.isspace():
+            if output and not previous_space:
+                output.append(" ")
+                previous_space = True
+        else:
+            output.append(char.lower())
+            previous_space = False
+    return "".join(output).strip()
+
+
+def _split_goal_steps(goal: str) -> List[str]:
+    stripped = goal.strip()
+    if not stripped:
+        return []
+
+    parts = []
+    buffer = []
+    quote = None
+    index = 0
+    while index < len(stripped):
+        char = stripped[index]
+        if char in {"'", '"'}:
+            if quote == char:
+                quote = None
+            elif quote is None:
+                quote = char
+            buffer.append(char)
+            index += 1
+        elif quote is None and char.isspace():
+            next_index = index
+            while next_index < len(stripped) and stripped[next_index].isspace():
+                next_index += 1
+            after_then = next_index + 4
+            if (
+                stripped[next_index:after_then].lower() == "then"
+                and (after_then == len(stripped) or stripped[after_then].isspace())
+            ):
+                while after_then < len(stripped) and stripped[after_then].isspace():
+                    after_then += 1
+                parts.append("".join(buffer))
+                buffer = []
+                index = after_then
+            else:
+                buffer.append(" ")
+                index = next_index
+        else:
+            buffer.append(char)
+            index += 1
+    parts.append("".join(buffer))
+    return parts

package/src/kagent/core/planning.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+from kagent.core.faults import validate_faults
+from kagent.core.normalization import normalize_goal
+from kagent.core.tools import expected_answer, matching_tool_name
+
+
+def normalize_fault_plan(fault_plan: Dict[str, List[str]]) -> Dict[str, List[str]]:
+    for faults in fault_plan.values():
+        validate_faults(faults)
+    return {
+        normalize_goal(step): list(faults)
+        for step, faults in fault_plan.items()
+    }
+
+
+def plan_errors(plan: List[str], max_steps: int) -> List[str]:
+    unsupported_step = _unsupported_planned_step(plan)
+    if not plan:
+        return ["empty plan"]
+    if len(plan) > max_steps:
+        return ["planned steps exceed max_steps"]
+    if unsupported_step is not None:
+        return [f"unsupported planned step: {unsupported_step}"]
+    return []
+
+
+def validate_plan_steps(plan: List[str]) -> List[Dict[str, str]]:
+    validations = []
+    for step in plan:
+        tool_name = matching_tool_name(step)
+        validations.append(
+            {
+                "step": step,
+                "supported": str(tool_name is not None).lower(),
+                "tool": tool_name or "",
+            }
+        )
+    return validations
+
+
+def _unsupported_planned_step(plan: List[str]) -> Optional[str]:
+    for step in plan:
+        if expected_answer(step) is None:
+            return step
+    return None

package/src/kagent/core/state.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from os import environ
+from typing import Any, Dict, List, Mapping, Optional, TypedDict
+
+
+class AgentStatus(str, Enum):
+    RUNNING = "running"
+    DONE = "done"
+    FAILED = "failed"
+
+
+@dataclass(frozen=True)
+class AgentConfig:
+    max_steps: int = 6
+    max_retries: int = 2
+
+    @classmethod
+    def from_env(cls, env: Optional[Mapping[str, str]] = None) -> "AgentConfig":
+        source = env if env is not None else environ
+        return cls(
+            max_steps=_env_int(source, "KAGENT_MAX_STEPS", cls.max_steps),
+            max_retries=_env_int(
+                source,
+                "KAGENT_MAX_RETRIES",
+                cls.max_retries,
+            ),
+        )
+
+    def __post_init__(self) -> None:
+        if self.max_steps < 1:
+            raise ValueError("max_steps must be at least 1")
+        if self.max_retries < 0:
+            raise ValueError("max_retries must be non-negative")
+
+
+class AgentState(TypedDict, total=False):
+    run_id: str
+    started_at: str
+    completed_at: str
+    duration_seconds: str
+    goal: str
+    config: Dict[str, int]
+    plan: List[str]
+    plan_validations: List[Dict[str, str]]
+    current_step: int
+    answer: Optional[str]
+    step_results: List[str]
+    tool_calls: List[Dict[str, str]]
+    execution_attempts: List[Dict[str, str]]
+    verified: bool
+    retry_count: int
+    step_retry_count: int
+    status: AgentStatus
+    errors: List[str]
+    events: List[Dict[str, Any]]
+    fault_plan: Dict[str, List[str]]
+    fault_counters: Dict[str, int]
+    reflection_notes: List[str]
+    reflections: List[Dict[str, str]]
+    verification_results: List[Dict[str, str]]
+
+
+def _env_int(env: Mapping[str, str], name: str, default: int) -> int:
+    value = env.get(name)
+    if value in {None, ""}:
+        return default
+    try:
+        return int(value)
+    except ValueError as exc:
+        raise ValueError(f"{name} must be an integer") from exc

package/src/kagent/core/summary.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from collections import Counter
+from enum import Enum
+from typing import Any, Dict, List
+
+
+def summarize_run(state: Dict[str, Any]) -> Dict[str, Any]:
+    node_counts = Counter(event["node"] for event in state.get("events", []))
+    status = _json_value(state.get("status"))
+    tool_calls = state.get("tool_calls", [])
+    failed_verifications = [
+        item for item in state.get("verification_results", []) if item["passed"] == "false"
+    ]
+    reflection_reasons = [
+        item["reason"] for item in state.get("reflections", [])
+    ]
+    reflection_reason_counts = Counter(reflection_reasons)
+    faults = [
+        item["fault"]
+        for item in state.get("execution_attempts", [])
+        if item.get("fault")
+    ]
+    return {
+        "status": status,
+        "answer": state.get("answer"),
+        "run_id": state.get("run_id", ""),
+        "started_at": state.get("started_at", ""),
+        "completed_at": state.get("completed_at", ""),
+        "duration_seconds": state.get("duration_seconds", "0.0000"),
+        "planned_steps": str(len(state.get("plan", []))),
+        "completed_steps": str(state.get("current_step", 0)),
+        "retry_count": str(state.get("retry_count", 0)),
+        "failed_verifications": str(len(failed_verifications)),
+        "recovered": str(status == "done" and bool(failed_verifications)).lower(),
+        "reflection_reasons": reflection_reasons,
+        "reflection_reason_counts": {
+            reason: str(count)
+            for reason, count in sorted(reflection_reason_counts.items())
+        },
+        "tool_call_count": str(len(tool_calls)),
+        "tool_names": _unique_tool_names(tool_calls),
+        "node_counts": {
+            node: str(count)
+            for node, count in sorted(node_counts.items())
+        },
+        "faults": faults,
+        "errors": list(state.get("errors", [])),
+    }
+
+
+def _unique_tool_names(tool_calls: List[Dict[str, str]]) -> List[str]:
+    names = []
+    for call in tool_calls:
+        name = call["tool"]
+        if name not in names:
+            names.append(name)
+    return names
+
+
+def _json_value(value: Any) -> Any:
+    if isinstance(value, Enum):
+        return value.value
+    return value