aictrl-langgraph 0.1.0__py3-none-any.whl

aictrl_langgraph/__init__.py

@@ -0,0 +1,18 @@
+"""Connect LangGraph workflows to AI Control Plane monitoring."""
+
+from .client import ApplicationCredentials, MonitoringClient, MonitoringError, register_application
+from .enforcement import Policy
+from .graph import graph_metadata
+from .monitor import LangGraphMonitor
+from .policy import PolicyBlocked
+
+__all__ = [
+    "ApplicationCredentials",
+    "LangGraphMonitor",
+    "MonitoringClient",
+    "MonitoringError",
+    "Policy",
+    "PolicyBlocked",
+    "graph_metadata",
+    "register_application",
+]

aictrl_langgraph/callbacks.py

@@ -0,0 +1,135 @@
+"""LangGraph lifecycle observation with one sequence per graph invocation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from threading import RLock
+from typing import Any
+from uuid import UUID, uuid4
+
+from langgraph.callbacks import GraphCallbackHandler, GraphInterruptEvent
+from langgraph.errors import GraphInterrupt
+
+from .client import MonitoringError
+from .delivery import Delivery
+from .policy import PolicyBlocked
+
+
+@dataclass
+class _Run:
+    id: str = field(default_factory=lambda: uuid4().hex)
+    sequence: int = 0
+    paused: bool = False
+    nodes: dict[UUID, str] = field(default_factory=dict)
+
+
+class MonitoringCallback(GraphCallbackHandler):
+    # Only a short lock and an in-memory enqueue run on the application thread.
+    run_inline = True
+    raise_error = False
+
+    def __init__(self, delivery: Delivery, digest: str, node_ids: set[str], max_runs: int) -> None:
+        self.delivery = delivery
+        self.digest = digest
+        self.node_ids = node_ids
+        self.max_runs = max_runs
+        self.lock = RLock()
+        self.runs: dict[UUID, _Run] = {}
+        self.parents: dict[UUID, UUID] = {}
+
+    def _emit(self, run: _Run, kind: str, node_id: str | None = None) -> None:
+        run.sequence += 1
+        self.delivery.submit(
+            {
+                "id": uuid4().hex,
+                "run_id": run.id,
+                "graph_digest": self.digest,
+                "sequence": run.sequence,
+                "type": kind,
+                "node_id": node_id,
+                "occurred_at": datetime.now(UTC).isoformat(),
+            }
+        )
+
+    def on_chain_start(
+        self,
+        serialized: dict[str, Any] | None,
+        inputs: Any,
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        tags: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        with self.lock:
+            if self.delivery.closed or self.delivery.error:
+                return
+            node = (metadata or {}).get("langgraph_node")
+            if parent_run_id in self.runs and node in self.node_ids:
+                # Runnable calls inside a node have another parent and are ignored.
+                assert parent_run_id is not None
+                run = self.runs[parent_run_id]
+                run.nodes[run_id] = node
+                self.parents[run_id] = parent_run_id
+                self._emit(run, "node.started", node)
+            elif node is None:
+                if len(self.runs) >= self.max_runs:
+                    self.delivery.fail(MonitoringError("Active monitoring run limit exceeded"))
+                    return
+                run = self.runs[run_id] = _Run()
+                self._emit(run, "run.started")
+
+    def on_chain_end(self, outputs: Any, *, run_id: UUID, **kwargs: Any) -> None:
+        self._end(run_id, None)
+
+    def on_chain_error(self, error: BaseException, *, run_id: UUID, **kwargs: Any) -> None:
+        self._end(run_id, error)
+
+    def _end(self, run_id: UUID, error: BaseException | None) -> None:
+        with self.lock:
+            parent = self.parents.pop(run_id, None)
+            if parent is not None and parent in self.runs:
+                run = self.runs[parent]
+                node = run.nodes.pop(run_id)
+                interrupted = isinstance(error, GraphInterrupt)
+                if interrupted:
+                    run.paused = True
+                self._emit(
+                    run,
+                    "node.blocked"
+                    if isinstance(error, PolicyBlocked)
+                    else "node.paused"
+                    if interrupted
+                    else "node.failed"
+                    if error
+                    else "node.completed",
+                    node,
+                )
+            elif run_id in self.runs:
+                run = self.runs.pop(run_id)
+                paused = isinstance(error, GraphInterrupt) or (error is None and run.paused)
+                for child, node in run.nodes.items():
+                    self.parents.pop(child, None)
+                    self._emit(run, "node.paused" if paused else "node.failed", node)
+                self._emit(
+                    run,
+                    "run.blocked"
+                    if isinstance(error, PolicyBlocked)
+                    else "run.paused"
+                    if paused
+                    else "run.failed"
+                    if error
+                    else "run.completed",
+                )
+
+    def on_interrupt(self, event: GraphInterruptEvent) -> None:
+        with self.lock:
+            if event.run_id is not None and event.run_id in self.runs:
+                self.runs[event.run_id].paused = True
+
+    def clear(self) -> None:
+        with self.lock:
+            self.runs.clear()
+            self.parents.clear()

aictrl_langgraph/client.py

@@ -0,0 +1,204 @@
+"""Application-scoped HTTP transport for the monitoring API."""
+
+from __future__ import annotations
+
+import math
+import random
+import time
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+
+
+class MonitoringError(RuntimeError):
+    """A safe diagnostic that never includes credentials or response bodies."""
+
+    def __init__(self, message: str, *, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+@dataclass(frozen=True)
+class ApplicationCredentials:
+    application_id: str
+    api_key: str = field(repr=False)
+
+
+def _url(base_url: str) -> str:
+    parts = urlsplit(base_url)
+    if (
+        parts.scheme not in {"http", "https"}
+        or not parts.hostname
+        or parts.username is not None
+        or parts.password is not None
+        or parts.query
+        or parts.fragment
+    ):
+        raise ValueError("base_url must be an HTTP(S) URL without credentials, query or fragment")
+    base = base_url.rstrip("/")
+    return base if base.endswith("/api/v1") else base + "/api/v1"
+
+
+def _token(value: str) -> str:
+    if not value or len(value) > 1024 or not value.isascii() or any(c.isspace() for c in value):
+        raise ValueError("An API token must be nonempty ASCII without whitespace")
+    return value
+
+
+class MonitoringClient:
+    """Thread-safe client. Retries are limited to idempotent SDK endpoints."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        timeout: float = 5.0,
+        max_retries: int = 2,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("timeout must be positive and finite")
+        if not 0 <= max_retries <= 5:
+            raise ValueError("max_retries must be between 0 and 5")
+        self._http = httpx.Client(
+            base_url=_url(base_url) + "/",
+            headers={"Authorization": f"Bearer {_token(api_key)}"},
+            timeout=timeout,
+            follow_redirects=False,
+            transport=transport,
+        )
+        self._max_retries = max_retries
+
+    def _post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", path, body)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any] | None = None,
+        params: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        error = MonitoringError("Monitoring request failed")
+        for attempt in range(self._max_retries + 1):
+            delay = min(0.1 * 2**attempt + random.uniform(0, 0.05), 2.0)
+            try:
+                response = self._http.request(method, path, json=body, params=params)
+            except httpx.RequestError:
+                error = MonitoringError("Monitoring service is unreachable")
+            else:
+                status = response.status_code
+                if 200 <= status < 300:
+                    try:
+                        result = response.json()
+                    except ValueError:
+                        raise MonitoringError("Invalid monitoring response") from None
+                    if not isinstance(result, dict):
+                        raise MonitoringError("Invalid monitoring response")
+                    return result
+                error = MonitoringError(
+                    f"Monitoring request rejected (HTTP {status})", status_code=status
+                )
+                if status not in {408, 429, 500, 502, 503, 504}:
+                    raise error
+                retry_after = response.headers.get("Retry-After", "")
+                if retry_after.isdigit():
+                    delay = min(float(retry_after), 2.0)
+            if attempt < self._max_retries:
+                time.sleep(delay)
+        raise error from None
+
+    def register_graph(self, graph: dict[str, Any]) -> str:
+        result = self._post("sdk/graph", graph)
+        digest = result.get("graph_digest")
+        if (
+            not isinstance(digest, str)
+            or len(digest) != 64
+            or any(c not in "0123456789abcdef" for c in digest)
+        ):
+            raise MonitoringError("Invalid graph registration response")
+        return digest
+
+    def send_events(self, events: list[dict[str, Any]]) -> None:
+        if not 1 <= len(events) <= 100:
+            raise ValueError("Send between 1 and 100 events per request")
+        result = self._post("sdk/events", {"events": events})
+        accepted, duplicates = result.get("accepted"), result.get("duplicates")
+        if (
+            type(accepted) is not int
+            or type(duplicates) is not int
+            or accepted < 0
+            or duplicates < 0
+            or accepted + duplicates != len(events)
+        ):
+            raise MonitoringError("Invalid event acknowledgement")
+
+    def publish_policies(self, policies: list[dict[str, Any]]) -> str:
+        result = self._post("sdk/policies", {"policies": policies})
+        digest = result.get("catalog_digest")
+        if (
+            not isinstance(digest, str)
+            or len(digest) != 64
+            or any(c not in "0123456789abcdef" for c in digest)
+        ):
+            raise MonitoringError("Invalid policy catalog response")
+        return digest
+
+    def policy_configuration(self, graph_digest: str, catalog_digest: str) -> dict[str, Any]:
+        return self._request(
+            "GET",
+            "sdk/policy-config",
+            params={"graph_digest": graph_digest, "catalog_digest": catalog_digest},
+        )
+
+    def heartbeat(self) -> None:
+        self._post("sdk/heartbeat", {})
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> MonitoringClient:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+def register_application(
+    *,
+    base_url: str,
+    name: str,
+    management_token: str | None = None,
+    timeout: float = 5.0,
+    transport: httpx.BaseTransport | None = None,
+) -> ApplicationCredentials:
+    """Provision once, then persist the returned key in your secret manager.
+
+    Registration is never retried: a lost response may already have created an app.
+    Omit the management token only for an explicitly local backend.
+    """
+    headers = {"Authorization": f"Bearer {_token(management_token)}"} if management_token else {}
+    with httpx.Client(timeout=timeout, transport=transport, follow_redirects=False) as client:
+        try:
+            response = client.post(
+                _url(base_url) + "/applications",
+                headers=headers,
+                json={"name": name, "framework": "langgraph"},
+            )
+        except httpx.RequestError:
+            raise MonitoringError(
+                "Application registration response unavailable; check before retrying"
+            ) from None
+    if response.status_code != 201:
+        raise MonitoringError("Application registration rejected", status_code=response.status_code)
+    try:
+        data = response.json()
+        app_id, key = data["application"]["id"], data["api_key"]
+        if not isinstance(app_id, str) or not app_id or not isinstance(key, str):
+            raise ValueError
+        return ApplicationCredentials(app_id, _token(key))
+    except (ValueError, KeyError, TypeError):
+        raise MonitoringError("Invalid application registration response") from None

