invokelens-sdk 0.1.0__tar.gz

invokelens_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 InvokeLens
+
+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.

invokelens_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: invokelens-sdk
+Version: 0.1.0
+Summary: SDK for InvokeLens — AI Agent Guardrails & Observability Platform
+Author-email: InvokeLens <support@invokelens.com>
+License: MIT
+Project-URL: Homepage, https://invokelens.com
+Project-URL: Repository, https://github.com/InvokeLens/invokelens-sdk
+Project-URL: Changelog, https://github.com/InvokeLens/invokelens-sdk/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://docs.invokelens.com
+Keywords: aws,bedrock,agents,observability,monitoring,guardrails,telemetry,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: eventbridge
+Requires-Dist: boto3>=1.28.0; extra == "eventbridge"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: moto[dynamodb,events]>=4.0; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# InvokeLens SDK
+
+**Observability & Guardrails for AWS Bedrock Agents**
+
+InvokeLens captures telemetry from your AWS Bedrock agent invocations — cost, latency, token usage, tool calls, and errors — and sends it to the InvokeLens platform for monitoring, alerting, and analysis.
+
+## Installation
+
+```bash
+pip install invokelens-sdk
+```
+
+## Quick Start
+
+```python
+from invokelens_sdk import InvokeLensClient
+
+# Initialize the client
+client = InvokeLensClient(
+    api_key="your-api-key",
+    endpoint_url="https://your-invokelens-api.com/v1",
+)
+
+# Decorate your Bedrock agent function
+@client.observe(agent_id="my-agent", agent_name="Customer Support Bot")
+def invoke_agent(prompt: str):
+    import boto3
+    bedrock = boto3.client("bedrock-agent-runtime")
+    response = bedrock.invoke_agent(
+        agentId="ABCDEFGHIJ",
+        agentAliasId="TSTALIASID",
+        sessionId="session-123",
+        inputText=prompt,
+    )
+    return response
+
+# Call your function as normal — telemetry is captured automatically
+result = invoke_agent("What is the status of order #1234?")
+
+# Flush remaining events on shutdown
+client.shutdown()
+```
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `api_key` | *(required)* | Your InvokeLens API key |
+| `endpoint_url` | `https://api.invokelens.com` | InvokeLens ingest endpoint URL |
+| `transport_mode` | `"http"` | Transport backend: `"http"` or `"eventbridge"` |
+| `event_bus_name` | `None` | EventBridge bus name (required if transport_mode is `"eventbridge"`) |
+| `batch_size` | `10` | Number of events per batch flush |
+| `flush_interval` | `5.0` | Seconds between automatic flushes |
+
+## What Gets Captured
+
+The `@client.observe()` decorator automatically captures:
+
+- **Timing** — invocation start, end, and duration
+- **Token usage** — input and output token counts (auto-detected from Bedrock response)
+- **Model ID** — which Bedrock model was used (auto-detected)
+- **Cost estimate** — computed from token usage and model pricing
+- **Status** — SUCCESS, FAILURE, or TIMEOUT
+- **Errors** — exception type and message (truncated to 500 chars)
+- **Tool calls** — names of tools invoked during execution
+
+### Optional Fields
+
+You can enrich events with additional context:
+
+```python
+@client.observe(
+    agent_id="my-agent",
+    agent_name="Customer Support Bot",
+    model_id="anthropic.claude-3-sonnet",  # override auto-detection
+)
+def invoke_agent(prompt: str):
+    ...
+```
+
+## Cost Estimation
+
+The SDK includes built-in pricing for common Bedrock models:
+
+```python
+from invokelens_sdk import estimate_cost
+
+cost = estimate_cost(
+    model_id="anthropic.claude-3-sonnet",
+    input_tokens=1000,
+    output_tokens=500,
+)
+print(f"Estimated cost: ${cost:.4f}")
+```
+
+## Transport Modes
+
+### HTTP (Default)
+
+Sends batched events to the InvokeLens API via HTTPS. Includes automatic retry with exponential backoff (3 attempts).
+
+### EventBridge
+
+Publishes events to an Amazon EventBridge bus. Useful for AWS-native architectures where you want to process events through EventBridge rules.
+
+```python
+client = InvokeLensClient(
+    api_key="your-api-key",
+    transport_mode="eventbridge",
+    event_bus_name="invokelens-events",
+)
+```
+
+## Requirements
+
+- Python 3.11+
+- `boto3` >= 1.28.0
+- `pydantic` >= 2.0
+- `httpx` >= 0.24.0
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

