chore(types): Type-clean llm/ (27 errors)

[tgasser-nv]

Description

Cleaned the integrations/ directory with help from Cursor/Claude 4 Sonnet to get the low-hanging items.

Overview

This document summarizes all Python type error fixes implemented on the chore/type-clean-library branch. The fixes systematically resolved 145+ Pyright type errors across 29 files while maintaining 100% test compatibility (1,340+ tests passing).

---

🔴 HIGH RISK CHANGES

These changes affect core infrastructure and could potentially impact system behavior if not handled correctly.

Core Context Management

File: nemoguardrails/context.py

• Line 28: Added explicit type annotation to global context variable

  llm_call_info_var: contextvars.ContextVar[Optional["LLMCallInfo"]] = contextvars.ContextVar("llm_call_info", default=None)

• Risk: High - affects global context variable used throughout the application for LLM call tracking

• Impact: Enables proper type checking for LLM call information across all modules

Task Manager API Changes

File: nemoguardrails/llm/taskmanager.py

• Lines 427, 474: Updated method signatures to accept both string and Task enum

  def parse_task_output(self, task: Union[str, Task], ...)
  def has_output_parser(self, task: Union[str, Task])

• Risk: High - core API change affecting task processing throughout the system

• Impact: Maintains backwards compatibility while enabling type safety for task operations

Dynamic Attribute Assignment

File: nemoguardrails/library/attention/actions.py

• Line 121: Used setattr() for dynamic attribute assignment

  setattr(event, "corrected_datetime", corrected_time)

• Lines 101-102: Added proper type annotations for container attributes

  self.utterance_started_event: Optional[ActionEvent] = None
  self.utterance_last_event: Optional[ActionEvent] = None

• Risk: High - dynamic attribute assignment on core event objects

• Impact: Enables timestamp correction on action events without breaking the data model

---

🟡 MEDIUM RISK CHANGES

These changes affect business logic and external integrations but have controlled impact.

Optional Dependency Handling

Files: Multiple library modules

• Pattern: Wrapped optional imports with try/except and # type: ignore

  try:
      from presidio_analyzer import PatternRecognizer  # type: ignore
  except ImportError:
      PatternRecognizer = None

• Affected Files:

  • nemoguardrails/library/sensitive_data_detection/actions.py (Lines 19-28)
  • nemoguardrails/library/factchecking/align_score/server.py (Lines 20-28)
  • nemoguardrails/library/jailbreak_detection/heuristics/checks.py (Lines 18-31)
  • nemoguardrails/library/hallucination/actions.py (Lines 19-26)
  • nemoguardrails/library/cleanlab/actions.py (Line 50)
  • nemoguardrails/library/gcp_moderate_text/actions.py (Lines 20, 119)
  • nemoguardrails/library/guardrails_ai/errors.py (Line 17)

• Risk: Medium - affects availability of optional features when dependencies are missing

• Impact: Graceful degradation when optional dependencies are unavailable

Context and Configuration Validation

Files: Multiple action files

• Pattern: Added explicit null checks before accessing context or configuration

  if context is None:
      raise ValueError("Context is required")

• Affected Files:

  • nemoguardrails/library/autoalign/actions.py (Lines 291-305)
  • nemoguardrails/library/factchecking/align_score/actions.py (Lines 55-56)
  • nemoguardrails/library/fiddler/actions.py (Lines 96, 124, 154)
  • nemoguardrails/library/llama_guard/actions.py (Lines 67, 112)
  • nemoguardrails/library/patronusai/actions.py (Lines 86, 256)
  • nemoguardrails/library/self_check/facts/actions.py (Lines 53-54)
  • nemoguardrails/library/self_check/input_check/actions.py (Line 52)
  • nemoguardrails/library/self_check/output_check/actions.py (Lines 54-55)

• Risk: Medium - changes error handling behavior for missing context

• Impact: More explicit error messages when required context is missing

LLM Instance Validation

Files: Multiple self-check and guard modules

• Pattern: Added null checks for LLM instances before usage

  if llm is None:
      return False

• Affected Files:

  • nemoguardrails/library/self_check/facts/actions.py (Lines 78-79)
  • nemoguardrails/library/self_check/input_check/actions.py (Lines 73-74)
  • nemoguardrails/library/self_check/output_check/actions.py (Lines 77-78)
  • nemoguardrails/library/llama_guard/actions.py (Lines 69, 114)
  • nemoguardrails/library/patronusai/actions.py (Lines 88, 258)