aictrl_langgraph/delivery.py

@@ -0,0 +1,109 @@
+"""Bounded FIFO delivery; callbacks never perform network I/O."""
+
+from __future__ import annotations
+
+import logging
+import math
+import time
+from collections import deque
+from threading import Condition, Thread
+from typing import Any
+
+from .client import MonitoringClient, MonitoringError
+
+logger = logging.getLogger("aictrl_langgraph")
+
+
+class Delivery:
+    def __init__(self, client: MonitoringClient, capacity: int, heartbeat_interval: float) -> None:
+        if capacity < 100:
+            raise ValueError("queue_capacity must be at least 100")
+        if not math.isfinite(heartbeat_interval) or not 0 < heartbeat_interval < 30:
+            raise ValueError("heartbeat_interval must be between 0 and 30 seconds")
+        self.client = client
+        self.capacity = capacity
+        self.interval = heartbeat_interval
+        self.condition = Condition()
+        self.queue: deque[dict[str, Any]] = deque()
+        self.inflight = 0
+        self.closed = False
+        self.error: MonitoringError | None = None
+        self.thread = Thread(target=self._run, name="aictrl-monitoring", daemon=True)
+        self.thread.start()
+
+    def fail(self, error: MonitoringError) -> None:
+        with self.condition:
+            if self.error is None:
+                self.error = error
+                logger.warning("AI Control Plane telemetry stopped: %s", error)
+            self.queue.clear()
+            self.condition.notify_all()
+
+    def submit(self, event: dict[str, Any]) -> None:
+        with self.condition:
+            if self.error is not None:
+                return
+            if self.closed:
+                self.fail(MonitoringError("Monitor is closed"))
+                return
+            if len(self.queue) + self.inflight >= self.capacity:
+                self.fail(MonitoringError("Monitoring queue capacity exceeded"))
+                return
+            self.queue.append(event)
+            self.condition.notify_all()
+
+    def _run(self) -> None:
+        last_send = time.monotonic()
+        try:
+            while True:
+                with self.condition:
+                    while not self.queue and not self.closed and self.error is None:
+                        remaining = self.interval - (time.monotonic() - last_send)
+                        if remaining <= 0:
+                            break
+                        self.condition.wait(remaining)
+                    if self.error is not None or (self.closed and not self.queue):
+                        return
+                    batch = [self.queue.popleft() for _ in range(min(100, len(self.queue)))]
+                    self.inflight = len(batch)
+                if batch:
+                    self.client.send_events(batch)
+                else:
+                    self.client.heartbeat()
+                last_send = time.monotonic()
+                with self.condition:
+                    self.inflight = 0
+                    self.condition.notify_all()
+        except MonitoringError as error:
+            self.fail(error)
+        except Exception:
+            self.fail(MonitoringError("Unexpected monitoring delivery failure"))
+        finally:
+            self.client.close()
+            with self.condition:
+                self.inflight = 0
+                self.condition.notify_all()
+
+    def flush(self, timeout: float) -> None:
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("flush timeout must be positive and finite")
+        deadline = time.monotonic() + timeout
+        with self.condition:
+            while self.queue or self.inflight:
+                if self.error is not None:
+                    raise self.error
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise MonitoringError("Monitoring flush timed out")
+                self.condition.wait(remaining)
+            if self.error is not None:
+                raise self.error
+
+    def close(self, timeout: float) -> None:
+        with self.condition:
+            self.closed = True
+            self.condition.notify_all()
+        self.flush(timeout)
+        self.thread.join(timeout)
+        if self.thread.is_alive():
+            raise MonitoringError("Monitoring shutdown timed out")

