refactor(aiguard): move AI Guard to top-level ddtrace.aiguard package (#18754)

## Description

Moves the AI Guard SDK out of the AppSec tree (`ddtrace/appsec/ai_guard` + `ddtrace/appsec/_ai_guard`) into a new top-level **`ddtrace/aiguard`** package, so the Python import path matches the other tracers — Node (`dd-trace/aiguard`) and Java (`datadog.trace.api.aiguard`) — and is no longer conflated with AAP/AppSec.

- New package `ddtrace/aiguard/`: cross-provider core (`_listener`, `_context`, `_common`, `_streaming`, `messages`, `_api_client`, `_initialization`) at top level; provider listeners/plugins under `ddtrace/aiguard/integrations/`.
- `init_ai_guard` is now `load_ai_guard` in `ddtrace/aiguard/_initialization.py`; the AppSec product loader imports it from there.
- **Backwards compatibility:** `ddtrace.appsec.ai_guard` remains as a lazy re-export shim that emits `ddtrace.DDTraceDeprecationWarning` on access and forwards to `ddtrace.aiguard`. Scheduled for removal in **5.0.0**.
- Tests moved to `tests/aiguard/` with their own `tests/aiguard/suitespec.yml` (split out of `tests/appsec/suitespec.yml`); `riotfile.py` test paths updated.

JIRA: [APPSEC-67628](https://datadoghq.atlassian.net/browse/APPSEC-67628)

## Testing

- New `tests/aiguard/api/test_compat_imports.py` asserts every public symbol is importable from the old `ddtrace.appsec.ai_guard` path, resolves to the same object as `ddtrace.aiguard`, and emits `DDTraceDeprecationWarning`.
- Ran `ai_guard_api` (88 passed) and `ai_guard_strands` (130 passed) locally — the latter includes the `TestLazyImport` Strands regression test, confirming the lazy-load contract survives the move. Other suites (openai/anthropic/langchain/litellm) are unchanged mechanically; their optional SDKs aren't installed in the local base env.
- `scripts/lint` `fmt` / `suitespec-check` / `error-log-check` / `riot` all pass.

## Risks

- Low. Pure relocation + import rewrites behind a backwards-compatible shim; no public API contract changes. The deprecated path keeps working until 5.0.0.
- Provider abort-error `__module__` identities now point to `ddtrace.aiguard.integrations.{openai,anthropic}` (used for span `error.type`).

## Additional Notes

- Release note added under `deprecations`.
- `docs/upgrading.rst` gains an "Upgrade to 5.0" entry; `.cursor/rules/ai-guard.mdc`, `AGENTS.md`, and the `.sg` rule updated to the new layout.

[APPSEC-67628]: https://datadoghq.atlassian.net/browse/APPSEC-67628?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

Co-authored-by: alberto.vara <alberto.vara@datadoghq.com>

Author: avara1986

.cursor/rules/ai-guard.mdc

@@ -1,9 +1,9 @@
 ---
 description: AI Guard - LLM/agentic workflow safety evaluation - how it works and development guidelines
 globs:
-  - "**/appsec/_ai_guard/**"
+  - "**/aiguard/**"
   - "**/appsec/ai_guard/**"
-  - "**/tests/appsec/ai_guard/**"
+  - "**/tests/aiguard/**"
 ---
 
 # AI Guard Development Guide
@@ -27,7 +27,7 @@ and acting on its verdict.
 ### Evaluation outcomes
 
 The service returns one of three actions (see `ACTIONS` in
-`ddtrace/appsec/ai_guard/_api_client.py`):
+`ddtrace/aiguard/_api_client.py`):
 
 | Action | Meaning |
 |--------|---------|
@@ -42,44 +42,49 @@ user code cannot accidentally swallow a block decision.
 
 ## Package layout
 
-AI Guard lives in two sibling packages under `ddtrace/appsec/`:
+AI Guard lives in the top-level `ddtrace/aiguard/` package (moved out of
+`ddtrace/appsec/` to align with Node `dd-trace/aiguard` and Java
+`datadog.trace.api.aiguard`):
 
 ```
-ddtrace/appsec/
-├── ai_guard/               # PUBLIC SDK (user-facing, stable API)
-│   ├── __init__.py         # re-exports: new_ai_guard_client, AIGuardClient,
-│   │                       #   AIGuardClientError, AIGuardAbortError, Message,
-│   │                       #   Evaluation, Options, ToolCall, Function, …
-│   ├── _api_client.py      # AIGuardClient.evaluate() + HTTP transport + types
-│   └── integrations/       # framework SDK plugins resolved lazily
-│       ├── litellm.py
-│       └── strands.py      # AIGuardStrandsPlugin / AIGuardStrandsHookProvider
-│
-└── _ai_guard/              # PRIVATE internals (listeners + converters)
-    ├── __init__.py         # init_ai_guard(): lazy, gated on DD_AI_GUARD_ENABLED
-    ├── _listener.py        # ai_guard_listen(): registers all core.on(...) hooks
-    ├── _context.py         # contextvar depth counter to avoid double-scanning
-    ├── _common.py          # _get(), wrap_abort_error() shared helpers
-    ├── _openai.py          # OpenAI common helpers
+ddtrace/aiguard/
+├── __init__.py             # PUBLIC SDK: re-exports new_ai_guard_client,
+│                           #   AIGuardClient, AIGuardClientError,
+│                           #   AIGuardAbortError, Message, Evaluation, Options,
+│                           #   ToolCall, Function, … (Strands plugins lazily)
+├── _api_client.py          # AIGuardClient.evaluate() + HTTP transport + types
+├── _initialization.py      # load_ai_guard(): lazy, gated on DD_AI_GUARD_ENABLED
+├── _listener.py            # ai_guard_listen(): registers all core.on(...) hooks
+├── _context.py             # contextvar depth counter to avoid double-scanning
+├── _common.py              # _get(), wrap_abort_error() shared helpers
+├── _streaming.py           # streaming response evaluation
+├── messages.py             # message formatting helpers
+└── integrations/           # provider listeners/converters + framework plugins
+    ├── litellm.py
+    ├── strands.py          # AIGuardStrandsPlugin / AIGuardStrandsHookProvider
+    ├── openai.py           # OpenAI common helpers
     ├── _openai_chat.py     # Chat Completions API converters + listeners
     ├── _openai_responses.py# Responses API converters + listeners
     ├── _openai_errors.py   # OpenAI-compatible abort error class
-    ├── _anthropic.py       # Anthropic Messages API converters + listeners
-    ├── _anthropic_errors.py# Anthropic-compatible abort error class
-    ├── _langchain.py       # LangChain agent/chatmodel/llm listeners
-    ├── _streaming.py       # streaming response evaluation
-    └── messages.py         # message formatting helpers
+    ├── anthropic.py        # Anthropic Messages API converters + listeners
+    ├── _anthropic_streaming.py # Anthropic stream reconstruction
+    ├── _anthropic_errors.py    # Anthropic-compatible abort error class
+    └── langchain.py        # LangChain agent/chatmodel/llm listeners
 ```
 
+The old import path `ddtrace.appsec.ai_guard` remains as a deprecated re-export
+shim (`ddtrace/appsec/ai_guard/__init__.py`) that emits
+`DDTraceDeprecationWarning` and will be removed in 5.0.0.
+
 **Rule of thumb:**
-- `ai_guard/` (no underscore) = **public**, stable contract. Don't break it.
-- `_ai_guard/` (underscore) = **private**, listeners and provider converters.
+- `ddtrace/aiguard/` top level + `__init__.py` = **public**, stable contract. Don't break it.
+- `_`-prefixed modules and `integrations/` provider listeners = **private** internals.
 
 ## How AI Guard Works: High-Level Architecture
 
 ### 1. Lazy, opt-in initialization
 
-`init_ai_guard()` (in `ddtrace/appsec/_ai_guard/__init__.py`) is a one-shot
+`load_ai_guard()` (in `ddtrace/aiguard/_initialization.py`) is a one-shot
 loader gated on `DD_AI_GUARD_ENABLED`. When enabled, it imports
 `ai_guard_listen()` from `_listener.py`, which constructs a single
 `AIGuardClient` and registers all event listeners. When disabled, nothing is
@@ -108,7 +113,7 @@ so a `DENY`/`ABORT` decision actually stops the SDK call.
 **Consumer side** — `_listener.py` registers listeners with `core.on(...)`:
 
 ```python
-# ddtrace/appsec/_ai_guard/_listener.py
+# ddtrace/aiguard/_listener.py
 core.on("openai.chat.completions.create.before",
         partial(_openai_chat_completion_before, client))
 core.on("openai.chat.completions.create.after",
@@ -174,7 +179,7 @@ All configuration is via environment variables, parsed in
 ## Public SDK usage
 
 ```python
-from ddtrace.appsec.ai_guard import new_ai_guard_client, AIGuardAbortError
+from ddtrace.aiguard import new_ai_guard_client, AIGuardAbortError
 
 client = new_ai_guard_client()
 try:
@@ -208,5 +213,5 @@ re-exported lazily from `ai_guard/__init__.py` via a module-level
   the provider listener honor `is_aiguard_context_active()`.
 - **Preserve `AIDEV-NOTE` anchors** (lazy import timing, stream counter
   lifecycle, legacy message translation) — they encode non-obvious invariants.
-- **Tests** live under `tests/appsec/ai_guard/`. Use the `run-tests` skill;
+- **Tests** live under `tests/aiguard/`. Use the `run-tests` skill;
   never run `pytest` directly.

.cursor/rules/isolated-responsibility.mdc

@@ -64,7 +64,7 @@ The contrib layer knows **nothing** about who (if anyone) is listening.
 ### Consumer — inside the security product
 
 Register listeners with `core.on(...)`. The canonical example is
-`ddtrace/appsec/_ai_guard/_listener.py`:
+`ddtrace/aiguard/_listener.py`:
 
 ```python
 from functools import partial
@@ -82,7 +82,7 @@ def ai_guard_listen():
 ```
 
 Listeners are only registered when the product is **enabled** (e.g. AI Guard's
-`init_ai_guard()` is gated on `DD_AI_GUARD_ENABLED`). When disabled, the events
+`load_ai_guard()` is gated on `DD_AI_GUARD_ENABLED`). When disabled, the events
 are still dispatched but have no subscribers — a cheap no-op.
 
 ## Mental model