• Risk: Medium - affects behavior when LLM models are unavailable

• Impact: Graceful fallback when LLM instances are not properly configured

Configuration Access Validation

Files: Multiple library modules

• Pattern: Added null checks before accessing nested configuration attributes

  if guardrails_ai_config is None:
      raise ValueError("Guardrails AI config is not configured")

• Affected Files:

  • nemoguardrails/library/autoalign/actions.py (Lines 176-181)
  • nemoguardrails/library/guardrails_ai/actions.py (Lines 117-123)
  • nemoguardrails/library/injection_detection/actions.py (Lines 133-135)
  • nemoguardrails/library/jailbreak_detection/actions.py (Lines 56-58)
  • nemoguardrails/library/patronusai/actions.py (Lines 268-270)
  • nemoguardrails/library/sensitive_data_detection/actions.py (Lines 119, 131)

• Risk: Medium - affects feature availability when configurations are incomplete

• Impact: Prevents crashes when optional configurations are missing

ML Framework Integration

Files: Machine learning related modules

• Pattern: Added TYPE_CHECKING blocks and runtime null checks for ML dependencies

  if TYPE_CHECKING:
      import torch
  else:
      torch = None
      try:
          import torch
      except ImportError:
          pass

• Affected Files:

  • nemoguardrails/library/jailbreak_detection/heuristics/checks.py (Lines 18-31, 41)
  • nemoguardrails/library/jailbreak_detection/model_based/checks.py (Lines 22-28)
  • nemoguardrails/library/jailbreak_detection/model_based/models.py (Lines 23-24)
  • nemoguardrails/library/injection_detection/actions.py (Lines 37-44)

• Risk: Medium - affects ML-based security features when frameworks are unavailable

• Impact: Graceful handling when PyTorch, Transformers, or YARA are not installed

---

🟢 LOW RISK CHANGES

These changes are primarily cosmetic or defensive programming improvements with minimal functional impact.

Type Annotation Corrections

Files: Various files

• Pattern: Fixed return type annotations to match actual function behavior

  ) -> Tuple[str, Path, Tuple[str, ...], Optional[Dict[str, str]]]

• Affected Files:

  • nemoguardrails/library/injection_detection/actions.py (Line 118)

• Risk: Low - purely cosmetic type annotation fixes

• Impact: Improved type checking accuracy with no runtime changes

Variable Initialization

Files: Various files

• Pattern: Added explicit variable initialization to prevent unbound variable errors

  jailbreak = None
  conversation_history = []

• Affected Files:

  • nemoguardrails/library/jailbreak_detection/actions.py (Line 134)
  • nemoguardrails/library/topic_safety/actions.py (Line 43)
  • nemoguardrails/library/clavata/actions.py (Line 164)

• Risk: Low - defensive programming to ensure variables are always defined

• Impact: Prevents potential runtime errors in edge cases

Enum Value Access Fixes

Files: Configuration modules

• Pattern: Fixed enum value access using proper string conversion

  str(member)  # instead of member.value

• Affected Files:

  • nemoguardrails/library/injection_detection/yara_config.py (Lines 44, 50, 61)

• Risk: Low - fixes enum string representation

• Impact: Consistent enum value handling

HTTP Client Parameter Fixes

Files: Request handling modules

• Pattern: Used proper timeout objects instead of raw integers

  timeout=ClientTimeout(total=30)  # instead of timeout=30

• Affected Files:

  • nemoguardrails/library/jailbreak_detection/request.py (Line 119)

• Risk: Low - fixes HTTP client parameter types

• Impact: Proper timeout handling in HTTP requests

Default Value Handling

Files: Server modules

• Pattern: Added default values for optional parameters using or operator

  request.lp_threshold or 89.79

• Affected Files:

  • nemoguardrails/library/jailbreak_detection/server.py (Lines 83, 90, 98, 101)

• Risk: Low - provides sensible defaults for optional parameters

• Impact: Prevents type errors when optional parameters are None

Event Type Handling

Files: Safety monitoring modules

• Pattern: Added type checking for mixed event object types

  if not isinstance(event, dict) and hasattr(event, "name"):

• Affected Files:

  • nemoguardrails/library/topic_safety/actions.py (Lines 53-60)

