agentropic 0.2.0__tar.gz → 0.2.2__tar.gz

{agentropic-0.2.0 → agentropic-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentropic
-Version: 0.2.0
+Version: 0.2.2
 Summary: A minimal, hackable agentic framework: LLM calls via litellm, @tool-decorated functions, and MCP server support.
 Author-email: Vishal Tiwari <vishaltiwari.up2019@gmail.com>
 License: MIT

{agentropic-0.2.0 → agentropic-0.2.2}/examples/basic_agent.py

@@ -31,7 +31,7 @@ async def main():
         tools=[get_weather, add],
         # Optional: pull in tools from a live MCP server too.
         # mcp_servers=[StdioServer(command="npx", args=["-y", "@modelcontextprotocol/server-filesystem", "."])],
-        max_iterations=6,
+        max_iterations=2,
     )
 
     result = await agent.arun("What's the weather in Tokyo, and what's 12 + 30?")

{agentropic-0.2.0 → agentropic-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentropic"
-version = "0.2.0"
+version = "0.2.2"
 description = "A minimal, hackable agentic framework: LLM calls via litellm, @tool-decorated functions, and MCP server support."
 readme = "README.md"
 requires-python = ">=3.9"

{agentropic-0.2.0 → agentropic-0.2.2}/src/agentropic/__init__.py

@@ -3,6 +3,7 @@ from .tools import tool, Tool, ToolRegistry
 from .llm import LLMClient, LLMResponse
 from .memory import Memory
 from .mcp.client import MCPConnection, StdioServer, SSEServer, MCPServerConfig
+from .tracing import AgentTracer, NullTracer
 
 __version__ = "0.2.0"
 
@@ -21,4 +22,6 @@ __all__ = [
     "StdioServer",
     "SSEServer",
     "MCPServerConfig",
+    "AgentTracer",
+    "NullTracer",
 ]

{agentropic-0.2.0 → agentropic-0.2.2}/src/agentropic/agent.py

@@ -3,6 +3,11 @@ optional MCP servers into a single run()/arun() loop that:
   1. sends messages + tool schemas to the LLM
   2. if the LLM asks for tool calls, executes them and feeds results back
   3. repeats until the LLM returns a final answer or max_iterations hits
+
+Set `verbose=True` (default) to get CrewAI-style colored terminal traces
+of every step — LLM calls, tool calls/results, final answer — via the
+zero-dependency `tracing.AgentTracer`. Pass `verbose=False` to silence it,
+or `tracer=YourTracer(...)` to plug in your own sink.
 """
 from __future__ import annotations
 
@@ -15,6 +20,7 @@ from .llm import LLMClient, LLMResponse
 from .memory import Memory
 from .tools import Tool, ToolRegistry
 from .mcp.client import MCPConnection, MCPServerConfig
+from .tracing import AgentTracer, NullTracer
 
 
 class AgentError(Exception):
@@ -120,6 +126,8 @@ class Agent:
         api_key: t.Optional[str] = None,
         api_base: t.Optional[str] = None,
         temperature: float = 0.7,
+        verbose: bool = True,
+        tracer: t.Optional[AgentTracer] = None,
         **llm_kwargs,
     ):
         self.name = name
@@ -137,6 +145,12 @@ class Agent:
         )
         self._mcp_tools_loaded = False
 
+        # -- tracing / pretty terminal logs ----------------------------
+        # `tracer` wins if explicitly supplied; otherwise `verbose` picks
+        # between the real colorful tracer and a silent no-op one.
+        self.verbose = verbose
+        self.tracer = tracer or (AgentTracer(name) if verbose else NullTracer(name))
+
     # -- tool management -------------------------------------------------
 
     def add_tool(self, item: t.Union[Tool, t.Callable]) -> Tool:
@@ -170,6 +184,8 @@ class Agent:
         error = False
         started = time.monotonic()
 
+        self.tracer.tool_call_start(name, args)
+
         if tl is None:
             result = f"Error: tool '{name}' is not registered."
             error = True
@@ -181,6 +197,7 @@ class Agent:
                 error = True
 
         duration = time.monotonic() - started
+        self.tracer.tool_call_end(name, str(result), duration, error)
 
         tool_msg = {
             "role": "tool",
@@ -208,6 +225,8 @@ class Agent:
 
     async def arun(self, user_input: str) -> AgentRunResult:
         run_started = time.monotonic()
+        self.tracer.run_start(user_input)
+
         await self._load_mcp_tools()
 
         messages = self._build_messages(user_input)
@@ -219,9 +238,18 @@ class Agent:
         raw_responses: list[LLMResponse] = []
 
         for iteration in range(1, self.max_iterations + 1):
+            self.tracer.iteration_start(iteration, self.max_iterations)
+            llm_started = time.monotonic()
             response = await self.llm.acomplete(messages, tools=tools_schema)
+            llm_duration = time.monotonic() - llm_started
             raw_responses.append(response)
 
+            self.tracer.llm_response(
+                response.content or "",
+                [tc.function.name for tc in (response.tool_calls or [])],
+                llm_duration,
+            )
+
             if response.tool_calls:
                 assistant_msg = {
                     "role": "assistant",
@@ -242,7 +270,7 @@ class Agent:
 
             # No tool calls -> final answer
             self.memory.add("assistant", response.content or "")
-            return AgentRunResult(
+            result = AgentRunResult(
                 output=response.content or "",
                 messages=messages,
                 tool_calls=all_tool_calls,
@@ -252,6 +280,11 @@ class Agent:
                 stopped_on_max_iterations=False,
                 duration_seconds=time.monotonic() - run_started,
             )
+            self.tracer.final_answer(
+                result.output, result.iterations, len(result.tool_calls),
+                result.duration_seconds, result.usage,
+            )
+            return result
 
         # Hit max_iterations without a final answer. Return what we have
         # instead of only raising, so the caller can inspect what happened —
@@ -267,6 +300,7 @@ class Agent:
             stopped_on_max_iterations=True,
             duration_seconds=time.monotonic() - run_started,
         )
+        self.tracer.max_iterations_error(self.max_iterations)
         error = AgentError(
             f"Agent '{self.name}' hit max_iterations ({self.max_iterations}) without a final answer."
         )
@@ -288,10 +322,12 @@ class Agent:
             yield result.output
             return
 
+        self.tracer.run_start(user_input)
         messages = self._build_messages(user_input)
         self.memory.add("user", user_input)
         full = ""
         async for chunk in self.llm.astream(messages):
             full += chunk
             yield chunk
-        self.memory.add("assistant", full)
+        self.memory.add("assistant", full)
+        self.tracer.final_answer(full, 1, 0, 0.0, {})

agentropic-0.2.2/src/agentropic/tracing.py

@@ -0,0 +1,269 @@
+"""Colorful terminal tracing for Agent.run()/arun(), CrewAI-style.
+
+Zero dependencies (pure ANSI escape codes) so it works in any terminal
+without needing `rich` or similar installed. Wraps every step of the
+agent loop — LLM calls, tool calls, tool results, final answer — in
+boxed, colored, timestamped output.
+
+Usage:
+    agent = Agent(..., verbose=True)          # on by default
+    agent = Agent(..., verbose=False)         # silence it
+    agent = Agent(..., tracer=MyTracer(...))  # bring your own sink
+"""
+from __future__ import annotations
+
+import shutil
+import sys
+import textwrap
+import time
+import typing as t
+
+
+# --------------------------------------------------------------------------
+# Low-level ANSI helpers
+# --------------------------------------------------------------------------
+
+class C:
+    RESET = "\033[0m"
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+    ITALIC = "\033[3m"
+
+    CYAN = "\033[36m"
+    MAGENTA = "\033[35m"
+    YELLOW = "\033[33m"
+    GREEN = "\033[32m"
+    RED = "\033[31m"
+    BLUE = "\033[34m"
+    WHITE = "\033[97m"
+    GREY = "\033[90m"
+
+    BG_CYAN = "\033[46m"
+
+
+def _supports_color() -> bool:
+    """Disable colors when piped/redirected (mirrors how most CLI tools behave)."""
+    return hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
+
+
+def _term_width(default: int = 88) -> int:
+    try:
+        return min(shutil.get_terminal_size().columns, 120)
+    except Exception:
+        return default
+
+
+def _wrap(text: str, width: int, indent: str = "") -> list[str]:
+    out: list[str] = []
+    for line in (text or "").splitlines() or [""]:
+        wrapped = textwrap.wrap(
+            line, width=width, subsequent_indent=indent, initial_indent=indent
+        ) or [indent]
+        out.extend(wrapped)
+    return out
+
+
+def _truncate(text: str, n: int) -> str:
+    text = text or ""
+    return text if len(text) <= n else text[: n - 1].rstrip() + "…"
+
+
+def _display_width(text: str) -> int:
+    """Approximate terminal column width, counting emoji/wide symbols as 2
+    columns (most terminals render them that way even though len() sees 1
+    codepoint). Good enough for box alignment without a wcwidth dependency."""
+    width = 0
+    for ch in text:
+        cp = ord(ch)
+        if (
+            0x1F300 <= cp <= 0x1FAFF  # emoji blocks
+            or 0x2600 <= cp <= 0x27BF  # misc symbols / dingbats (✅ ⚠ etc.)
+            or cp in (0x2705, 0x274C, 0x2714, 0x2716)
+        ):
+            width += 2
+        else:
+            width += 1
+    return width
+
+
+# --------------------------------------------------------------------------
+# Tracer
+# --------------------------------------------------------------------------
+
+# Module-level so the welcome banner shows exactly once per process,
+# no matter how many Agent/AgentTracer instances get created.
+_WELCOME_SHOWN = False
+
+
+class AgentTracer:
+    """Renders one Agent run as a live, colorized trace in the terminal.
+
+    Every method is a no-op if `enabled=False`, so it's cheap to leave
+    wired in and toggle via a single flag.
+    """
+
+    def __init__(self, agent_name: str, enabled: bool = True, stream: t.TextIO = sys.stdout):
+        self.agent_name = agent_name
+        self.enabled = enabled
+        self.stream = stream
+        self._color = enabled and _supports_color()
+        self._run_started: t.Optional[float] = None
+        self._iter_started: t.Optional[float] = None
+
+    # -- internals --------------------------------------------------------
+
+    def _c(self, code: str) -> str:
+        return code if self._color else ""
+
+    def _print(self, text: str = "") -> None:
+        if not self.enabled:
+            return
+        print(text, file=self.stream, flush=True)
+
+    def _rule(self, char: str = "─", color: str = "") -> str:
+        width = _term_width()
+        return f"{self._c(color)}{char * width}{self._c(C.RESET)}"
+
+    def _box(
+        self,
+        title: str,
+        lines: list[str],
+        color: str,
+        title_color: str = "",
+        center_title: bool = False,
+        center_lines: bool = False,
+    ) -> None:
+        width = _term_width()
+        inner = width - 4
+        title_color = title_color or color
+        top = f"{self._c(color)}╭{'─' * (width - 2)}╮{self._c(C.RESET)}"
+        bot = f"{self._c(color)}╰{'─' * (width - 2)}╯{self._c(C.RESET)}"
+
+        if center_title:
+            left_pad = max((inner - _display_width(title)) // 2, 0)
+            right_pad = max(inner - _display_width(title) - left_pad, 0)
+        else:
+            left_pad, right_pad = 0, max(inner - _display_width(title), 0)
+
+        head = (
+            f"{self._c(color)}│ {self._c(C.RESET)}{' ' * left_pad}"
+            f"{self._c(C.BOLD)}{self._c(title_color)}{title}{self._c(C.RESET)}"
+            f"{' ' * right_pad}{self._c(color)} │{self._c(C.RESET)}"
+        )
+        self._print(top)
+        self._print(head)
+        if lines:
+            self._print(f"{self._c(color)}├{'─' * (width - 2)}┤{self._c(C.RESET)}")
+            for raw in lines:
+                for wrapped in _wrap(raw, inner) or [""]:
+                    w = _display_width(wrapped)
+                    if center_lines:
+                        lp = max((inner - w) // 2, 0)
+                        rp = max(inner - w - lp, 0)
+                    else:
+                        lp, rp = 0, max(inner - w, 0)
+                    self._print(
+                        f"{self._c(color)}│ {self._c(C.RESET)}{' ' * lp}{wrapped}"
+                        f"{' ' * rp}{self._c(color)} │{self._c(C.RESET)}"
+                    )
+        self._print(bot)
+
+    # -- lifecycle events ---------------------------------------------------
+
+    def welcome_banner(self, force: bool = False) -> None:
+        """Prints a one-time 'Welcome to Agentropic' banner. Shown
+        automatically before the first run in a process; call with
+        force=True to show it again (e.g. at the very start of a script)."""
+        global _WELCOME_SHOWN
+        if _WELCOME_SHOWN and not force:
+            return
+        _WELCOME_SHOWN = True
+        self._print()
+        self._box(
+            "🚀  Welcome to Agentropic — Agentic AI System",
+            [f"{self._c(C.DIM)}Powered by your agents, tools, and memory.{self._c(C.RESET)}"],
+            color=C.MAGENTA,
+            center_title=True,
+            center_lines=True,
+        )
+
+    def run_start(self, user_input: str) -> None:
+        self.welcome_banner()
+        self._run_started = time.monotonic()
+        self._print()
+        self._box(
+            f"🤖  Agent: {self.agent_name}",
+            [f"{self._c(C.DIM)}Task ▸{self._c(C.RESET)} {_truncate(user_input, 400)}"],
+            color=C.CYAN,
+        )
+
+    def iteration_start(self, iteration: int, max_iterations: int) -> None:
+        self._iter_started = time.monotonic()
+        self._print(
+            f"\n{self._c(C.BOLD)}{self._c(C.BLUE)}▸ Iteration {iteration}/{max_iterations}"
+            f"{self._c(C.RESET)} {self._c(C.GREY)}— calling LLM…{self._c(C.RESET)}"
+        )
+
+    def llm_response(self, content: str, tool_call_names: list[str], duration: float) -> None:
+        dur = f"{duration:.2f}s"
+        if tool_call_names:
+            calls = ", ".join(tool_call_names)
+            self._print(
+                f"  {self._c(C.GREY)}↳ response in {dur}{self._c(C.RESET)} "
+                f"{self._c(C.MAGENTA)}requests {len(tool_call_names)} tool call(s):{self._c(C.RESET)} "
+                f"{self._c(C.BOLD)}{calls}{self._c(C.RESET)}"
+            )
+            if content and content.strip():
+                self._print(f"  {self._c(C.DIM)}💭 {_truncate(content.strip(), 200)}{self._c(C.RESET)}")
+        else:
+            self._print(f"  {self._c(C.GREY)}↳ response in {dur} — final answer{self._c(C.RESET)}")
+
+    def tool_call_start(self, name: str, arguments: dict) -> None:
+        args_str = ", ".join(f"{k}={v!r}" for k, v in (arguments or {}).items())
+        self._print(
+            f"    {self._c(C.YELLOW)}🔧 {self._c(C.BOLD)}{name}{self._c(C.RESET)}"
+            f"{self._c(C.GREY)}({_truncate(args_str, 140)}){self._c(C.RESET)}"
+        )
+
+    def tool_call_end(self, name: str, result: str, duration: float, error: bool) -> None:
+        icon = "❌" if error else "✅"
+        color = C.RED if error else C.GREEN
+        self._print(
+            f"    {self._c(color)}{icon} {name} → {duration:.2f}s{self._c(C.RESET)} "
+            f"{self._c(C.DIM)}{_truncate(str(result).replace(chr(10), ' '), 160)}{self._c(C.RESET)}"
+        )
+
+    def final_answer(self, output: str, iterations: int, tool_call_count: int, duration: float, usage: dict) -> None:
+        stats = (
+            f"{self._c(C.DIM)}⏱ {duration:.2f}s   🔁 {iterations} iteration(s)   "
+            f"🔧 {tool_call_count} tool call(s)"
+        )
+        if usage and usage.get("total_tokens"):
+            stats += f"   🎫 {usage['total_tokens']} tokens"
+        stats += self._c(C.RESET)
+        self._print()
+        self._box(
+            "✅  Final Answer",
+            [output, "", stats],
+            color=C.GREEN,
+        )
+        self._print()
+
+    def max_iterations_error(self, max_iterations: int) -> None:
+        self._print()
+        self._box(
+            "⚠️  Max iterations reached",
+            [f"Agent '{self.agent_name}' hit max_iterations ({max_iterations}) without a final answer."],
+            color=C.RED,
+        )
+        self._print()
+
+    def error(self, message: str) -> None:
+        self._print(f"  {self._c(C.RED)}{self._c(C.BOLD)}✖ {message}{self._c(C.RESET)}")
+
+
+class NullTracer(AgentTracer):
+    """Same interface, does nothing — used when verbose=False."""
+
+    def __init__(self, agent_name: str = ""):
+        super().__init__(agent_name, enabled=False)