.github/CODEOWNERS

@@ -142,6 +142,7 @@ benchmarks/base/aspects_benchmarks_generate.py @DataDog/asm-python
 benchmarks/bm/iast_fixtures*        @DataDog/asm-python
 benchmarks/bm/iast_utils*           @DataDog/asm-python
 # ddtrace files
+ddtrace/aiguard/                    @DataDog/asm-python
 ddtrace/appsec/                     @DataDog/asm-python
 ddtrace/contrib/internal/flask_login/        @DataDog/asm-python
 ddtrace/contrib/internal/subprocess/         @DataDog/asm-python
@@ -153,6 +154,7 @@ ddtrace/internal/iast/              @DataDog/asm-python
 ddtrace/internal/sca/               @DataDog/asm-python
 ddtrace/internal/settings/asm.py             @DataDog/asm-python
 # tests files
+tests/aiguard/                      @DataDog/asm-python
 tests/appsec/                       @DataDog/asm-python
 tests/contrib/subprocess            @DataDog/asm-python
 tests/snapshots/tests*appsec*.json  @DataDog/asm-python

.sg/rules/span-meta-access.yml

@@ -9,7 +9,7 @@ severity: error
 language: python
 ignores:
   - "ddtrace/_trace/context.py"
-  - "ddtrace/appsec/ai_guard/_api_client.py"
+  - "ddtrace/aiguard/_api_client.py"
 rule:
   pattern: $X._meta
 constraints:

