agentlatch 0.1.0__tar.gz

agentlatch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentLatch Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentlatch-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: agentlatch
+Version: 0.1.0
+Summary: Zero-dependency, terminal-native Python middleware for resilient and observable AI agents.
+Author: AgentLatch Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/arav7781/AgentLatch
+Project-URL: Repository, https://github.com/arav7781/AgentLatch
+Project-URL: Issues, https://github.com/arav7781/AgentLatch/issues
+Keywords: agents,llm,observability,middleware,terminal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Provides-Extra: server
+Requires-Dist: starlette>=0.27; extra == "server"
+Requires-Dist: httpx>=0.24; extra == "server"
+Dynamic: license-file
+
+![AgentLatch Banner](banner.png)
+
+**Terminal-native agent resilience middleware for Python.**
+
+AgentLatch is a zero-dependency framework that makes AI agents resilient and observable. It solves two massive pain points in agent development:
+
+1. **Silent Tool Failures** — When an LLM executes a tool that crashes, AgentLatch intercepts the Python exception, prevents a runtime crash, and feeds a structured JSON error back to the LLM so it can self-correct.
+
+2. **Blind Latency** — It tracks millisecond execution time of LLM vs. tools and prints a color-coded ASCII flamegraph directly in the terminal using the `rich` library. No API keys, no dashboards, no cloud.
+
+## Quick Install
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+## Usage
+
+```python
+from agentlatch import profile_agent, safe_tool
+
+@safe_tool
+def query_database(sql: str) -> str:
+    """This tool is now protected — exceptions become JSON errors."""
+    import sqlite3
+    conn = sqlite3.connect("my.db")
+    return str(conn.execute(sql).fetchall())
+
+@safe_tool(timeout=5.0)
+def call_api(url: str) -> str:
+    """This tool has a 5-second timeout."""
+    import requests
+    return requests.get(url).text
+
+@profile_agent
+def run_agent():
+    """The agent loop — traced and visualized automatically."""
+    result = query_database("SELECT * FROM users")
+    weather = call_api("https://api.weather.com/sf")
+    return f"Got {result} and {weather}"
+
+run_agent()
+```
+
+## What Happens
+
+1. **Execution**: Every `@safe_tool` call is timed and protected.
+2. **On Error**: Instead of crashing, the tool returns a JSON error string:
+   ```json
+   {
+     "status": "error",
+     "error_type": "ProgrammingError",
+     "message": "column 'age' does not exist",
+     "instruction": "The tool execution failed. Review your parameters and retry with corrected inputs."
+   }
+   ```
+3. **On Completion**: A rich flamegraph is printed to the terminal:
+   ```
+   ┌─────────────────────────────────────────────────────────┐
+   │  ⚡ AGENTLATCH EXECUTION PROFILE                        │
+   │  Total: 1.23s │ Tools: 0.85s │ LLM Reasoning: 0.38s    │
+   ├─────────────────────────────────────────────────────────┤
+   │  ████████████████████████████████████████████ 1.23s      │
+   │  ░░░░████████████░░░████░░░░░░░░░░░░░░░░░░░░            │
+   │      query_db 0.5s  call_api 0.2s                       │
+   │      ▲ ERROR                                             │
+   │  Legend: █ LLM  █ Tool (OK)  █ Tool (ERROR)              │
+   └─────────────────────────────────────────────────────────┘
+   ```
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| `@safe_tool` | Wraps any function — catches exceptions, returns JSON errors |
+| `@safe_tool(timeout=N)` | Adds a thread-based timeout (cross-platform) |
+| `@profile_agent` | Traces the full agent loop and renders the flamegraph |
+| Async support | Both decorators work with `async def` functions |
+| Framework agnostic | Works with LangGraph, AutoGen, CrewAI, or vanilla scripts |
+| CI-safe | Banner auto-disables in non-TTY environments |
+
+## Running Examples
+
+```bash
+# Vanilla agent with a forced failure + self-correction
+python examples/vanilla_agent.py
+
+# LangGraph-style state machine
+python examples/langgraph_agent.py
+```
+
+## Running Tests
+
+```bash
+uv pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## Architecture
+
+- **`contextvars`** — Thread-safe trace propagation without manual trace IDs
+- **`concurrent.futures`** — Cross-platform timeouts (no `signal.alarm`)
+- **`rich`** — Premium terminal rendering (the only external dependency)
+
+## License
+
+MIT

agentlatch-0.1.0/README.md

@@ -0,0 +1,107 @@
+![AgentLatch Banner](banner.png)
+
+**Terminal-native agent resilience middleware for Python.**
+
+AgentLatch is a zero-dependency framework that makes AI agents resilient and observable. It solves two massive pain points in agent development:
+
+1. **Silent Tool Failures** — When an LLM executes a tool that crashes, AgentLatch intercepts the Python exception, prevents a runtime crash, and feeds a structured JSON error back to the LLM so it can self-correct.
+
+2. **Blind Latency** — It tracks millisecond execution time of LLM vs. tools and prints a color-coded ASCII flamegraph directly in the terminal using the `rich` library. No API keys, no dashboards, no cloud.
+
+## Quick Install
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+## Usage
+
+```python
+from agentlatch import profile_agent, safe_tool
+
+@safe_tool
+def query_database(sql: str) -> str:
+    """This tool is now protected — exceptions become JSON errors."""
+    import sqlite3
+    conn = sqlite3.connect("my.db")
+    return str(conn.execute(sql).fetchall())
+
+@safe_tool(timeout=5.0)
+def call_api(url: str) -> str:
+    """This tool has a 5-second timeout."""
+    import requests
+    return requests.get(url).text
+
+@profile_agent
+def run_agent():
+    """The agent loop — traced and visualized automatically."""
+    result = query_database("SELECT * FROM users")
+    weather = call_api("https://api.weather.com/sf")
+    return f"Got {result} and {weather}"
+
+run_agent()
+```
+
+## What Happens
+
+1. **Execution**: Every `@safe_tool` call is timed and protected.
+2. **On Error**: Instead of crashing, the tool returns a JSON error string:
+   ```json
+   {
+     "status": "error",
+     "error_type": "ProgrammingError",
+     "message": "column 'age' does not exist",
+     "instruction": "The tool execution failed. Review your parameters and retry with corrected inputs."
+   }
+   ```
+3. **On Completion**: A rich flamegraph is printed to the terminal:
+   ```
+   ┌─────────────────────────────────────────────────────────┐
+   │  ⚡ AGENTLATCH EXECUTION PROFILE                        │
+   │  Total: 1.23s │ Tools: 0.85s │ LLM Reasoning: 0.38s    │
+   ├─────────────────────────────────────────────────────────┤
+   │  ████████████████████████████████████████████ 1.23s      │
+   │  ░░░░████████████░░░████░░░░░░░░░░░░░░░░░░░░            │
+   │      query_db 0.5s  call_api 0.2s                       │
+   │      ▲ ERROR                                             │
+   │  Legend: █ LLM  █ Tool (OK)  █ Tool (ERROR)              │
+   └─────────────────────────────────────────────────────────┘
+   ```
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| `@safe_tool` | Wraps any function — catches exceptions, returns JSON errors |
+| `@safe_tool(timeout=N)` | Adds a thread-based timeout (cross-platform) |
+| `@profile_agent` | Traces the full agent loop and renders the flamegraph |
+| Async support | Both decorators work with `async def` functions |
+| Framework agnostic | Works with LangGraph, AutoGen, CrewAI, or vanilla scripts |
+| CI-safe | Banner auto-disables in non-TTY environments |
+
+## Running Examples
+
+```bash
+# Vanilla agent with a forced failure + self-correction
+python examples/vanilla_agent.py
+
+# LangGraph-style state machine
+python examples/langgraph_agent.py
+```
+
+## Running Tests
+
+```bash
+uv pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## Architecture
+
+- **`contextvars`** — Thread-safe trace propagation without manual trace IDs
+- **`concurrent.futures`** — Cross-platform timeouts (no `signal.alarm`)
+- **`rich`** — Premium terminal rendering (the only external dependency)
+
+## License
+
+MIT

