raindrop-strands 0.0.1__tar.gz

raindrop_strands-0.0.1/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.1
+Name: raindrop-strands
+Version: 0.0.1
+Summary: Raindrop integration for Strands Agents
+License: MIT
+Author: Raindrop AI
+Author-email: sdk@raindrop.ai
+Requires-Python: >=3.10,<4.0
+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
+Requires-Dist: raindrop-ai (>=0.0.42)
+Requires-Dist: strands-agents (>=1.0.0)
+Description-Content-Type: text/markdown
+
+# raindrop-strands
+
+Raindrop integration for [Strands Agents](https://strandsagents.com) (Python). Automatically captures agent invocations, model calls, tool usage, and token metrics via the Strands hook system.
+
+## Installation
+
+```bash
+pip install raindrop-strands strands-agents
+```
+
+`strands-agents` is a required dependency.
+
+## Usage
+
+```python
+import os
+from strands import Agent
+from raindrop_strands import create_raindrop_strands
+
+raindrop = create_raindrop_strands(
+    api_key=os.environ.get("RAINDROP_API_KEY"),
+    user_id="user_123",
+    convo_id="session_456",
+)
+
+agent = Agent(
+    model="us.amazon.nova-lite-v1:0",
+    system_prompt="You are a helpful assistant.",
+)
+
+raindrop["handler"].register_hooks(agent)
+
+result = agent("What is the capital of France?")
+print(result)
+
+raindrop["flush"]()
+```
+
+Omitting `api_key` disables telemetry shipping (a warning is emitted) but does not crash your application.
+
+## API
+
+### `create_raindrop_strands(api_key, user_id, convo_id)`
+
+Returns a dict with:
+
+- `"handler"` — `RaindropStrandsHandler` instance to register on agents
+- `"flush"` — flush pending telemetry
+- `"shutdown"` — flush and release resources
+
+## Testing
+
+```bash
+cd packages/strands-python
+poetry install --with dev
+pytest
+```
+
+## License
+
+MIT
+

raindrop_strands-0.0.1/README.md

@@ -0,0 +1,61 @@
+# raindrop-strands
+
+Raindrop integration for [Strands Agents](https://strandsagents.com) (Python). Automatically captures agent invocations, model calls, tool usage, and token metrics via the Strands hook system.
+
+## Installation
+
+```bash
+pip install raindrop-strands strands-agents
+```
+
+`strands-agents` is a required dependency.
+
+## Usage
+
+```python
+import os
+from strands import Agent
+from raindrop_strands import create_raindrop_strands
+
+raindrop = create_raindrop_strands(
+    api_key=os.environ.get("RAINDROP_API_KEY"),
+    user_id="user_123",
+    convo_id="session_456",
+)
+
+agent = Agent(
+    model="us.amazon.nova-lite-v1:0",
+    system_prompt="You are a helpful assistant.",
+)
+
+raindrop["handler"].register_hooks(agent)
+
+result = agent("What is the capital of France?")
+print(result)
+
+raindrop["flush"]()
+```
+
+Omitting `api_key` disables telemetry shipping (a warning is emitted) but does not crash your application.
+
+## API
+
+### `create_raindrop_strands(api_key, user_id, convo_id)`
+
+Returns a dict with:
+
+- `"handler"` — `RaindropStrandsHandler` instance to register on agents
+- `"flush"` — flush pending telemetry
+- `"shutdown"` — flush and release resources
+
+## Testing
+
+```bash
+cd packages/strands-python
+poetry install --with dev
+pytest
+```
+
+## License
+
+MIT

raindrop_strands-0.0.1/pyproject.toml

@@ -0,0 +1,27 @@
+[tool.poetry]
+name = "raindrop-strands"
+version = "0.0.1"
+description = "Raindrop integration for Strands Agents"
+authors = ["Raindrop AI <sdk@raindrop.ai>"]
+license = "MIT"
+readme = "README.md"
+packages = [{ include = "raindrop_strands" }]
+
+[tool.poetry.dependencies]
+python = ">=3.10,<4.0"
+raindrop-ai = ">=0.0.42"
+strands-agents = ">=1.0.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = ["-v", "--tb=short"]
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

raindrop_strands-0.0.1/raindrop_strands/__init__.py

@@ -0,0 +1,3 @@
+from .handler import create_raindrop_strands
+
+__all__ = ["create_raindrop_strands"]

raindrop_strands-0.0.1/raindrop_strands/handler.py

@@ -0,0 +1,400 @@
+"""
+Strands Agents callback handler for Raindrop observability.
+
+Captures agent invocations, model calls, and tool usage via the Strands
+Agents hook system and ships them to the Raindrop API.
+
+Usage:
+    from raindrop_strands import create_raindrop_strands
+
+    raindrop = create_raindrop_strands(api_key="rk_...")
+    agent = Agent(model=model)
+    raindrop["handler"].register_hooks(agent)
+    agent("Hello!")
+    raindrop["flush"]()
+
+IMPORTANT: Every handler method MUST be wrapped in try/except.
+Telemetry must NEVER crash the user's pipeline.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from typing import Any, Dict, Optional
+
+import raindrop.analytics as raindrop
+
+
+def _safe_serialize(value: Any) -> str:
+    """Safely serialize a value to string. Never throws."""
+    try:
+        return json.dumps(value)
+    except Exception:
+        return str(value)
+
+
+def _extract_text_from_message(message: Any) -> Optional[str]:
+    """Extract text content from a Strands Message (TypedDict with 'content' list)."""
+    try:
+        content = message.get("content") if isinstance(message, dict) else None
+        if not content or not isinstance(content, list):
+            return None
+
+        text_parts = []
+        for block in content:
+            if block is None:
+                continue
+            if isinstance(block, str):
+                text_parts.append(block)
+            elif isinstance(block, dict) and "text" in block:
+                text = block["text"]
+                if isinstance(text, str):
+                    text_parts.append(text)
+        return "\n".join(text_parts) if text_parts else None
+    except Exception:
+        return None
+
+
+def _extract_user_input(messages: Any) -> Optional[str]:
+    """Extract the last user message text from a conversation history."""
+    try:
+        if not messages or not isinstance(messages, list):
+            return None
+
+        # Find the last user message
+        for msg in reversed(messages):
+            if not isinstance(msg, dict):
+                continue
+            if msg.get("role") != "user":
+                continue
+            text = _extract_text_from_message(msg)
+            if text:
+                return text
+
+        # Fallback: try the last message regardless of role
+        if messages:
+            last_msg = messages[-1]
+            if isinstance(last_msg, dict):
+                return _extract_text_from_message(last_msg)
+
+        return None
+    except Exception:
+        return None
+
+
+class RaindropStrandsHandler:
+    """Strands Agents hook handler that ships events to Raindrop."""
+
+    def __init__(
+        self,
+        user_id: Optional[str] = None,
+        convo_id: Optional[str] = None,
+    ):
+        self._user_id = user_id
+        self._convo_id = convo_id
+
+        # Map id(agent) -> invocation context dict.
+        # Cleaned up explicitly in on_after_invocation to prevent leaks.
+        self._invocations: Dict[int, Dict[str, Any]] = {}
+        # toolUseId -> span context for active tool calls
+        self._tool_spans: Dict[str, Dict[str, Any]] = {}
+
+        # Tracking counters for memory leak detection in tests
+        self._active_invocations = 0
+        self._active_tool_spans = 0
+
+    def register_hooks(self, agent: Any) -> None:
+        """Register all Raindrop hook callbacks on a Strands agent.
+
+        Args:
+            agent: A Strands Agent instance with an ``add_hook`` method.
+        """
+        from strands.hooks.events import (
+            AfterInvocationEvent,
+            AfterModelCallEvent,
+            AfterToolCallEvent,
+            BeforeInvocationEvent,
+            BeforeModelCallEvent,
+            BeforeToolCallEvent,
+        )
+
+        agent.add_hook(self.on_before_invocation, BeforeInvocationEvent)
+        agent.add_hook(self.on_after_invocation, AfterInvocationEvent)
+        agent.add_hook(self.on_before_model_call, BeforeModelCallEvent)
+        agent.add_hook(self.on_after_model_call, AfterModelCallEvent)
+        agent.add_hook(self.on_before_tool_call, BeforeToolCallEvent)
+        agent.add_hook(self.on_after_tool_call, AfterToolCallEvent)
+
+    # --- Hook callback methods ---
+
+    def on_before_invocation(self, event: Any, **kwargs: Any) -> None:
+        """Called before an agent invocation starts."""
+        try:
+            agent = event.agent
+            event_id = str(uuid.uuid4())
+
+            # Extract input from the last user message
+            messages = getattr(agent, "messages", None)
+            input_text = _extract_user_input(messages)
+
+            ctx: Dict[str, Any] = {
+                "event_id": event_id,
+                "input": input_text,
+                "output": None,
+                "model": None,
+                "prompt_tokens": None,
+                "completion_tokens": None,
+                "tool_use_ids": set(),
+            }
+            self._invocations[id(agent)] = ctx
+            self._active_invocations += 1
+        except Exception:
+            pass  # telemetry must not interfere with user's pipeline
+
+    def on_after_invocation(self, event: Any, **kwargs: Any) -> None:
+        """Called after an agent invocation completes."""
+        try:
+            agent = event.agent
+            ctx = self._invocations.get(id(agent))
+            if not ctx:
+                return
+
+            # Extract output from the result if available
+            result = getattr(event, "result", None)
+            if result is not None:
+                message = getattr(result, "message", None)
+                if message is not None:
+                    output = _extract_text_from_message(message)
+                    if output:
+                        ctx["output"] = output
+
+                # Extract token usage from metrics
+                metrics = getattr(result, "metrics", None)
+                if metrics is not None:
+                    accumulated = getattr(metrics, "accumulated_usage", None)
+                    if accumulated is not None:
+                        input_tokens = (
+                            accumulated.get("inputTokens")
+                            if isinstance(accumulated, dict)
+                            else getattr(accumulated, "inputTokens", None)
+                        )
+                        output_tokens = (
+                            accumulated.get("outputTokens")
+                            if isinstance(accumulated, dict)
+                            else getattr(accumulated, "outputTokens", None)
+                        )
+                        if input_tokens is not None:
+                            ctx["prompt_tokens"] = input_tokens
+                        if output_tokens is not None:
+                            ctx["completion_tokens"] = output_tokens
+
+            properties: Dict[str, Any] = {}
+            if ctx.get("prompt_tokens") is not None:
+                properties["ai.usage.prompt_tokens"] = ctx["prompt_tokens"]
+            if ctx.get("completion_tokens") is not None:
+                properties["ai.usage.completion_tokens"] = ctx["completion_tokens"]
+
+            raindrop.track_ai(
+                user_id=self._user_id or "",
+                event="ai_generation",
+                event_id=ctx["event_id"],
+                input=ctx.get("input"),
+                output=ctx.get("output"),
+                model=ctx.get("model"),
+                convo_id=self._convo_id,
+                properties=properties if properties else None,
+            )
+        except Exception:
+            pass  # telemetry must not interfere
+        finally:
+            try:
+                agent = event.agent
+                # Get ctx BEFORE popping, for orphan tool span cleanup
+                ctx = self._invocations.get(id(agent))
+                if ctx is not None:
+                    self._invocations.pop(id(agent), None)
+                    self._active_invocations = max(0, self._active_invocations - 1)
+                    # Clean up any orphaned tool spans owned by this invocation
+                    for tool_id in ctx.get("tool_use_ids", set()):
+                        if self._tool_spans.pop(tool_id, None) is not None:
+                            self._active_tool_spans = max(0, self._active_tool_spans - 1)
+            except Exception:
+                pass
+
+    def on_before_model_call(self, event: Any, **kwargs: Any) -> None:
+        """Called before a model call within an invocation."""
+        try:
+            # No span-based tracing in Python SDK; model call data is
+            # captured in on_after_model_call and attached to the invocation.
+            pass
+        except Exception:
+            pass
+
+    def on_after_model_call(self, event: Any, **kwargs: Any) -> None:
+        """Called after a model call completes."""
+        try:
+            agent = event.agent
+            ctx = self._invocations.get(id(agent))
+            if not ctx:
+                return
+
+            # Extract output from stop response
+            stop_response = getattr(event, "stop_response", None)
+            if stop_response is not None:
+                message = getattr(stop_response, "message", None)
+                if message is not None:
+                    output = _extract_text_from_message(message)
+                    if output:
+                        ctx["output"] = output
+
+                # Extract usage from stop response
+                usage = getattr(stop_response, "usage", None)
+                if usage is not None:
+                    input_tokens = (
+                        usage.get("inputTokens")
+                        if isinstance(usage, dict)
+                        else getattr(usage, "inputTokens", None)
+                    )
+                    output_tokens = (
+                        usage.get("outputTokens")
+                        if isinstance(usage, dict)
+                        else getattr(usage, "outputTokens", None)
+                    )
+                    if input_tokens is not None:
+                        ctx["prompt_tokens"] = input_tokens
+                    if output_tokens is not None:
+                        ctx["completion_tokens"] = output_tokens
+
+                # Extract model name
+                model_id = getattr(stop_response, "model", None)
+                if model_id is not None:
+                    ctx["model"] = str(model_id)
+        except Exception:
+            pass  # telemetry must not interfere
+
+    def on_before_tool_call(self, event: Any, **kwargs: Any) -> None:
+        """Called before a tool call within an invocation."""
+        try:
+            agent = getattr(event, "agent", None)
+            if agent is None:
+                return
+            ctx = self._invocations.get(id(agent))
+            if not ctx:
+                return
+
+            tool_use = getattr(event, "tool_use", None)
+            if tool_use is None:
+                return
+
+            tool_use_id = (
+                tool_use.get("toolUseId")
+                if isinstance(tool_use, dict)
+                else getattr(tool_use, "toolUseId", None)
+            )
+            tool_name = (
+                tool_use.get("name")
+                if isinstance(tool_use, dict)
+                else getattr(tool_use, "name", None)
+            )
+            tool_input = (
+                tool_use.get("input")
+                if isinstance(tool_use, dict)
+                else getattr(tool_use, "input", None)
+            )
+
+            if tool_use_id:
+                tid = str(tool_use_id)
+                self._tool_spans[tid] = {
+                    "name": tool_name,
+                    "input": _safe_serialize(tool_input) if tool_input is not None else None,
+                }
+                if "tool_use_ids" in ctx:
+                    ctx["tool_use_ids"].add(tid)
+                self._active_tool_spans += 1
+        except Exception:
+            pass
+
+    def on_after_tool_call(self, event: Any, **kwargs: Any) -> None:
+        """Called after a tool call completes."""
+        try:
+            tool_use = getattr(event, "tool_use", None)
+            if tool_use is None:
+                return
+
+            tool_use_id = (
+                tool_use.get("toolUseId")
+                if isinstance(tool_use, dict)
+                else getattr(tool_use, "toolUseId", None)
+            )
+            if tool_use_id:
+                tid = str(tool_use_id)
+                deleted = self._tool_spans.pop(tid, None)
+                if deleted is not None:
+                    self._active_tool_spans = max(0, self._active_tool_spans - 1)
+                # Also remove from invocation's tracked set
+                agent = getattr(event, "agent", None)
+                if agent is not None:
+                    ctx = self._invocations.get(id(agent))
+                    if ctx:
+                        if "tool_use_ids" in ctx:
+                            ctx["tool_use_ids"].discard(tid)
+        except Exception:
+            pass
+
+    @property
+    def _map_sizes(self) -> Dict[str, int]:
+        """Get the current sizes of internal tracking maps (for testing)."""
+        return {
+            "invocations": self._active_invocations,
+            "tool_spans": self._active_tool_spans,
+        }
+
+
+def create_raindrop_strands(
+    api_key: Optional[str] = None,
+    user_id: Optional[str] = None,
+    convo_id: Optional[str] = None,
+    **kwargs: Any,
+) -> Dict[str, Any]:
+    """
+    Create a Raindrop-instrumented Strands Agents callback handler.
+
+    Args:
+        api_key: Raindrop API key (rk_...). Omit to disable telemetry shipping.
+        user_id: Associate all events with this user.
+        convo_id: Conversation ID to group related events.
+        **kwargs: Additional options (reserved for future use).
+
+    Returns:
+        Dict with 'handler', 'flush', and 'shutdown'.
+
+    Usage:
+        from raindrop_strands import create_raindrop_strands
+
+        raindrop = create_raindrop_strands(api_key="rk_...")
+        agent = Agent(model=model)
+        raindrop["handler"].register_hooks(agent)
+        agent("Hello!")
+        raindrop["flush"]()
+    """
+    import warnings
+
+    if not api_key:
+        warnings.warn(
+            "[raindrop-strands] api_key not provided; telemetry shipping is disabled",
+            stacklevel=2,
+        )
+
+    raindrop.init(api_key=api_key or "")
+
+    handler = RaindropStrandsHandler(
+        user_id=user_id,
+        convo_id=convo_id,
+    )
+
+    return {
+        "handler": handler,
+        "flush": raindrop.flush,
+        "shutdown": raindrop.shutdown,
+    }