clevagent 0.1.0__tar.gz

clevagent-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: clevagent
+Version: 0.1.0
+Summary: Monitor your AI agents. Heartbeat watchdog, loop detection, cost tracking.
+License-Expression: MIT
+Project-URL: Homepage, https://clevagent.io
+Project-URL: Documentation, https://clevagent.io/docs
+Project-URL: Repository, https://github.com/clevagent/clevagent-python
+Keywords: ai,agent,monitoring,heartbeat,observability
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.26.0; extra == "anthropic"
+Provides-Extra: all
+Requires-Dist: openai>=1.0.0; extra == "all"
+Requires-Dist: anthropic>=0.26.0; extra == "all"
+
+# ClevAgent SDK
+
+Monitor your AI agents in 2 lines of code.
+
+```python
+import clevagent
+clevagent.init(api_key=os.environ["CLEVAGENT_API_KEY"], agent="my-agent")
+```
+
+That's it. ClevAgent sends heartbeats every 60 seconds. If your agent goes silent, you get an alert.
+
+## Install
+
+```bash
+pip install clevagent
+```
+
+## Features
+
+- **Heartbeat watchdog** — detect dead agents automatically
+- **Loop detection** — catch runaway tool-call loops
+- **Cost tracking** — auto-capture for OpenAI/Anthropic SDKs; manual `log_cost()` for others
+- **Auto-restart** — restart Docker containers when agents die (requires `container_id`)
+- **Crash capture** — send last error as an emergency heartbeat on unhandled exceptions
+
+## Quick Start
+
+```python
+import os
+import clevagent
+
+clevagent.init(
+    api_key=os.environ["CLEVAGENT_API_KEY"],
+    agent="my-trading-bot",        # agent name (auto-created on first ping)
+    interval=60,                   # heartbeat interval in seconds
+    auto_cost=True,                # auto-capture OpenAI/Anthropic usage
+)
+
+# --- your agent code runs here ---
+
+# Optional: manual ping with context
+clevagent.ping(
+    status="ok",
+    message="Processed 42 signals",
+    iteration_count=42,
+)
+
+# Optional: manual cost logging (for other SDKs)
+clevagent.log_cost(tokens=1500, cost_usd=0.0023)
+```
+
+## Cost Tracking
+
+| Method | SDKs |
+|--------|------|
+| Auto ✅ | OpenAI (`gpt-4o`, `gpt-4o-mini`, etc.), Anthropic (`claude-3`, `claude-4`) |
+| Manual 📝 | Any other SDK — use `clevagent.log_cost(tokens=N, cost_usd=X)` |
+| Not supported ❌ | Streaming responses (use manual for those) |
+
+## Auto-Restart
+
+Auto-restart requires Docker and a `container_id` configured in the ClevAgent dashboard. Non-Docker deployments are not supported.
+
+## Links
+
+- [Dashboard](https://clevagent.io)
+- [Documentation](https://clevagent.io/docs)
+- [Support](mailto:support@clevagent.io)

clevagent-0.1.0/README.md

@@ -0,0 +1,68 @@
+# ClevAgent SDK
+
+Monitor your AI agents in 2 lines of code.
+
+```python
+import clevagent
+clevagent.init(api_key=os.environ["CLEVAGENT_API_KEY"], agent="my-agent")
+```
+
+That's it. ClevAgent sends heartbeats every 60 seconds. If your agent goes silent, you get an alert.
+
+## Install
+
+```bash
+pip install clevagent
+```
+
+## Features
+
+- **Heartbeat watchdog** — detect dead agents automatically
+- **Loop detection** — catch runaway tool-call loops
+- **Cost tracking** — auto-capture for OpenAI/Anthropic SDKs; manual `log_cost()` for others
+- **Auto-restart** — restart Docker containers when agents die (requires `container_id`)
+- **Crash capture** — send last error as an emergency heartbeat on unhandled exceptions
+
+## Quick Start
+
+```python
+import os
+import clevagent
+
+clevagent.init(
+    api_key=os.environ["CLEVAGENT_API_KEY"],
+    agent="my-trading-bot",        # agent name (auto-created on first ping)
+    interval=60,                   # heartbeat interval in seconds
+    auto_cost=True,                # auto-capture OpenAI/Anthropic usage
+)
+
+# --- your agent code runs here ---
+
+# Optional: manual ping with context
+clevagent.ping(
+    status="ok",
+    message="Processed 42 signals",
+    iteration_count=42,
+)
+
+# Optional: manual cost logging (for other SDKs)
+clevagent.log_cost(tokens=1500, cost_usd=0.0023)
+```
+
+## Cost Tracking
+
+| Method | SDKs |
+|--------|------|
+| Auto ✅ | OpenAI (`gpt-4o`, `gpt-4o-mini`, etc.), Anthropic (`claude-3`, `claude-4`) |
+| Manual 📝 | Any other SDK — use `clevagent.log_cost(tokens=N, cost_usd=X)` |
+| Not supported ❌ | Streaming responses (use manual for those) |
+
+## Auto-Restart
+
+Auto-restart requires Docker and a `container_id` configured in the ClevAgent dashboard. Non-Docker deployments are not supported.
+
+## Links
+
+- [Dashboard](https://clevagent.io)
+- [Documentation](https://clevagent.io/docs)
+- [Support](mailto:support@clevagent.io)

clevagent-0.1.0/clevagent/__init__.py

@@ -0,0 +1,156 @@
+"""
+ClevAgent SDK — Monitor your AI agents in 2 lines of code.
+
+    import clevagent
+    clevagent.init(api_key="cv_xxx", agent="my-agent")
+
+The SDK starts a background daemon thread that sends heartbeats to the
+ClevAgent API every `interval` seconds. If the process dies, pings stop,
+and the server detects the silence and fires an alert.
+"""
+
+import logging
+from typing import Optional
+
+from ._state import _state
+from ._heartbeat import HeartbeatThread
+from ._cost_tracker import install_auto_cost
+from ._signals import install_signal_handlers
+from ._crash_handler import install as _install_crash_handler
+
+logger = logging.getLogger("clevagent")
+
+# Module-level thread reference — replaced on each init() call
+_thread: Optional[HeartbeatThread] = None
+
+
+def init(
+    api_key: str,
+    agent: str,
+    interval: int = 60,
+    endpoint: str = "https://api.clevagent.io",
+    auto_cost: bool = True,
+) -> None:
+    """
+    Initialize ClevAgent monitoring. Call once at agent startup.
+
+    Args:
+        api_key:   Project API key from the ClevAgent dashboard (cv_xxx).
+        agent:     Unique agent name within the project. Auto-created on first ping.
+        interval:  Heartbeat interval in seconds (default: 60).
+        endpoint:  API base URL (override for self-hosted or local dev).
+        auto_cost: If True, monkey-patches OpenAI/Anthropic SDKs to capture usage.
+                   Falls back gracefully if SDKs are not installed or have changed.
+    """
+    global _thread
+
+    # Stop existing thread if re-initializing
+    if _thread is not None and _thread.is_alive():
+        _thread.stop(send_final=False)
+
+    _state.api_key = api_key
+    _state.agent = agent
+    _state.interval = interval
+    _state.endpoint = endpoint.rstrip("/")
+    _state.initialized = True
+
+    if auto_cost:
+        install_auto_cost()
+
+    _install_crash_handler()
+
+    _thread = HeartbeatThread()
+    _thread.start()
+
+    install_signal_handlers()
+
+    logger.info(
+        "ClevAgent initialized — agent=%s endpoint=%s interval=%ds auto_cost=%s",
+        agent, _state.endpoint, interval, auto_cost,
+    )
+
+
+def ping(
+    status: str = "ok",
+    message: Optional[str] = None,
+    tokens_used: Optional[int] = None,
+    cost_usd: Optional[float] = None,
+    tool_calls: Optional[int] = None,
+    iteration_count: Optional[int] = None,
+    memory_mb: Optional[float] = None,
+    custom: Optional[dict] = None,
+) -> None:
+    """
+    Send a manual heartbeat ping.
+
+    Use for granular control — e.g., after completing a task loop, or to
+    report a warning/error state before the regular interval fires.
+
+    Args:
+        status:          "ok" | "warning" | "error"
+        message:         Optional free-text status message (used for loop detection).
+        tokens_used:     Token count for this ping cycle.
+        cost_usd:        Cost for this ping cycle in USD.
+        tool_calls:      Number of tool calls made since last ping.
+        iteration_count: Current loop iteration count (for loop detection).
+        memory_mb:       Current memory usage in MB.
+        custom:          Arbitrary JSON-serializable dict stored in Heartbeat.custom_data.
+    """
+    if _thread is None:
+        raise RuntimeError(
+            "clevagent.init() must be called before ping(). "
+            "Example: clevagent.init(api_key='cv_xxx', agent='my-agent')"
+        )
+    extra: dict = {}
+    if custom is not None:
+        import json
+        extra["custom_data"] = json.dumps(custom)
+
+    _thread.send_now(
+        status=status,
+        message=message,
+        tokens_used=tokens_used,
+        cost_usd=cost_usd,
+        tool_calls=tool_calls,
+        iteration_count=iteration_count,
+        memory_mb=memory_mb,
+        **extra,
+    )
+
+
+def log_cost(tokens: int, cost_usd: float, model: Optional[str] = None) -> None:  # noqa: ARG001
+    """
+    Explicitly log cost data. Use this as a fallback when auto_cost is
+    unavailable or when you want precise cost accounting.
+
+    Example:
+        response = client.messages.create(...)
+        clevagent.log_cost(
+            tokens=response.usage.input_tokens + response.usage.output_tokens,
+            cost_usd=0.0045,
+        )
+    """
+    _state.accumulate_cost(tokens=tokens, cost_usd=cost_usd)
+
+
+def log_iteration(count: int) -> None:
+    """
+    Log the current iteration count. Used by the loop detector to identify
+    runaway agents that keep incrementing without progress.
+    """
+    _state._iteration_count = count
+
+
+def shutdown() -> None:
+    """
+    Stop the heartbeat thread gracefully.
+
+    Sends a final "shutdown" heartbeat so the server knows the agent
+    stopped intentionally (not crashed). Auto-called on SIGTERM/SIGINT.
+    """
+    global _thread
+    if _thread is not None:
+        _thread.stop(send_final=True)
+        _thread = None
+    _state.initialized = False
+    logger.info("ClevAgent shutdown complete")

clevagent-0.1.0/clevagent/_client.py

@@ -0,0 +1,49 @@
+"""HTTP client for ClevAgent API.
+
+Uses `requests` (only external dependency) with a 5-second timeout and 1 retry.
+X-API-Key auth header is set automatically from _state.
+"""
+
+import logging
+from typing import Any, Optional
+
+import requests
+
+logger = logging.getLogger("clevagent")
+
+_TIMEOUT = 5   # seconds per request
+_RETRIES = 1   # retry once on network error
+
+
+def send_heartbeat(
+    endpoint: str,
+    api_key: str,
+    agent: str,
+    **payload: Any,
+) -> Optional[dict]:
+    """
+    POST /api/v1/heartbeat.
+
+    Returns the parsed JSON response on success, or None on failure.
+    Never raises — all errors are logged as warnings.
+    """
+    url = f"{endpoint}/api/v1/heartbeat"
+    headers = {"X-API-Key": api_key, "Content-Type": "application/json"}
+    body = {"agent": agent, **{k: v for k, v in payload.items() if v is not None}}
+
+    last_err: Optional[Exception] = None
+    for attempt in range(_RETRIES + 1):
+        try:
+            resp = requests.post(url, json=body, headers=headers, timeout=_TIMEOUT)
+            resp.raise_for_status()
+            return resp.json()
+        except requests.exceptions.RequestException as exc:
+            last_err = exc
+            if attempt < _RETRIES:
+                logger.debug("Heartbeat attempt %d failed, retrying: %s", attempt + 1, exc)
+
+    logger.warning(
+        "Heartbeat failed after %d attempt(s) — agent=%s error=%s",
+        _RETRIES + 1, agent, last_err,
+    )
+    return None

clevagent-0.1.0/clevagent/_cost_tracker.py

@@ -0,0 +1,265 @@
+"""Auto cost tracking — monkey-patches OpenAI and Anthropic SDK clients.
+
+⚠️  SDK versioning risk: internal class paths may change between library versions.
+    All patches are wrapped in try/except. On failure: logs a warning, leaves auto_cost
+    inactive, and directs the user to clevagent.log_cost() for manual tracking.
+
+OpenAI v1.x: patches openai.resources.chat.completions.Completions.create
+             patches openai.resources.chat.completions.AsyncCompletions.create
+Anthropic:   patches anthropic.resources.messages.Messages.create
+             patches anthropic.resources.messages.AsyncMessages.create
+
+⚠️  Streaming (stream=True) is NOT auto-tracked in v0.1.0.
+    For streaming calls, use clevagent.log_cost(tokens=N, cost_usd=X.XX) manually.
+    Streaming auto-cost is planned for v0.2.0.
+"""
+
+import logging
+from typing import Optional
+
+logger = logging.getLogger("clevagent")
+
+
+# ── Pricing tables ─────────────────────────────────────────────────────────────
+
+# USD per 1,000 input/output tokens
+_OPENAI_PRICING: dict[str, dict[str, float]] = {
+    "gpt-4o-mini":       {"input": 0.000150, "output": 0.000600},
+    "gpt-4o":            {"input": 0.005,    "output": 0.015},
+    "gpt-4-turbo":       {"input": 0.01,     "output": 0.03},
+    "gpt-4":             {"input": 0.03,     "output": 0.06},
+    "gpt-3.5-turbo":     {"input": 0.0005,   "output": 0.0015},
+}
+
+# USD per 1,000,000 input/output tokens
+_ANTHROPIC_PRICING: dict[str, dict[str, float]] = {
+    "claude-haiku-4":    {"input": 0.80,  "output": 4.0},
+    "claude-sonnet-4":   {"input": 3.0,   "output": 15.0},
+    "claude-opus-4":     {"input": 15.0,  "output": 75.0},
+    "claude-3-haiku":    {"input": 0.25,  "output": 1.25},
+    "claude-3-5-sonnet": {"input": 3.0,   "output": 15.0},
+    "claude-3-opus":     {"input": 15.0,  "output": 75.0},
+}
+
+
+def _match_pricing(model: str, table: dict) -> Optional[dict]:
+    """Find the best pricing entry for a model name (substring match)."""
+    model_lower = model.lower()
+    for key, pricing in table.items():
+        if key in model_lower:
+            return pricing
+    return None
+
+
+def _calc_openai_cost(model: str, usage) -> float:
+    pricing = _match_pricing(model, _OPENAI_PRICING)
+    if not pricing:
+        return 0.0
+    return (
+        (getattr(usage, "prompt_tokens", 0) / 1000) * pricing["input"] +
+        (getattr(usage, "completion_tokens", 0) / 1000) * pricing["output"]
+    )
+
+
+def _calc_anthropic_cost(model: str, usage) -> float:
+    pricing = _match_pricing(model, _ANTHROPIC_PRICING)
+    if not pricing:
+        return 0.0
+    return (
+        (getattr(usage, "input_tokens", 0) / 1_000_000) * pricing["input"] +
+        (getattr(usage, "output_tokens", 0) / 1_000_000) * pricing["output"]
+    )
+
+
+# ── Patches ────────────────────────────────────────────────────────────────────
+
+def _patch_openai() -> bool:
+    """
+    Patch OpenAI SDK v1.x (openai.resources.chat.completions.Completions.create).
+    Returns True if patch was applied successfully.
+    """
+    try:
+        from openai.resources.chat.completions import Completions  # type: ignore
+        from ._state import _state
+
+        _original = Completions.create
+
+        def _patched(self_inner, *args, **kwargs):
+            if kwargs.get("stream"):
+                logger.warning(
+                    "clevagent auto_cost: stream=True detected — streaming is not auto-tracked "
+                    "in v0.1.0. Use clevagent.log_cost(tokens=N, cost_usd=X) manually."
+                )
+                return _original(self_inner, *args, **kwargs)
+            resp = _original(self_inner, *args, **kwargs)
+            try:
+                usage = getattr(resp, "usage", None)
+                if usage:
+                    model = getattr(resp, "model", "")
+                    tokens = getattr(usage, "total_tokens", 0)
+                    cost = _calc_openai_cost(model, usage)
+                    # Count tool calls from response choices
+                    tool_calls = 0
+                    choices = getattr(resp, "choices", [])
+                    if choices:
+                        tc = getattr(getattr(choices[0], "message", None), "tool_calls", None)
+                        tool_calls = len(tc) if tc else 0
+                    _state.accumulate_cost(tokens=tokens, cost_usd=cost, tool_calls=tool_calls)
+            except Exception:
+                pass  # Never let tracking errors affect the actual API call
+            return resp
+
+        Completions.create = _patched
+        logger.debug("OpenAI SDK patched (Completions.create)")
+        return True
+
+    except (ImportError, AttributeError) as exc:
+        logger.debug("OpenAI patch skipped: %s", exc)
+        return False
+
+
+def _patch_openai_async() -> bool:
+    """
+    Patch OpenAI SDK v1.x async client (AsyncCompletions.create).
+    Returns True if patch was applied successfully.
+    """
+    try:
+        from openai.resources.chat.completions import AsyncCompletions  # type: ignore
+        from ._state import _state
+
+        _original = AsyncCompletions.create
+
+        async def _patched_async(self_inner, *args, **kwargs):
+            if kwargs.get("stream"):
+                logger.warning(
+                    "clevagent auto_cost: stream=True detected — streaming is not auto-tracked "
+                    "in v0.1.0. Use clevagent.log_cost(tokens=N, cost_usd=X) manually."
+                )
+                return await _original(self_inner, *args, **kwargs)
+            resp = await _original(self_inner, *args, **kwargs)
+            try:
+                usage = getattr(resp, "usage", None)
+                if usage:
+                    model = getattr(resp, "model", "")
+                    tokens = getattr(usage, "total_tokens", 0)
+                    cost = _calc_openai_cost(model, usage)
+                    tool_calls = 0
+                    choices = getattr(resp, "choices", [])
+                    if choices:
+                        tc = getattr(getattr(choices[0], "message", None), "tool_calls", None)
+                        tool_calls = len(tc) if tc else 0
+                    _state.accumulate_cost(tokens=tokens, cost_usd=cost, tool_calls=tool_calls)
+            except Exception:
+                pass
+            return resp
+
+        AsyncCompletions.create = _patched_async
+        logger.debug("OpenAI SDK patched (AsyncCompletions.create)")
+        return True
+
+    except (ImportError, AttributeError) as exc:
+        logger.debug("OpenAI async patch skipped: %s", exc)
+        return False
+
+
+def _patch_anthropic() -> bool:
+    """
+    Patch Anthropic SDK (anthropic.resources.messages.Messages.create).
+    Returns True if patch was applied successfully.
+    """
+    try:
+        from anthropic.resources.messages import Messages  # type: ignore
+        from ._state import _state
+
+        _original = Messages.create
+
+        def _patched(self_inner, *args, **kwargs):
+            if kwargs.get("stream"):
+                logger.warning(
+                    "clevagent auto_cost: stream=True detected — streaming is not auto-tracked "
+                    "in v0.1.0. Use clevagent.log_cost(tokens=N, cost_usd=X) manually."
+                )
+                return _original(self_inner, *args, **kwargs)
+            resp = _original(self_inner, *args, **kwargs)
+            try:
+                usage = getattr(resp, "usage", None)
+                if usage:
+                    model = getattr(resp, "model", "")
+                    tokens = (
+                        getattr(usage, "input_tokens", 0) +
+                        getattr(usage, "output_tokens", 0)
+                    )
+                    cost = _calc_anthropic_cost(model, usage)
+                    _state.accumulate_cost(tokens=tokens, cost_usd=cost)
+            except Exception:
+                pass
+            return resp
+
+        Messages.create = _patched
+        logger.debug("Anthropic SDK patched (Messages.create)")
+        return True
+
+    except (ImportError, AttributeError) as exc:
+        logger.debug("Anthropic patch skipped: %s", exc)
+        return False
+
+
+def _patch_anthropic_async() -> bool:
+    """
+    Patch Anthropic SDK async client (AsyncMessages.create).
+    Returns True if patch was applied successfully.
+    """
+    try:
+        from anthropic.resources.messages import AsyncMessages  # type: ignore
+        from ._state import _state
+
+        _original = AsyncMessages.create
+
+        async def _patched_async(self_inner, *args, **kwargs):
+            if kwargs.get("stream"):
+                logger.warning(
+                    "clevagent auto_cost: stream=True detected — streaming is not auto-tracked "
+                    "in v0.1.0. Use clevagent.log_cost(tokens=N, cost_usd=X) manually."
+                )
+                return await _original(self_inner, *args, **kwargs)
+            resp = await _original(self_inner, *args, **kwargs)
+            try:
+                usage = getattr(resp, "usage", None)
+                if usage:
+                    model = getattr(resp, "model", "")
+                    tokens = (
+                        getattr(usage, "input_tokens", 0) +
+                        getattr(usage, "output_tokens", 0)
+                    )
+                    cost = _calc_anthropic_cost(model, usage)
+                    _state.accumulate_cost(tokens=tokens, cost_usd=cost)
+            except Exception:
+                pass
+            return resp
+
+        AsyncMessages.create = _patched_async
+        logger.debug("Anthropic SDK patched (AsyncMessages.create)")
+        return True
+
+    except (ImportError, AttributeError) as exc:
+        logger.debug("Anthropic async patch skipped: %s", exc)
+        return False
+
+
+def install_auto_cost() -> None:
+    """
+    Activate auto cost tracking. Patches available AI SDKs; skips missing ones.
+    If no SDK is found, logs guidance for manual tracking via clevagent.log_cost().
+    """
+    from ._state import _state
+
+    patched = _patch_openai() | _patch_openai_async() | _patch_anthropic() | _patch_anthropic_async()
+
+    if patched:
+        _state.auto_cost_active = True
+        logger.info("Auto cost tracking enabled")
+    else:
+        logger.info(
+            "Auto cost tracking inactive — openai/anthropic not installed. "
+            "Use clevagent.log_cost(tokens=N, cost_usd=X.XX) for manual tracking."
+        )

clevagent-0.1.0/clevagent/_crash_handler.py

@@ -0,0 +1,35 @@
+"""
+Crash handler — captures unhandled exceptions and sends an emergency heartbeat.
+
+Chains the existing sys.excepthook so other libraries (e.g., IPython, pytest)
+are not broken. Only fires if clevagent.init() has been called.
+"""
+
+import sys
+import traceback
+
+_original_excepthook = sys.excepthook
+
+
+def _crash_handler(exc_type, exc_value, exc_tb):
+    error_msg = f"{exc_type.__name__}: {exc_value}"
+    tb_short = "".join(traceback.format_tb(exc_tb)[-3:])
+
+    try:
+        from clevagent._state import _state
+        if _state.initialized:
+            from clevagent._client import send_heartbeat
+            send_heartbeat(
+                status="error",
+                message=f"CRASH: {error_msg}",
+                custom={"traceback": tb_short, "crash": True},
+            )
+    except Exception:
+        pass  # Never let crash-capture errors suppress the real traceback
+
+    _original_excepthook(exc_type, exc_value, exc_tb)
+
+
+def install():
+    """Install the crash handler as sys.excepthook."""
+    sys.excepthook = _crash_handler

clevagent-0.1.0/clevagent/_heartbeat.py

@@ -0,0 +1,80 @@
+"""Background heartbeat thread.
+
+A daemon thread sends POST /api/v1/heartbeat every `_state.interval` seconds.
+On shutdown(), a final "shutdown" heartbeat is sent before the thread exits.
+The stop event allows immediate wake-up when shutdown() is called mid-sleep.
+"""
+
+import logging
+import threading
+from typing import Any, Optional
+
+from ._client import send_heartbeat
+from ._state import _state
+
+logger = logging.getLogger("clevagent")
+
+
+class HeartbeatThread(threading.Thread):
+
+    def __init__(self) -> None:
+        super().__init__(daemon=True, name="clevagent-heartbeat")
+        self._stop_event = threading.Event()
+
+    def run(self) -> None:
+        logger.debug(
+            "Heartbeat thread started (agent=%s interval=%ds endpoint=%s)",
+            _state.agent, _state.interval, _state.endpoint,
+        )
+        # Send initial heartbeat immediately so the server knows the agent is alive.
+        self._send_heartbeat()
+
+        # wait(timeout) returns True if stop was requested, False on timeout.
+        # Loop continues as long as the event is NOT set (i.e., normal operation).
+        while not self._stop_event.wait(timeout=_state.interval):
+            self._send_heartbeat()
+
+    def _send_heartbeat(
+        self,
+        status: str = "ok",
+        message: Optional[str] = None,
+        extra: Optional[dict] = None,
+    ) -> None:
+        """Send one heartbeat, including accumulated cost/usage data."""
+        data = _state.flush_and_reset()
+        if extra:
+            data.update({k: v for k, v in extra.items() if v is not None})
+
+        resp = send_heartbeat(
+            endpoint=_state.endpoint,
+            api_key=_state.api_key,
+            agent=_state.agent,
+            status=status,
+            message=message,
+            **data,
+        )
+
+        if resp and resp.get("agent_id"):
+            _state.agent_id = resp["agent_id"]
+            logger.debug("Heartbeat OK — agent_id=%s server_status=%s",
+                         _state.agent_id, resp.get("status"))
+
+    def send_now(
+        self,
+        status: str = "ok",
+        message: Optional[str] = None,
+        **extra: Any,
+    ) -> None:
+        """Trigger an immediate out-of-band heartbeat (used by ping())."""
+        self._send_heartbeat(status=status, message=message, extra=extra)
+
+    def stop(self, send_final: bool = True) -> None:
+        """Signal the thread to stop. If send_final=True, sends a shutdown heartbeat."""
+        self._stop_event.set()
+        if send_final:
+            try:
+                self._send_heartbeat(status="shutdown", message="Agent shutting down gracefully")
+            except Exception as exc:
+                logger.debug("Final heartbeat skipped: %s", exc)
+        self.join(timeout=10)
+        logger.debug("Heartbeat thread stopped")

clevagent-0.1.0/clevagent/_signals.py

@@ -0,0 +1,32 @@
+"""SIGTERM/SIGINT signal handler — calls clevagent.shutdown() on process termination.
+
+Must be installed from the main thread; safely skips if called from a non-main thread
+(e.g., when the user embeds clevagent in a thread-based framework).
+"""
+
+import logging
+import signal
+
+logger = logging.getLogger("clevagent")
+
+
+def install_signal_handlers() -> None:
+    """Register SIGTERM and SIGINT handlers to call clevagent.shutdown()."""
+
+    def _handle(signum: int, frame) -> None:  # noqa: ARG001
+        logger.info("clevagent: signal %s received — shutting down gracefully", signum)
+        # Import at call-time to avoid circular import at module load
+        import clevagent
+        clevagent.shutdown()
+
+    try:
+        signal.signal(signal.SIGTERM, _handle)
+        signal.signal(signal.SIGINT, _handle)
+        logger.debug("Signal handlers registered (SIGTERM, SIGINT)")
+    except (OSError, ValueError):
+        # signal.signal() raises ValueError if called from a non-main thread,
+        # and OSError on some restricted environments.
+        logger.debug(
+            "clevagent: signal handler registration skipped "
+            "(not in main thread or restricted environment)"
+        )

clevagent-0.1.0/clevagent/_state.py

@@ -0,0 +1,59 @@
+"""Shared SDK state — single mutable object shared across all SDK modules."""
+
+import threading
+from typing import Optional
+
+
+class _SDKState:
+    """Thread-safe container for SDK runtime state."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+
+        # Configuration (set by init())
+        self.api_key: str = ""
+        self.agent: str = ""
+        self.interval: int = 60
+        self.endpoint: str = "https://api.clevagent.io"
+
+        # Runtime
+        self.agent_id: Optional[int] = None
+        self.auto_cost_active: bool = False
+        self.initialized: bool = False
+
+        # Accumulated cost/usage between heartbeats (reset after each send)
+        self._tokens: int = 0
+        self._cost_usd: float = 0.0
+        self._tool_calls: int = 0
+        self._iteration_count: Optional[int] = None
+
+    def accumulate_cost(
+        self,
+        tokens: int = 0,
+        cost_usd: float = 0.0,
+        tool_calls: int = 0,
+    ) -> None:
+        """Thread-safe accumulation of usage data."""
+        with self._lock:
+            self._tokens += tokens
+            self._cost_usd += cost_usd
+            self._tool_calls += tool_calls
+
+    def flush_and_reset(self) -> dict:
+        """Return accumulated data as a dict and reset counters. Thread-safe."""
+        with self._lock:
+            data = {
+                "tokens_used": self._tokens if self._tokens else None,
+                "cost_usd": self._cost_usd if self._cost_usd else None,
+                "tool_calls": self._tool_calls if self._tool_calls else None,
+                "iteration_count": self._iteration_count,
+            }
+            self._tokens = 0
+            self._cost_usd = 0.0
+            self._tool_calls = 0
+            # iteration_count is set externally by log_iteration() — don't reset
+            return data
+
+
+# Module-level singleton
+_state = _SDKState()

clevagent-0.1.0/clevagent.egg-info/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: clevagent
+Version: 0.1.0
+Summary: Monitor your AI agents. Heartbeat watchdog, loop detection, cost tracking.
+License-Expression: MIT
+Project-URL: Homepage, https://clevagent.io
+Project-URL: Documentation, https://clevagent.io/docs
+Project-URL: Repository, https://github.com/clevagent/clevagent-python
+Keywords: ai,agent,monitoring,heartbeat,observability
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.26.0; extra == "anthropic"
+Provides-Extra: all
+Requires-Dist: openai>=1.0.0; extra == "all"
+Requires-Dist: anthropic>=0.26.0; extra == "all"
+
+# ClevAgent SDK
+
+Monitor your AI agents in 2 lines of code.
+
+```python
+import clevagent
+clevagent.init(api_key=os.environ["CLEVAGENT_API_KEY"], agent="my-agent")
+```
+
+That's it. ClevAgent sends heartbeats every 60 seconds. If your agent goes silent, you get an alert.
+
+## Install
+
+```bash
+pip install clevagent
+```
+
+## Features
+
+- **Heartbeat watchdog** — detect dead agents automatically
+- **Loop detection** — catch runaway tool-call loops
+- **Cost tracking** — auto-capture for OpenAI/Anthropic SDKs; manual `log_cost()` for others
+- **Auto-restart** — restart Docker containers when agents die (requires `container_id`)
+- **Crash capture** — send last error as an emergency heartbeat on unhandled exceptions
+
+## Quick Start
+
+```python
+import os
+import clevagent
+
+clevagent.init(
+    api_key=os.environ["CLEVAGENT_API_KEY"],
+    agent="my-trading-bot",        # agent name (auto-created on first ping)
+    interval=60,                   # heartbeat interval in seconds
+    auto_cost=True,                # auto-capture OpenAI/Anthropic usage
+)
+
+# --- your agent code runs here ---
+
+# Optional: manual ping with context
+clevagent.ping(
+    status="ok",
+    message="Processed 42 signals",
+    iteration_count=42,
+)
+
+# Optional: manual cost logging (for other SDKs)
+clevagent.log_cost(tokens=1500, cost_usd=0.0023)
+```
+
+## Cost Tracking
+
+| Method | SDKs |
+|--------|------|
+| Auto ✅ | OpenAI (`gpt-4o`, `gpt-4o-mini`, etc.), Anthropic (`claude-3`, `claude-4`) |
+| Manual 📝 | Any other SDK — use `clevagent.log_cost(tokens=N, cost_usd=X)` |
+| Not supported ❌ | Streaming responses (use manual for those) |
+
+## Auto-Restart
+
+Auto-restart requires Docker and a `container_id` configured in the ClevAgent dashboard. Non-Docker deployments are not supported.
+
+## Links
+
+- [Dashboard](https://clevagent.io)
+- [Documentation](https://clevagent.io/docs)
+- [Support](mailto:support@clevagent.io)

clevagent-0.1.0/clevagent.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+clevagent/__init__.py
+clevagent/_client.py
+clevagent/_cost_tracker.py
+clevagent/_crash_handler.py
+clevagent/_heartbeat.py
+clevagent/_signals.py
+clevagent/_state.py
+clevagent.egg-info/PKG-INFO
+clevagent.egg-info/SOURCES.txt
+clevagent.egg-info/dependency_links.txt
+clevagent.egg-info/requires.txt
+clevagent.egg-info/top_level.txt

clevagent-0.1.0/clevagent.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

clevagent-0.1.0/clevagent.egg-info/requires.txt

@@ -0,0 +1,11 @@
+requests>=2.25.0
+
+[all]
+openai>=1.0.0
+anthropic>=0.26.0
+
+[anthropic]
+anthropic>=0.26.0
+
+[openai]
+openai>=1.0.0

clevagent-0.1.0/clevagent.egg-info/top_level.txt

@@ -0,0 +1 @@
+clevagent

clevagent-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "clevagent"
+version = "0.1.0"
+description = "Monitor your AI agents. Heartbeat watchdog, loop detection, cost tracking."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+keywords = ["ai", "agent", "monitoring", "heartbeat", "observability"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "requests>=2.25.0",
+]
+
+[project.optional-dependencies]
+# Auto-cost tracking works if these are installed — not required
+openai = ["openai>=1.0.0"]
+anthropic = ["anthropic>=0.26.0"]
+all = ["openai>=1.0.0", "anthropic>=0.26.0"]
+
+[project.urls]
+Homepage = "https://clevagent.io"
+Documentation = "https://clevagent.io/docs"
+Repository = "https://github.com/clevagent/clevagent-python"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["clevagent*"]

clevagent-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+