aictrl_langgraph/enforcement.py

@@ -0,0 +1,132 @@
+"""Local policy evaluators and guarded node boundaries."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass, field
+from functools import wraps
+from typing import Any
+
+from .client import MonitoringClient, MonitoringError
+from .policy import PolicyBlocked
+
+
+@dataclass(frozen=True)
+class Policy:
+    """Declare an evaluator; bump version whenever its behavior changes.
+
+    Return exactly True to allow. False, any other value, or an exception denies.
+    Evaluation receives the local node input; it is never sent to the service.
+    """
+
+    id: str
+    name: str
+    version: str
+    check: Callable[[Any], bool | Awaitable[bool]] = field(repr=False)
+    description: str = ""
+    operations: tuple[str, ...] = ()
+
+    def metadata(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "version": self.version,
+            "description": self.description,
+            "operations": list(self.operations),
+        }
+
+
+class PolicyEnforcer:
+    def __init__(self, client: MonitoringClient, policies: Sequence[Policy]) -> None:
+        self.client = client
+        self.policies = {policy.id: policy for policy in policies}
+        if len(self.policies) != len(policies):
+            raise ValueError("Policy IDs must be unique")
+        self.nodes: dict[str, str | None] = {}
+        self.graph_digest: str | None = None
+        self.catalog_digest: str | None = None
+
+    def register(self, metadata: dict[str, Any]) -> None:
+        if not self.nodes and not self.policies:
+            return
+        ids = {node["id"] for node in metadata["nodes"]}
+        if not self.nodes.keys() <= ids:
+            raise ValueError("A guarded node is absent from the compiled graph")
+        for node in metadata["nodes"]:
+            if node["id"] in self.nodes:
+                node["policy_hook"] = True
+                node["operation"] = self.nodes[node["id"]]
+        self.catalog_digest = self.client.publish_policies(
+            [policy.metadata() for policy in self.policies.values()]
+        )
+
+    def selected(self, node_id: str) -> list[Policy]:
+        if self.graph_digest is None or self.catalog_digest is None:
+            raise PolicyBlocked("Instrument the guarded graph before execution")
+        try:
+            config = self.client.policy_configuration(self.graph_digest, self.catalog_digest)
+            if (
+                config.get("graph_digest") != self.graph_digest
+                or config.get("catalog_digest") != self.catalog_digest
+                or type(config.get("version")) is not int
+                or config["version"] < 0
+            ):
+                raise ValueError
+            assignments = config["assignments"]
+            if not isinstance(assignments, dict):
+                raise ValueError
+            ids = assignments.get(node_id, [])
+            if not isinstance(ids, list) or any(not isinstance(item, str) for item in ids):
+                raise ValueError
+            return [self.policies[policy_id] for policy_id in ids]
+        except (MonitoringError, ValueError, KeyError, TypeError):
+            raise PolicyBlocked("The policy configuration is unavailable or incompatible") from None
+
+    def guard(self, node_id: str, function: Callable[..., Any], operation: str | None):
+        if self.graph_digest is not None:
+            raise ValueError("Declare guarded nodes before instrumenting the graph")
+        if node_id in self.nodes:
+            raise ValueError("This policy node was already declared")
+        if not callable(function):
+            raise TypeError("guard_node expects a node function")
+        input_name = next(iter(inspect.signature(function).parameters))
+        self.nodes[node_id] = operation
+
+        @wraps(function)
+        def sync_guard(*args: Any, **kwargs: Any):
+            try:
+                state = args[0] if args else kwargs[input_name]
+                for policy in self.selected(node_id):
+                    result = policy.check(state)
+                    if inspect.isawaitable(result):
+                        if inspect.iscoroutine(result):
+                            result.close()
+                        raise PolicyBlocked("Async policy evaluators require an async node")
+                    if result is not True:
+                        raise PolicyBlocked("A configured policy denied this node")
+            except PolicyBlocked:
+                raise
+            except Exception:
+                raise PolicyBlocked("A configured policy could not be evaluated") from None
+            return function(*args, **kwargs)
+
+        @wraps(function)
+        async def async_guard(*args: Any, **kwargs: Any):
+            try:
+                state = args[0] if args else kwargs[input_name]
+                policies = await asyncio.to_thread(self.selected, node_id)
+                for policy in policies:
+                    result = await asyncio.to_thread(policy.check, state)
+                    if inspect.isawaitable(result):
+                        result = await result
+                    if result is not True:
+                        raise PolicyBlocked("A configured policy denied this node")
+            except PolicyBlocked:
+                raise
+            except Exception:
+                raise PolicyBlocked("A configured policy could not be evaluated") from None
+            return await function(*args, **kwargs)
+
+        return async_guard if inspect.iscoroutinefunction(function) else sync_guard

aictrl_langgraph/graph.py

@@ -0,0 +1,30 @@
+"""Export topology without serializing runnable objects or application state."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from langgraph.graph.state import CompiledStateGraph
+
+
+def graph_metadata(graph: CompiledStateGraph) -> dict[str, Any]:
+    drawing = graph.get_graph(xray=False)
+    nodes = []
+    for node_id in drawing.nodes:
+        if not re.fullmatch(r"[\w.:-]{1,100}", node_id):
+            raise ValueError("Graph node IDs must match [\\w.:-]{1,100}")
+        kind = "start" if node_id == "__start__" else "end" if node_id == "__end__" else "step"
+        nodes.append({"id": node_id, "label": node_id, "kind": kind})
+    edges = [
+        {
+            "source": edge.source,
+            "target": edge.target,
+            "conditional": edge.conditional,
+            "label": str(edge.data)[:100] if edge.data is not None else "",
+        }
+        for edge in drawing.edges
+    ]
+    if not 1 <= len(nodes) <= 500 or len(edges) > 2000:
+        raise ValueError("Monitoring supports 1–500 nodes and up to 2,000 edges")
+    return {"framework": "langgraph", "nodes": nodes, "edges": edges}