invokelens_sdk-0.1.0/README.md

@@ -0,0 +1,123 @@
+# InvokeLens SDK
+
+**Observability & Guardrails for AWS Bedrock Agents**
+
+InvokeLens captures telemetry from your AWS Bedrock agent invocations — cost, latency, token usage, tool calls, and errors — and sends it to the InvokeLens platform for monitoring, alerting, and analysis.
+
+## Installation
+
+```bash
+pip install invokelens-sdk
+```
+
+## Quick Start
+
+```python
+from invokelens_sdk import InvokeLensClient
+
+# Initialize the client
+client = InvokeLensClient(
+    api_key="your-api-key",
+    endpoint_url="https://your-invokelens-api.com/v1",
+)
+
+# Decorate your Bedrock agent function
+@client.observe(agent_id="my-agent", agent_name="Customer Support Bot")
+def invoke_agent(prompt: str):
+    import boto3
+    bedrock = boto3.client("bedrock-agent-runtime")
+    response = bedrock.invoke_agent(
+        agentId="ABCDEFGHIJ",
+        agentAliasId="TSTALIASID",
+        sessionId="session-123",
+        inputText=prompt,
+    )
+    return response
+
+# Call your function as normal — telemetry is captured automatically
+result = invoke_agent("What is the status of order #1234?")
+
+# Flush remaining events on shutdown
+client.shutdown()
+```
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `api_key` | *(required)* | Your InvokeLens API key |
+| `endpoint_url` | `https://api.invokelens.com` | InvokeLens ingest endpoint URL |
+| `transport_mode` | `"http"` | Transport backend: `"http"` or `"eventbridge"` |
+| `event_bus_name` | `None` | EventBridge bus name (required if transport_mode is `"eventbridge"`) |
+| `batch_size` | `10` | Number of events per batch flush |
+| `flush_interval` | `5.0` | Seconds between automatic flushes |
+
+## What Gets Captured
+
+The `@client.observe()` decorator automatically captures:
+
+- **Timing** — invocation start, end, and duration
+- **Token usage** — input and output token counts (auto-detected from Bedrock response)
+- **Model ID** — which Bedrock model was used (auto-detected)
+- **Cost estimate** — computed from token usage and model pricing
+- **Status** — SUCCESS, FAILURE, or TIMEOUT
+- **Errors** — exception type and message (truncated to 500 chars)
+- **Tool calls** — names of tools invoked during execution
+
+### Optional Fields
+
+You can enrich events with additional context:
+
+```python
+@client.observe(
+    agent_id="my-agent",
+    agent_name="Customer Support Bot",
+    model_id="anthropic.claude-3-sonnet",  # override auto-detection
+)
+def invoke_agent(prompt: str):
+    ...
+```
+
+## Cost Estimation
+
+The SDK includes built-in pricing for common Bedrock models:
+
+```python
+from invokelens_sdk import estimate_cost
+
+cost = estimate_cost(
+    model_id="anthropic.claude-3-sonnet",
+    input_tokens=1000,
+    output_tokens=500,
+)
+print(f"Estimated cost: ${cost:.4f}")
+```
+
+## Transport Modes
+
+### HTTP (Default)
+
+Sends batched events to the InvokeLens API via HTTPS. Includes automatic retry with exponential backoff (3 attempts).
+
+### EventBridge
+
+Publishes events to an Amazon EventBridge bus. Useful for AWS-native architectures where you want to process events through EventBridge rules.
+
+```python
+client = InvokeLensClient(
+    api_key="your-api-key",
+    transport_mode="eventbridge",
+    event_bus_name="invokelens-events",
+)
+```
+
+## Requirements
+
+- Python 3.11+
+- `boto3` >= 1.28.0
+- `pydantic` >= 2.0
+- `httpx` >= 0.24.0
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

