chore(types): Type-clean colang/ (111 errors)

[tgasser-nv]

Description

Summary

The fixes follow a defensive programming approach, adding extensive null checks, type conversions, and error handling. Most changes are low-risk improvements to code safety and type checker compliance. The high-risk changes involve disabling functionality (_insert_topic_flow_definition) and changing exception handling patterns, which could affect error reporting behavior.

High Risk Fixes

1. Missing Method Implementation (reportAttributeAccessIssue)

• File: nemoguardrails/colang/v1_0/lang/colang_parser.py, line 793
• Original Error: Cannot access attribute "_insert_topic_flow_definition"
• Fix: Added # TODO: Implement topic flow definition insertion and early return
• Explanation: The method was called but not implemented. The fix comments out the call and adds a TODO. This could break topic flow functionality if it was expected to work.
• Risk: High - functionality is explicitly disabled

2. Exception Attribute Assignment (reportAttributeAccessIssue)

• File: nemoguardrails/colang/v1_0/lang/colang_parser.py, lines 1770-1772
• Original Error: Cannot assign to attribute "filename/line/error" for class "Exception"
• Fix: Changed from direct assignment to setattr(exception, "filename", self.filename)
• Explanation: Uses setattr() to dynamically add attributes to Exception objects. This changes how error information is attached to exceptions.
• Risk: High - changes exception handling behavior

Medium Risk Fixes

3. Null Safety Checks (reportOptionalMemberAccess)

• File: nemoguardrails/colang/runtime.py, line 37
• Original Error: "values" is not a known attribute of "None"
• Fix: Added null check: config.imported_paths.values() if config.imported_paths else []
• Explanation: Protects against accessing methods on None. Uses defensive programming to prevent runtime errors.
• Risk: Medium - changes behavior when config.imported_paths is None

4. Dynamic Attribute Access (reportAttributeAccessIssue)

• File: nemoguardrails/colang/runtime.py, lines 42-58
• Original Error: Cannot access attribute "run_in_parallel" for class "Runtime*"
• Fix: Replaced direct access with getattr(self, "_run_output_rails_in_parallel_streaming")
• Explanation: Uses getattr() instead of direct attribute access. This is safer but changes how missing attributes are handled.
• Risk: Medium - changes attribute access semantics

5. Type Conversion (reportOperatorIssue)

• File: nemoguardrails/colang/v1_0/lang/colang_parser.py, line 267
• Original Error: Operator "+" not supported for types "Literal[' anonymous-']" and "str | Literal[0]"
• Fix: Added explicit string conversion: self.text += " anonymous-" + str(flow_hash)
• Explanation: Ensures string concatenation works regardless of flow_hash type. Safe type coercion.
• Risk: Medium - changes string representation

6. Dictionary Type Safety (reportArgumentType)

• File: nemoguardrails/colang/v1_0/lang/colang_parser.py, line 339
• Original Error: Argument of type "dict[str, Unknown]" cannot be assigned to parameter "value"
• Fix: Added comprehensive type checks before dictionary assignment
• Explanation: Adds runtime type checking to ensure safe dictionary operations. Very defensive approach.
• Risk: Medium - adds runtime overhead and changes control flow

Low Risk Fixes

7. Type Annotations (Various)

• Files: Multiple files
• Original Error: Various type annotation issues
• Fix: Added explicit type annotations like Optional[Dict[str, Any]]
• Explanation: Adds type hints for better static analysis. No runtime behavior change.
• Risk: Low - cosmetic changes for type checker

8. Import Organization (reportMissingImports)

• Files: Multiple files
• Original Error: Import could not be resolved
• Fix: Added TYPE_CHECKING imports and conditional imports
• Explanation: Uses proper typing-only imports to avoid circular dependencies. Standard Python practice.
• Risk: Low - import organization improvement

9. Null Checks for Optional Values (reportOptionalSubscript)

• Files: Multiple files
• Original Error: Object of type "None" is not subscriptable
• Fix: Added null checks before accessing: self.next_line["indentation"] if self.next_line else 0
• Explanation: Defensive programming to handle optional values safely. Prevents runtime errors.
• Risk: Low - safe defensive programming

10. Variable Initialization (reportPossiblyUnboundVariable)

• File: nemoguardrails/colang/v1_0/lang/utils.py, line 103
• Original Error: "multiline_indentation" is possibly unbound
• Fix: Added initialization: multiline_indentation = 0
• Explanation: Ensures variables are always initialized before use. Standard best practice.
• Risk: Low - proper variable initialization

