bug: TypeError in chat.py when processing events

[notetiene]

Did you check docs and existing issues?

• I have read all the NeMo-Guardrails docs
• I have updated the package to the latest version before submitting this issue
• (optional) I have used the develop branch
• I have searched the existing issues of NeMo-Guardrails

Python version (python --version)

Python 3.10.13

Operating system/version

Ubuntu 22.04

NeMo-Guardrails version (if you must use a specific version and not the latest

Develop

Describe the bug

A TypeError occurs when running the hello_world example after commit df51265 from #1380. The error message is:

TypeError: nemoguardrails.colang.v2_x.runtime.flows.State() argument after ** must be a mapping, not State

Error Location:

Guardrails/nemoguardrails/cli/chat.py

Line 543 in d2bfaea

output_state_typed: State = cast(State, State(**output_state))

Full Stack Trace:

File "nemoguardrails/cli/chat.py", line 543, in _process_input_events
    output_state_typed: State = cast(State, State(**output_state))
TypeError: nemoguardrails.colang.v2_x.runtime.flows.State() argument after ** must be a mapping, not State

Root Cause:

In commit df51265, the code in nemoguardrails/cli/chat.py was refactored to assume process_events_async returns a dictionary for the state parameter. However, process_events_async actually returns a State object (not a dict), causing the code to attempt State(**output_state) where output_state is already a State instance.

Type Mismatch Chain:

1. RuntimeV2_x.process_events():

   • Returns: Tuple[List[Dict[str, Any]], State]
   • Returns a State object, not a dict

   • Guardrails/nemoguardrails/colang/v2_x/runtime/runtime.py

     Line 403 in d2bfaea

     ) -> Tuple[List[Dict[str, Any]], State]:

2. LLMRails.process_events_async():

   • Calls self.runtime.process_events() and returns the result directly
   • Type annotation is incorrect:

     1. Guardrails/nemoguardrails/rails/llm/llmrails.py

        Line 1433 in d2bfaea

        ) -> Tuple[List[dict], dict]:

     2. Guardrails/nemoguardrails/colang/v2_x/runtime/runtime.py

        Line 403 in ea92409

        ) -> Tuple[List[Dict[str, Any]], State]:

3. chat.py:

   • Assumes output_state is a dict based on the incorrect type annotation
   • Attempts to reconstruct: State(**output_state)
   • Fails because output_state is already a State instance

   • Guardrails/nemoguardrails/cli/chat.py

     Line 543 in d2bfaea

     output_state_typed: State = cast(State, State(**output_state))

Affected Files:

1. nemoguardrails/cli/chat.py:

   • Line 507: chat_state.output_state = cast(State, State(**output_state))
   • Line 543: output_state_typed: State = cast(State, State(**output_state))
   • Both lines incorrectly assume output_state is a dict

   • Guardrails/nemoguardrails/cli/chat.py

     Line 507 in d2bfaea

     chat_state.output_state = cast(State, State(**output_state))

   • Guardrails/nemoguardrails/cli/chat.py

     Line 543 in d2bfaea

     output_state_typed: State = cast(State, State(**output_state))

2. nemoguardrails/rails/llm/llmrails.py:

   • Type annotation incorrectly states: -> Tuple[List[dict], dict]
   • Should be: -> Tuple[List[dict], State]

   • Guardrails/nemoguardrails/rails/llm/llmrails.py

     Line 1433 in d2bfaea

     ) -> Tuple[List[dict], dict]:

Related Commit:

• Commit: df51265
• PR: chore(types): Type-clean /cli (37 errors) #1380
• Title: "chore(types): Type-clean /cli (37 errors)"

Steps To Reproduce

1. Use the hello_world example:

   • examples/v2_x/tutorial/hello_world_1/config.yml
   • examples/v2_x/tutorial/hello_world_1/rails.co

2. Run the chat interface:

   nemoguardrails chat --config examples/v2_x/tutorial/hello_world_1/config.yml

3. The error occurs immediately when processing input events during initialization or when processing user input.

Expected Behavior

The chat interface should start successfully and be able to process user input events without errors. The process_events_async method should return a State object, and the code should handle it correctly without attempting to unpack it as a dictionary.

Actual Behavior

The chat interface crashes with a TypeError when attempting to process events. The error occurs because the code tries to unpack a State object as if it were a dictionary using State(**output_state), but output_state is already a State instance, not a mapping.

Impact:

• Severity: High - Breaks the chat interface for v2.x runtime
• Scope: Affects all users of the v2.x runtime with the chat CLI
• Workaround: None - the error occurs during normal operation

[Pouyanpi]