invokelens_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "invokelens-sdk"
+version = "0.1.0"
+description = "SDK for InvokeLens — AI Agent Guardrails & Observability Platform"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+authors = [
+    { name = "InvokeLens", email = "support@invokelens.com" },
+]
+keywords = [
+    "aws",
+    "bedrock",
+    "agents",
+    "observability",
+    "monitoring",
+    "guardrails",
+    "telemetry",
+    "llm",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.0",
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+eventbridge = ["boto3>=1.28.0"]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio",
+    "moto[dynamodb,events]>=4.0",
+    "mypy",
+    "ruff",
+]
+
+[project.urls]
+Homepage = "https://invokelens.com"
+Repository = "https://github.com/InvokeLens/invokelens-sdk"
+Changelog = "https://github.com/InvokeLens/invokelens-sdk/blob/main/CHANGELOG.md"
+Documentation = "https://docs.invokelens.com"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100

invokelens_sdk-0.1.0/setup.cfg

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

invokelens_sdk-0.1.0/src/invokelens_sdk/__init__.py

@@ -0,0 +1,22 @@
+"""InvokeLens SDK — AI Agent Observability & Guardrails Platform."""
+
+from .client import InvokeLensClient
+from .schema import TelemetryEvent
+from .cost import estimate_cost, set_custom_pricing
+from .exceptions import AgentBlockedError, PolicyViolationError
+from .tracing import Span, TraceContext
+from .fingerprint import compute_fingerprint
+from ._version import __version__
+
+__all__ = [
+    "InvokeLensClient",
+    "TelemetryEvent",
+    "estimate_cost",
+    "set_custom_pricing",
+    "AgentBlockedError",
+    "PolicyViolationError",
+    "Span",
+    "TraceContext",
+    "compute_fingerprint",
+    "__version__",
+]

invokelens_sdk-0.1.0/src/invokelens_sdk/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

invokelens_sdk-0.1.0/src/invokelens_sdk/client.py