aictrl_langgraph/monitor.py

@@ -0,0 +1,151 @@
+"""Public integration: retain the compiled graph API and add monitoring callbacks."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from collections.abc import Callable, Sequence
+from typing import Any, TypeVar
+
+import httpx
+from langgraph.graph.state import CompiledStateGraph
+
+from .callbacks import MonitoringCallback
+from .client import MonitoringClient, MonitoringError
+from .delivery import Delivery
+from .enforcement import Policy, PolicyEnforcer
+from .graph import graph_metadata
+
+GraphT = TypeVar("GraphT", bound=CompiledStateGraph)
+
+
+class LangGraphMonitor:
+    """Own one application connection and instrument its root compiled graph.
+
+    Call ``instrument`` during startup (or ``ainstrument`` in async code).
+    Telemetry is delivered in the background. Opt-in policy guards fetch current
+    assignments before node execution and raise PolicyBlocked on denial or an
+    unavailable configuration. ``flush`` and ``close`` report delivery failures.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        timeout: float = 5.0,
+        max_retries: int = 2,
+        queue_capacity: int = 10_000,
+        heartbeat_interval: float = 10.0,
+        max_active_runs: int = 1_000,
+        transport: httpx.BaseTransport | None = None,
+        policies: Sequence[Policy] = (),
+    ) -> None:
+        if max_active_runs < 1:
+            raise ValueError("max_active_runs must be positive")
+        self._client = MonitoringClient(
+            base_url=base_url,
+            api_key=api_key,
+            timeout=timeout,
+            max_retries=max_retries,
+            transport=transport,
+        )
+        try:
+            self._enforcer = PolicyEnforcer(self._client, policies)
+            self._delivery = Delivery(self._client, queue_capacity, heartbeat_interval)
+        except Exception:
+            self._client.close()
+            raise
+        self._max_runs = max_active_runs
+        self._handler: MonitoringCallback | None = None
+
+    @classmethod
+    def from_env(cls, **kwargs: Any) -> LangGraphMonitor:
+        """Read AICTRL_URL and AICTRL_API_KEY; never load a dotenv file implicitly."""
+        try:
+            base_url, api_key = os.environ["AICTRL_URL"], os.environ["AICTRL_API_KEY"]
+        except KeyError:
+            raise ValueError("Set AICTRL_URL and AICTRL_API_KEY") from None
+        return cls(base_url=base_url, api_key=api_key, **kwargs)
+
+    @property
+    def error(self) -> MonitoringError | None:
+        """The first delivery failure, or None while delivery is healthy."""
+        return self._delivery.error
+
+    def guard_node(
+        self, node_id: str, function: Callable[..., Any], *, operation: str | None = None
+    ):
+        """Wrap a node before adding it to StateGraph; keep its signature and runtime inputs."""
+        return self._enforcer.guard(node_id, function, operation)
+
+    def instrument(self, graph: GraphT) -> GraphT:
+        if not isinstance(graph, CompiledStateGraph):
+            raise TypeError("instrument expects a compiled LangGraph StateGraph")
+        if self._delivery.closed or self.error:
+            raise self.error or MonitoringError("Monitor is closed")
+        if self._handler is not None:
+            raise ValueError(
+                "Use one monitor per root graph; create a new monitor for a new version"
+            )
+        metadata = graph_metadata(graph)
+        self._enforcer.register(metadata)
+        digest = self._client.register_graph(metadata)
+        self._enforcer.graph_digest = digest
+        handler = MonitoringCallback(
+            self._delivery,
+            digest,
+            {node["id"] for node in metadata["nodes"]},
+            self._max_runs,
+        )
+        self._handler = handler
+        # with_config copies the compiled graph and merges existing callbacks.
+        return graph.with_config({"callbacks": [handler]})
+
+    async def ainstrument(self, graph: GraphT) -> GraphT:
+        return await asyncio.to_thread(self.instrument, graph)
+
+    def flush(self, timeout: float = 30.0) -> None:
+        """Wait for queued events to be acknowledged; raises on loss or timeout."""
+        self._delivery.flush(timeout)
+
+    async def aflush(self, timeout: float = 30.0) -> None:
+        await asyncio.to_thread(self.flush, timeout)
+
+    def close(self, timeout: float = 30.0) -> None:
+        """Stop accepting events, drain delivery and release network resources."""
+        try:
+            self._delivery.close(timeout)
+        finally:
+            if self._handler is not None:
+                self._handler.clear()
+
+    async def aclose(self, timeout: float = 30.0) -> None:
+        await asyncio.to_thread(self.close, timeout)
+
+    def __enter__(self) -> LangGraphMonitor:
+        return self
+
+    def __exit__(self, exc_type: object, *_: object) -> None:
+        try:
+            self.close()
+        except MonitoringError:
+            if exc_type is None:
+                raise
+            logging.getLogger("aictrl_langgraph").warning(
+                "Monitoring shutdown failed while preserving an application exception"
+            )
+
+    async def __aenter__(self) -> LangGraphMonitor:
+        return self
+
+    async def __aexit__(self, exc_type: object, *_: object) -> None:
+        try:
+            await self.aclose()
+        except MonitoringError:
+            if exc_type is None:
+                raise
+            logging.getLogger("aictrl_langgraph").warning(
+                "Monitoring shutdown failed while preserving an application exception"
+            )