AGENTS.md

@@ -78,7 +78,7 @@ Use the Skill tool to invoke these. **Always prefer skills over raw commands.**
 |--------|-------|-------|
 | Application Security (AppSec) | `.cursor/rules/appsec.mdc` | `ddtrace/appsec/`, `tests/appsec/` |
 | IAST | `.cursor/rules/iast.mdc` | `ddtrace/appsec/_iast/`, `tests/appsec/iast*/` |
-| AI Guard | `.cursor/rules/ai-guard.mdc` | `ddtrace/appsec/ai_guard/`, `ddtrace/appsec/_ai_guard/`, `tests/appsec/ai_guard/` |
+| AI Guard | `.cursor/rules/ai-guard.mdc` | `ddtrace/aiguard/`, `tests/aiguard/` |
 | Isolated Responsibility (security vs. shared integrations) | `.cursor/rules/isolated-responsibility.mdc` | `ddtrace/contrib/`, `ddtrace/appsec/` |
 | Native Code (C/C++/Rust/Cython) | `.cursor/rules/native-code.mdc` | `*.c`, `*.cc`, `*.cpp`, `*.h`, `*.hh`, `*.hpp`, `*.rs`, `*.pyx`, `*.pxd` |
 | Internal module (fork safety, periodic threads, forksafe hooks) | `ddtrace/internal/README.md` | `ddtrace/internal/`, `ddtrace/internal/periodic.py`, `ddtrace/internal/threads.py`, `ddtrace/internal/forksafe.py`, `ddtrace/internal/_threads.cpp` |

ddtrace/aiguard/__init__.py

@@ -0,0 +1,30 @@
+"""
+AI Guard public SDK
+"""
+
+from ._api_client import AIGuardAbortError
+from ._api_client import AIGuardClient
+from ._api_client import AIGuardClientError
+from ._api_client import ContentPart
+from ._api_client import Evaluation
+from ._api_client import Function
+from ._api_client import ImageURL
+from ._api_client import Message
+from ._api_client import Options
+from ._api_client import ToolCall
+from ._api_client import new_ai_guard_client
+
+
+__all__ = [
+    "new_ai_guard_client",
+    "AIGuardClient",
+    "AIGuardClientError",
+    "AIGuardAbortError",
+    "ContentPart",
+    "Evaluation",
+    "Function",
+    "ImageURL",
+    "Message",
+    "Options",
+    "ToolCall",
+]