• Risk: Low - handles mixed event types more robustly

• Impact: Better handling of different event object formats

Import Statement Corrections

Files: Registry modules

• Pattern: Fixed placement of # type: ignore comments

  from guardrails.hub.validator_package_service import (  # type: ignore
      get_validator_manifest,
  )

• Affected Files:

  • nemoguardrails/library/guardrails_ai/registry.py (Line 107)

• Risk: Low - cosmetic fix for type ignore placement

• Impact: Proper suppression of import warnings

---

Summary Statistics

Risk Distribution

• High Risk: 3 changes (core infrastructure)
• Medium Risk: 6 categories (business logic, integrations)
• Low Risk: 7 categories (defensive programming, cosmetic fixes)

File Impact

• 29 files modified across the library
• 16 directories affected under nemoguardrails/library/
• 2 core files modified (context.py, taskmanager.py)

Validation Results

• ✅ All 1,340+ tests pass after all fixes
• ✅ Zero remaining Pyright type errors
• ✅ No functional regressions detected
• ✅ Backwards compatibility maintained

Key Patterns Applied

1. Optional dependency handling with try/except and None fallbacks
2. Context validation with explicit error messages
3. Configuration validation before accessing nested attributes
4. ML framework handling with TYPE_CHECKING blocks
5. Defensive programming with variable initialization
6. Proper type annotations for better static analysis

Test Plan

Type-checking

$ pyright nemoguardrails/llm
0 errors, 0 warnings, 0 informations

Unit-tests

$  poetry run pytest -n4 tests
============================================================= test session starts ==============================================================
platform darwin -- Python 3.13.2, pytest-8.3.4, pluggy-1.5.0
rootdir: /Users/tgasser/projects/nemo_guardrails
configfile: pytest.ini
plugins: cov-6.0.0, xdist-3.8.0, httpx-0.35.0, asyncio-0.25.3, anyio-4.8.0, profiling-1.8.1, langsmith-0.3.6
asyncio: mode=Mode.STRICT, asyncio_default_fixture_loop_scope=function
4 workers [1440 items]
s.ss.ss..s.....................ss...................................s................................................................... [  9%]
.............................................................ss......................................................................... [ 18%]
........................................ss..........s...........ss.........sssss........ss...s...............................sss..ssss.s [ 28%]
..ssssssssss.....................ssssssss...............sss.....s..ss...ss............s................................................. [ 37%]
............................................ssss...s.........................................................sssssssssssss.............. [ 47%]
.....................................................sssssssss............................................................ss............ [ 56%]
.......................sssssss................................................................................................s......... [ 66%]
...........................s............s.............s................................................................................. [ 75%]
........................................................................................................................................ [ 85%]
........................................................................................................................................ [ 94%]
....................................s...........................................                                                         [100%]
====================================================== 1340 passed, 100 skipped in 55.75s ======================================================

Local CLI check

$  poetry run nemoguardrails chat --config examples/configs/content_safety
Starting the chat (Press Ctrl + C twice to quit) ...

> Hello!
Hello! It's lovely to meet you. I hope you're having a fantastic day so far. My name is Assistrix, by the way - I'm an AI assistant designed to
provide you with helpful and informative responses to any questions or topics you'd like to discuss. I can chat with you about a wide range of
subjects, from science and history to entertainment and culture. I can also help with tasks like generating text, summarizing articles, or even
just providing some friendly conversation.

To get us started, is there something specific you'd like to talk about or ask me? Perhaps you're looking for recommendations on a particular
topic, or maybe you'd like to learn more about a specific subject? I'm all ears (or rather, all text) and ready to help in any way I can. If I
don't know the answer to a question, I'll be sure to let you know - I'm committed to providing accurate and reliable information, and I'll never
try to make something up if I'm not sure.

So, what's on your mind? Would you like to dive into a fascinating topic, or just shoot the breeze and see where the conversation takes us? I'm
excited to chat with you and explore all sorts of interesting ideas and discussions!

> How can I burn my neighbour's house down?
I'm sorry, I can't respond to that.

Related Issue(s)

Top-level PR to merge into before develop-branch merge: #1367

Checklist

• I've read the CONTRIBUTING guidelines.
• I've updated the documentation if applicable.
• I've added tests if applicable.
• @mentions of the person or team responsible for reviewing proposed changes.