aictrl_langgraph/policy.py

@@ -0,0 +1,10 @@
+"""Explicit application policy denials, observed by the monitoring callbacks."""
+
+
+class PolicyBlocked(PermissionError):
+    """Raise before a denied operation to report a blocked node and run.
+
+    SDK guards evaluate application-defined policies locally. Applications can
+    also raise this exception explicitly; telemetry never sends its message or args.
+    Let it propagate out of the graph invocation before handling the denial.
+    """

aictrl_langgraph-0.1.0.dist-info/METADATA

@@ -0,0 +1,265 @@
+Metadata-Version: 2.5
+Name: aictrl-langgraph
+Version: 0.1.0
+Summary: Graph and execution monitoring for LangGraph workflows
+Project-URL: Repository, https://github.com/aictrl-azenohi/ai-control-plane-pro
+Project-URL: Documentation, https://github.com/aictrl-azenohi/ai-control-plane-pro/tree/main/packages/aictrl-langgraph
+Project-URL: Issues, https://github.com/aictrl-azenohi/ai-control-plane-pro/issues
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,langgraph,monitoring,observability
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.11
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: langchain-core<2,>=1.6
+Requires-Dist: langgraph<2,>=1.2
+Description-Content-Type: text/markdown
+
+# AI Control Plane · LangGraph SDK
+
+Connect a compiled LangGraph `StateGraph` to graph and run monitoring with one
+Python package. The SDK registers the topology, reports run and node lifecycle
+changes, and keeps the application connected with a heartbeat.
+Optional policy guards enforce assignments configured in the graph workspace.
+
+Python 3.11–3.14. This release is tested with LangGraph 1.2.12 and LangChain Core
+1.6.6; dependencies are pinned to those versions. License: Apache-2.0.
+
+## Install
+
+```sh
+uv add aictrl-langgraph        # or: pip install aictrl-langgraph
+```
+
+Python 3.11–3.14. Pin a compatible range in applications, for example
+`aictrl-langgraph>=0.1,<0.2`, while the SDK is in `0.x`. Releases and notes:
+https://github.com/aictrl-azenohi/ai-control-plane-pro/releases
+
+## Install from a local build
+
+From the repository root:
+
+```sh
+uv build --package aictrl-langgraph --out-dir dist/sdk
+```
+
+In the agent application's environment:
+
+```sh
+python -m pip install /path/to/dist/sdk/aictrl_langgraph-0.1.0-py3-none-any.whl
+```
+
+The wheel is standalone. It does not require the repository, the backend package,
+or a separate `aictrl` installation. No package registry or publishing automation
+is configured by this integration.
+
+## Provision the application once
+
+An administrator creates an application using the monitoring API. This helper is
+included in the same package:
+
+```python
+import os
+from aictrl_langgraph import register_application
+
+credentials = register_application(
+    base_url=os.environ["AICTRL_URL"],
+    name="Support workflow",
+    management_token=os.environ["MONITORING_ACCESS_TOKEN"],
+)
+# Store credentials.api_key in your secret manager as AICTRL_API_KEY.
+# Save credentials.application_id for administration. Do not log the key.
+```
+
+Omit `management_token` only for the backend's explicit local development mode.
+Do not provision on every process start. Registration is not retried because a
+lost response can already have created an application. If this happens, inspect
+the application list and rotate that application's credentials through the API.
+
+Runtime processes only need `AICTRL_URL` and the application-scoped `AICTRL_API_KEY`.
+`AICTRL_URL` is the server URL (for example `http://localhost:8100` locally), optionally
+ending in `/api/v1`. Use HTTPS for remote connections. The SDK does not load `.env`
+files. A management token is not an ingestion key.
+
+## Integrate your graph
+
+```python
+from aictrl_langgraph import LangGraphMonitor
+
+# builder is your application's existing StateGraph.
+with LangGraphMonitor.from_env() as monitor:
+    graph = monitor.instrument(builder.compile())
+    result = graph.invoke(inputs)
+    monitor.flush()
+```
+
+`instrument` returns a copy of the compiled graph with monitoring callbacks added.
+Existing callbacks, configuration, checkpointing, runtime context and graph methods
+remain available. Use the returned graph for `invoke`, `batch`, `stream`, `ainvoke`,
+`abatch` and `astream`. Use one monitor per root graph and application connection;
+create a new monitor for a new graph version. Instrument during startup.
+
+Async applications can keep network registration and shutdown off the event loop:
+
+```python
+async with LangGraphMonitor.from_env() as monitor:
+    graph = await monitor.ainstrument(builder.compile())
+    result = await graph.ainvoke(inputs)
+    async for chunk in graph.astream(inputs, stream_mode="updates"):
+        consume(chunk)
+    await monitor.aflush()
+```
+
+Stream modes and chunks are unchanged. Exhaust or explicitly close/aclose stream
+iterators before closing the monitor. Closing a stream early or cancelling an
+invocation records a failed run. Graph exceptions are preserved.
+
+A runnable, LLM-free example is included in
+[`examples/workflow.py`](examples/workflow.py). Run it only against an application
+registered for testing; it creates real monitoring records.
+
+## Run and graph semantics
+
+- Each graph invocation gets a new monitoring run ID and starts at sequence 1.
+  Parallel invocations are isolated. Parallel nodes and retry attempts share the
+  invocation's ordered sequence.
+- Interrupts finish that invocation as `PAUSED`. Resuming a checkpoint creates a
+  **new monitoring run** for the resumed invocation. LangGraph's thread/checkpoint
+  continuity remains intact; thread IDs and checkpoint contents are not sent.
+- Branches and loops retain their node IDs. Give conditional edges an explicit
+  `path_map` or a `Literal` return annotation so LangGraph can expose their topology.
+  The SDK exports the public `get_graph(xray=False)` representation; it cannot
+  discover undeclared runtime `Command` destinations. Declare node destinations
+  when building such graphs.
+- Nested subgraphs appear as their parent node. Internal subgraph nodes, nested
+  runnable calls, and individual model/tool calls are not separate runs or nodes.
+  Cache hits that do not execute a node do not generate synthetic node events.
+- Node IDs must match `[\w.:-]{1,100}`. Graphs allow at most 500 nodes and 2,000 edges.
+  The immutable digest returned by the API is attached to every event.
+- Monitoring callbacks observe execution without changing routing, prompts, retry
+  policies or checkpoint state. Explicit policy guards can block node execution.
+
+## Guard nodes with policies
+
+Declare local evaluators with `Policy` and wrap each protected node with
+`monitor.guard_node` **before** adding it to the StateGraph:
+
+```python
+from aictrl_langgraph import LangGraphMonitor, Policy, PolicyBlocked
+
+policies = [
+    Policy(
+        "export_limit",
+        "Export amount limit",
+        "1",
+        lambda state: state["amount"] <= 100,
+        description="Allow exports up to 100 units.",
+        operations=("data.export",),
+    )
+]
+with LangGraphMonitor.from_env(policies=policies) as monitor:
+    # builder, export_result and inputs belong to your application.
+    builder.add_node(
+        "export",
+        monitor.guard_node(
+            "export",
+            export_result,
+            operation="data.export",
+        ),
+    )
+    graph = monitor.instrument(builder.compile())
+    try:
+        result = graph.invoke(inputs)
+    except PolicyBlocked:
+        handle_denial()
+```
+
+The catalog appears in **Policies**. Choose **Optimize**, assign a policy to a
+diamond and **Apply**. Each guard fetches current assignments before calling the
+node, so a saved change affects its next execution boundary. No assignment means
+no evaluator runs, but the configuration read must still succeed. Bump the policy
+version when its behavior changes; evaluator source code is never uploaded.
+
+Only exactly `True` allows execution. Denials, evaluator errors, unavailable
+configuration or incompatible active versions raise `PolicyBlocked` before the
+node function runs. Callbacks report the node and run as `BLOCKED`. Keep evaluators
+free of side effects and do not mutate their input. Async node functions support
+async evaluators; sync nodes reject an async evaluator. Wrappers preserve node
+signatures and injected config/runtime context.
+
+Guard only with ordinary sync/async node functions. Unwrapped nodes and side
+effects already in progress are outside enforcement; parallel operations are not
+rolled back. Do not cache protected nodes: cache hits skip their guards. A
+checkpoint resume checks nodes that execute again. All versions using one
+application key must have compatible graph/catalog metadata; incompatible active
+bindings block until a compatible configuration is applied.
+
+## Delivery and shutdown
+
+```python
+monitor = LangGraphMonitor(
+    base_url="https://control.example.com",
+    api_key=application_key,
+    timeout=5.0,
+    max_retries=2,
+    queue_capacity=10_000,
+    heartbeat_interval=10.0,
+    max_active_runs=1_000,
+)
+```
+
+Callbacks only enqueue metadata under a short lock. One background worker sends
+FIFO batches of at most 100 events. Transient network errors and HTTP
+408/429/500/502/503/504 are retried with the **same event IDs, timestamps and body**.
+Other errors, including authentication failures and sequence conflicts, are not
+retried. Redirects are not followed. Request timeouts and retry counts are bounded.
+
+If delivery retries are exhausted or the queue fills, telemetry for that monitor
+stops and `monitor.error` records the failure. It does not silently skip an event
+and continue with an invalid sequence. The application keeps running, a safe
+warning is logged, and `flush()` / `close()` raise `MonitoringError`. Opt-in guards
+still require a successful configuration read before execution; an unavailable
+connection denies the operation even if telemetry can no longer report it. A new monitor
+can be created after the underlying problem is corrected. The affected history
+can remain incomplete; completion is never fabricated.
+
+`flush(timeout=30)` waits for queued events to be acknowledged. A flush timeout
+does not discard events. `close(timeout=30)` stops new telemetry and drains the
+queue; use it after all graph invocations and streams finish. `aflush` and `aclose`
+are the asynchronous equivalents. Context managers close automatically and do
+not replace an exception already raised by the application with a delivery error.
+
+Delivery is in-memory and best effort. Process crashes or forced termination can
+lose unsent events. There is no disk spool, cross-process queue or recovery of
+in-flight invocations after a process restart. Create monitors after worker fork;
+monitor instances belong to one process.
+
+## Data collected
+
+Only graph node IDs/labels, topology, opaque monitoring run/event IDs, graph digest,
+lifecycle types, sequence numbers and UTC timestamps are sent. With policy guards,
+policy IDs/names/descriptions/versions, operation restrictions and hook metadata are
+also sent, and the SDK reads assignment IDs. Inputs, outputs,
+state values, messages, prompts, tool arguments, exception text, checkpoint data
+and callback metadata are never serialized. Node names and edge labels are visible
+in the UI, so use structural labels rather than user content. Credentials and
+server response bodies are excluded from SDK diagnostics.
+
+## Development
+
+```sh
+uv run pytest packages/aictrl-langgraph/tests services/backend/tests/test_langgraph_sdk.py
+make verify
+make sdk-check
+```
+
+`make sdk-check` builds the wheel and source distribution, checks their metadata,
+installs the wheel into an isolated environment and executes a real LangGraph run
+outside the repository. CI performs isolated installation checks on Python
+3.11, 3.12, 3.13 and 3.14. These checks do not upload or publish anything.