ddtrace/appsec/ai_guard/_api_client.py ddtrace/aiguard/_api_client.pyddtrace/appsec/ai_guard/_api_client.py renamed to ddtrace/aiguard/_api_client.py

@@ -64,7 +64,7 @@ class Evaluation(TypedDict):
     action: Literal["ALLOW", "DENY", "ABORT"]
     reason: str
     tags: list[str]
-    sds: list
+    sds: list[Any]
     tag_probs: dict[str, float]
 
 
@@ -108,7 +108,7 @@ def __init__(
         action: str,
         reason: str,
         tags: Optional[list[str]] = None,
-        sds: Optional[list] = None,
+        sds: Optional[list[Any]] = None,
         tag_probs: Optional[dict[str, float]] = None,
     ):
         self.action = action
@@ -267,7 +267,7 @@ def evaluate(self, messages: list[Message], options: Optional[Options] = None) -
 
                 try:
                     response = self._execute_request(f"{self._endpoint}/evaluate", payload)
-                    result = response.get_json() or {}
+                    result = response.get_json() or {}  # type: ignore[no-untyped-call]
                 except Exception as e:
                     raise AIGuardClientError(message=f"Unexpected error calling AI Guard service: {e}") from e
 
@@ -362,9 +362,9 @@ def _execute_request(self, url: str, payload: Any) -> Response:
         try:
             conn = get_connection(url, self._timeout)
             json_body = json.dumps(payload, ensure_ascii=True, skipkeys=True, default=str)
-            conn.request("POST", url, json_body, self._headers)
+            conn.request("POST", url, json_body, self._headers)  # type: ignore[no-untyped-call]
             resp = conn.getresponse()
-            return Response.from_http_response(resp)
+            return Response.from_http_response(resp)  # type: ignore[no-any-return,no-untyped-call]
         finally:
             conn.close()
 

ddtrace/appsec/_ai_guard/_common.py ddtrace/aiguard/_common.pyddtrace/appsec/_ai_guard/_common.py renamed to ddtrace/aiguard/_common.py

@@ -8,7 +8,7 @@
 from collections.abc import Mapping
 from typing import Any
 
-from ddtrace.appsec.ai_guard._api_client import AIGuardAbortError
+from ddtrace.aiguard._api_client import AIGuardAbortError
 
 
 def _get(obj: Any, key: str, default: Any = None) -> Any:

ddtrace/appsec/_ai_guard/_context.py ddtrace/aiguard/_context.pyddtrace/appsec/_ai_guard/_context.py renamed to ddtrace/aiguard/_context.py

@@ -10,6 +10,7 @@
 
 import contextlib
 import contextvars
+from typing import Iterator
 from typing import Optional
 
 
@@ -21,7 +22,7 @@ def is_aiguard_context_active() -> bool:
     return _AI_GUARD_DEPTH.get() > 0
 
 
-def set_aiguard_context_active() -> contextvars.Token:
+def set_aiguard_context_active() -> contextvars.Token[int]:
     """Mark the current execution context as already under AI Guard evaluation.
 
     Returns an opaque :class:`contextvars.Token` to pair with
@@ -32,7 +33,7 @@ def set_aiguard_context_active() -> contextvars.Token:
     return _AI_GUARD_DEPTH.set(_AI_GUARD_DEPTH.get() + 1)
 
 
-def reset_aiguard_context_active(token: Optional[contextvars.Token]) -> None:
+def reset_aiguard_context_active(token: Optional[contextvars.Token[int]]) -> None:
     """Restore the depth counter to its value before the matching ``set``.
 
     A ``None`` token is a defensive no-op (e.g. cleanup paths that may run
@@ -62,7 +63,7 @@ def reset_aiguard_context_active_current() -> None:
 
 
 @contextlib.contextmanager
-def aiguard_context():
+def aiguard_context() -> Iterator[None]:
     """Mark the current task as under AI Guard evaluation for the block's duration.
 
     Framework integrations (LangChain, Strands) wrap their dispatch + LLM

ddtrace/appsec/_ai_guard/__init__.py ddtrace/aiguard/_initialization.pyddtrace/appsec/_ai_guard/__init__.py renamed to ddtrace/aiguard/_initialization.py

@@ -7,15 +7,15 @@
 _AI_GUARD_TO_BE_LOADED: bool = True
 
 
-def init_ai_guard():
+def load_ai_guard() -> None:
     """Lazily load the ai_guard module listeners."""
     global _AI_GUARD_TO_BE_LOADED
     if _AI_GUARD_TO_BE_LOADED:
         try:
             if not ai_guard_config._ai_guard_enabled:
                 return
 
-            from ddtrace.appsec._ai_guard._listener import ai_guard_listen
+            from ddtrace.aiguard._listener import ai_guard_listen
 
             ai_guard_listen()