agentlatch-0.1.0/agentlatch/__init__.py

@@ -0,0 +1,34 @@
+"""AgentLatch — Terminal-native agent resilience middleware.
+
+Two decorators are all you need::
+
+    from agentlatch import profile_agent, safe_tool
+
+    @safe_tool
+    def query_db(sql: str) -> str:
+        ...
+
+    @profile_agent
+    def run_agent():
+        result = query_db("SELECT ...")
+        ...
+"""
+
+from agentlatch.config import is_dev_mode, set_dev_mode
+from agentlatch.decorators import profile_agent, safe_tool
+from agentlatch.renderer import render_flamegraph
+from agentlatch.sampler import sample_response
+from agentlatch.tracker import TraceEvent, get_trace
+
+__version__ = "0.1.0"
+__all__ = [
+    "profile_agent",
+    "safe_tool",
+    "render_flamegraph",
+    "sample_response",
+    "is_dev_mode",
+    "set_dev_mode",
+    "TraceEvent",
+    "get_trace",
+    "__version__",
+]

agentlatch-0.1.0/agentlatch/_types.py

@@ -0,0 +1,26 @@
+"""Shared types and enumerations for AgentLatch."""
+
+from __future__ import annotations
+
+import enum
+from typing import Any, TypeAlias
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+
+class EventStatus(enum.Enum):
+    """Status of a traced execution event."""
+
+    SUCCESS = "success"
+    ERROR = "error"
+    TIMEOUT = "timeout"
+
+
+# ---------------------------------------------------------------------------
+# Type Aliases
+# ---------------------------------------------------------------------------
+
+ErrorPayload: TypeAlias = dict[str, Any]
+"""Structured error information returned to the LLM instead of raising."""

