viktron-sdk 0.2.0__py3-none-any.whl

viktron_sdk/__init__.py

@@ -0,0 +1,7 @@
+"""Viktron SDK — policy enforcement and telemetry for AI agents."""
+from .telemetry import ViktronTelemetry
+from .analytics import ViktronAnalytics
+from .guard import ViktronGuard, ViktronPolicyViolation
+
+__all__ = ["ViktronTelemetry", "ViktronAnalytics", "ViktronGuard", "ViktronPolicyViolation"]
+__version__ = "0.2.0"

viktron_sdk/analytics.py

@@ -0,0 +1,117 @@
+"""Direct API client for AGENT IRL analytics and AI metrics."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+import httpx
+
+
+class ViktronAnalytics:
+    """Thin client for /api/saas analytics endpoints."""
+
+    def __init__(self, auth_token: str, endpoint: str = "https://api.viktron.ai", timeout: float = 10.0):
+        self.auth_token = auth_token
+        self.endpoint = endpoint.rstrip("/")
+        self._client = httpx.Client(timeout=timeout)
+
+    def ingest_events(
+        self,
+        workspace_id: str,
+        events: list[dict[str, Any]],
+        batch_id: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        payload_events = []
+        for event in events:
+            item = dict(event)
+            item.setdefault("workspace_id", workspace_id)
+            item.setdefault("occurred_at", datetime.now(timezone.utc).isoformat())
+            payload_events.append(item)
+
+        headers = self._auth_headers()
+        if idempotency_key:
+            headers["x-idempotency-key"] = idempotency_key
+
+        response = self._client.post(
+            f"{self.endpoint}/api/saas/events/ingest",
+            json={"events": payload_events, "batch_id": batch_id},
+            headers=headers,
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def record_llm_call(
+        self,
+        workspace_id: str,
+        *,
+        model: str,
+        provider: str,
+        input_tokens: int,
+        output_tokens: int,
+        latency_ms: int,
+        status: str = "ok",
+        mission_id: str | None = None,
+        session_id: str | None = None,
+        properties: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        total_tokens = max(0, input_tokens) + max(0, output_tokens)
+        return self.ingest_events(
+            workspace_id=workspace_id,
+            events=[
+                {
+                    "category": "llm",
+                    "event": "llm_call",
+                    "status": status,
+                    "session_id": session_id,
+                    "mission_id": mission_id,
+                    "llm_provider": provider,
+                    "llm_model": model,
+                    "input_tokens": input_tokens,
+                    "output_tokens": output_tokens,
+                    "total_tokens": total_tokens,
+                    "latency_ms": latency_ms,
+                    "properties": properties or {},
+                }
+            ],
+        )
+
+    def get_llm_analytics(self, workspace_id: str, lookback_hours: int = 168) -> dict[str, Any]:
+        response = self._client.get(
+            f"{self.endpoint}/api/saas/ai/llm-analytics",
+            params={"workspace_id": workspace_id, "lookback_hours": lookback_hours},
+            headers=self._auth_headers(),
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def get_mission_analytics(self, workspace_id: str, lookback_hours: int = 168) -> dict[str, Any]:
+        response = self._client.get(
+            f"{self.endpoint}/api/saas/ai/mission-analytics",
+            params={"workspace_id": workspace_id, "lookback_hours": lookback_hours},
+            headers=self._auth_headers(),
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def get_tool_failure_rates(self, workspace_id: str, lookback_days: int = 30) -> dict[str, Any]:
+        response = self._client.get(
+            f"{self.endpoint}/api/saas/events/queries/agent-failure-rate-by-tool",
+            params={"workspace_id": workspace_id, "lookback_days": lookback_days},
+            headers=self._auth_headers(),
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "ViktronAnalytics":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def _auth_headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self.auth_token}"}

viktron_sdk/guard.py

@@ -0,0 +1,356 @@
+"""ViktronGuard — LLM call interception proxy with policy enforcement and telemetry."""
+from __future__ import annotations
+
+import inspect
+import time
+from typing import Any, Callable, Optional
+
+
+class ViktronPolicyViolation(Exception):
+    """Raised when ViktronGuard blocks an action due to a policy rule.
+
+    Attributes
+    ----------
+    policy_id : str | None
+        The ID of the matched policy rule, if available.
+    reason : str | None
+        Human-readable explanation of why the call was blocked.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        policy_id: Optional[str] = None,
+        reason: Optional[str] = None,
+    ):
+        super().__init__(message)
+        self.policy_id = policy_id
+        self.reason = reason
+
+
+# Leaf method names we intercept at any proxy depth.
+# Covers OpenAI `create`, Anthropic `create`, Cohere `generate`, etc.
+_INTERCEPT_NAMES = frozenset({"create", "generate", "complete", "invoke", "run"})
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _extract_prompt(kwargs: dict) -> str:
+    """Best-effort extraction of the user prompt for policy evaluation."""
+    messages = kwargs.get("messages", [])
+    if messages and isinstance(messages, list):
+        for msg in reversed(messages):
+            if not isinstance(msg, dict):
+                continue
+            if msg.get("role") == "user":
+                content = msg.get("content", "")
+                if isinstance(content, str):
+                    return content[:1000]
+                if isinstance(content, list):
+                    for block in content:
+                        if isinstance(block, dict) and block.get("type") == "text":
+                            return block.get("text", "")[:1000]
+    prompt = kwargs.get("prompt", "")
+    if isinstance(prompt, str):
+        return prompt[:1000]
+    return ""
+
+
+def _extract_tokens(result: Any) -> tuple[Optional[int], Optional[int]]:
+    """Extract (input_tokens, output_tokens) from an LLM response object."""
+    usage = getattr(result, "usage", None)
+    if usage:
+        inp = getattr(usage, "prompt_tokens", None) or getattr(usage, "input_tokens", None)
+        out = getattr(usage, "completion_tokens", None) or getattr(usage, "output_tokens", None)
+        return inp, out
+    return None, None
+
+
+# ── Policy HTTP client ────────────────────────────────────────────────────────
+
+class _PolicyClient:
+    """Thin synchronous HTTP client for the /api/sdk/policy-check endpoint."""
+
+    def __init__(self, api_key: str, endpoint: str, timeout: float, fail_open: bool):
+        self._api_key = api_key
+        self._endpoint = endpoint.rstrip("/")
+        self._timeout = timeout
+        self._fail_open = fail_open
+        self._http: Any = None  # lazy-loaded httpx.Client
+
+    def _client(self) -> Any:
+        if self._http is None:
+            try:
+                import httpx  # optional dep; guard falls back to fail-open if missing
+                self._http = httpx.Client(timeout=self._timeout)
+            except ImportError:
+                self._http = False
+        return self._http
+
+    def check(
+        self,
+        action_type: str,
+        agent_id: str,
+        model: str,
+        prompt_preview: str,
+        tool_name: str = "",
+    ) -> tuple[bool, Optional[str], Optional[str]]:
+        """Call policy-check. Returns (allowed, policy_id, reason).
+
+        On network/server error: honours fail_open.
+        """
+        http = self._client()
+        if not http:
+            return True, None, None  # httpx unavailable → fail open
+
+        payload = {
+            "action_type": action_type,
+            "agent_id": agent_id,
+            "model": model,
+            "prompt_preview": prompt_preview[:500],
+            "tool_name": tool_name,
+        }
+        try:
+            resp = http.post(
+                f"{self._endpoint}/api/sdk/policy-check",
+                json=payload,
+                headers={"Authorization": f"Bearer {self._api_key}"},
+                timeout=self._timeout,
+            )
+            if resp.status_code == 200:
+                data = resp.json()
+                return (
+                    bool(data.get("allowed", True)),
+                    data.get("policy_id"),
+                    data.get("reason"),
+                )
+            # Non-200 from policy server
+            if self._fail_open:
+                return True, None, f"policy-server-http-{resp.status_code}"
+            raise ViktronPolicyViolation(f"Policy server returned {resp.status_code}")
+        except ViktronPolicyViolation:
+            raise
+        except Exception as exc:
+            if self._fail_open:
+                return True, None, f"policy-error:{exc}"
+            raise ViktronPolicyViolation(f"Policy check failed: {exc}") from exc
+
+
+# ── Interceptor ───────────────────────────────────────────────────────────────
+
+class _Interceptor:
+    """Wraps a single callable to enforce policy + emit telemetry."""
+
+    def __init__(
+        self,
+        fn: Callable,
+        path: str,
+        policy: _PolicyClient,
+        telemetry: Any,
+        agent_id: str,
+    ):
+        self._fn = fn
+        self._path = path
+        self._policy = policy
+        self._tel = telemetry
+        self._agent_id = agent_id
+
+    # ── Internal helpers ──────────────────────────────────────────────────
+
+    def _run_policy(self, kwargs: dict) -> tuple[Optional[str], Optional[str]]:
+        allowed, policy_id, reason = self._policy.check(
+            action_type="llm_call",
+            agent_id=self._agent_id,
+            model=kwargs.get("model", ""),
+            prompt_preview=_extract_prompt(kwargs),
+        )
+        if not allowed:
+            if self._tel:
+                self._tel.record_event("guard.blocked", {
+                    "agent_id": self._agent_id,
+                    "policy_id": policy_id,
+                    "reason": reason,
+                })
+            raise ViktronPolicyViolation(
+                f"Blocked by Viktron policy: {reason or 'policy violation'}",
+                policy_id=policy_id,
+                reason=reason,
+            )
+        return policy_id, reason
+
+    def _record(
+        self,
+        kwargs: dict,
+        result: Any,
+        duration_ms: int,
+        error: Optional[str],
+        policy_id: Optional[str],
+    ) -> None:
+        if not self._tel:
+            return
+        inp, out = _extract_tokens(result) if result is not None else (None, None)
+        self._tel.record_event("llm.call", {
+            "agent_id": self._agent_id,
+            "model": kwargs.get("model", ""),
+            "duration_ms": duration_ms,
+            "tokens_in": inp,
+            "tokens_out": out,
+            "path": self._path,
+            "error": error,
+            "policy_id": policy_id,
+        })
+
+    # ── Public entry points ───────────────────────────────────────────────
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Synchronous intercept path."""
+        policy_id, _ = self._run_policy(kwargs)
+        start = time.perf_counter()
+        error: Optional[str] = None
+        result = None
+        try:
+            result = self._fn(*args, **kwargs)
+            return result
+        except ViktronPolicyViolation:
+            raise
+        except Exception as exc:
+            error = str(exc)
+            raise
+        finally:
+            self._record(kwargs, result, int((time.perf_counter() - start) * 1000), error, policy_id)
+
+    async def async_call(self, *args: Any, **kwargs: Any) -> Any:
+        """Asynchronous intercept path (used when wrapping async clients)."""
+        policy_id, _ = self._run_policy(kwargs)
+        start = time.perf_counter()
+        error: Optional[str] = None
+        result = None
+        try:
+            result = await self._fn(*args, **kwargs)
+            return result
+        except ViktronPolicyViolation:
+            raise
+        except Exception as exc:
+            error = str(exc)
+            raise
+        finally:
+            self._record(kwargs, result, int((time.perf_counter() - start) * 1000), error, policy_id)
+
+
+# ── Recursive proxy ───────────────────────────────────────────────────────────
+
+class _RecursiveProxy:
+    """
+    Walks an object's attribute tree and intercepts calls to methods whose
+    names appear in _INTERCEPT_NAMES (e.g. ``client.chat.completions.create``).
+
+    Uses object.__setattr__/__getattribute__ to avoid infinite recursion
+    through our own __getattr__.
+    """
+
+    __slots__ = ("_obj", "_factory")
+
+    def __init__(self, obj: Any, factory: Callable) -> None:
+        object.__setattr__(self, "_obj", obj)
+        object.__setattr__(self, "_factory", factory)
+
+    def __getattr__(self, name: str) -> Any:
+        obj = object.__getattribute__(self, "_obj")
+        factory = object.__getattribute__(self, "_factory")
+        attr = getattr(obj, name)
+
+        if name in _INTERCEPT_NAMES and callable(attr):
+            interceptor = factory(attr, name)
+            if inspect.iscoroutinefunction(attr):
+                async def _async_wrapper(*a: Any, **kw: Any) -> Any:
+                    return await interceptor.async_call(*a, **kw)
+                return _async_wrapper
+            return interceptor
+
+        # Recurse into namespace objects (e.g. client.chat, client.messages)
+        if not inspect.isbuiltin(attr) and (hasattr(attr, "__dict__") or hasattr(type(attr), "__dict__")):
+            return _RecursiveProxy(attr, factory)
+
+        return attr
+
+    def __repr__(self) -> str:
+        obj = object.__getattribute__(self, "_obj")
+        return f"<ViktronGuardProxy wrapping {type(obj).__name__}>"
+
+
+# ── Public API ────────────────────────────────────────────────────────────────
+
+class ViktronGuard:
+    """One-line LLM client wrapper with policy enforcement and telemetry.
+
+    Supports OpenAI (sync & async), Anthropic, and any client whose call
+    pattern matches ``client.<namespace>.create(messages=[...], model="...")``.
+
+    Example — synchronous OpenAI::
+
+        import openai
+        from viktron_sdk import ViktronGuard
+
+        client = ViktronGuard.wrap(
+            openai.OpenAI(),
+            api_key="vk_live_...",
+            agent_id="sales-agent-prod",
+        )
+        # All client.chat.completions.create() calls are now guarded.
+        response = client.chat.completions.create(
+            model="gpt-4o",
+            messages=[{"role": "user", "content": "Hello"}],
+        )
+
+    Example — async OpenAI::
+
+        client = ViktronGuard.wrap(openai.AsyncOpenAI(), api_key="vk_live_...", agent_id="my-agent")
+        response = await client.chat.completions.create(...)
+
+    Example — Anthropic::
+
+        import anthropic
+        client = ViktronGuard.wrap(anthropic.Anthropic(), api_key="vk_live_...", agent_id="my-agent")
+        msg = client.messages.create(model="claude-3-5-sonnet-20241022", ...)
+
+    Parameters
+    ----------
+    client
+        An LLM provider client (OpenAI, AsyncOpenAI, Anthropic, Cohere, …).
+    api_key
+        Viktron API key (``vk_live_...`` or ``vk_test_...``).
+    agent_id
+        Stable identifier for this agent shown in the Viktron dashboard.
+    endpoint
+        Viktron API base URL (default: ``https://api.viktron.ai``).
+    fail_open
+        If ``True`` (default), allow LLM calls when Viktron is unreachable.
+        Set ``False`` for zero-trust enforcement.
+    timeout
+        Policy-check HTTP timeout in seconds (default: ``0.5``).
+    telemetry
+        Optional :class:`ViktronTelemetry` instance for usage observability.
+    """
+
+    @staticmethod
+    def wrap(
+        client: Any,
+        api_key: str,
+        agent_id: str = "unknown",
+        endpoint: str = "https://api.viktron.ai",
+        fail_open: bool = True,
+        timeout: float = 0.5,
+        telemetry: Any = None,
+    ) -> Any:
+        """Return a proxied version of *client* with Viktron policy enforcement."""
+        policy = _PolicyClient(
+            api_key=api_key,
+            endpoint=endpoint,
+            timeout=timeout,
+            fail_open=fail_open,
+        )
+
+        def factory(fn: Callable, path: str) -> _Interceptor:
+            return _Interceptor(fn=fn, path=path, policy=policy, telemetry=telemetry, agent_id=agent_id)
+
+        return _RecursiveProxy(client, factory)

viktron_sdk/integrations/autogen.py

@@ -0,0 +1,191 @@
+"""AutoGen integration for Viktron telemetry and policy enforcement.
+
+Two patterns:
+
+1. **LLM config hook** (AutoGen v0.2 / pyautogen)::
+
+       from viktron_sdk.integrations.autogen import viktron_llm_config
+
+       config = viktron_llm_config(
+           base_config={"model": "gpt-4o", "api_key": "sk-..."},
+           api_key="vk_live_...",
+           agent_id="autogen-planner",
+       )
+       assistant = AssistantAgent("planner", llm_config=config)
+
+2. **Message hook** (AutoGen v0.4+ / autogen-agentchat)::
+
+       from viktron_sdk.integrations.autogen import ViktronAutoGenHook
+
+       hook = ViktronAutoGenHook(api_key="vk_live_...", agent_id="my-agent")
+       agent.register_hook("process_message_before_send", hook.before_send)
+       agent.register_hook("process_all_messages_before_reply", hook.before_reply)
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Optional
+
+
+# ── AutoGen v0.2 / pyautogen LLM config wrapper ───────────────────────────────
+
+def viktron_llm_config(
+    base_config: dict,
+    api_key: str,
+    agent_id: str = "autogen-agent",
+    endpoint: str = "https://api.viktron.ai",
+    fail_open: bool = True,
+    timeout: float = 0.5,
+    telemetry: Any = None,
+) -> dict:
+    """Return an AutoGen ``llm_config`` dict with Viktron policy enforcement.
+
+    Wraps the ``openai_client_cls`` so every LLM call passes through
+    ViktronGuard before reaching the provider.
+
+    Example::
+
+        config = viktron_llm_config(
+            base_config={
+                "model": "gpt-4o",
+                "api_key": os.environ["OPENAI_API_KEY"],
+                "temperature": 0.0,
+            },
+            api_key="vk_live_...",
+            agent_id="planner",
+        )
+        agent = AssistantAgent("planner", llm_config=config)
+    """
+    try:
+        from viktron_sdk.guard import ViktronGuard  # noqa: PLC0415
+    except ImportError:
+        return base_config  # guard not available; return as-is
+
+    original_cls = base_config.get("openai_client_cls")
+
+    class _GuardedClientFactory:
+        """Substitute openai_client_cls that wraps the real client after construction."""
+
+        def __new__(cls, *args: Any, **kwargs: Any) -> Any:  # type: ignore[misc]
+            real_cls = original_cls or _default_openai_cls()
+            if real_cls is None:
+                raise RuntimeError("openai package is required for AutoGen LLM integration")
+            instance = real_cls(*args, **kwargs)
+            return ViktronGuard.wrap(
+                instance,
+                api_key=api_key,
+                agent_id=agent_id,
+                endpoint=endpoint,
+                fail_open=fail_open,
+                timeout=timeout,
+                telemetry=telemetry,
+            )
+
+    merged = dict(base_config)
+    merged["openai_client_cls"] = _GuardedClientFactory
+    return merged
+
+
+def _default_openai_cls() -> Any:
+    try:
+        import openai  # noqa: PLC0415
+        return openai.OpenAI
+    except ImportError:
+        return None
+
+
+# ── AutoGen v0.4+ agent hook ──────────────────────────────────────────────────
+
+class ViktronAutoGenHook:
+    """Hook for AutoGen v0.4+ ``register_hook`` API.
+
+    Provides ``before_send`` and ``before_reply`` callbacks that record
+    messages and enforce policy.
+
+    Usage::
+
+        hook = ViktronAutoGenHook(api_key="vk_live_...", agent_id="planner")
+        agent.register_hook("process_message_before_send", hook.before_send)
+        agent.register_hook("process_all_messages_before_reply", hook.before_reply)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        agent_id: str = "autogen-agent",
+        endpoint: str = "https://api.viktron.ai",
+        fail_open: bool = True,
+        timeout: float = 0.5,
+        telemetry: Any = None,
+    ) -> None:
+        self._api_key = api_key
+        self._agent_id = agent_id
+        self._endpoint = endpoint
+        self._fail_open = fail_open
+        self._timeout = timeout
+        self._tel = telemetry
+        self._policy: Any = None  # lazy-loaded _PolicyClient
+
+    def _get_policy(self) -> Any:
+        if self._policy is None:
+            try:
+                from viktron_sdk.guard import _PolicyClient  # noqa: PLC0415
+                self._policy = _PolicyClient(
+                    api_key=self._api_key,
+                    endpoint=self._endpoint,
+                    timeout=self._timeout,
+                    fail_open=self._fail_open,
+                )
+            except ImportError:
+                self._policy = False
+        return self._policy
+
+    def before_send(self, message: Any, recipient: Any, silent: bool) -> Any:
+        """Called before an agent sends a message. Returns message unchanged or raises."""
+        policy = self._get_policy()
+        if not policy:
+            return message
+
+        content = ""
+        if isinstance(message, dict):
+            content = str(message.get("content", ""))
+        elif isinstance(message, str):
+            content = message
+
+        allowed, policy_id, reason = policy.check(
+            action_type="llm_call",
+            agent_id=self._agent_id,
+            model="",
+            prompt_preview=content[:500],
+        )
+
+        if not allowed:
+            from viktron_sdk.guard import ViktronPolicyViolation  # noqa: PLC0415
+            if self._tel:
+                self._tel.record_event("guard.blocked", {
+                    "agent_id": self._agent_id,
+                    "policy_id": policy_id,
+                    "reason": reason,
+                })
+            raise ViktronPolicyViolation(
+                f"Blocked by Viktron policy: {reason or 'policy violation'}",
+                policy_id=policy_id,
+                reason=reason,
+            )
+
+        if self._tel:
+            self._tel.record_event("autogen.message.sent", {
+                "agent_id": self._agent_id,
+                "content_preview": content[:300],
+            })
+
+        return message
+
+    def before_reply(self, messages: list, sender: Any, config: Any) -> tuple[bool, Any]:
+        """Called before processing reply messages. Returns (False, None) to continue."""
+        if self._tel and messages:
+            self._tel.record_event("autogen.reply.start", {
+                "agent_id": self._agent_id,
+                "message_count": len(messages),
+            })
+        return False, None

viktron_sdk/integrations/crewai.py

@@ -0,0 +1,125 @@
+"""CrewAI integration for Viktron telemetry and policy enforcement.
+
+Two ways to instrument a CrewAI workflow:
+
+1. **LLM guard** (recommended) — wraps the LLM before passing it to your agents::
+
+       from viktron_sdk import ViktronGuard
+       from langchain_openai import ChatOpenAI
+
+       llm = ViktronGuard.wrap(ChatOpenAI(model="gpt-4o"), api_key="vk_live_...", agent_id="my-crew")
+       agent = Agent(role="researcher", llm=llm, ...)
+
+2. **Callback handler** — attaches to the crew for step-level telemetry without
+   wrapping the LLM (useful when you can't swap the LLM)::
+
+       from viktron_sdk import ViktronTelemetry
+       from viktron_sdk.integrations.crewai import ViktronCrewCallback
+
+       tel = ViktronTelemetry(api_key="vk_live_...", agent_slug="my-crew")
+       crew = Crew(agents=[...], tasks=[...], step_callback=ViktronCrewCallback(tel))
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+
+class ViktronCrewCallback:
+    """CrewAI ``step_callback`` / ``task_callback`` compatible handler.
+
+    Sends every agent step and task lifecycle event to Viktron telemetry.
+
+    Usage::
+
+        from viktron_sdk import ViktronTelemetry
+        from viktron_sdk.integrations.crewai import ViktronCrewCallback
+
+        tel = ViktronTelemetry(api_key="vk_live_...", agent_slug="sales-crew")
+        crew = Crew(
+            agents=[researcher, writer],
+            tasks=[research_task, write_task],
+            step_callback=ViktronCrewCallback(tel),
+        )
+    """
+
+    def __init__(self, telemetry: Any) -> None:
+        self._tel = telemetry
+        self._task_starts: dict[str, float] = {}
+
+    # ── step_callback interface ───────────────────────────────────────────
+
+    def __call__(self, agent_output: Any) -> None:
+        """Called by CrewAI after every agent step (step_callback)."""
+        try:
+            thought = getattr(agent_output, "thought", None)
+            action = getattr(agent_output, "tool", None) or getattr(agent_output, "action", None)
+            action_input = getattr(agent_output, "tool_input", None) or getattr(agent_output, "action_input", None)
+            output_text = getattr(agent_output, "result", None) or str(agent_output)[:500]
+
+            self._tel.record_event("crew.step", {
+                "thought_preview": str(thought or "")[:300],
+                "action": str(action or ""),
+                "action_input_preview": str(action_input or "")[:300],
+                "output_preview": str(output_text)[:300],
+            })
+        except Exception:
+            pass  # Never break the crew run
+
+    # ── task_callback interface ───────────────────────────────────────────
+
+    def on_task_start(self, task: Any) -> None:
+        task_id = str(id(task))
+        self._task_starts[task_id] = time.time()
+        self._tel.record_event("crew.task.start", {
+            "task_description": str(getattr(task, "description", ""))[:200],
+            "task_id": task_id,
+        })
+
+    def on_task_end(self, task: Any, output: Any) -> None:
+        task_id = str(id(task))
+        started = self._task_starts.pop(task_id, time.time())
+        duration_ms = int((time.time() - started) * 1000)
+        self._tel.record_task(
+            task_id=task_id,
+            status="completed",
+            duration_ms=duration_ms,
+        )
+        self._tel.record_event("crew.task.end", {
+            "task_id": task_id,
+            "duration_ms": duration_ms,
+            "output_preview": str(output or "")[:300],
+        })
+        self._tel.flush()
+
+
+def wrap_crew(crew: Any, api_key: str, agent_id: str = "crew", **guard_kwargs: Any) -> Any:
+    """Convenience helper that wraps a CrewAI Crew's LLM with ViktronGuard.
+
+    Iterates over all agents on the crew and replaces their LLM with a
+    guarded version.  Returns the crew unchanged (mutation in place).
+
+    Usage::
+
+        from viktron_sdk.integrations.crewai import wrap_crew
+
+        crew = wrap_crew(crew, api_key="vk_live_...", agent_id="sales-crew")
+        crew.kickoff()
+    """
+    try:
+        from viktron_sdk.guard import ViktronGuard
+    except ImportError:
+        return crew  # SDK not available; return as-is
+
+    agents = getattr(crew, "agents", [])
+    for agent in agents:
+        llm = getattr(agent, "llm", None)
+        if llm is not None:
+            agent.llm = ViktronGuard.wrap(
+                llm,
+                api_key=api_key,
+                agent_id=f"{agent_id}:{getattr(agent, 'role', 'agent')}",
+                **guard_kwargs,
+            )
+
+    return crew

viktron_sdk/integrations/langchain.py

@@ -0,0 +1,74 @@
+"""LangChain callback handler for ViktronTelemetry."""
+from __future__ import annotations
+
+import time
+from typing import Any
+from uuid import UUID
+
+try:
+    from langchain_core.callbacks import BaseCallbackHandler
+    from langchain_core.outputs import LLMResult
+except ImportError:
+    raise ImportError(
+        "LangChain integration requires: pip install 'viktron-sdk[langchain]'"
+    )
+
+from viktron_sdk.telemetry import ViktronTelemetry
+
+
+class ViktronCallbackHandler(BaseCallbackHandler):
+    """LangChain callback that sends all events to ViktronTelemetry.
+
+    Example:
+        handler = ViktronCallbackHandler(tel)
+        llm = ChatOpenAI(callbacks=[handler])
+    """
+
+    def __init__(self, telemetry: ViktronTelemetry) -> None:
+        self._tel = telemetry
+        self._timers: dict[str, float] = {}
+
+    def on_chain_start(self, serialized: dict, inputs: dict, run_id: UUID, **kw: Any) -> None:
+        self._timers[str(run_id)] = time.time()
+        self._tel.record_event("chain.start", {
+            "chain": serialized.get("name", "unknown"),
+            "run_id": str(run_id),
+        })
+
+    def on_chain_end(self, outputs: dict, run_id: UUID, **kw: Any) -> None:
+        elapsed = self._timers.pop(str(run_id), time.time())
+        self._tel.record_event("chain.end", {
+            "run_id": str(run_id),
+            "duration_ms": int((time.time() - elapsed) * 1000),
+        })
+
+    def on_llm_start(self, serialized: dict, prompts: list, run_id: UUID, **kw: Any) -> None:
+        self._timers[str(run_id)] = time.time()
+
+    def on_llm_end(self, response: LLMResult, run_id: UUID, **kw: Any) -> None:
+        elapsed = self._timers.pop(str(run_id), time.time())
+        usage = (response.llm_output or {}).get("token_usage", {})
+        self._tel.record_event("llm.end", {
+            "run_id": str(run_id),
+            "duration_ms": int((time.time() - elapsed) * 1000),
+            "prompt_tokens": usage.get("prompt_tokens"),
+            "completion_tokens": usage.get("completion_tokens"),
+            "total_tokens": usage.get("total_tokens"),
+        })
+
+    def on_tool_start(self, serialized: dict, input_str: str, run_id: UUID, **kw: Any) -> None:
+        self._timers[str(run_id)] = time.time()
+        self._tel.record_event("tool.start", {
+            "tool": serialized.get("name", "unknown"),
+            "run_id": str(run_id),
+        })
+
+    def on_tool_end(self, output: str, run_id: UUID, **kw: Any) -> None:
+        elapsed = self._timers.pop(str(run_id), time.time())
+        self._tel.record_event("tool.end", {
+            "run_id": str(run_id),
+            "duration_ms": int((time.time() - elapsed) * 1000),
+        })
+
+    def on_agent_finish(self, finish: Any, run_id: UUID, **kw: Any) -> None:
+        self._tel.flush()

viktron_sdk/telemetry.py

@@ -0,0 +1,175 @@
+"""ViktronTelemetry — send agent events to cloud.viktron.ai or self-hosted."""
+from __future__ import annotations
+
+import threading
+import time
+import uuid
+from contextlib import contextmanager
+from typing import Any, Iterator
+
+import httpx
+
+
+class ViktronTelemetry:
+    """Framework-agnostic telemetry client.
+
+    Usage:
+        from viktron_sdk import ViktronTelemetry
+
+        tel = ViktronTelemetry(api_key="vk_...", agent_slug="marketing")
+
+        # Record a task
+        tel.record_task("t-123", status="completed", duration_ms=4200, cost_usd=0.003)
+
+        # Use as context manager for a span
+        with tel.span("run_campaign") as span:
+            span.set_attribute("platform", "meta")
+            result = run_campaign(...)
+            span.set_output(result)
+
+        tel.close()  # flush remaining events
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        agent_slug: str = "unknown",
+        endpoint: str = "https://api.viktron.ai",
+        flush_interval: int = 10,
+        async_flush: bool = True,
+    ):
+        self.api_key = api_key
+        self.agent_slug = agent_slug
+        self.endpoint = endpoint.rstrip("/")
+        self.flush_interval = flush_interval
+        self._session_id = str(uuid.uuid4())
+        self._buffer: list[dict] = []
+        self._lock = threading.Lock()
+        self._stopped = False
+        self._client = httpx.Client(timeout=5.0)
+        if async_flush:
+            self._flush_thread = threading.Thread(target=self._flush_loop, daemon=True)
+            self._flush_thread.start()
+
+    # ── Public API ─────────────────────────────────────────────────────────
+
+    def record_event(self, event_type: str, data: dict[str, Any] | None = None) -> None:
+        """Record an arbitrary event. Buffered and auto-flushed every N events."""
+        with self._lock:
+            self._buffer.append({
+                "event_type": event_type,
+                "agent_slug": self.agent_slug,
+                "session_id": self._session_id,
+                "ts": time.time(),
+                "data": data or {},
+            })
+            should_flush = len(self._buffer) >= self.flush_interval
+        if should_flush:
+            self.flush()
+
+    def record_task(
+        self,
+        task_id: str,
+        status: str,
+        duration_ms: int | None = None,
+        tokens_used: int | None = None,
+        cost_usd: float | None = None,
+        error: str | None = None,
+    ) -> None:
+        """Record a task lifecycle event — primary billing and observability signal."""
+        self.record_event("task", {
+            "task_id": task_id,
+            "status": status,
+            "duration_ms": duration_ms,
+            "tokens_used": tokens_used,
+            "cost_usd": cost_usd,
+            "error": error,
+        })
+
+    @contextmanager
+    def span(self, name: str, attributes: dict[str, Any] | None = None) -> Iterator[_Span]:
+        """Context manager that records start/end of a named operation with timing."""
+        s = _Span(self, name, attributes or {})
+        s._start()
+        try:
+            yield s
+        except Exception as exc:
+            s._error = str(exc)
+            raise
+        finally:
+            s._end()
+
+    def flush(self) -> bool:
+        """Send buffered events to the endpoint. Returns True on success."""
+        with self._lock:
+            if not self._buffer:
+                return True
+            events = self._buffer.copy()
+            self._buffer.clear()
+        try:
+            resp = self._client.post(
+                f"{self.endpoint}/api/observability/ingest",
+                json={"events": events},
+                headers={"Authorization": f"Bearer {self.api_key}"},
+                timeout=5.0,
+            )
+            return resp.status_code < 400
+        except Exception:
+            with self._lock:
+                self._buffer = events + self._buffer
+            return False
+
+    def _flush_loop(self) -> None:
+        while not self._stopped:
+            time.sleep(self.flush_interval)
+            if not self._stopped:
+                self.flush()
+
+    def close(self) -> None:
+        """Flush and close the HTTP client."""
+        self._stopped = True
+        self.flush()
+        self._client.close()
+
+    # ── Context manager support ────────────────────────────────────────────
+
+    def __enter__(self) -> "ViktronTelemetry":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+
+class _Span:
+    """Internal span object yielded by ViktronTelemetry.span()."""
+
+    def __init__(self, tel: ViktronTelemetry, name: str, attributes: dict[str, Any]):
+        self._tel = tel
+        self._name = name
+        self._attrs = dict(attributes)
+        self._start_time: float = 0.0
+        self._output: str | None = None
+        self._error: str | None = None
+
+    def set_attribute(self, key: str, value: Any) -> None:
+        """Add or update a span attribute."""
+        self._attrs[key] = value
+
+    def set_output(self, value: Any) -> None:
+        """Record a preview of the span output (truncated to 500 chars)."""
+        self._output = str(value)[:500]
+
+    # ── Internal ──────────────────────────────────────────────────────────
+
+    def _start(self) -> None:
+        self._start_time = time.time()
+        self._tel.record_event(f"{self._name}.start", self._attrs)
+
+    def _end(self) -> None:
+        duration_ms = int((time.time() - self._start_time) * 1000)
+        self._tel.record_event(f"{self._name}.end", {
+            **self._attrs,
+            "duration_ms": duration_ms,
+            "output_preview": self._output,
+            "error": self._error,
+        })

viktron_sdk-0.2.0.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: viktron-sdk
+Version: 0.2.0
+Summary: Framework-agnostic governance SDK for AI agents — policy enforcement, telemetry, and observability
+Author-email: Viktron AI <support@viktron.ai>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://viktron.ai
+Project-URL: Documentation, https://viktron.ai/docs
+Project-URL: Repository, https://github.com/vikasvardhanv/viktron-agentsALR
+Keywords: ai,agents,governance,telemetry,observability,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.1.0; extra == "crewai"
+Provides-Extra: autogen
+Requires-Dist: pyautogen>=0.2.0; extra == "autogen"
+Provides-Extra: all
+Requires-Dist: langchain-core>=0.1.0; extra == "all"
+Requires-Dist: crewai>=0.1.0; extra == "all"
+Requires-Dist: pyautogen>=0.2.0; extra == "all"
+
+# Viktron SDK
+
+Framework-agnostic governance SDK for AI agents — policy enforcement, telemetry, and real-time observability for production AI systems.
+
+## Install
+
+```bash
+pip install viktron-sdk
+```
+
+## Quick Start
+
+### Telemetry (send agent events to your Viktron dashboard)
+
+```python
+from viktron_sdk import ViktronTelemetry
+
+tel = ViktronTelemetry(api_key="vk_live_...", agent_slug="my-agent")
+
+# Record a task
+tel.record_task("task-123", status="completed", duration_ms=4200, cost_usd=0.003)
+
+# Use a context-managed span
+with tel.span("run_campaign") as span:
+    span.set_attribute("platform", "meta")
+    result = run_campaign()
+    span.set_output(result)
+
+tel.close()  # flush remaining events
+```
+
+### Policy Guard (intercept LLM calls with governance rules)
+
+```python
+import openai
+from viktron_sdk import ViktronGuard
+
+client = ViktronGuard.wrap(
+    openai.OpenAI(),
+    api_key="vk_live_...",
+    agent_id="sales-agent-prod",
+)
+
+# All create() calls are now policy-checked
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+Works with OpenAI (sync & async), Anthropic, Cohere, and any client with `.create()` / `.generate()` call patterns.
+
+### Framework Integrations
+
+```python
+# LangChain
+from viktron_sdk.integrations.langchain import ViktronCallbackHandler
+handler = ViktronCallbackHandler(api_key="vk_live_...", agent_id="my-chain")
+
+# CrewAI
+from viktron_sdk.integrations.crewai import ViktronCrewAIObserver
+observer = ViktronCrewAIObserver(api_key="vk_live_...", agent_id="my-crew")
+
+# AutoGen
+from viktron_sdk.integrations.autogen import ViktronAutoGenHook
+hook = ViktronAutoGenHook(api_key="vk_live_...", agent_id="my-autogen")
+```
+
+## API Keys
+
+Generate your API key at [app.viktron.ai](https://app.viktron.ai) → Settings → API Keys.
+
+Keys prefixed `vk_live_` are production; `vk_test_` are for testing.
+
+## Links
+
+- [Dashboard](https://app.viktron.ai)
+- [Documentation](https://viktron.ai/docs)
+- [GitHub](https://github.com/vikasvardhanv/viktron-agentsALR)

viktron_sdk-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+viktron_sdk/__init__.py,sha256=1nYJZ5IH1p8dTCD8xkdKLTEVFQPjos_aAJkHbqs0Uh8,322
+viktron_sdk/analytics.py,sha256=GhX_yBpQcQBPm6EEjLhc6Y3sl887B9m4DuDf6aGf7EU,4052
+viktron_sdk/guard.py,sha256=HUyjJ7Rk24r0f3t8XN0W51DwgUbdiMjL0W0_QTyVQGs,13162
+viktron_sdk/telemetry.py,sha256=CaQgUXuusYF1IhYGWO8xHa1STTrUWMteJNC3GMrEWfY,5997
+viktron_sdk/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+viktron_sdk/integrations/autogen.py,sha256=1DpmwBmAjyFEoGOTcu1wVJqZwY-k2aoR_Ma6Byw9EfI,6544
+viktron_sdk/integrations/crewai.py,sha256=QzLkUbXoO6IBY12Q85zA4uRWf1pmq54hKX_Guhs-s5M,4736
+viktron_sdk/integrations/langchain.py,sha256=g32q4SPFRVvzUx4DfsCdsy08f-UfMB_s_QQexU0-A3M,2774
+viktron_sdk-0.2.0.dist-info/METADATA,sha256=uK8BPv2oNz8MmLsFk8K7mEiqQ43JA9bfKNf0lgSad-k,3233
+viktron_sdk-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+viktron_sdk-0.2.0.dist-info/top_level.txt,sha256=NRKby0lu3wr4_5ty0tOgTerhZoKQU6BIsIP4144nJhE,12
+viktron_sdk-0.2.0.dist-info/RECORD,,

viktron_sdk-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

viktron_sdk-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+viktron_sdk