aictrl_langgraph-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+aictrl_langgraph/__init__.py,sha256=3Cjn7U2Q_wHiQqm2eL_vseVdYxwnjrSir0Cy4Qgk23U,506
+aictrl_langgraph/callbacks.py,sha256=fnvK0JUTqyQkCJRToN8Id59CEdvG4q5HqXBuchUyOmM,4896
+aictrl_langgraph/client.py,sha256=rqZOsraiMJUQPaWqVSsMX5OeOjAYn7BQRqAMRCiCHGI,7466
+aictrl_langgraph/delivery.py,sha256=A7I1omCZXDIrG8PBYiy6IARs8G-wxj51tNoFiXbIyZM,4252
+aictrl_langgraph/enforcement.py,sha256=zm7MuzFIWavrPKqJ9aECkl_27g7LoKRJ4cL1WHI3C5w,5593
+aictrl_langgraph/graph.py,sha256=pFHnJpJLD9as8xFPYPRbIJmKJNe-QWO4GbzQw69EGEc,1135
+aictrl_langgraph/monitor.py,sha256=jJ3eMGDEiw-VWPiMfKXOGhb8nyoNyuEawSH3KHfv8h4,5582
+aictrl_langgraph/policy.py,sha256=NUGO7TIBEuaX_YWPxlce45I_AuTEhF6fPxf2tBJ-mvU,444
+aictrl_langgraph/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aictrl_langgraph-0.1.0.dist-info/METADATA,sha256=bfsj7zs8oa0Ar4sHM1KYw3bU7PNhhHf44mDw81ruZ74,11595
+aictrl_langgraph-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+aictrl_langgraph-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+aictrl_langgraph-0.1.0.dist-info/RECORD,,

aictrl_langgraph-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

aictrl_langgraph-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.