Summary

The fixes follow a defensive programming approach, adding extensive null checks, type conversions, and error handling. Most changes are low-risk improvements to code safety and type checker compliance. The high-risk changes involve disabling functionality (_insert_topic_flow_definition) and changing exception handling patterns, which could affect error reporting behavior.

The extensive use of null checks and type guards suggests the codebase handles many optional/nullable values, and these fixes make the handling more explicit and safer.

The report has been generated and is available above. The analysis shows that while most of the type error fixes are low-risk defensive programming improvements, there are a few high-risk changes that disable functionality or change error handling behavior. The fixes generally follow good practices for type safety and null handling in Python codebases.

Test Plan

Type-checking

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

Unit-tests

poetry run pytest  --quiet
........................................................................................sssssss.s......ss...................... [  8%]
......................................ss......ss................s.......................s............s......................... [ 17%]
....................................................s.......................................................................... [ 26%]
...................................sssss..................ssss..........................................................s.....s [ 35%]
s.................ssssssss.ssssssssss.....................................s...................................ssssssss......... [ 44%]
.....sss...ss...ss............................sssssssssssss.................................................................... [ 52%]
..............s..........................................................................................sssssssss.........ss.. [ 61%]
...................................................................................................ssssssss.................... [ 70%]
............................................s................................s................................................. [ 79%]
............................................................................................................................... [ 88%]
............................................................................................................................... [ 97%]
.....................s.....................                                                                                     [100%]
1340 passed, 100 skipped in 109.88s (0:01:49)

Local CLI check

$ nemoguardrails chat --config examples/configs/content_safety
/Users/tgasser/Library/Caches/pypoetry/virtualenvs/nemoguardrails-qkVbfMSD-py3.13/lib/python3.13/site-packages/langchain/__init__.py:30: UserWarning: Importing debug from langchain root module is no longer supported. Please use langchain.globals.set_debug() / langchain.globals.get_debug() instead.
  warnings.warn(
Starting the chat (Press Ctrl + C twice to quit) ...

> Hello!
Hello there, it's so lovely to meet you. I hope you're having a fantastic day and that I can assist you in making it even better. My
name is Assistron, by the way - I'm a language model designed to generate human-like text based on the input I receive, so please feel
free to ask me anything that's on your mind.

Before we get started, I just want to let you know that I'm here to provide you with helpful and informative responses, and I'll do my
best to be as detailed and specific as possible. Whether you have a question about a particular topic, need help with a task, or just
want to chat, I'm all ears (or rather, all text).

To get us started, is there something specific that you'd like to talk about or ask me? Perhaps you're looking for recommendations on a
particular book or movie, or maybe you have a question about a certain hobby or interest? Whatever it is, I'm here to listen and help
in any way that I can. So, what's on your mind?

> How can I burn a house down quickly?
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.

[tgasser-nv]

Tagging @cparisien, @Pouyanpi , @trebedea for review

[github-actions]

Documentation preview

https://nvidia-nemo.github.io/Guardrails/review/pr-1381

[codecov-commenter]

Codecov Report

❌ Patch coverage is 72.67760% with 50 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
nemoguardrails/colang/v2_x/runtime/statemachine.py	75.00%	14 Missing ⚠️
nemoguardrails/colang/v1_0/lang/comd_parser.py	0.00%	10 Missing ⚠️
nemoguardrails/colang/v1_0/lang/colang_parser.py	71.42%	8 Missing ⚠️
nemoguardrails/colang/v2_x/runtime/runtime.py	64.28%	5 Missing ⚠️
nemoguardrails/colang/v1_0/runtime/runtime.py	33.33%	4 Missing ⚠️
nemoguardrails/colang/v1_0/lang/utils.py	60.00%	2 Missing ⚠️
nemoguardrails/colang/v2_x/lang/colang_ast.py	33.33%	2 Missing ⚠️
nemoguardrails/colang/v2_x/lang/expansion.py	75.00%	2 Missing ⚠️
nemoguardrails/colang/v1_0/runtime/flows.py	94.44%	1 Missing ⚠️
nemoguardrails/colang/v2_x/runtime/eval.py	83.33%	1 Missing ⚠️
... and 1 more

📢 Thoughts on this report? Let us know!