@@ -0,0 +1,118 @@
+"""Main entry point for the InvokeLens SDK."""
+
+import functools
+from typing import Optional
+
+from .decorators import ObserveDecorator
+from .transport import EventTransport
+from .config import SDKConfig
+from .status import AgentStatusChecker
+from .tracing import TraceContext
+from ._version import __version__
+
+
+class InvokeLensClient:
+    """Client for sending agent telemetry to the InvokeLens platform.
+
+    Usage:
+        client = InvokeLensClient(api_key="il_live_abc123")
+
+        @client.observe(agent_id="my-agent", agent_name="Support Bot")
+        def ask_agent(prompt: str):
+            response = bedrock.invoke_agent(...)
+            return response
+
+        # On app shutdown:
+        client.shutdown()
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        endpoint_url: Optional[str] = None,
+        transport_mode: str = "http",
+        event_bus_name: Optional[str] = None,
+        batch_size: int = 10,
+        flush_interval: float = 5.0,
+        enable_kill_switch: bool = True,
+        status_check_ttl: float = 10.0,
+    ):
+        self.api_key = api_key
+        self.config = SDKConfig(
+            api_key=api_key,
+            endpoint_url=endpoint_url or "https://api.invokelens.com",
+            transport_mode=transport_mode,
+            event_bus_name=event_bus_name,
+        )
+        self._transport = EventTransport(
+            endpoint_url=self.config.endpoint_url,
+            mode=transport_mode,
+            event_bus_name=event_bus_name,
+            api_key=api_key,
+            batch_size=batch_size,
+            flush_interval_seconds=flush_interval,
+        )
+
+        self._status_checker = None
+        if enable_kill_switch:
+            self._status_checker = AgentStatusChecker(
+                endpoint_url=self.config.endpoint_url,
+                api_key=api_key,
+                ttl_seconds=status_check_ttl,
+            )
+
+    def observe(
+        self,
+        agent_id: str,
+        agent_name: Optional[str] = None,
+        model_id: Optional[str] = None,
+    ):
+        """Decorator that wraps a function and emits telemetry.
+
+        Args:
+            agent_id: Unique identifier for the agent.
+            agent_name: Human-readable name for the agent.
+            model_id: Bedrock model ID (auto-detected from response if possible).
+        """
+        return ObserveDecorator(
+            transport=self._transport,
+            agent_id=agent_id,
+            agent_name=agent_name,
+            model_id=model_id,
+            api_key=self.api_key,
+            sdk_version=__version__,
+            status_checker=self._status_checker,
+        )
+
+    def trace_tool(self, name: Optional[str] = None, span_type: str = "tool"):
+        """Decorator for tool functions that creates a span around the call.
+
+        The decorated function must accept a 'trace' keyword argument
+        (injected by @observe). If no trace context is present, the function
+        runs without tracing.
+
+        Usage:
+            @client.trace_tool(name="web_search")
+            def search(query: str, trace: TraceContext = None):
+                return do_search(query)
+        """
+        def decorator(func):
+            tool_name = name or func.__name__
+
+            @functools.wraps(func)
+            def wrapper(*args, **kwargs):
+                trace = kwargs.get("trace")
+                if not isinstance(trace, TraceContext):
+                    return func(*args, **kwargs)
+
+                with trace.span(tool_name, span_type=span_type) as s:
+                    result = func(*args, **kwargs)
+                    s.output = str(result)[:2000] if result is not None else None
+                    return result
+
+            return wrapper
+        return decorator
+
+    def shutdown(self):
+        """Flush pending events and clean up. Call on app exit."""
+        self._transport.shutdown()

invokelens_sdk-0.1.0/src/invokelens_sdk/config.py

@@ -0,0 +1,14 @@
+"""SDK configuration."""
+
+from pydantic import BaseModel
+from typing import Optional
+
+
+class SDKConfig(BaseModel):
+    api_key: str
+    endpoint_url: str = "https://api.invokelens.com"
+    transport_mode: str = "http"  # "http" or "eventbridge"
+    event_bus_name: Optional[str] = None
+    batch_size: int = 10
+    flush_interval: float = 5.0
+    max_queue_size: int = 1000

invokelens_sdk-0.1.0/src/invokelens_sdk/cost.py

@@ -0,0 +1,36 @@
+"""Bedrock model pricing lookup for cost estimation."""
+
+# Prices in USD per 1,000 tokens (approximate on-demand rates)
+MODEL_PRICING: dict[str, dict[str, float]] = {
+    "anthropic.claude-3-5-sonnet": {"input": 0.003, "output": 0.015},
+    "anthropic.claude-3-sonnet": {"input": 0.003, "output": 0.015},
+    "anthropic.claude-3-haiku": {"input": 0.00025, "output": 0.00125},
+    "anthropic.claude-3-opus": {"input": 0.015, "output": 0.075},
+    "amazon.titan-text-lite-v1": {"input": 0.0003, "output": 0.0004},
+    "amazon.titan-text-express-v1": {"input": 0.0008, "output": 0.0016},
+    "meta.llama3-70b-instruct-v1": {"input": 0.00265, "output": 0.0035},
+    "meta.llama3-8b-instruct-v1": {"input": 0.0003, "output": 0.0006},
+    "mistral.mistral-large": {"input": 0.004, "output": 0.012},
+    "mistral.mistral-small": {"input": 0.001, "output": 0.003},
+    "cohere.command-r-plus-v1": {"input": 0.003, "output": 0.015},
+    "_default": {"input": 0.003, "output": 0.015},
+}
+
+_custom_pricing: dict[str, dict[str, float]] = {}
+
+
+def set_custom_pricing(model_id: str, input_per_1k: float, output_per_1k: float):
+    """Override pricing for a specific model."""
+    _custom_pricing[model_id] = {"input": input_per_1k, "output": output_per_1k}
+
+
+def estimate_cost(model_id: str, input_tokens: int, output_tokens: int) -> float:
+    """Estimate cost in USD for a given invocation."""
+    pricing = (
+        _custom_pricing.get(model_id)
+        or MODEL_PRICING.get(model_id)
+        or MODEL_PRICING["_default"]
+    )
+    input_cost = (input_tokens / 1000) * pricing["input"]
+    output_cost = (output_tokens / 1000) * pricing["output"]
+    return round(input_cost + output_cost, 8)