watchlight-agent-sdk 0.5.0__tar.gz

watchlight_agent_sdk-0.5.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: watchlight-agent-sdk
+Version: 0.5.0
+Summary: Watchlight Agent SDK — build governed AI-agent plugins for any framework
+Author-email: Watchlight AI <team@watchlight.ai>
+License: Apache-2.0
+Project-URL: Homepage, https://www.watchlight.ai
+Project-URL: Documentation, https://docs.watchlight.ai
+Project-URL: Repository, https://github.com/watchlight-ai-beacon/watchlight
+Project-URL: Plugin SDK Guide, https://github.com/watchlight-ai-beacon/watchlight/tree/main/plugins
+Keywords: watchlight,ai-governance,agent-runtime,ai-agents,agent-sdk,policy-decision-point,cedar-policy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typing-extensions>=4.5; python_version < "3.12"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: cryptography>=42; extra == "dev"
+Requires-Dist: requests>=2.32; extra == "dev"
+Provides-Extra: otlp
+Requires-Dist: opentelemetry-api>=1.20; extra == "otlp"
+Requires-Dist: opentelemetry-sdk>=1.20; extra == "otlp"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20; extra == "otlp"
+
+# watchlight-core
+
+Shared HTTP client and governance primitives used by every Watchlight
+AI framework plugin (`watchlight-adk`, `watchlight-langgraph`,
+`watchlight-bedrock`, …).
+
+## Why this exists
+
+Until #312, the same APDP HTTP client lived as three near-identical
+copies under each framework plugin. As the contract stabilised across
+ADK / LangGraph / Bedrock, three copies became the right trigger for
+extraction. This package is the single source of truth for:
+
+- The HTTP wire format with WL-APDP (`ApdpClient`)
+- Plan-validation / preflight result wrappers (`PlanResult`,
+  `PreflightResult`)
+- The plan-normalisation contract (`normalize_plan`)
+- The framework-agnostic `GovernanceState` shape consumed by the
+  Beacon Dashboard / Streamlit governance card
+- The base run-handle lifecycle (`BaseRunHandle`)
+- Shared error types and the `governance_mode` env reader
+- Plugin telemetry contract (`GovernanceTelemetry`)
+
+## What's intentionally NOT here
+
+Framework-specific behaviour stays in the plugin packages:
+
+- ADK lifecycle callbacks + `PlanReActPlanner` parser + `BaseToolset`
+  — `watchlight-adk`
+- LangGraph plan-and-execute primitives — `watchlight-langgraph`
+- AWS Bedrock event parsing + Lambda action-group decorator +
+  `bedrock_session_attributes()` helper — `watchlight-bedrock`
+
+## Install
+
+```bash
+# Minimal — APDP client + governance primitives only
+pip install watchlight-core
+
+# With OpenTelemetry export support (adds ~50MB of OTel SDK deps)
+pip install 'watchlight-core[otlp]'
+
+# Or in this monorepo:
+pip install -e plugins/watchlight-core
+pip install -e 'plugins/watchlight-core[otlp]'
+```
+
+Plugins depend on it explicitly via their `pyproject.toml`; the core
+package depends only on `httpx` and (on Python 3.10) `typing-extensions`.
+The `[otlp]` extra pulls in `opentelemetry-api`, `opentelemetry-sdk`, and
+`opentelemetry-exporter-otlp-proto-http` — optional so cold-start-
+sensitive environments (Lambda, Cloudflare Workers) don't pay the install
+weight when they're not exporting to OTel.
+
+## Public API
+
+```python
+from watchlight_core import (
+    # HTTP client
+    ApdpClient,
+
+    # Errors
+    WatchlightError,
+    AgentNotRegistered,
+    GovernanceUnavailable,
+
+    # Result wrappers
+    PlanResult,
+    PreflightResult,
+
+    # Plan / state
+    normalize_plan,
+    GovernanceState,
+    GovernanceTelemetry,
+    state_from_attrs,
+
+    # Lifecycle
+    BaseRunHandle,
+    GovernedPlugin,
+
+    # Custom-agent SDK (EN.6)
+    watchlight,
+
+    # OpenTelemetry export (EN.6) — requires [otlp] extra at construction
+    OtlpConfig,
+    OtlpProfile,
+    WatchlightOtlpExporter,
+
+    # Env
+    governance_mode,
+)
+```
+
+### Custom-agent SDK (`@watchlight`)
+
+For agents NOT built on a framework with a Watchlight plugin (LangGraph,
+ADK, Bedrock), the `@watchlight` decorator emits the canonical lineage
+events for any Python function:
+
+```python
+from watchlight_core import ApdpClient, watchlight
+
+client = ApdpClient(base_url="http://localhost:8081")
+
+@watchlight(agent_id="custom-research", apdp_client=client)
+async def run_research(query: str) -> str:
+    # Your agent logic — emits execution_started / completed / failed
+    return result
+```
+
+### OpenTelemetry export
+
+Opt-in customer observability — sends a deliberate **subset** of the
+lineage stream to your OTel collector. Default is `profile=off`; the
+exporter is a no-op until you turn it on.
+
+```python
+from watchlight_core import OtlpConfig, WatchlightOtlpExporter
+
+# Profile ladder: off ⊂ metrics ⊂ standard ⊂ governance
+otlp = WatchlightOtlpExporter(OtlpConfig.from_env())
+# WL_OTLP_PROFILE=standard
+# WL_OTLP_ENDPOINT=http://otel-collector:4318
+```
+
+Tool arguments, LLM prompts, ABR raw scores, drift baselines, and
+security-internal anomalies never leave Watchlight. The exported subset
+is documented in `dev-docs/architecture/otlp-export.md`.
+
+The package exposes a `py.typed` marker so type checkers (mypy, pyright)
+pick up the inline annotations directly.
+
+## Contract stability
+
+Anything in `watchlight_core/__init__.py`'s `__all__` is a **stable
+public API** under SemVer minor-version compatibility. Anything else
+is internal and may move between minor versions.
+
+When changing the wire format with WL-APDP (e.g. adding a route or
+field), update `ApdpClient` here — the plugins inherit it for free.
+
+## Building a new plugin
+
+Implement the framework integration surface (lifecycle hooks, native
+plan format, etc.) in your plugin package and use this package for
+everything else:
+
+1. Inherit `GovernanceTelemetry` to satisfy the `last_*` contract.
+2. For frameworks with explicit primitives (LangGraph, Bedrock):
+   subclass `BaseRunHandle` and add framework-specific helpers; expose
+   `start_run(slug)` returning your subclass.
+3. For frameworks with lifecycle callbacks (ADK): use `ApdpClient`
+   directly and populate the `last_*` attributes from your callbacks.
+4. Provide a one-line `state_from_<framework>_plugin` state helper
+   using `state_from_attrs(plugin, framework="<name>")`.
+
+The `GovernanceState` shape parity test in your plugin's test suite
+guarantees the dashboard renders consistently across frameworks.
+
+## Cross-references
+
+- Multi-framework contract: `dev-docs/architecture/proxy-plugin-interop.md` §6
+- Threat model: `dev-docs/security/HARDENING.md` (entries #301, #312, plus this PR's entry)
+
+## Open-source by design — the plugin is glue
+
+This package (and the framework plugins built on it) ships as readable,
+Apache-2.0 source. That's safe because **all authorization decisions, scope
+strict-subset attenuation, lineage/audit signing, and drift/anomaly scoring are
+server-side** — in the compiled Rust core (`wl-apdp`) and the governed platform.
+The plugin registers hooks, shapes a request, round-trips it to the PDP, and
+projects the answer.
+
+There is **no differentiating IP to strip** for a community build: the
+difference between Developer Edition and Enterprise is the *backend* the plugin
+talks to (the in-process DE engine vs. the full governed plane), never the
+plugin code. And because any decision made client-side is *bypassable*, keeping
+enforcement server-side is a security rule, not just an IP one.
+
+This boundary is documented in [`plugins/CONTRIBUTING.md`](../CONTRIBUTING.md)
+and enforced in CI by the plugin IP-boundary gate
+(`scripts/ci/check_plugin_ip_boundary.py`).

watchlight_agent_sdk-0.5.0/README.md

@@ -0,0 +1,182 @@
+# watchlight-core
+
+Shared HTTP client and governance primitives used by every Watchlight
+AI framework plugin (`watchlight-adk`, `watchlight-langgraph`,
+`watchlight-bedrock`, …).
+
+## Why this exists
+
+Until #312, the same APDP HTTP client lived as three near-identical
+copies under each framework plugin. As the contract stabilised across
+ADK / LangGraph / Bedrock, three copies became the right trigger for
+extraction. This package is the single source of truth for:
+
+- The HTTP wire format with WL-APDP (`ApdpClient`)
+- Plan-validation / preflight result wrappers (`PlanResult`,
+  `PreflightResult`)
+- The plan-normalisation contract (`normalize_plan`)
+- The framework-agnostic `GovernanceState` shape consumed by the
+  Beacon Dashboard / Streamlit governance card
+- The base run-handle lifecycle (`BaseRunHandle`)
+- Shared error types and the `governance_mode` env reader
+- Plugin telemetry contract (`GovernanceTelemetry`)
+
+## What's intentionally NOT here
+
+Framework-specific behaviour stays in the plugin packages:
+
+- ADK lifecycle callbacks + `PlanReActPlanner` parser + `BaseToolset`
+  — `watchlight-adk`
+- LangGraph plan-and-execute primitives — `watchlight-langgraph`
+- AWS Bedrock event parsing + Lambda action-group decorator +
+  `bedrock_session_attributes()` helper — `watchlight-bedrock`
+
+## Install
+
+```bash
+# Minimal — APDP client + governance primitives only
+pip install watchlight-core
+
+# With OpenTelemetry export support (adds ~50MB of OTel SDK deps)
+pip install 'watchlight-core[otlp]'
+
+# Or in this monorepo:
+pip install -e plugins/watchlight-core
+pip install -e 'plugins/watchlight-core[otlp]'
+```
+
+Plugins depend on it explicitly via their `pyproject.toml`; the core
+package depends only on `httpx` and (on Python 3.10) `typing-extensions`.
+The `[otlp]` extra pulls in `opentelemetry-api`, `opentelemetry-sdk`, and
+`opentelemetry-exporter-otlp-proto-http` — optional so cold-start-
+sensitive environments (Lambda, Cloudflare Workers) don't pay the install
+weight when they're not exporting to OTel.
+
+## Public API
+
+```python
+from watchlight_core import (
+    # HTTP client
+    ApdpClient,
+
+    # Errors
+    WatchlightError,
+    AgentNotRegistered,
+    GovernanceUnavailable,
+
+    # Result wrappers
+    PlanResult,
+    PreflightResult,
+
+    # Plan / state
+    normalize_plan,
+    GovernanceState,
+    GovernanceTelemetry,
+    state_from_attrs,
+
+    # Lifecycle
+    BaseRunHandle,
+    GovernedPlugin,
+
+    # Custom-agent SDK (EN.6)
+    watchlight,
+
+    # OpenTelemetry export (EN.6) — requires [otlp] extra at construction
+    OtlpConfig,
+    OtlpProfile,
+    WatchlightOtlpExporter,
+
+    # Env
+    governance_mode,
+)
+```
+
+### Custom-agent SDK (`@watchlight`)
+
+For agents NOT built on a framework with a Watchlight plugin (LangGraph,
+ADK, Bedrock), the `@watchlight` decorator emits the canonical lineage
+events for any Python function:
+
+```python
+from watchlight_core import ApdpClient, watchlight
+
+client = ApdpClient(base_url="http://localhost:8081")
+
+@watchlight(agent_id="custom-research", apdp_client=client)
+async def run_research(query: str) -> str:
+    # Your agent logic — emits execution_started / completed / failed
+    return result
+```
+
+### OpenTelemetry export
+
+Opt-in customer observability — sends a deliberate **subset** of the
+lineage stream to your OTel collector. Default is `profile=off`; the
+exporter is a no-op until you turn it on.
+
+```python
+from watchlight_core import OtlpConfig, WatchlightOtlpExporter
+
+# Profile ladder: off ⊂ metrics ⊂ standard ⊂ governance
+otlp = WatchlightOtlpExporter(OtlpConfig.from_env())
+# WL_OTLP_PROFILE=standard
+# WL_OTLP_ENDPOINT=http://otel-collector:4318
+```
+
+Tool arguments, LLM prompts, ABR raw scores, drift baselines, and
+security-internal anomalies never leave Watchlight. The exported subset
+is documented in `dev-docs/architecture/otlp-export.md`.
+
+The package exposes a `py.typed` marker so type checkers (mypy, pyright)
+pick up the inline annotations directly.
+
+## Contract stability
+
+Anything in `watchlight_core/__init__.py`'s `__all__` is a **stable
+public API** under SemVer minor-version compatibility. Anything else
+is internal and may move between minor versions.
+
+When changing the wire format with WL-APDP (e.g. adding a route or
+field), update `ApdpClient` here — the plugins inherit it for free.
+
+## Building a new plugin
+
+Implement the framework integration surface (lifecycle hooks, native
+plan format, etc.) in your plugin package and use this package for
+everything else:
+
+1. Inherit `GovernanceTelemetry` to satisfy the `last_*` contract.
+2. For frameworks with explicit primitives (LangGraph, Bedrock):
+   subclass `BaseRunHandle` and add framework-specific helpers; expose
+   `start_run(slug)` returning your subclass.
+3. For frameworks with lifecycle callbacks (ADK): use `ApdpClient`
+   directly and populate the `last_*` attributes from your callbacks.
+4. Provide a one-line `state_from_<framework>_plugin` state helper
+   using `state_from_attrs(plugin, framework="<name>")`.
+
+The `GovernanceState` shape parity test in your plugin's test suite
+guarantees the dashboard renders consistently across frameworks.
+
+## Cross-references
+
+- Multi-framework contract: `dev-docs/architecture/proxy-plugin-interop.md` §6
+- Threat model: `dev-docs/security/HARDENING.md` (entries #301, #312, plus this PR's entry)
+
+## Open-source by design — the plugin is glue
+
+This package (and the framework plugins built on it) ships as readable,
+Apache-2.0 source. That's safe because **all authorization decisions, scope
+strict-subset attenuation, lineage/audit signing, and drift/anomaly scoring are
+server-side** — in the compiled Rust core (`wl-apdp`) and the governed platform.
+The plugin registers hooks, shapes a request, round-trips it to the PDP, and
+projects the answer.
+
+There is **no differentiating IP to strip** for a community build: the
+difference between Developer Edition and Enterprise is the *backend* the plugin
+talks to (the in-process DE engine vs. the full governed plane), never the
+plugin code. And because any decision made client-side is *bypassable*, keeping
+enforcement server-side is a security rule, not just an IP one.
+
+This boundary is documented in [`plugins/CONTRIBUTING.md`](../CONTRIBUTING.md)
+and enforced in CI by the plugin IP-boundary gate
+(`scripts/ci/check_plugin_ip_boundary.py`).

watchlight_agent_sdk-0.5.0/pyproject.toml

@@ -0,0 +1,101 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# PyPI distribution name. The IMPORTABLE name stays ``watchlight_core``
+# (see [tool.setuptools.packages.find] below) — keeping it preserves
+# every existing plugin's import path. The distribution name is what
+# customers `pip install` and what surfaces on the PyPI listing.
+name = "watchlight-agent-sdk"
+version = "0.5.0"
+description = "Watchlight Agent SDK — build governed AI-agent plugins for any framework"
+readme = "README.md"
+license = {text = "Apache-2.0"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Watchlight AI", email = "team@watchlight.ai"},
+]
+keywords = [
+    "watchlight",
+    "ai-governance",
+    "agent-runtime",
+    "ai-agents",
+    "agent-sdk",
+    "policy-decision-point",
+    "cedar-policy",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+
+# Strictly minimal. Pydantic v2 is required (events_schema mirror).
+# Framework plugins add their own deps (langgraph, google-adk, boto3,
+# pydantic-ai, …).
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.0",
+    "typing-extensions>=4.5; python_version<'3.12'",
+]
+
+[project.optional-dependencies]
+# `cryptography` is used only to issue throwaway PEMs for the mTLS
+# round-trip test in test_core.py — it's not a runtime dep. The test
+# auto-skips if the package is missing, so any caller pip-installing
+# without [dev] still gets a working SDK, just without the
+# SSL-context load_cert_chain coverage on their machine.
+#
+# `requests` is used only by `tests/test_connect_proxy.py::
+# test_works_for_requests_library_too` — proves the local sidecar
+# CONNECT proxy intercepts BOTH httpx and requests (universal-
+# coverage claim). The test auto-skips when requests is missing,
+# but we include it in [dev] so CI always exercises the universal-
+# coverage path. Not a runtime dep of watchlight-core itself.
+dev = [
+    "pytest>=7",
+    "pytest-asyncio>=0.21",
+    "mypy>=1.8",
+    "cryptography>=42",
+    "requests>=2.32",
+]
+
+# OpenTelemetry export (EN.6) — opt-in customer-facing observability.
+# The OTel SDK is ~50MB installed; customers who don't want OTLP
+# (or run in cold-start-sensitive Lambda environments) install
+# without this extra. `WatchlightOtlpExporter` construction raises
+# ImportError at startup if a non-OFF profile is requested without
+# the extra installed — fail-loud, not silent-no-op.
+otlp = [
+    "opentelemetry-api>=1.20",
+    "opentelemetry-sdk>=1.20",
+    "opentelemetry-exporter-otlp-proto-http>=1.20",
+]
+
+[project.urls]
+Homepage = "https://www.watchlight.ai"
+Documentation = "https://docs.watchlight.ai"
+Repository = "https://github.com/watchlight-ai-beacon/watchlight"
+"Plugin SDK Guide" = "https://github.com/watchlight-ai-beacon/watchlight/tree/main/plugins"
+
+[project.scripts]
+# Allows ``watchlight-conformance my_plugin`` as an alias for
+# ``python -m watchlight_core.conformance my_plugin`` so plugin
+# authors can run the SDK CLI without remembering the module path.
+watchlight-conformance = "watchlight_core.conformance:_main"
+
+[tool.setuptools.packages.find]
+include = ["watchlight_core*"]
+
+[tool.setuptools.package-data]
+watchlight_core = ["py.typed"]

watchlight_agent_sdk-0.5.0/setup.cfg

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

watchlight_agent_sdk-0.5.0/tests/test_arg_key_summary.py

@@ -0,0 +1,84 @@
+"""Tests for the ``arg_key_summary`` behavioural feature — the
+sorted, comma-joined argument KEYS (never values) of a tool call.
+
+This is the privacy-safe feature wl-drift's arg-shape scorer consumes.
+The wire contract spans three ends that MUST agree:
+
+* Rust canonical (``wl-lineage::events::ToolCallObservedPayload``)
+* this Pydantic mirror (``watchlight_core.events_schema``)
+* ``wl-proxy``'s MCP translator + every SDK plugin emitter
+
+If these tests fail, the emitters and wl-drift have drifted on how the
+arg-shape distribution is keyed, and drift scoring will be inconsistent
+across the SDK and proxy vantages.
+"""
+
+from __future__ import annotations
+
+from watchlight_core import INPUT_SUMMARY_MAX_CHARS, summarize_arg_keys
+from watchlight_core.events_schema import ToolCallObservedPayload
+
+
+class TestSummarizeArgKeys:
+    def test_sorted_comma_joined_keys(self) -> None:
+        # Order-independent: whatever kwarg order the framework used,
+        # the same call shape yields the same summary.
+        assert summarize_arg_keys({"text": "a", "format": "b"}) == "format,text"
+        assert summarize_arg_keys({"format": "b", "text": "a"}) == "format,text"
+
+    def test_single_key(self) -> None:
+        assert summarize_arg_keys({"query": "anything"}) == "query"
+
+    def test_values_never_appear(self) -> None:
+        out = summarize_arg_keys({"path": "/etc/passwd", "mode": "r"})
+        assert out == "mode,path"
+        assert "/etc/passwd" not in out
+        assert "r" not in out.split(",")
+
+    def test_empty_mapping_is_none(self) -> None:
+        # A no-argument call contributes no shape.
+        assert summarize_arg_keys({}) is None
+
+    def test_non_mapping_is_none(self) -> None:
+        # Only structured mappings carry keys; a flat string rendering
+        # (e.g. langchain's input_str) must NOT be treated as keys.
+        assert summarize_arg_keys(None) is None
+        assert summarize_arg_keys("query=hello") is None
+        assert summarize_arg_keys(42) is None
+        # A raw list (e.g. Bedrock's parameter dicts) is NOT a mapping;
+        # the bedrock emitter projects names into a mapping first.
+        assert summarize_arg_keys([{"name": "a"}]) is None
+
+    def test_non_string_keys_are_stringified(self) -> None:
+        assert summarize_arg_keys({1: "x", 2: "y"}) == "1,2"
+
+    def test_bounded_to_input_summary_max(self) -> None:
+        big = {f"key_{i:04d}": None for i in range(200)}
+        out = summarize_arg_keys(big)
+        assert out is not None
+        assert len(out) <= INPUT_SUMMARY_MAX_CHARS
+
+
+class TestToolCallObservedPayloadField:
+    def test_field_round_trips(self) -> None:
+        p = ToolCallObservedPayload.model_validate(
+            {
+                "tool": {"resource_type": "tool", "identifier": "web_search"},
+                "action": {"action": "invoke"},
+                "arg_key_summary": "max_results,query",
+            }
+        )
+        assert p.arg_key_summary == "max_results,query"
+        assert p.model_dump(exclude_none=True)["arg_key_summary"] == "max_results,query"
+
+    def test_field_is_optional(self) -> None:
+        # Absent on the wire (older emitters / no structured args) →
+        # no arg-shape contribution, never a validation error.
+        p = ToolCallObservedPayload.model_validate(
+            {
+                "tool": {"resource_type": "tool", "identifier": "t"},
+                "action": {"action": "invoke"},
+            }
+        )
+        assert p.arg_key_summary is None
+        assert "arg_key_summary" not in p.model_dump(exclude_none=True)