fix(docs): make ai_shell example sphinx-gallery compatible

- Rename to ai_shell_machine.py to match gallery filename_pattern
- Move PEP 723 metadata after docstring so gallery finds the RST title
- Lazy-import openai so the class definition works without the package
  (allows diagram generation during docs build)
- Skip sphinx-gallery execution via sys.modules guard
- Graceful degradation: main() prints a message if openai is missing

Author: fgmacedo

tests/examples/ai_shell.py tests/examples/ai_shell_machine.pytests/examples/ai_shell.py renamed to tests/examples/ai_shell_machine.py

@@ -39,8 +39,6 @@
 import sys
 import threading
 
-from openai import OpenAI  # type: ignore[import-not-found]
-
 from statemachine import HistoryState
 from statemachine import State
 from statemachine import StateChart
@@ -410,6 +408,8 @@ class context_tracker(State.Compound):
     # --- Initialization ---
 
     def __init__(self):
+        from openai import OpenAI  # type: ignore[import-not-found]
+
         self.client = OpenAI()
         self.messages: list = [{"role": "system", "content": SYSTEM_PROMPT}]
         self._last_text: str = ""
@@ -510,7 +510,22 @@ def on_enter_conversation_ended(self, **kwargs):
 # ---------------------------------------------------------------------------
 
 
+def _check_openai():
+    """Return True if the openai package is available."""
+    try:
+        import openai  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
 def main():
+    if not _check_openai():
+        print("This example requires the 'openai' package.")
+        print("Install it with: pip install openai")
+        return
+
     print("AI Shell")
     print("A coding assistant powered by python-statemachine + OpenAI.")
     print("Type 'bye', 'exit', or 'quit' to end. Ctrl+C to interrupt.")
@@ -534,5 +549,5 @@ def main():
             sm.send("user_message", text=text)
 
 
-if __name__ == "__main__":
+if __name__ == "__main__" and "sphinx" not in sys.modules:  # pragma: no cover
     main()