Thank you very much @notetiene for opening this issue. We'll get it fixed for the next release.

cc @tgasser-nv

[notetiene]

I tried to make a fix yersterday. Sadly, I've got no more time for that.

@Pouyanpi @tgasser-nv I came to the conclusion only using one state datastructure State would be better. Using dict some places is error prone.

Also several tests would need to be modified accordingly.

[tgasser-nv]

Hi @notetiene , thanks for reporting this bug with a detailed write-up of the issue. I reproduced the issue using the chat app with nemoguards_v2 example config. I'll prepare a fix for the next release.

$ poetry run nemoguardrails chat --config examples/configs/nemoguards_v2
Starting the chat (Press Ctrl + C twice to quit) ...
Traceback (most recent call last):
  File "<string>", line 1, in <module>
    import sys; from importlib import import_module; sys.argv = ['/Users/tgasser/Library/Caches/pypoetry/virtualenvs
/nemoguardrails-qkVbfMSD-py3.13/bin/nemoguardrails', 'chat', '--config', 'examples/configs/nemoguards_v2']; sys.exit
(import_module('nemoguardrails.__main__').app())


 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/Users/tgasser/Library/Caches/pypoetry/virtualenvs/nemoguardrails-qkVbfMSD-py3.13/lib/python3.13/site-packag
es/typer/main.py", line 341, in __call__
    raise e
  File "/Users/tgasser/Library/Caches/pypoetry/virtualenvs/nemoguardrails-qkVbfMSD-py3.13/lib/python3.13/site-packag
es/typer/main.py", line 324, in __call__
    return get_command(self)(*args, **kwargs)
           ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
  File "/Users/tgasser/Library/Caches/pypoetry/virtualenvs/nemoguardrails-qkVbfMSD-py3.13/lib/python3.13/site-packag
es/click/core.py", line 1161, in __call__
    return self.main(*args, **kwargs)
           ~~~~~~~~~^^^^^^^^^^^^^^^^^
  File "/Users/tgasser/Library/Caches/pypoetry/virtualenvs/nemoguardrails-qkVbfMSD-py3.13/lib/python3.13/site-packag
es/typer/core.py", line 757, in main
    return _main(
        self,
    ...<6 lines>...
        **extra,
    )
  File "/Users/tgasser/Library/Caches/pypoetry/virtualenvs/nemoguardrails-qkVbfMSD-py3.13/lib/python3.13/site-packag
es/typer/core.py", line 195, in _main
    rv = self.invoke(ctx)
  File "/Users/tgasser/Library/Caches/pypoetry/virtualenvs/nemoguardrails-qkVbfMSD-py3.13/lib/python3.13/site-packag
es/click/core.py", line 1697, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^
  File "/Users/tgasser/Library/Caches/pypoetry/virtualenvs/nemoguardrails-qkVbfMSD-py3.13/lib/python3.13/site-packag
es/click/core.py", line 1443, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/tgasser/Library/Caches/pypoetry/virtualenvs/nemoguardrails-qkVbfMSD-py3.13/lib/python3.13/site-packag
es/click/core.py", line 788, in invoke
    return __callback(*args, **kwargs)
  File "/Users/tgasser/Library/Caches/pypoetry/virtualenvs/nemoguardrails-qkVbfMSD-py3.13/lib/python3.13/site-packag
es/typer/main.py", line 699, in wrapper
    return callback(**use_params)
  File "/Users/tgasser/projects/nemo_guardrails/nemoguardrails/cli/__init__.py", line 115, in chat
    run_chat(
    ~~~~~~~~^
        config_path=config[0],
        ^^^^^^^^^^^^^^^^^^^^^^
    ...<4 lines>...
        config_id=config_id,
        ^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/Users/tgasser/projects/nemo_guardrails/nemoguardrails/cli/chat.py", line 732, in run_chat
    loop.run_until_complete(_run_chat_v2_x(rails_app))
    ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/Cellar/python@3.13/3.13.2/Frameworks/Python.framework/Versions/3.13/lib/python3.13/asyncio/bas
e_events.py", line 725, in run_until_complete
    return future.result()
           ~~~~~~~~~~~~~^^
  File "/Users/tgasser/projects/nemo_guardrails/nemoguardrails/cli/chat.py", line 616, in _run_chat_v2_x
    await _process_input_events()
  File "/Users/tgasser/projects/nemo_guardrails/nemoguardrails/cli/chat.py", line 543, in _process_input_events
    output_state_typed: State = cast(State, State(**output_state))
                                            ~~~~~^^^^^^^^^^^^^^^^
TypeError: nemoguardrails.colang.v2_x.runtime.flows.State() argument after ** must be a mapping, not State