agentlatch-0.1.0/agentlatch/banner.py

@@ -0,0 +1,336 @@
+"""Startup banner animation — Claude Code-style cosmic reveal.
+
+Displays a large ASCII art banner spelling AGENT / LATCH in bold block
+letters, surrounded by cosmic cloud formations and scattered stars.
+The entire scene progressively "decrypts" from noise into the final art
+via a diagonal sweep, followed by a typing effect for the welcome message.
+
+Gracefully degrades in non-TTY environments (CI, Docker, piped output).
+"""
+
+from __future__ import annotations
+
+import os
+import random
+import sys
+import time
+
+from rich.console import Console
+from rich.live import Live
+from rich.text import Text
+
+# ---------------------------------------------------------------------------
+# Block Letter Definitions  (each char is exactly 6 columns wide)
+# ---------------------------------------------------------------------------
+
+_LETTER_DATA: dict[str, list[str]] = {
+    "A": [" ████ ", "██  ██", "██████", "██  ██", "██  ██"],
+    "G": [" █████", "██    ", "██ ███", "██  ██", " █████"],
+    "E": ["██████", "██    ", "████  ", "██    ", "██████"],
+    "N": ["██  ██", "███ ██", "██████", "██ ███", "██  ██"],
+    "T": ["██████", "  ██  ", "  ██  ", "  ██  ", "  ██  "],
+    "L": ["██    ", "██    ", "██    ", "██    ", "██████"],
+    "C": [" █████", "██    ", "██    ", "██    ", " █████"],
+    "H": ["██  ██", "██  ██", "██████", "██  ██", "██  ██"],
+}
+
+
+def _build_word_lines(word: str, indent: int = 4, gap: int = 2) -> list[str]:
+    """Render a word as 5 lines of block-letter ASCII art."""
+    pad = " " * indent
+    sep = " " * gap
+    return [pad + sep.join(_LETTER_DATA[ch][row] for ch in word) for row in range(5)]
+
+
+# ---------------------------------------------------------------------------
+# Build the Full Art Scene
+# ---------------------------------------------------------------------------
+
+_ATMOS_TOP: list[str] = [
+    "...............................................................",
+    "",
+    "  *        ░░░░░░                              █████▓▓░       ",
+    "         ░░░░░░░░░░              *           ███▓░   ░░       ",
+    "       ░░░░░░░░░░░░░░░░                      ███▓░            ",
+    "    *                        *                 ██▓░░    ▓     ",
+    "                                                ░▓▓██▓▓░     ",
+    "",
+]
+
+_AGENT_LINES: list[str] = _build_word_lines("AGENT")
+_DIVIDER: list[str] = ["                       ⚡"]
+_LATCH_LINES: list[str] = _build_word_lines("LATCH")
+
+_ATMOS_BOTTOM: list[str] = [
+    "",
+    " *                       ░░░░                          *      ",
+    "                       ░░░░░░░░                               ",
+    "                     ░░░░░░░░░░░░░░                           ",
+    "                                                *             ",
+    "...............................................................",
+]
+
+_ART_LINES: list[str] = (
+    _ATMOS_TOP + _AGENT_LINES + _DIVIDER + _LATCH_LINES + _ATMOS_BOTTOM
+)
+
+# Pre-compute which rows are ASCII-art text (not atmosphere).
+_TEXT_ROW_START = len(_ATMOS_TOP)
+_TEXT_ROW_END = _TEXT_ROW_START + len(_AGENT_LINES) + len(_DIVIDER) + len(_LATCH_LINES)
+_TEXT_ROWS: set[int] = set(range(_TEXT_ROW_START, _TEXT_ROW_END))
+
+# ---------------------------------------------------------------------------
+# Welcome / Tagline
+# ---------------------------------------------------------------------------
+
+_WELCOME_LINE = "  Terminal-native agent resilience middleware  v0.1.0"
+_READY_LINE = "  Let's get started."
+
+# ---------------------------------------------------------------------------
+# Noise / Animation Config
+# ---------------------------------------------------------------------------
+
+_NOISE_CHARS: list[str] = [
+    "█",
+    "▓",
+    "▒",
+    "░",
+    "#",
+    "@",
+    "%",
+    "&",
+    "╬",
+    "╠",
+    "╣",
+    "╋",
+    "┃",
+    "┫",
+]
+
+_TOTAL_FRAMES = 32  # total decryption frames
+_FRAME_DELAY = 0.015  # ~15ms per frame → ~480ms total
+_TYPING_DELAY = 0.025  # per character for welcome text
+
+# ---------------------------------------------------------------------------
+# State
+# ---------------------------------------------------------------------------
+
+_banner_shown: bool = False
+
+# ---------------------------------------------------------------------------
+# Style Mapping
+# ---------------------------------------------------------------------------
+
+
+def _char_style(char: str, row: int) -> str:
+    """Determine the Rich style for a resolved character."""
+    if char == "⚡":
+        return "bold bright_yellow"
+    if char == "*":
+        return "bright_yellow"
+    if char == ".":
+        return "dim white"
+
+    # ASCII-art text rows → bold block letters
+    if row in _TEXT_ROWS:
+        return "bold bright_cyan"
+
+    # Atmosphere gradient (clouds with depth)
+    if char == "█":
+        return "bright_cyan"
+    if char == "▓":
+        return "cyan"
+    if char == "▒":
+        return "dim cyan"
+    if char == "░":
+        return "dim bright_white"
+
+    return "white"
+
+
+# ---------------------------------------------------------------------------
+# Resolve Map — when each character "decrypts"
+# ---------------------------------------------------------------------------
+
+
+def _build_resolve_map(
+    lines: list[str],
+    total_frames: int,
+) -> list[list[int]]:
+    """Assign a resolve-frame to every non-space character.
+
+    Dot borders flicker in first (frames 0–3).
+    The rest decrypts in a diagonal sweep (top-left → bottom-right)
+    with random jitter for an organic feel.
+    """
+    max_row = len(lines)
+    max_col = max((len(ln) for ln in lines), default=1)
+
+    rmap: list[list[int]] = []
+    for row, line in enumerate(lines):
+        row_map: list[int] = []
+        for col, ch in enumerate(line):
+            if ch == " ":
+                row_map.append(-1)  # always transparent
+            elif ch == ".":
+                row_map.append(random.randint(0, 3))  # dots early
+            else:
+                row_pct = row / max(max_row - 1, 1)
+                col_pct = col / max(max_col - 1, 1)
+                progress = row_pct * 0.55 + col_pct * 0.45
+                base = int(progress * (total_frames - 6)) + 3
+                jitter = random.randint(-3, 3)
+                frame = max(2, min(total_frames - 1, base + jitter))
+                row_map.append(frame)
+        rmap.append(row_map)
+    return rmap
+
+
+# ---------------------------------------------------------------------------
+# Frame Renderer
+# ---------------------------------------------------------------------------
+
+
+def _render_frame(
+    frame: int,
+    lines: list[str],
+    resolve_map: list[list[int]],
+) -> Text:
+    """Produce one animation frame as a Rich Text object."""
+    output = Text()
+
+    for row, line in enumerate(lines):
+        for col, ch in enumerate(line):
+            if ch == " ":
+                output.append(" ")
+                continue
+
+            resolve_at = resolve_map[row][col]
+
+            if frame >= resolve_at:
+                style = _char_style(ch, row)
+                output.append(ch, style=style)
+            else:
+                noise = random.choice(_NOISE_CHARS)
+                output.append(noise, style="dim bright_white")
+
+        output.append("\n")
+
+    return output
+
+
+# ---------------------------------------------------------------------------
+# Typing Effect
+# ---------------------------------------------------------------------------
+
+
+def _type_text(console: Console, text: str, style: str, delay: float) -> None:
+    """Print text character-by-character with a typing effect."""
+    for ch in text:
+        console.print(ch, end="", style=style, highlight=False)
+        time.sleep(delay)
+    console.print()  # newline
+
+
+# ---------------------------------------------------------------------------
+# Interactive Animation
+# ---------------------------------------------------------------------------
+
+
+def _play_animation(console: Console) -> None:
+    """Run the full cosmic reveal sequence."""
+    resolve_map = _build_resolve_map(_ART_LINES, _TOTAL_FRAMES)
+
+    # Phase 1: Decryption sweep of the ASCII art.
+    with Live(
+        _render_frame(0, _ART_LINES, resolve_map),
+        console=console,
+        refresh_per_second=62,
+        transient=True,
+    ) as live:
+        for frame in range(_TOTAL_FRAMES):
+            live.update(_render_frame(frame, _ART_LINES, resolve_map))
+            time.sleep(_FRAME_DELAY)
+
+    # Print the final, fully-resolved art (stays on screen).
+    final_art = _render_frame(_TOTAL_FRAMES, _ART_LINES, resolve_map)
+    console.print(final_art, end="")
+
+    # Phase 2: Welcome text types in.
+    console.print()
+    _type_text(console, _WELCOME_LINE, "bright_white", _TYPING_DELAY)
+    time.sleep(0.12)
+    _type_text(console, _READY_LINE, "dim bright_green", _TYPING_DELAY * 0.7)
+    console.print()
+
+
+# ---------------------------------------------------------------------------
+# Non-TTY Fallback
+# ---------------------------------------------------------------------------
+
+
+def _print_fallback(console: Console) -> None:
+    """Clean output for CI / Docker / piped environments."""
+    # Still show the ASCII art, just without animation.
+    for row, line in enumerate(_ART_LINES):
+        styled = Text()
+        for ch in line:
+            if ch == " ":
+                styled.append(" ")
+            else:
+                styled.append(ch, style=_char_style(ch, row))
+        console.print(styled)
+
+    console.print()
+    console.print(_WELCOME_LINE, style="bright_white")
+    console.print(_READY_LINE, style="dim bright_green")
+    console.print()
+
+
+# ---------------------------------------------------------------------------
+# Environment Detection
+# ---------------------------------------------------------------------------
+
+
+def _is_interactive() -> bool:
+    """Return True only if stdout is a real interactive terminal."""
+    if not sys.stdout.isatty():
+        return False
+    if os.environ.get("CI", "").lower() in ("true", "1"):
+        return False
+    if os.environ.get("TERM", "") == "dumb":
+        return False
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def initialize_latch(console: Console | None = None) -> None:
+    """Display the AgentLatch startup banner (once per process).
+
+    - **Interactive terminal**: plays the full cosmic decryption animation
+      with block-letter ASCII art reveal and typing effect.
+    - **Non-TTY / CI / Docker**: prints the static colored art without animation.
+
+    Calling this more than once per process is a no-op.
+    """
+    global _banner_shown
+    if _banner_shown:
+        return
+    _banner_shown = True
+
+    con = console or Console()
+
+    if _is_interactive():
+        _play_animation(con)
+    else:
+        _print_fallback(con)
+
+
+def reset_banner() -> None:
+    """Reset the banner flag.  Useful for tests."""
+    global _banner_shown
+    _banner_shown = False