viktron-sdk 0.2.0__tar.gz

viktron_sdk-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,79 @@
+# 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/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "viktron-sdk"
+version = "0.2.0"
+description = "Framework-agnostic governance SDK for AI agents — policy enforcement, telemetry, and observability"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [{ name = "Viktron AI", email = "support@viktron.ai" }]
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.24.0"]
+keywords = ["ai", "agents", "governance", "telemetry", "observability", "llm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.1.0"]
+crewai = ["crewai>=0.1.0"]
+autogen = ["pyautogen>=0.2.0"]
+all = ["langchain-core>=0.1.0", "crewai>=0.1.0", "pyautogen>=0.2.0"]
+
+[project.urls]
+Homepage = "https://viktron.ai"
+Documentation = "https://viktron.ai/docs"
+Repository = "https://github.com/vikasvardhanv/viktron-agentsALR"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["viktron_sdk*"]

viktron_sdk-0.2.0/setup.cfg

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

viktron_sdk-0.2.0/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-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}"}